Skip to content

t1k:unity:dots-core:performance

FieldValue
Moduledots-core
Version3.56.1
Effortmedium
Tools—

Keywords: DOTS, optimization, performance, profiling

/t1k:unity:dots-core:performance

Coding patterns: see /t1k-unity-dots-core-ecs (Performance Priority section). Job specifics: see /t1k-unity-dots-core-jobs-burst. Draw calls / batching: see /t1k-unity-dots-rendering-graphics (RenderMeshArray, SRP Batcher, GPU instancing).

Context7 sources: /needle-mirror/com.unity.entities (query optimization), /needle-mirror/com.unity.burst (Burst best practices), /websites/unity3d_packages_com_unity_collections_2_6 (collection perf).

Never optimize without data. Profile → identify → fix → verify.

t1k unity play enter # dots commands are live-World bound; play exit when done
1. t1k unity dots get_render_stats → rendered entities, batches (draw calls / FPS: t1k unity eval with UnityEditor.UnityStats)
2. t1k unity eval '<C# expr>' → mono heap, graphics driver memory (UnityEngine.Profiling.Profiler)
3. t1k unity dots performance_snapshot --limit 30 → per-DOTS-system CPU breakdown, chunk utilization
4. identify the ONE worst bottleneck
5. fix it, re-profile, confirm improvement

Post-Session Analysis (No Play Mode Required)

Section titled “Post-Session Analysis (No Play Mode Required)”

Session JSON files, if the project’s perf recorder saves them on Play exit → Logs/PerfSessions/perf-YYYYMMDD-HHmmss.json.

1. ls -t Logs/PerfSessions/perf-*.json → list saved session files, newest first
2. read the file → summary, top 30 systems by CPU, HIGH/MEDIUM issues

Session JSON contains: FPS avg/min/max/p95, CPU avg/min/max/p95, top 30 systems by CPU, 500-point timeline, scene name, duration, peak entity count.

Regression workflow: record baseline session → implement optimization → record again → read both files → compare top-system rankings.

→ See profiling-workflow-guide.md (references/profiling-workflow-guide.md) for step-by-step post-session workflow.

TopicFileCoverage
t1k unity profiling workflowprofiling-workflow-guide.md (references/profiling-workflow-guide.md)Live t1k unity steps, post-session analysis, verification checklist, mandatory reporting
Parallelization & queriesparallelization-guide.md (references/parallelization-guide.md)Job decision tree, SystemAPI random access fix, query optimization, Burst tips
Navigation performancenavigation-perf-guide.md (references/navigation-perf-guide.md)Nav scaling, dead agent cleanup, tier throttling, FixedStep, NavMesh gotchas
Memory & collectionsmemory-patterns-guide.md (references/memory-patterns-guide.md)Anti-patterns, SharedStatic, SpatialHash, chunk utilization, InternalBufferCapacity

SRP Batcher (free, always-on for URP):

  • Requires all objects share the same shader variant
  • Anti-pattern: MaterialPropertyBlock per-instance disables SRP Batcher

GPU Instancing via ECS:

  • RenderMeshArray + MaterialMeshInfo enable automatic instancing
  • Each unique (mesh, material, layer) = separate draw call bucket — minimize combinations
  • Tag components that change render state (color, emission) must use MaterialProperty attribute

Static batching for terrain/walls:

  • Walls use per-segment LODGroup with impostor billboard at LOD1 — no mesh combining needed
  • Do NOT combine meshes that need individual LODGroups or physics colliders

Transparent materials cause per-entity draw calls (CRITICAL): URP entities with _SURFACE_TYPE_TRANSPARENT get DepthSorted_Tag from Entities Graphics, forcing per-entity back-to-front rendering. This defeats SRP Batcher AND GPU instancing. Fix: Use AlphaTest (cutout) with _AlphaClip=1 + _Cutoff=0.5 instead of Transparent for sprites/quads. Only use Transparent for genuinely semi-transparent effects (particles, AoE blasts). In BattleDemo2D this reduced 608 to 28 batches (95.4%).

Anti-PatternFixReference
Optimizing without profilingMeasure First (Rule #1)This file
SystemAPI.GetComponent in foreachCache ComponentLookup<T> in OnCreateparallelization-guide.md (references/parallelization-guide.md)
Allocating NativeList per entity per frameHoist before foreach, Clear each iterationmemory-patterns-guide.md (references/memory-patterns-guide.md)
Dead agents processing through all nav systemsDeadAgentStopSystem disables NavMeshPathnavigation-perf-guide.md (references/navigation-perf-guide.md)
AIUpdateTierSystem counting allies for distanceFilter by team in distance checksnavigation-perf-guide.md (references/navigation-perf-guide.md)
Transparent materials on spritesUse AlphaTest (cutout) insteadThis file
Optimizing without saving a reportAlways save to plans/reports/profiling-workflow-guide.md (references/profiling-workflow-guide.md)
O(n²) nested scan on a hot pathNativeHashSet/hash-lookup or grid-coordinate lookupThis file (H4)
Hot buffer spilling to heapCap [InternalBufferCapacity(N)] to the realistic maxThis file (H4)
Guard-less system ticking on idle frames[RequireMatchingQueriesForUpdate] (if it registers a query)This file (H4)
Dropping a scheduled JobHandlestate.Dependency = job.Schedule(state.Dependency)This file (H4)

Patterns applied library-wide in the H4 hardening wave. Apply to any new hot-path ISystem (same list mirrored in t1k-unity-dots-core-ecs § “H4 Hardening”):

  • [RequireMatchingQueriesForUpdate] blanket on guard-less systems that register ≥1 query and can be empty/idle — skips idle-frame ticks. (Never on a system that only delegates to a static query-building helper — that deadlocks; see t1k-unity-dots-core-ecs Best Practices #2.)
  • Hot buffer InternalCapacity caps so buffers stay inline in the chunk: DamageEvent 4, HealEvent 2, AggroEntry + PerceivedEntity 8, ItemPassiveEffect 4.
  • O(n²) → NativeHashSet/hash-lookup — SynergyResolutionSystem.HasTrait (nested scan → NativeHashSet); PatternMatch (O(n²) cell scan → grid-coordinate lookup).
  • Cache ComponentLookup<T> over SystemAPI.GetComponent in hot loops — resolve the handle once in OnCreate, .Update(ref state) per OnUpdate, index inside the loop.
  • Job-dependency discipline — assign the returned JobHandle to state.Dependency; dropping it races the next system’s reads (nondeterministic corruption no test reliably catches).
  • NaN / overflow guards — math.normalizesafe for possibly-zero vectors; guard math.pow against pow(0, neg) (→ +∞) and pow(neg, frac) (→ NaN). A single NaN in LocalTransform → ChunkWorldRenderBounds NaN → entities silently vanish.
  • EnabledRefRW<T> over WithNone<T> + SetComponentEnabled<T> to toggle an enableable inside a query — avoids the structural-change cost + BufferTypeHandle invalidation that mid-iteration SetComponentEnabled incurs.