icleanupcomponentdata-runtime

ICleanupComponentData — Runtime Entity Lifecycle

Intent

React to entity destruction at runtime by attaching a cleanup component that survives DestroyEntity, allowing a system to detect destroyed entities, release associated resources, and finalise true removal.

Use When

An entity owns external resources (GPU buffers, physics bodies, audio instances, spatial index entries, registry slots) that must be explicitly released when the entity is destroyed. Any system that needs an "on-destroy" callback pattern.

Avoid When

The entity has no associated resources requiring cleanup — cleanup components add chunk overhead for entities that don't need them. Do not use in the baking world without [BakingType] (see [[baking-type-cleanup-component]] for baking lifecycle tracking).

Senior Pattern

• Declare public struct MyCleanup : ICleanupComponentData { /* resource handles */ }.
• A setup system adds MyCleanup to entities when they are created (or when the resource is acquired).
• DestroyEntity removes all non-cleanup components but keeps MyCleanup — the entity persists in a "tombstone" state.
• Cleanup system query: .WithAll<MyCleanup>().WithNone<MyMainComponent>() — matches only destroyed entities.
• Cleanup system: releases resource, then ecb.RemoveComponent<MyCleanup>(entity) — triggers true entity destruction.

Code Template

public struct AudioInstanceCleanup : ICleanupComponentData
{
    public int AudioHandle;
}

// Setup system — adds cleanup when audio entity is created
[BurstCompile]
public partial struct AudioSetupSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        var ecb = SystemAPI
            .GetSingleton<BeginSimulationEntityCommandBufferSystem.Singleton>()
            .CreateCommandBuffer(state.WorldUnmanaged);

        foreach (var (audio, entity) in
            SystemAPI.Query<RefRO<AudioSource>>()
                .WithNone<AudioInstanceCleanup>()
                .WithEntityAccess())
        {
            int handle = AcquireAudioHandle(audio.ValueRO.ClipId);
            ecb.AddComponent(entity, new AudioInstanceCleanup { AudioHandle = handle });
        }
    }
}

// Cleanup system — detects destroyed audio entities, releases resources
[BurstCompile]
public partial struct AudioCleanupSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        var ecb = SystemAPI
            .GetSingleton<BeginSimulationEntityCommandBufferSystem.Singleton>()
            .CreateCommandBuffer(state.WorldUnmanaged);

        // WithNone<AudioSource> = entity was destroyed (cleanup survived)
        foreach (var (cleanup, entity) in
            SystemAPI.Query<RefRO<AudioInstanceCleanup>>()
                .WithNone<AudioSource>()
                .WithEntityAccess())
        {
            ReleaseAudioHandle(cleanup.ValueRO.AudioHandle);
            ecb.RemoveComponent<AudioInstanceCleanup>(entity);  // triggers true destruction
        }
    }
}