NavWorld2D
Vaelis 1.0.0 NavWorld2D component reference: fields, script API, behavior and examples.
#What it does
Shared navigation world for baked or dynamic 2D pathfinding, with 16 navigation areas.
#How to add and use NavWorld2D
Editor path: Select the target entity in the Hierarchy (left side) → look at the Inspector (right side) → click Add Component at the bottom of the Inspector → search for NavWorld2D → click the component row. The Add Component picker is a centered modal with a search box; it only lists components not already attached.
For components with a dedicated editor tool, the tool is opened or activated from the location described below. Do not assume that adding the component alone activates its editor; some systems require a separate window, panel, or viewport tool.
#Component setup & editor tools
- Select/create an entity → Inspector → Add Component → Nav World 2D. Use the Navigation toolbar and Edit → Nav Areas… controls to define/bake the navigation world; then connect agents to it through the documented navigation workflow.
#What you should see after adding it
The component appears as its own section in the Inspector. Its serialized settings are listed in the Component data table below. If a field is conditional, it appears only when the relevant mode/type is selected. If a field is a runtime state field (for example grounded or resolved velocity), treat it as read-only diagnostic state unless the API reference explicitly documents it as writable.
#How to read the settings
For every setting below, the documentation distinguishes type, default, meaning, and tuning direction where behavior is known. When a value represents a direction, use the engine's coordinate convention documented in Coordinate system; do not substitute Unity/Godot conventions.
#Component data
| Field | Type | Purpose | Default |
|---|---|---|---|
boundsX | number | World-space bounds X. | -400 |
boundsY | number | World-space bounds Y. | -400 |
boundsWidth | number | Bounds width. | 800 |
boundsHeight | number | Bounds height. | 800 |
cellSize | number | Navigation cell size. | 32 |
cells | sparse map | Authored filled cells. | {} |
bakedCells | data|null | Derived baked representation. | null |
paintOverrides | sparse map | Explicit walkability overrides. | {} |
cellAreas | sparse map | Per-cell area assignment overrides. | {} |
areaCosts | 16-entry array|null | Traversal cost multipliers. | null |
allowDiagonal | boolean | Allow diagonal A* connections. | false |
dynamic | boolean | Rebuild from dynamic scene obstacles. | false |
minObstacleFootprint | number | Minimum obstacle footprint used for baking. | 0 |
#Tuning behavior
These are the practical direction-of-change rules for the most important controls on this component.
| Setting | What changing it does |
|---|---|
cellSize | Smaller cells give a finer grid and can represent narrower corridors, but increase navigation work/memory. |
allowDiagonal | Off means 4-neighbor movement; on adds diagonal connections. |
dynamic | When enabled, navigation can be rebuilt dynamically from current geometry; use only when runtime rebaking is actually needed. |
areaCosts | 1 means neutral cost; 3 makes an allowed area approximately three times as expensive to traverse. Cost is preference, not a hard exclusion. |
#Script API
| Member | Kind | Description |
|---|---|---|
nav.findPath() | Global | Find world-space path through a NavWorld2D. |
nav.isWalkable() | Global | Check a world-space point. |
nav.bake() | Global | Bake navigation data after authored changes. |
nav.areaIndex | Property | Current/selected navigation area index surface. |
nav.areaMask | Property | Navigation area mask. |
nav.areaCosts | Property | Navigation area costs. |
#Notes & behavior
- NavWorld2D is a scene component; there is no `this.navWorld` object. Scripts use the global `nav` module.