feat(ecs): pathfinding — A* on block grid with CPU budget

[iverly]

Context

The server runtime architecture spec (section 8) defines a pathfinding system with CPU budgeting. The ECS, physics plugin (gravity, AABB collision), and world collision utilities (ray_cast, check_overlap, resolve_movement) are all in place. AI goals (separate issue) will depend on pathfinding to navigate entities toward targets.

Spec reference: docs/superpowers/specs/2026-04-15-server-runtime-architecture-design.md sections 8.1 and 8.2.

Problem

1. No pathfinding capability exists — AI goals cannot navigate entities around obstacles.
2. No budget system prevents pathfinding from consuming excessive tick time.
3. No priority queue ensures closest entities are pathfound first.
4. No Path component exists for the movement system to consume.

Proposed approach

8.1 — PathfindingScheduler

An ECS system running in the Simulate phase at every(5) (same frequency as AI). Maintains a priority queue of pathfinding requests:

• Requests ordered by distance to nearest player (closest = highest priority).
• Each tick, processes requests until the CPU budget is exhausted.
• Unfinished requests carry over to the next tick.
• Results stored on the entity's Path component for the movement system to consume.

Configuration:

[server.budgets]
pathfinding_ms = 2

8.2 — A* algorithm

Core provides A* pathfinding on the block grid:

• Reads world block data (is_solid(), is_passable()) to determine walkable positions.
• Produces a Vec<BlockPos> path from source to destination.
• Supports configurable max distance to limit search space.
• Considers entity dimensions (1-block-wide vs 2-block-wide entities).

Components to add

• PathTarget — target: BlockPos, max_distance: f64 (requested destination)
• Path — waypoints: Vec<BlockPos>, current_index: usize (computed path)

Movement integration

A PathFollowSystem (or integrated into existing movement) consumes the Path component:

• Each tick, moves entity toward the next waypoint using Velocity.
• Removes completed waypoints.
• Requests recomputation when path is blocked or target changes.

Plugin extensibility

Plugins can provide custom heuristics or navigation mesh implementations by replacing the pathfinding system.

Scope

• crates/basalt-ecs/ — new components (PathTarget, Path)
• crates/basalt-world/ — block passability queries (extend is_solid())
• crates/basalt-server/src/game/tick.rs — register pathfinding system
• New module for A* algorithm (in basalt-world or dedicated crate)
• crates/basalt-server/src/config.rs — pathfinding budget config

Benefits

• Enables mob navigation around obstacles and terrain
• CPU budget prevents pathfinding from causing tick overruns
• Priority queue ensures player-visible entities are pathed first
• Foundation for all movement-based AI goals (chase, flee, patrol)

Non-goals

• Navigation meshes or advanced pathfinding structures (plugin territory)
• Flying entity pathfinding (3D A* variant — future enhancement)
• Inter-dimensional pathfinding
• Path smoothing or bezier curves (movement system handles interpolation)