wave6-with-disabled-query-filter

WithDisabled Query Filter

Intent

Query only entities where a specific IEnableableComponent is present but currently disabled using .WithDisabled(), enabling systems to act specifically on inactive populations.

Use When

• Logic must act only on entities in the "inactive" state (balls not being carried, units not yet activated)
• Multi-phase state filtering where different systems handle active vs inactive populations separately

Avoid When

• Component may be absent entirely — WithDisabled requires component to be present; use WithNone only when component absence is the correct filter

Senior Pattern

// Query filter semantics for IEnableableComponent:
// WithAll<T>()     — present AND enabled
// WithDisabled<T>()— present AND disabled
// WithNone<T>()    — absent entirely (structural)
// WithPresent<T>() — present regardless of bit (enabled OR disabled)
// IgnoreComponentEnabledState — all entities regardless of bit

// Foreach — find available (not-carried) balls:
foreach (var (transform, entity) in
    SystemAPI.Query<RefRO<LocalTransform>>()
             .WithAll<Ball>()
             .WithDisabled<Carry>()
             .WithEntityAccess())
{
    // ball is present and NOT being carried — can be picked up
}

// IJobEntity form:
[WithAll(typeof(Ball))]
[WithDisabled(typeof(Carry))]
[BurstCompile]
public partial struct FindAvailableBallsJob : IJobEntity
{
    [BurstCompile]
    public void Execute(Entity entity, in LocalTransform transform)
    {
        // process available balls
    }
}

// IJobChunk form — SetChangedVersionFilter equivalent:
query = state.GetEntityQuery(
    ComponentType.ReadOnly<Ball>(),
    ComponentType.Disabled<Carry>());   // Disabled<T> is the ComponentType variant

Anti-Patterns

• Using WithNone instead of WithDisabled — WithNone excludes entities with the component entirely (both enabled and disabled); completely wrong semantics for "present but inactive".
• Using WithAll and expecting to see disabled entities — WithAll on an IEnableableComponent filters to enabled-only.
• Using IgnoreComponentEnabledState when only the disabled population is needed — processes all entities; less efficient than WithDisabled.