Skip to content

t1k:unity:dots-nav:agents-navigation

FieldValue
Moduledots-nav
Version3.30.4
Efforthigh
Tools—

Keywords: AI agents, DOTS, navigation, pathfinding

/t1k:unity:dots-nav:agents-navigation

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)


  • Adding Agent, AgentBody, AgentShape, AgentLocomotion components
  • Setting up NavMesh pathfinding (NavMeshPath, AgentNavMeshAuthoring)
  • Configuring avoidance: AgentSonarAvoid, AgentSeparation, AgentCollider, AgentReciprocalAvoid
  • Working with AgentSystemGroup and sub-groups
  • Setting up crowd navigation, flow-field pathfinding
  • Configuring CrowdSurface, CrowdGroup, CrowdObstacle
  • Using AgentCrowdPath for crowd-based steering
  • Working with CrowdFlow, CrowdWorld, potential fields
  • Implementing continuum crowds algorithm
  • Runtime crowd group assignment (CrowdGroupAssignmentSystem, TeamCrowdGroup)

PackageVersionContents
com.projectdawn.navigation4.4.4Base: Agent, AgentBody, AgentShape, AgentLocomotion, NavMesh pathing, avoidance, flocking
com.projectdawn.navigation.crowds1.2.0Extension: 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:

CheckEstablishesBlind to
grep using <Vendor>, asmdef references, package depsCore cannot name vendor typesAnything coupling through shared data
Enumerate shared components/singletons the vendor writes and core readsCore 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).


ModuleReferenceKey Types
Base Packagebase-guide.md (references/base-guide.md)Agent, AgentBody, AgentShape, AgentLocomotion, NavMeshPath, AgentSonarAvoid, AgentSeparation, FlockGroup
Crowds Corecrowds-guide.md (references/crowds-guide.md)CrowdSurface, CrowdGroup, CrowdFlow, CrowdObstacle, CrowdDiscomfort, AgentCrowdPath
Provider Seamprovider-seam-guide.md (references/provider-seam-guide.md)INavProvider, NavProviderRegistry, DirectSteeringNavProvider, NavAgentTag, NavAgentBody, NavPathEnabled, NavCrowdEnabled, ProjectDawnNavActiveTag

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)

  • Agent: Required tag component; holds NavigationLayers for spatial filtering
  • AgentBody: Runtime state — Destination, Velocity, Force, RemainingDistance, IsStopped; call SetDestination(float3) or Stop()
  • AgentLocomotion: Motion config — Speed, Acceleration, AngularSpeed, StoppingDistance; replaces deprecated AgentSteering
  • AgentShape: Radius, Height, ShapeType (Circle=2D/Z-up, Cylinder=3D/Y-up)
  • NavMeshPath: IEnableableComponent; check HasFullPath/HasPartialPath; NavMeshNode buffer 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 RaycastCommand grounding — replace with a DOTS-based grounding system using CollisionWorld.CastRay(). Classic raycasts can’t see SubScene-baked PhysicsCollider components
  • 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
  1. Create CrowdSurface: GameObject > AI > Crowd Surface
  2. Optionally bake: Create CrowdData asset, assign to surface, press Bake
  3. Create CrowdGroup: GameObject > AI > Crowd Group — assign surface reference
  4. Add AgentCrowdPathingAuthoring to agent prefabs — assign crowd group
  5. Add obstacles: GameObject > AI > Crowd Obstacle
LayerComponentRoleCost
Macro routingAgentCrowdPathFlow-field steering, density-awareO(grid²) shared
Steering-levelAgentSonarAvoidCone-based local avoidO(agents)
PhysicalAgentColliderSpatial-partitioned displacementO(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 units
  • AgentReciprocalAvoid: O(N²) — avoid at scale; use AgentCollider + SonarAvoid instead

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.

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 parallel
if (HandedOff(entity)) continue;
// RIGHT — explicitly stop the agent for the whole hand-off
if (HandedOff(entity)) { navBody.ValueRW.Stop(); continue; } // IsStopped=true, Velocity=0

Stop() 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.

-> See references/avoidance-ordering-guide.md for 3-layer avoidance pattern, navigation system ordering, and system ordering constraint gotchas.


  • 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