Celestia 3D Navigation System Documentation

Version 1.0.0 · Unreal Engine 5.8 · Windows (Win64) · Code plugin with demo content

Celestia 3D Navigation System gives flying and swimming AI real 3D pathfinding in Unreal Engine. You keep the tools you already know: place a standard Nav Mesh Bounds Volume, put an AI Character in Flying or Swimming mode, and call the normal AI Move To. Walking characters keep using Unreal's regular navmesh.

No new actors or nodes required. The plugin registers its 3D navigation automatically.
Works with stock AI. AI Move To, Behavior Tree Move To and StateTree Move To use the 3D routes with the normal path follower.
Reacts to a changing level. Moving, spawned and removed objects are detected at runtime. Only the changed area is rebuilt, and AI elsewhere keep moving.
Press P to see it. The viewport shows navigable or blocked 3D space, plus live path overlays.

Quick start (5 minutes)

Enable Celestia 3D Navigation System in Edit > Plugins and restart the editor.
Place a Nav Mesh Bounds Volume (Quick Add > Volumes). Scale it so it covers the floor and all the air your AI should fly through. The volume should reach a little below the floor.
Press P in the viewport. You see the blocked space around your geometry, and a notification tells you when navigation is ready.
Add an AI Character (for example the included BP_CelestiaFlyingExample). In its Blueprint, on Event BeginPlay call Configure Pawn For 3D Navigation (Self), then AI Move To with a location or target actor.
Press Play. The character flies around obstacles to the goal, also above or below them.

Tip: open the demo map Celestia3DNavigationSystem Content > Demo > L_Celestia3DNavigation to see a ready example that flies over a wall.

Example: patrol between two points

A common setup is an AI that flies back and forth forever:

Place two Target Point actors, one on each side of the level.
In your flying Character Blueprint, add two variables PointA and PointB of type Actor, with Instance Editable checked. Pick the two target points in the Details panel.
Create two custom events, GoA and GoB.
Event BeginPlay → Configure Pawn For 3D Navigation → GoA.
GoA → AI MoveTo (Pawn: Self, Target Actor: PointA, Acceptance Radius: 80). On Success → GoB. On Fail → Delay 1 s → GoA.
GoB does the same with PointB and calls GoA on success.

The AI replans automatically when you add buildings, walls or moving doors while the game runs.

What is included

Runtime module (Celestia3DNavigationSystem): 3D navigation data, path search, live collision observation, local 3D avoidance, optional flight component, diagnostics.
Editor module (Celestia3DNavigationSystemEditor): P display, build notifications, Health Check panel, Gameplay Debugger category, automated tests.
Demo content: map L_Celestia3DNavigation and Blueprint BP_CelestiaFlyingExample.
Platform: Windows (Win64), Unreal Engine 5.8.

How it works

Your Nav Mesh Bounds Volume defines where 3D navigation exists. The plugin fills that space with an adaptive 3D grid: large cells in open air and smaller cells near geometry. Each cell is tested against real collision using the full body of the agent, so a path never leads somewhere the agent does not fit.

Flying characters use the air navigation data.
Swimming characters use the water navigation data (inside water volumes).
Walking characters keep using Unreal's normal Recast navmesh.

Navigation is built automatically when the level loads. Collision changes are observed with bounded work, and rebuild generation is sliced on the game thread across frames. Paths come back through Unreal's normal path following, so Move To success, failure and acceptance radius behave exactly as you expect.

Setting up AI characters

Flying characters

Use a Character with the standard CharacterMovement component, possessed by an AIController.
Put it in Flying mode. Either call Configure Pawn For 3D Navigation (it sets Flying by default), or set Default Land Movement Mode = Flying on the CharacterMovement.
Call AI Move To with a location or an actor.

You can switch a character between Walking and Flying at any time. With the default settings, an active move continues to the same goal in the new mode.

Swimming characters

Place a Physics Volume with Water Volume checked. Its brush must enclose the swimming area (convex shapes; several touching volumes are combined).
Make sure the Nav Mesh Bounds Volume also covers that water.
Put the character in Swimming mode and call AI Move To.

A water material or a water mesh alone does not define swimmable space. The plugin uses the water Physics Volume.

Blueprint node (category Celestia | 3D Navigation), authority only.

Pawn: the pawn to set up.
Set Character Flying Mode (default true): also switches a Character to Flying. Pass false to keep its current mode (for example Walking or Swimming).

It selects the matching 3D navigation for the pawn and applies 3D arrival tuning. For a normal Character with automatic mode routing it is optional, but it is the simplest way to start.

Behavior Trees, StateTree and EQS

Behavior Tree Move To and StateTree Move To work unchanged.
EQS: use the generator Celestia: Navigable Volume Grid to sample points in 3D around a context, or Celestia: Reachable Volume Grid to keep only points with a complete route. Score them with the normal Distance and Pathfinding tests.
Stock EQS Pathing Grid and Pathfinding Batch are ground-only (Recast) and stay that way.
Keep reachability-query sample counts and query frequency modest, and profile representative scenes on your target hardware. Reachability checks perform path searches; functional support does not provide a fixed frame-time or crowd-performance guarantee.

Runtime changes: moving objects, doors and spawning

The plugin watches blocking collision inside the navigation bounds while the game runs. You do not need to call anything when you:

spawn or destroy actors with collision,
move doors, platforms or elevators,
turn collision on or off.

What happens when something changes:

Once a collision change is detected, the affected navigation is invalidated and unavailable areas are blocked while replacement navigation is prepared. Source observation is budgeted, so detection is not guaranteed in the same frame as the change.
AI whose route does not touch the change keep moving without interruption.
AI whose route crosses the change fly around it if possible, or wait until that area is rebuilt.
The changed area is rebuilt in game-thread slices, then normal routing resumes when current navigation is ready. Detection and rebuild latency depend on the scene, queued work, Dirty Build Delay, Runtime Build Time Budget Ms and Max Build Queries Per Frame; there is no fixed frame-count guarantee.

If an obstacle appears right on top of an AI (for example a closing door), the AI moves out of it instead of getting stuck.

Special case: if you change the shape of a mesh, instance or brush without moving it (same bounds), call Notify Source Geometry Changed on the world's Celestia Navigation Source Observation Subsystem with the changed component.

Press P in the level viewport to show navigation. Use the Celestia Nav menu in the viewport toolbar to choose what you see:

Blocked space (default, pink): where the agent cannot be, including its body clearance.
Navigable space (green): where the agent's feet can be.
Bounds only: just the navigation volume outlines.

Blocked space can be drawn as cube outlines (default), filled cubes or lightweight boundary surfaces. While a path is active, its planned route and the agent's body are drawn as an overlay.

The editor shows a small notification while navigation is building and when it is ready.

Pink cells show collision plus body clearance, so they are a bit larger than your meshes. That is expected.

Health Check and debugging

Health Check panel

Open Celestia Nav > Health Check. Pick the world, optionally a pawn and a goal, and click Refresh. It explains in plain words what is missing or wrong, for example: no navigation bounds, build still running, pawn too large for the agent profile, start or goal outside navigation, goal not reachable, or a move waiting for a nearby navigation change.

Returns the same report in Blueprint: severity, a stable code and a message for each finding. It only observes; it never rebuilds or moves anything.

Gameplay Debugger

Enable the CelestiaNavigation category in Unreal's Gameplay Debugger settings to see the selected pawn's current request and health in game.

Common problems

Nothing is built: check that a Nav Mesh Bounds Volume exists and covers the area. Press P and wait for the "ready" notification. Use Health Check.
"NAVMESH NEEDS TO BE REBUILT": this message is about the ground (Recast) navmesh. Make the volume reach below the floor and use Build > Build Paths, then save.
The AI does not move: make sure it is possessed by an AIController and is in Flying or Swimming mode. Check the start position is inside the volume.
No route through a narrow gap: the gap may be smaller than the agent body or the cell size. See Cell Size and Agent size below.
The AI waits briefly near a door: the door changed the route. The AI continues as soon as the area is rebuilt or the door opens.
Pink cells look larger than meshes: they include body clearance.

Project settings

All settings are in Project Settings > Plugins > Celestia 3D Navigation. The defaults work for most projects.

Agent

Setting: Auto Register Agent — Default: on — Effect: creates the 3D navigation automatically from your Nav Mesh Bounds Volume.
Setting: Agent Radius; Agent Height — Default: Agent Radius: 42 cm; Agent Height: 192 cm — Effect: the default flying body size. Pawns larger than this are not routed through it.
Setting: Additional Agent Profiles — Default: empty — Effect: extra sizes or shapes (upright capsule, sphere, box) for air or water. Restart the editor after changing them.
Setting: Register Swimming Agent — Default: on — Effect: also creates water navigation for swimming characters.
Setting: Automatic Character Mode Routing — Default: on — Effect: Flying uses air navigation, Swimming uses water navigation, Walking uses the ground navmesh.
Setting: Continue Move On Navigation Mode Change — Default: on — Effect: when a character changes between walking, flying and swimming, its active move continues to the same goal.
Setting: Adapt Stock Crowd Controllers — Default: on — Effect: lets Detour crowd AI controllers fly and swim; ground crowd steering is restored on the ground.

Generation

Setting: Cell Size — Default: 100 cm — Effect: the smallest cell. Smaller cells fit through narrower gaps but use more memory.
Setting: Automatic Cell Size — Default: on — Effect: makes cells larger in big levels so they fit the budget below. Turn off for fixed precision.
Setting: Max Cells — Default: 262,144 — Effect: the memory budget for one navigation data.
Setting: Runtime Build Time Budget Ms; Max Build Queries Per Frame — Default: Runtime Build Time Budget Ms: 3 ms; Max Build Queries Per Frame: 2,048 — Effect: how much rebuild work runs per frame.
Setting: Dirty Build Delay — Default: 0.1 s — Effect: short wait before a rebuild starts, so many changes are combined.
Setting: Collision Channel — Default: Pawn — Effect: which collision blocks navigation.

Queries

Setting: Max Search Nodes — Default: 65,536 — Effect: path search limit. Very large or complex levels may need more.
Setting: Configure 3D Reach Tolerance; Vertical Reach Tolerance — Default: Configure 3D Reach Tolerance: on; Vertical Reach Tolerance: 10 cm — Effect: how close in height the AI must get to its goal.
Setting: Allow Native Custom Traversal — Default: on — Effect: allows smart nav links that have your own traversal logic.

Avoidance

Setting: Automatic 3D Avoidance — Default: on — Effect: flying and swimming AI steer around each other and around nearby walking characters.

Display

Setting: Debug Draw Mode — Default: Blocked space — Effect: what P shows by default.
Setting: Blocked Preview Style — Default: Cube outlines — Effect: cube outlines, filled cubes or boundary surfaces.
Setting: Max Preview Elements; Max Visible Voxels; Voxel Draw Distance — Default: Max Preview Elements: 20,000; Max Visible Voxels: 20,000; Voxel Draw Distance: 10,000 cm — Effect: limits for the P preview only. They never change routes.

Advanced features

Nav Modifier Volumes and nav areas work in 3D: area costs, entering costs and Null (blocked) areas are respected for the whole agent body.
Navigation Query Filters (costs, exclusions, include/exclude flags) work with Move To.
Nav Link Proxy simple links can connect separate navigation regions. A link is only used if the agent's full body fits along it.
Smart links work when your link has its own traversal logic (Allow Native Custom Traversal must be on).

Local 3D avoidance

With Automatic 3D Avoidance on, eligible flying and swimming Characters automatically get a small avoidance helper. It adjusts the movement direction only, so Move To success, collision and arrival stay Unreal's own. Add a Celestia Navigation Avoidance Component yourself to change its parameters, read Last Result, or call Get Last Avoidance Error. If you already use Unreal's RVO avoidance or bind Post Process Move yourself, the plugin leaves your setup alone.

Optional flight component for non-Character pawns

Celestia Flight Movement Component moves a generic Pawn (not a Character) along 3D routes. Do not add it to a Character.

Modes: Kinematic, Hover, Fixed Wing, Zero Gravity, Swimming and Bird.
Use exactly one navigation movement authority: remove competing Pawn movement components rather than leaving an ambiguous binding. Characters continue to use native CharacterMovement.
Use one enclosing root PrimitiveComponent (a shape or simple collision mesh proxy) that covers the whole moving body. It must be Movable, have query collision enabled and physics simulation disabled. Attached visual or overlap-only components may remain; blocking child collision is not swept and is rejected.
Before binding, choose a valid navigation reference vertically below the entire rotating collision envelope. Synchronize Navigation Reference defaults to false. Explicitly enable it to set the Pawn's BaseEyeHeight to the conservative collision radius, or supply a sufficient BaseEyeHeight/custom GetNavAgentLocation reference yourself. Custom overrides must honor the same vertical alignment and full-envelope clearance.
Disable movement plane constraints, plane snapping and render-only movement ticking.
Call Bind Flight Collision with the Pawn's explicitly selected root collision component. Branch on its Boolean return value: only issue AI Move To after a successful bind. If it returns false, read Get Last Flight Error, correct the reported setup and bind again. Flight Ready and Validate Flight Configuration help check readiness after configuration or body-scale changes.
Use Set Flight Mode, Set Desired Flight Rotation, Validate Flight Configuration and Get Last Flight Error as needed.
Turn off Use Controller Rotation Pitch, Yaw and Roll on the pawn.

These are game steering models, not aircraft or fluid simulations. Fixed Wing and Bird need room to turn, so very sharp routes can fail.

On the navigation data actor (CelestiaNavigationData-Celestia3D) you can call Bake Navigation to store the built navigation in the level, so it loads faster. The saved data is checked against the current collision when the level loads; if anything changed it is rebuilt automatically. Rebuild Navigation, Get Effective Cell Size, Get Free Cell Count, Last Build Summary and Get Last Build Error help with tuning.

Level streaming and World Partition

Only loaded, physically ready collision counts as known space. Areas with unloaded collision or coverage that cannot be established are treated conservatively as blocked. Keep an ordinary loaded Nav Mesh Bounds Volume covering the required air or water; it also supplies the finite vertical range for a 2D World Partition runtime hash.

Use an axis-aligned World Partition instance placement. Rotated or tilted partition/cell placements are rejected because their coverage is not certified by the current implementation.
Cook the map with Celestia enabled. Packaged World Partition navigation needs current per-cell physical collision certificates for ordinary spatial cells. Editor live preview needs actual collision inspection of every ordinary spatial cell; a loaded visual alone is not sufficient.
If the native cell identity, bounds, placement or collision metadata changes, recook the partition map. Stale or missing certificates are not trusted. Read Health Check and navigation errors for the affected cell or coverage issue.
Do not treat unknown coverage as open space. Routes remain blocked where current collision coverage cannot be established, including unloaded or not-yet-ready cells.

Multiplayer

Run AI possession and AI Move To on the server, as usual.
Characters keep Unreal's normal replicated movement. Clients do not run AI navigation.
Configure Pawn For 3D Navigation and Set Flight Mode are server (authority) only.
For the optional flight component, enable the pawn's Replicates and Replicate Movement. The component does not add client prediction.

C++

Public headers live in the Celestia3DNavigationSystem module. Useful entry points: UCelestiaNavigationLibrary, ACelestiaNavigationData, UCelestiaNavigationDiagnostics, UCelestiaNavigationSourceObservationSubsystem, UCelestiaNavigationAvoidanceComponent, UCelestiaFlightMovementComponent, and the manual flow-field API in CelestiaNavigationFlowField.h.

Limits and good to know

Windows (Win64) and Unreal Engine 5.8 only.
All distances are in centimetres. Navigation positions are the agent's feet.
Coarse cells (large levels with Automatic Cell Size) can close very narrow gaps. Lower Cell Size or raise Max Cells if you need them.
Avoidance is sampled local steering. It is not a global crowd solver and makes no promise for thousands of agents.
A Nav Mesh Bounds Volume is still needed for ground characters, which use Recast as usual.

Support

Questions, bug reports and feature requests: CelestiaDominance Discord · celestiadominance.com

Celestia 3D Navigation System Documentation