t1k:unity:dots-nav:agents-navigation
| Field | Value |
|---|---|
| Module | dots-nav |
| Version | 3.30.4 |
| Effort | high |
| Tools | — |
Keywords: AI agents, DOTS, navigation, pathfinding
How to invoke
Section titled “How to invoke”/t1k:unity:dots-nav:agents-navigationAgents Navigation Reference
Section titled “Agents Navigation Reference”Skill Purpose
Section titled “Skill Purpose”Reference for Agents Navigation v4.4.4 + Crowds Extension v1.2.0 — a high-performance DOTS navigation system using continuum crowds for flow-field pathfinding, obstacle avoidance, and crowd steering.
Prerequisites:
t1k-unity-dots-core-ecs(IComponentData, ISystem, Baker) ·t1k-unity-dots-core-jobs-burst(Jobs, Burst, NativeContainers) Related skills:t1k-unity-dots-combat-rpg(RPG gameplay) ·t1k-unity-dots-combat-physics(physics queries)
When This Skill Triggers
Section titled “When This Skill Triggers”- Adding
Agent,AgentBody,AgentShape,AgentLocomotioncomponents - Setting up NavMesh pathfinding (
NavMeshPath,AgentNavMeshAuthoring) - Configuring avoidance:
AgentSonarAvoid,AgentSeparation,AgentCollider,AgentReciprocalAvoid - Working with
AgentSystemGroupand sub-groups - Setting up crowd navigation, flow-field pathfinding
- Configuring
CrowdSurface,CrowdGroup,CrowdObstacle - Using
AgentCrowdPathfor crowd-based steering - Working with
CrowdFlow,CrowdWorld, potential fields - Implementing continuum crowds algorithm
- Runtime crowd group assignment (
CrowdGroupAssignmentSystem,TeamCrowdGroup)
Package Structure
Section titled “Package Structure”| Package | Version | Contents |
|---|---|---|
| com.projectdawn.navigation | 4.4.4 | Base: Agent, AgentBody, AgentShape, AgentLocomotion, NavMesh pathing, avoidance, flocking |
| com.projectdawn.navigation.crowds | 1.2.0 | Extension: Continuum crowds, flow fields, surfaces, obstacles |
⛔ A seam is not finished when the assembly reference is gone
Section titled “⛔ A seam is not finished when the assembly reference is gone”A core package can be provably free of this vendor at compile level — 0 using ProjectDawn, 0
asmdef references, no package dependency — and still be coupled to it at runtime. Observed in
dots-core: a shared fieldless boolean (ExternalNavProviderActiveTag) let the ProjectDawn provider
switch on dots-core’s own flow-field systems, which survived the decoupling untouched. The
consequence in four BattleDemo variants was ProjectDawn’s AgentLocomotionSystem and dots-core’s
FlowFieldMoveJob both writing the same LocalTransform every frame.
The part worth internalising is what the audit missed. A decoupling audit that greps using
directives and asmdef references would score this seam fully conformant and miss the defect
entirely. Compile-level absence of a vendor is necessary, never sufficient — it establishes that core
cannot name vendor types, which is a different claim from core not being driven by the vendor.
A seam audit therefore has two halves, and the second is the one that gets skipped:
| Check | Establishes | Blind to |
|---|---|---|
grep using <Vendor>, asmdef references, package deps | Core cannot name vendor types | Anything coupling through shared data |
| Enumerate shared components/singletons the vendor writes and core reads | Core cannot be switched on by the vendor | — |
Concretely: for every tag, singleton, or shared component a vendor bridge writes and a core system reads, ask “can this turn a core system on?” If yes, the packages are still coupled at runtime no matter how clean the assembly graph looks.
A fieldless tag is the worst offender, because it can say that a provider is active but never which — so every consumer gating on it is switched on together, including consumers the vendor never intended to drive. Gate each consumer on a signal that carries provider identity, or that the consumer itself owns.
This is the same shape as the general verification rule: a check that reads the input side
(assembly graph) cannot see a fault introduced downstream of where it reads (runtime component
state). Evidence: audit-260813-navprovider-blind.md (D2), library commit d8038228. See also
skills/t1k-library-decoupling/references/third-party-decoupling.md (theonekit-core).
Module Quick Reference
Section titled “Module Quick Reference”| Module | Reference | Key Types |
|---|---|---|
| Base Package | base-guide.md (references/base-guide.md) | Agent, AgentBody, AgentShape, AgentLocomotion, NavMeshPath, AgentSonarAvoid, AgentSeparation, FlockGroup |
| Crowds Core | crowds-guide.md (references/crowds-guide.md) | CrowdSurface, CrowdGroup, CrowdFlow, CrowdObstacle, CrowdDiscomfort, AgentCrowdPath |
| Provider Seam | provider-seam-guide.md (references/provider-seam-guide.md) | INavProvider, NavProviderRegistry, DirectSteeringNavProvider, NavAgentTag, NavAgentBody, NavPathEnabled, NavCrowdEnabled, ProjectDawnNavActiveTag |
System Execution Order
Section titled “System Execution Order”All crowd systems run inside SimulationSystemGroup:
CrowdSurfaceSystem (creates/destroys runtime worlds) → CrowdWorldSystem (splats obstacles, discomfort, density) → CrowdGoalSystem (updates goals from agent destinations) → CrowdFlowSystem (computes speed/cost/potential fields) [EXPENSIVE] → CrowdSteeringSystem (samples velocity, applies steering) → CrowdDisplacementSystem (maps agents to surface, ground constraint)Key Concepts
Section titled “Key Concepts”Base Package
Section titled “Base Package”- Agent: Required tag component; holds
NavigationLayersfor spatial filtering - AgentBody: Runtime state —
Destination,Velocity,Force,RemainingDistance,IsStopped; callSetDestination(float3)orStop() - AgentLocomotion: Motion config —
Speed,Acceleration,AngularSpeed,StoppingDistance; replaces deprecatedAgentSteering - AgentShape:
Radius,Height,ShapeType(Circle=2D/Z-up, Cylinder=3D/Y-up) - NavMeshPath:
IEnableableComponent; checkHasFullPath/HasPartialPath;NavMeshNodebuffer holds polygon ids - AgentSonarAvoid: Cone-based local avoidance;
IEnableableComponent— toggle without removing - AgentSystemGroup: Runs in
FixedStepSimulationSystemGroup(before physics) by default - AgentGrounding (DEPRECATED when using DOTS Physics): Classic physics
RaycastCommandgrounding — replace with a DOTS-based grounding system usingCollisionWorld.CastRay(). Classic raycasts can’t see SubScene-bakedPhysicsCollidercomponents
Crowds Extension
Section titled “Crowds Extension”- CrowdSurface: Grid-based walkable area. Width×height cells determine resolution vs performance
- CrowdGroup: Agents sharing same destination + speed. Minimize groups for performance
- CrowdFlow: 3 fields per group — Cost, Speed, Potential (lower potential = attraction)
- AgentCrowdPath: ISharedComponentData linking agent to crowd group entity
- CrowdObstacle: Marks unwalkable cells (Quad/Circle shape)
- CrowdDiscomfort: Soft avoidance zones agents prefer to avoid
- CostWeights: Balance Distance, Time, Discomfort in pathfinding cost
Setup Quick Start
Section titled “Setup Quick Start”- Create CrowdSurface:
GameObject > AI > Crowd Surface - Optionally bake: Create CrowdData asset, assign to surface, press Bake
- Create CrowdGroup:
GameObject > AI > Crowd Group— assign surface reference - Add
AgentCrowdPathingAuthoringto agent prefabs — assign crowd group - Add obstacles:
GameObject > AI > Crowd Obstacle
3-Layer Avoidance Pattern (2K+ units)
Section titled “3-Layer Avoidance Pattern (2K+ units)”| Layer | Component | Role | Cost |
|---|---|---|---|
| Macro routing | AgentCrowdPath | Flow-field steering, density-aware | O(grid²) shared |
| Steering-level | AgentSonarAvoid | Cone-based local avoid | O(agents) |
| Physical | AgentCollider | Spatial-partitioned displacement | O(log N) |
Scale rules:
AgentSonarAvoid.Radius: use 1.0f for 2K+ units (default 2.0f causes ~4× overlap with dense crowds)AgentCollider:IEnableableComponent, spatial-partitioned — NOT O(N²); safe to enable for all unitsAgentReciprocalAvoid: O(N²) — avoid at scale; use AgentCollider + SonarAvoid instead
CrowdGroupAssignmentSystem Pattern
Section titled “CrowdGroupAssignmentSystem Pattern”Prefabs can’t reference SubScene CrowdGroup GameObjects at bake time. Use runtime assignment:
// On CrowdGroup entity (SubScene):public struct TeamCrowdGroup : IComponentData { public byte TeamId; }
// CrowdGroupAssignmentSystem (SimulationSystemGroup, runs after spawn):// 1. Build NativeHashMap<byte, Entity>: TeamId → CrowdGroup entity// 2. For each agent with AgentCrowdPath.Group == Entity.Null:// em.SetSharedComponent(agent, new AgentCrowdPath { Group = groupMap[teamId] })Gotcha: AgentCrowdPath.Group = Entity.Null until this system runs — agents default to no crowd steering.
Gotcha: AgentCrowdPath is ISharedComponentData — setting it is a structural change; batch via ECB or direct EntityManager calls outside jobs.
Performance Rules
Section titled “Performance Rules”Agents Navigation runs in FixedStepSimulationSystemGroup — minimize CrowdGroups (O(cells²) each), use static obstacles, batch destination changes, one CrowdSurface per arena. Disable AgentSonarAvoid for distant agents. Never use RaycastCommand for grounding — use CollisionWorld.CastRay().
→ See references/performance-guide.md for full rules, anti-patterns table (8 entries), common patterns, and DOTS Physics grounding code example.
Defect class — two writers on one LocalTransform, only one of them stopped
Section titled “Defect class — two writers on one LocalTransform, only one of them stopped”Before adding any system that writes LocalTransform (or any shared component), ask: what else
writes it in the same frame, and what gates each writer? This failure is silent by construction —
no conflict, no error, no log, often no symptom beyond “that thing doesn’t move right”. A writer
that skips an update (if (state) continue;) rather than clearing/stopping it leaves stale
state that keeps steering in parallel with a second, legitimate writer — both individually correct,
the bug exists only in their overlap:
// WRONG — the stale NavigationTarget keeps steering LocalTransform in parallelif (HandedOff(entity)) continue;
// RIGHT — explicitly stop the agent for the whole hand-offif (HandedOff(entity)) { navBody.ValueRW.Stop(); continue; } // IsStopped=true, Velocity=0Stop() must be re-asserted every frame of the hand-off, not once at the start. Diagnostic tell:
a frozen NON-ZERO Velocity means a writer is ACTIVE and being cancelled by a second one — enumerate
every system writing that agent’s LocalTransform before investigating either in isolation. Sample
TRAJECTORIES, not two-point endpoints — an endpoint sample can’t distinguish “moved throughout” from
“moved then froze”.
Two independent real instances (TinyTerraces carry-stall, BattleDemo fieldless-tag ambiguity), the two
structural smells that predict this defect class, and the full diagnostic narrative:
references/two-writers-postmortem.md.
Documentation
Section titled “Documentation”-> See references/avoidance-ordering-guide.md for 3-layer avoidance pattern, navigation system ordering, and system ordering constraint gotchas.
Related rules
Section titled “Related rules”docs/library-feature-discovery-protocol.md— run the corpus-first reuse search before implementing new functionality; always update this skill with what you find (or with the new code if you implement it)rules/kit-wide-fix-discipline.md— if you manually inject library/API knowledge into a teammate brief, that knowledge belongs in this skill, not the brief