t1k:unity:dots-core:performance
| Field | Value |
|---|---|
| Module | dots-core |
| Version | 3.56.1 |
| Effort | medium |
| Tools | — |
Keywords: DOTS, optimization, performance, profiling
How to invoke
Section titled “How to invoke”/t1k:unity:dots-core:performanceDOTS Performance Optimization
Section titled “DOTS Performance Optimization”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).
Rule #1 — Measure First
Section titled “Rule #1 — Measure First”Never optimize without data. Profile → identify → fix → verify.
t1k unity play enter # dots commands are live-World bound; play exit when done1. 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 utilization4. identify the ONE worst bottleneck5. fix it, re-profile, confirm improvementPost-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 first2. read the file → summary, top 30 systems by CPU, HIGH/MEDIUM issuesSession 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.
Reference Guides
Section titled “Reference Guides”| Topic | File | Coverage |
|---|---|---|
t1k unity profiling workflow | profiling-workflow-guide.md (references/profiling-workflow-guide.md) | Live t1k unity steps, post-session analysis, verification checklist, mandatory reporting |
| Parallelization & queries | parallelization-guide.md (references/parallelization-guide.md) | Job decision tree, SystemAPI random access fix, query optimization, Burst tips |
| Navigation performance | navigation-perf-guide.md (references/navigation-perf-guide.md) | Nav scaling, dead agent cleanup, tier throttling, FixedStep, NavMesh gotchas |
| Memory & collections | memory-patterns-guide.md (references/memory-patterns-guide.md) | Anti-patterns, SharedStatic, SpatialHash, chunk utilization, InternalBufferCapacity |
Draw Call Reduction
Section titled “Draw Call Reduction”SRP Batcher (free, always-on for URP):
- Requires all objects share the same shader variant
- Anti-pattern:
MaterialPropertyBlockper-instance disables SRP Batcher
GPU Instancing via ECS:
RenderMeshArray+MaterialMeshInfoenable automatic instancing- Each unique (mesh, material, layer) = separate draw call bucket — minimize combinations
- Tag components that change render state (color, emission) must use
MaterialPropertyattribute
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%).
Key Anti-Patterns Summary
Section titled “Key Anti-Patterns Summary”| Anti-Pattern | Fix | Reference |
|---|---|---|
| Optimizing without profiling | Measure First (Rule #1) | This file |
SystemAPI.GetComponent in foreach | Cache ComponentLookup<T> in OnCreate | parallelization-guide.md (references/parallelization-guide.md) |
| Allocating NativeList per entity per frame | Hoist before foreach, Clear each iteration | memory-patterns-guide.md (references/memory-patterns-guide.md) |
| Dead agents processing through all nav systems | DeadAgentStopSystem disables NavMeshPath | navigation-perf-guide.md (references/navigation-perf-guide.md) |
| AIUpdateTierSystem counting allies for distance | Filter by team in distance checks | navigation-perf-guide.md (references/navigation-perf-guide.md) |
| Transparent materials on sprites | Use AlphaTest (cutout) instead | This file |
| Optimizing without saving a report | Always save to plans/reports/ | profiling-workflow-guide.md (references/profiling-workflow-guide.md) |
| O(n²) nested scan on a hot path | NativeHashSet/hash-lookup or grid-coordinate lookup | This file (H4) |
| Hot buffer spilling to heap | Cap [InternalBufferCapacity(N)] to the realistic max | This file (H4) |
| Guard-less system ticking on idle frames | [RequireMatchingQueriesForUpdate] (if it registers a query) | This file (H4) |
Dropping a scheduled JobHandle | state.Dependency = job.Schedule(state.Dependency) | This file (H4) |
H4 Hardening — Perf & Safety Patterns
Section titled “H4 Hardening — Perf & Safety Patterns”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; seet1k-unity-dots-core-ecsBest Practices #2.)- Hot buffer
InternalCapacitycaps so buffers stay inline in the chunk:DamageEvent4,HealEvent2,AggroEntry+PerceivedEntity8,ItemPassiveEffect4. - O(n²) →
NativeHashSet/hash-lookup —SynergyResolutionSystem.HasTrait(nested scan →NativeHashSet);PatternMatch(O(n²) cell scan → grid-coordinate lookup). - Cache
ComponentLookup<T>overSystemAPI.GetComponentin hot loops — resolve the handle once inOnCreate,.Update(ref state)perOnUpdate, index inside the loop. - Job-dependency discipline — assign the returned
JobHandletostate.Dependency; dropping it races the next system’s reads (nondeterministic corruption no test reliably catches). - NaN / overflow guards —
math.normalizesafefor possibly-zero vectors; guardmath.powagainstpow(0, neg)(→ +∞) andpow(neg, frac)(→ NaN). A single NaN inLocalTransform→ChunkWorldRenderBoundsNaN → entities silently vanish. EnabledRefRW<T>overWithNone<T>+SetComponentEnabled<T>to toggle an enableable inside a query — avoids the structural-change cost +BufferTypeHandleinvalidation that mid-iterationSetComponentEnabledincurs.