enableable-component

Enableable Component

Intent

Toggle a component's active state without archetype migration, preserving component data while excluding the entity from standard queries until re-enabled.

Use When

Component state that toggles at moderate-to-high frequency (sleeping/awake, visible/invisible, stunned/active). More efficient than AddComponent/RemoveComponent for toggle patterns.

Avoid When

The state rarely changes (once at spawn or never) — structural change (add/remove) is more readable and has negligible cost at low frequency. Avoid when the disabled component's value should be reset on re-enable — enableable components preserve the last value.

Senior Pattern

• Component implements both IComponentData and IEnableableComponent.
• Query sees only enabled entities by default. To iterate all (enabled and disabled): .WithOptions(EntityQueryOptions.IgnoreComponentEnabledState).
• Read/write enable state via EnabledRefRW<T> or EnabledRefRO<T> in a query.
• From a job without ECB: set enabledRef.ValueRW = false directly (safe in IJobEntity).
• From a parallel job via ECB: ecb.SetComponentEnabled<T>(chunkIndex, entity, false) with sort key.

Code Template

public struct Sleeping : IComponentData, IEnableableComponent
{
    public float WakeTimer;
}

// Toggle from main thread:
foreach (var (sleeping, entity) in
    SystemAPI.Query<EnabledRefRW<Sleeping>>()
        .WithOptions(EntityQueryOptions.IgnoreComponentEnabledState)
        .WithEntityAccess())
{
    sleeping.ValueRW = ShouldBeAsleep(entity);
}

// Toggle from IJobEntity:
partial struct WakeJob : IJobEntity
{
    public float CurrentTime;
    void Execute(ref Sleeping sleeping, EnabledRefRW<Sleeping> sleepingEnabled)
    {
        if (CurrentTime >= sleeping.WakeTimer)
            sleepingEnabled.ValueRW = false;  // disable = entity is no longer sleeping
    }
}

Query Filter Semantics (IEnableableComponent)

• WithAll<T>() — present AND enabled
• WithDisabled<T>() — present AND disabled
• WithNone<T>() — absent entirely (structural; do NOT use to filter disabled entities)
• WithPresent<T>() — present regardless of enabled bit (enabled OR disabled)
• IgnoreComponentEnabledState — all entities regardless of bit