# Navigation

SimVX provides 2D pathfinding through graph-based A* (`AStar2D`), grid-based A* (`AStarGrid2D`), and a steering agent node (`NavigationAgent2D`).

## Graph-Based A* (AStar2D)

Build an arbitrary waypoint graph and find shortest paths:

```python
from simvx.core import AStar2D

astar = AStar2D()

# Add waypoints
astar.add_point(0, (0, 0))
astar.add_point(1, (100, 0))
astar.add_point(2, (100, 100))
astar.add_point(3, (50, 50), weight=2.0)  # Costlier to traverse

# Connect them
astar.connect_points(0, 1)  # Bidirectional by default
astar.connect_points(1, 2)
astar.connect_points(0, 3)
astar.connect_points(3, 2)

# Find path (returns world positions)
path = astar.get_point_path(0, 2)  # [(0,0), (100,0), (100,100)]

# Or get point IDs
id_path = astar.get_id_path(0, 2)  # [0, 1, 2]
```

### Additional Operations

```python
astar.set_point_disabled(3)           # Exclude from pathfinding
astar.disconnect_points(0, 1)         # Remove a connection
closest = astar.get_closest_point((45, 45))  # Nearest non-disabled point
```

## Grid-Based A* (AStarGrid2D)

For tile-based games, `AStarGrid2D` manages a rectangular grid automatically:

```python
from simvx.core import AStarGrid2D

grid = AStarGrid2D(width=20, height=20, cell_size=32.0, diagonal=True)

# Mark obstacles
grid.set_solid(5, 5)
grid.set_solid(5, 6)
grid.set_solid(5, 7)

# Set terrain cost (swamp = 3x slower)
grid.set_weight(10, 10, 3.0)

# Find path in grid coordinates
path = grid.find_path((0, 0), (19, 19))  # [(0,0), (1,1), ...]

# Or use world positions (auto-converts via cell_size)
world_path = grid.find_path_world((16.0, 16.0), (624.0, 624.0))
```

## NavigationAgent2D

A node that follows computed paths with built-in steering. Assign a pathfinder, set a target, and the agent moves each physics frame:

```python
from simvx.core import NavigationAgent2D, AStarGrid2D, Vec2

grid = AStarGrid2D(50, 50, cell_size=16.0)

class Enemy(NavigationAgent2D):
    max_speed = 120.0
    path_desired_distance = 4.0

    def ready(self):
        self.set_navigation(grid)
        self.navigation_finished.connect(self._on_arrived)
        self.target_position = Vec2(400, 300)

    def _on_arrived(self):
        print("Reached destination!")
```

### Properties

| Property | Default | Description |
|---------|---------|-------------|
| `max_speed` | `100.0` | Maximum movement speed in units/sec |
| `path_desired_distance` | `4.0` | Distance to a waypoint before advancing to the next |

### Properties and Signals

- **`target_position`** -- Assigning this recomputes the path immediately.
- **`velocity`** -- Current velocity vector (read-only, computed each physics frame).
- **`is_navigation_finished`** -- `True` when the agent has reached its target.
- **`navigation_finished`** -- Signal emitted when the target is reached.

## API Reference

See {py:mod}`simvx.core.navigation` for the complete navigation API.