t1k:unity:dots-nav:battlefield
| Field | Value |
|---|---|
| Module | dots-nav |
| Version | 3.30.4 |
| Effort | high |
| Tools | — |
Keywords: battlefield, DOTS, strategy
How to invoke
Section titled “How to invoke”/t1k:unity:dots-nav:battlefieldDOTS Battlefield — Arena Geometry Package
Section titled “DOTS Battlefield — Arena Geometry Package”Render Pipeline: URP ONLY — All terrain shaders, materials, and visual effects must target URP. Never create Built-in RP or HDRP materials.
Related skills:
/t1k-unity-rendering-synty-polygon(Generic + Knights prefab catalogs),/t1k-unity-dots-nav-agents-navigation(NavMeshSurface, CrowdSurface),/t1k-unity-dots-combat-physics(PhysicsCollider, DOTS raycasts),/t1k-unity-rendering-terrain(TerrainData, heightmap).
Packages (two, since v5.0.0 — see below):
- Runtime —
com.the1studio.dots-core, asmdef + namespaceDOTSCore.Battlefield(ArenaConfig,ImpostorBakeConfig,BattlefieldConstants,VertexColorTerrain.shader) - Editor tooling —
com.the1studio.dots-battlefield, asmdefDOTSBattlefield.Editor(all MenuItems). Zero Runtime files.
Does NOT handle: agent AI logic, combat, spawning, behavior trees.
⚠️ Runtime moved out of
dots-battlefieldat v5.0.0. A consumer asmdef still referencingDOTSBattlefield.Runtimeno longer resolves — the transitional stub asmdef is gone. Swap it forDOTSCore.Battlefieldand changeusing DOTSBattlefield;→using DOTSCore.Battlefield;..assetfiles migrate themselves ([MovedFrom(autoUpdateAPI: true, …)]). Menu paths, theDOTSBattlefield/Arena Configcreate-menu, and theDOTSBattlefield/VertexColorTerrainshader name are unchanged on purpose — they are strings, and renaming them breaks existing scenes, materials, andt1k unity menucalls. Full migration table: references/package-api.md.
Architecture
Section titled “Architecture”ArenaConfig (ScriptableObject) — DOTSCore.Battlefield, in com.the1studio.dots-core ├── Grid: Width, Depth, TileSize ├── Obstacles: Density, Seed (= BattlefieldConstants.DefaultSeed), PreMadePrefabs[] ├── Spawn: CenterA, CenterB, ClearRadius ├── Elevation: Variance (0=flat, >0=hills) ├── Terrain Noise: NoiseScale, NoiseOctaves, Persistence, Lacunarity ├── Ridge/Cliff: RidgePower, CliffThreshold ├── Boundaries: WallHeight, WallThickness ├── Trees: Count, RingOffset, Jitter, ScaleRange, Prefabs[], ImpostorAssets[] (index-matched) └── OutputFolder → computed path helpers
Editor Tools (DOTSBattlefield.Editor, in com.the1studio.dots-battlefield — menu items invokable by AI via `t1k unity menu`): ├── Tools/DOTSBattlefield/Create Prefabs ├── Tools/DOTSBattlefield/Assemble Arena └── Tools/DOTSBattlefield/Generate Procedural TerrainAI Workflow — Creating a Battlefield
Section titled “AI Workflow — Creating a Battlefield”- Create config:
Assets > Create > DOTSBattlefield > Arena Config - Set OutputFolder on config (e.g.
Demos/MyGame-> assets go toAssets/Demos/MyGame/...) - Create prefabs: Execute
Tools/DOTSBattlefield/Create Prefabs - Choose approach:
- Tile-based:
Tools/DOTSBattlefield/Assemble Arena - Procedural mesh:
Tools/DOTSBattlefield/Generate Procedural Terrain
- Tile-based:
- Verify navigation: Agents get
DOTSGrounding(DOTS Physics raycasts) viaNavigationAuthoring.EnableGrounding
Key Rules
Section titled “Key Rules”- No hardcoded values: All tunable params live on
ArenaConfig; implementation details useprivate const - Config lookup: All tools use
ConfigLookup.FindConfig()— finds firstt:ArenaConfigin project - OutputFolder: All generated assets (materials, meshes, prefabs) go under
Assets/{OutputFolder}/ - Spawn zones:
SpawnCenterA/SpawnCenterBwithSpawnClearRadius— obstacles excluded, terrain flattened - NavMesh: Auto-baked with
CollectObjects.Volume+PhysicsColliders— volume auto-sized to arena bounds - Single NavMeshSurface: Generator removes stale
NavMeshSurfacefrom old “Ground” GO to prevent conflicts - Pre-made assets: Assign FBX/glTF to
PreMadeObstaclePrefabs[]array on config - Seed-based: Obstacle placement is deterministic via
Seedfield - Idempotent: Tools skip existing prefabs/materials; assembly destroys old root first
-> See references/terrain-guide.md for terrain tuning fields and VertexColorTerrain shader details.
Navigation Integration
Section titled “Navigation Integration”When ElevationVariance > 0, agents need terrain-aware navigation:
| Component | Purpose | Source |
|---|---|---|
NavMeshPath | Pathfinding on baked NavMesh | NavigationAuthoring.EnableNavMeshPathing |
DOTSGrounding | Y-snap via DOTS Physics raycasts | NavigationAuthoring.EnableGrounding |
DOTSGrounding (replaces AgentGrounding)
Section titled “DOTSGrounding (replaces AgentGrounding)”The original AgentGroundingSystem uses classic Unity RaycastCommand (MonoBehaviour physics). When terrain and obstacles live in a SubScene, their MeshCollider components get baked to DOTS PhysicsCollider — classic raycasts can’t see them. DOTSGroundingSystem uses CollisionWorld.CastRay() instead.
- Component:
DOTSGrounding(IComponentData + IEnableableComponent) —MaxRayDistance(default 50f) +CollisionFilter(default: collide with all) - System:
DOTSGroundingSysteminAgentDisplacementSystemGroup— applies gravity, casts DOTS Physics ray downward, snaps Y tohit.Position.y + halfHeight - Baking:
NavigationAuthoring.EnableGrounding = truebakesDOTSGrounding(NOTAgentGrounding) - asmdef:
DOTSNavigationreferencesUnity.Physics
Terrain-Aware Obstacle/Wall Y-Placement
Section titled “Terrain-Aware Obstacle/Wall Y-Placement”TerrainHeightSampler provides bilinear-interpolated height sampling from the procedural heightmap. Used by PlaceObstacles() and PlaceBoundaryWalls(). When called from ProceduralTerrainGenerator, the heightmap is generated first. When called from AssembleBattlefield (tile-based), heightmap is null and Y defaults to 0.
Hard rules
Section titled “Hard rules”-
CollectObjects.Childrenexcludes root GO’s mesh — useVolumemode -
Multiple
NavMeshSurfacein one scene causes erratic pathing — keep only one -
After code changes, rename
Library/EntityScenes/aside (Editor closed) to force SubScene rebake -
Obstacles placed at Y=0 clip through elevated terrain — always pass heightmap when
ElevationVariance > 0 -
NavMeshObstacle carving required (CRITICAL):
(StaticEditorFlags)8(NavigationStatic) +SetNavMeshArea(obs, 1)only marks the obstacle’s own surface as “Not Walkable”. Always useNavMeshObstaclewithcarving = trueinstead -
HealthBarRenderer missing from scene (CRITICAL):
HealthBarAuthoringonly bakes ECS data — actual rendering requiresHealthBarRendererMonoBehaviour on the Camera +DOTSCore/HealthBarshader material -
Obstacle/primitive pivot at center (CRITICAL): Unity primitives have pivot at center, not bottom. Use bounds-based offset after instantiation
-
The package that owns the tooling is NOT the package that owns
ArenaConfig. Addingcom.the1studio.dots-battlefieldalone gets you MenuItems that cannot compile against the config type; a runtime consumer needsDOTSCore.Battlefield(which lives indots-core) and nothing else.DOTSCore.Battlefield’s asmdef has an emptyreferencesarray, so taking it pulls in no extra ECS surface. -
Do not “finish the rename” on the string surfaces.
Tools/DOTSBattlefield/*,Assets > Create > DOTSBattlefield > Arena Config, andShader.Find("DOTSBattlefield/VertexColorTerrain")all still sayDOTSBattlefieldafter the namespace move, and that is deliberate. Renaming a menu path breakst1k unity menucalls; renaming the shader path breaks every material already bound to it. -
TreePrefabsempty ⇒ tree placement silently skipped, andTreeImpostorAssetspairs to it by array index — reorder one without the other and trees get the wrong impostor, with no validation error.
Runtime Performance Rules
Section titled “Runtime Performance Rules”- DOTSGroundingSystem must be
[BurstCompile]withIJobEntity— raycasts every frame for all agents - CollisionFilter on DOTSGrounding should target terrain layer only — reduces broadphase search
- NavMesh baking: Use
CollectObjects.Volume(notChildren) — volume is pre-bounded, faster bake - Static obstacles: Baked into SubScene as static physics bodies — zero runtime cost after bake
-> See t1k-unity-dots-core-performance skill for rendering optimization checklist and impostor LOD details.
References
Section titled “References”- package-api.md (
references/package-api.md) — Full API reference - ai-tool-guide.md (
references/ai-tool-guide.md) — Step-by-step for AI-driven arena creation + navigation integration - terrain-guide.md (
references/terrain-guide.md) — Terrain tuning fields and VertexColorTerrain shader