dots-enableable-components

Enableable Components — Senior Patterns

IEnableableComponent lets you toggle a component on/off without a structural change. No archetype move, no chunk shuffle, no ECB playback. For state that flips often, this is the difference between a 0.05ms system and a 5ms system.

Intent

Model boolean state that changes faster than once per second as an enabled/disabled bit on a present component, not as add/remove of a tag.

Decision rule (memorize this)

Cost model: structural change costs archetype move (potentially copying every component on the entity to a different chunk). Enableable toggle costs one bit flip in the chunk's enabled-mask. At any scale above "occasional" the bit wins by orders of magnitude.

Senior pattern

// Component: just an empty struct or one with payload, marked IEnableableComponent.
public struct Spin : IComponentData, IEnableableComponent
{
    public float RadiansPerSecond;
}

public partial struct SpinSystem : ISystem
{
    [BurstCompile]
    public void OnUpdate(ref SystemState state)
    {
        var dt = SystemAPI.Time.DeltaTime;

        // Default query semantics: only entities whose Spin is ENABLED match.
        foreach (var (transform, spin) in
                 SystemAPI.Query<RefRW<LocalTransform>, RefRO<Spin>>())
        {
            transform.ValueRW = transform.ValueRO.RotateY(
                spin.ValueRO.RadiansPerSecond * dt);
        }
    }
}

// Toggling the bit from a job: use EnabledRefRW<T>, not AddComponent/RemoveComponent.
[BurstCompile]
partial struct TogglerJob : IJobEntity
{
    void Execute(EnabledRefRW<Spin> spinEnabled, in HealthComponent hp)
    {
        spinEnabled.ValueRW = hp.Current > 0;
    }
}