unity-dots-ecb-lifecycle-debugger

Unity DOTS ECB Lifecycle Debugger

When to load this skill:

• Runtime exception contains: EntityCommandBuffer playback failed, entityExists=False, AppendDestroyedEntityRecordError, Buffer does not exist on entity, Component does not exist on entity, Invalid deferred entity, Duplicate AddComponent during playback, SetComponent on missing component, DestroyEntity executed before another ECB command
• Question is about ordering of ECB commands across multiple systems targeting the same playback phase
• Entity is valid at record time but invalid at playback time

When NOT to load this skill:

• MonoBehaviour performance optimization
• ECS architecture design / component layout planning
• NavMesh, Addressables, UI events, Timeline, Animator
• Generic NullReferenceException without ECB stack trace
• Burst compilation errors (use burst-safety)
• NativeContainer leaks (use memory-safety)
• General ECS job implementation (use ecs-job-patterns)

NOT THIS SKILL — If ECB is being used correctly and you want guidance on patterns (when to use which singleton, how to schedule jobs with ECB, ParallelWriter usage), load ecs-job-patterns instead. This skill starts where ecs-job-patterns ends: at playback failure. It does not teach correct ECB usage — it diagnoses why playback threw an exception.

---

Core Mental Model

The fundamental ECB trap: an entity is valid at record time but invalid at playback time.

Frame N:
  ProducerSystem.OnUpdate():
    ecb.AppendToBuffer(TargetEntity, new TargetBufferElement{...})  // entity valid here ✓

  CleanupSystem.OnUpdate():
    ecb.DestroyEntity(TargetEntity)                                  // also valid here ✓

  // Both write to the SAME ECB singleton (same playback point)

Playback at BeginSimulationECBSystem:
  [1] ecb command from CleanupSystem executes first  → TargetEntity destroyed
  [2] ecb command from ProducerSystem executes next  → entityExists=False ✗

The guard if (entityManager.Exists(entity)) before recording is always wrong — the entity exists at record time. The problem is what happens between record and playback.