Voxel Navigation

Voxel navigation finds paths through three-dimensional free space for flying or underwater characters. It uses a voxel grid instead of the surface-based navmesh.

The grid visualization extends through the room's height as well as across its floor. Use it to inspect grid coverage around level geometry; enable VisPath separately to inspect a computed route. Click the image to view it at full resolution.

Set up the grid

Add one AI Voxel Grid Settings component (plAiVoxelGridSettingsComponent) to the scene.

• ResolutionX, ResolutionY, and ResolutionZ set the number of cells per axis.
• VoxelSize sets each cell's width in meters.
• CollisionLayer filters geometry used to mark occupied cells.
• The owner's position is the center of the grid.

The default 64 × 64 × 32 grid at 0.5 m covers 32 × 32 × 16 m. Both endpoints and the route must fit within the configured volume. Increasing all three resolutions rapidly increases work; keep the grid focused on the navigation space you need.

Voxelization queries static and dynamic physics geometry at initialization. Use a working physics module and verify collision-layer filtering. Restart simulation after changing the settings.

Move an object

Add AI Voxel Navigation (plAiVoxelNavigationComponent) to the moving object.

Property	Purpose
NavigationTarget	Optional target object. While idle, the component requests a path if it is not already close enough.
Speed, Acceleration, Deceleration	Movement and braking.
ReachedDistance	Arrival tolerance.
ApplySteering	Apply the computed transform to the owner.
DebugFlags	PrintState, VisPath, and VisGrid.

You can also call SetDestination(worldPosition) from gameplay code. CancelNavigation() stops the current navigation, and GetState() returns Idle, Moving, or Failed. With a target reference still assigned, an idle component may request another route; clear the reference when you want it to stay stopped.

GetSteeringPosition() and GetSteeringRotation() expose the computed transform when you apply movement yourself. The target reference is checked while idle; it is not a promise of continuous pursuit updates throughout a move.

Dynamic obstacles

AI Voxel Obstacle (plAiVoxelObstacleComponent) injects the owner's physics bounds into the grid and removes them on deactivation. Its CollisionLayer controls the bounds query.

Call UpdateObstacle() after moving or changing the obstacle. Unlike the navmesh obstacle component, it does not poll movement automatically. Keep obstacle updates and route requests coordinated in gameplay; changing grid occupancy is not a guarantee that an already-computed path is immediately replanned.

Diagnose a path

Enable AI.VoxelGrid.Visualize and the component's path/state flags during simulation. Check that the start and destination lie inside free cells and that there is enough open space between them.

A failed path may indicate an endpoint outside the grid, an occupied endpoint, or disconnected free space. Test with small simple geometry before increasing the resolution. This component applies steering transforms; it does not expose the navmesh component's crowd or character-controller movement modes.

See also

• AI Navigation Component
• Testing and Debugging