Skip to content

t1k:unity:dots-nav:battlefield

FieldValue
Moduledots-nav
Version3.30.4
Efforthigh
Tools—

Keywords: battlefield, DOTS, strategy

/t1k:unity:dots-nav:battlefield

DOTS 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 + namespace DOTSCore.Battlefield (ArenaConfig, ImpostorBakeConfig, BattlefieldConstants, VertexColorTerrain.shader)
  • Editor tooling — com.the1studio.dots-battlefield, asmdef DOTSBattlefield.Editor (all MenuItems). Zero Runtime files.

Does NOT handle: agent AI logic, combat, spawning, behavior trees.

⚠️ Runtime moved out of dots-battlefield at v5.0.0. A consumer asmdef still referencing DOTSBattlefield.Runtime no longer resolves — the transitional stub asmdef is gone. Swap it for DOTSCore.Battlefield and change using DOTSBattlefield; → using DOTSCore.Battlefield;. .asset files migrate themselves ([MovedFrom(autoUpdateAPI: true, …)]). Menu paths, the DOTSBattlefield/Arena Config create-menu, and the DOTSBattlefield/VertexColorTerrain shader name are unchanged on purpose — they are strings, and renaming them breaks existing scenes, materials, and t1k unity menu calls. Full migration table: references/package-api.md.

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 Terrain
  1. Create config: Assets > Create > DOTSBattlefield > Arena Config
  2. Set OutputFolder on config (e.g. Demos/MyGame -> assets go to Assets/Demos/MyGame/...)
  3. Create prefabs: Execute Tools/DOTSBattlefield/Create Prefabs
  4. Choose approach:
    • Tile-based: Tools/DOTSBattlefield/Assemble Arena
    • Procedural mesh: Tools/DOTSBattlefield/Generate Procedural Terrain
  5. Verify navigation: Agents get DOTSGrounding (DOTS Physics raycasts) via NavigationAuthoring.EnableGrounding
  • No hardcoded values: All tunable params live on ArenaConfig; implementation details use private const
  • Config lookup: All tools use ConfigLookup.FindConfig() — finds first t:ArenaConfig in project
  • OutputFolder: All generated assets (materials, meshes, prefabs) go under Assets/{OutputFolder}/
  • Spawn zones: SpawnCenterA/SpawnCenterB with SpawnClearRadius — obstacles excluded, terrain flattened
  • NavMesh: Auto-baked with CollectObjects.Volume + PhysicsColliders — volume auto-sized to arena bounds
  • Single NavMeshSurface: Generator removes stale NavMeshSurface from old “Ground” GO to prevent conflicts
  • Pre-made assets: Assign FBX/glTF to PreMadeObstaclePrefabs[] array on config
  • Seed-based: Obstacle placement is deterministic via Seed field
  • Idempotent: Tools skip existing prefabs/materials; assembly destroys old root first

-> See references/terrain-guide.md for terrain tuning fields and VertexColorTerrain shader details.

When ElevationVariance > 0, agents need terrain-aware navigation:

ComponentPurposeSource
NavMeshPathPathfinding on baked NavMeshNavigationAuthoring.EnableNavMeshPathing
DOTSGroundingY-snap via DOTS Physics raycastsNavigationAuthoring.EnableGrounding

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: DOTSGroundingSystem in AgentDisplacementSystemGroup — applies gravity, casts DOTS Physics ray downward, snaps Y to hit.Position.y + halfHeight
  • Baking: NavigationAuthoring.EnableGrounding = true bakes DOTSGrounding (NOT AgentGrounding)
  • asmdef: DOTSNavigation references Unity.Physics

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.

  • CollectObjects.Children excludes root GO’s mesh — use Volume mode

  • Multiple NavMeshSurface in 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 use NavMeshObstacle with carving = true instead

  • HealthBarRenderer missing from scene (CRITICAL): HealthBarAuthoring only bakes ECS data — actual rendering requires HealthBarRenderer MonoBehaviour on the Camera + DOTSCore/HealthBar shader 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. Adding com.the1studio.dots-battlefield alone gets you MenuItems that cannot compile against the config type; a runtime consumer needs DOTSCore.Battlefield (which lives in dots-core) and nothing else. DOTSCore.Battlefield’s asmdef has an empty references array, 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, and Shader.Find("DOTSBattlefield/VertexColorTerrain") all still say DOTSBattlefield after the namespace move, and that is deliberate. Renaming a menu path breaks t1k unity menu calls; renaming the shader path breaks every material already bound to it.

  • TreePrefabs empty ⇒ tree placement silently skipped, and TreeImpostorAssets pairs to it by array index — reorder one without the other and trees get the wrong impostor, with no validation error.

  • DOTSGroundingSystem must be [BurstCompile] with IJobEntity — raycasts every frame for all agents
  • CollisionFilter on DOTSGrounding should target terrain layer only — reduces broadphase search
  • NavMesh baking: Use CollectObjects.Volume (not Children) — 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.

  • 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