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:

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

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:

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:

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 simvx.core.navigation for the complete navigation API.