t1k:unity:dots-nav:agents-navigation

Field	Value
Module	`dots-nav`
Version	`2.1.7`
Effort	`high`
Tools	—

Keywords: AI agents, DOTS, navigation, pathfinding

How to invoke

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

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: dots-ecs (IComponentData, ISystem, Baker) · dots-jobs-burst (Jobs, Burst, NativeContainers) Related skills: dots-rpg (RPG gameplay) · dots-physics (physics queries)

When This Skill Triggers

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)

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

Module Quick Reference

Module	Reference	Key Types
Base Package	base-guide.md	Agent, AgentBody, AgentShape, AgentLocomotion, NavMeshPath, AgentSonarAvoid, AgentSeparation, FlockGroup
Crowds Core	crowds-guide.md	CrowdSurface, CrowdGroup, CrowdFlow, CrowdObstacle, CrowdDiscomfort, AgentCrowdPath

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

Base Package

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

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

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 AgentCrowdPathingAuthoring to agent prefabs — assign crowd group
Add obstacles: GameObject > AI > Crowd Obstacle

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 units
AgentReciprocalAvoid: O(N²) — avoid at scale; use AgentCollider + SonarAvoid instead

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

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.

Documentation

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

rules/library-feature-discovery-protocol.md — research the library 3× before implementing new functionality; always update this skill with what you find (or with the new code if you implement it)
rules/manual-correction-implies-skill-gap-unity.md — if you manually inject library/API knowledge into a teammate brief, that knowledge belongs in this skill, not the brief