dots-entity-lifecycle

Entity Lifecycle — Senior Patterns

Entities are not GameObjects. There is no OnDestroy callback to do cleanup. Destruction is structural, can invalidate active queries, and any other entity holding the Entity value still has it — it's a generation-tagged handle, not a managed reference. Two-phase teardown via ICleanupComponentData is the senior tool for "run cleanup before this entity actually disappears."

Intent

Make entity creation and destruction explicit, deferred, and survivable across the systems that read the same state.

The three lifecycle rules

1. Never make a structural change inside the query you're iterating. Use an ECB to record DestroyEntity / AddComponent / RemoveComponent, then let the ECB system play it back.
2. An Entity value outlives the entity. Validate with EntityManager.Exists(entity) (or SystemAPI.HasComponent<T>(entity)) before dereferencing.
3. Cleanup needs explicit components. ICleanupComponentData keeps the entity alive after DestroyEntity is called, until you remove the cleanup component.

Senior pattern — destroy via ECB during iteration

public partial struct FallAndDestroySystem : ISystem
{
    [BurstCompile]
    public void OnCreate(ref SystemState state) {
        state.RequireForUpdate<BeginSimulationEntityCommandBufferSystem.Singleton>();
    }

    [BurstCompile]
    public void OnUpdate(ref SystemState state)
    {
        var ecbSingleton = SystemAPI.GetSingleton<BeginSimulationEntityCommandBufferSystem.Singleton>();
        var ecb = ecbSingleton.CreateCommandBuffer(state.WorldUnmanaged);

        var dropPerFrame = new float3(0, -SystemAPI.Time.DeltaTime * 5f, 0);

        foreach (var (transform, entity) in
                 SystemAPI.Query<RefRW<LocalTransform>>().WithEntityAccess())
        {
            transform.ValueRW.Position += dropPerFrame;
            if (transform.ValueRO.Position.y < 0)
            {
                // Structural change during iteration would invalidate the query.
                // Record the intent; playback happens AFTER OnUpdate.
                ecb.DestroyEntity(entity);
            }
        }
    }
}