wave6-enabled-ref-rw-in-job

EnabledRefRW in Jobs — Inline Bit Toggle

Intent

Read and write the enabled bit of an IEnableableComponent directly inside IJobEntity.Execute() or SystemAPI.Query foreach using EnabledRefRW, avoiding ECB overhead and one-frame delay.

Use When

• Enable/disable decision depends on component data computed inside a job (proximity culling, LOD activation, range-based behavior)
• Bulk enable/disable in one pass without ECB one-frame delay
• Toggle must happen in same frame without deferred playback cost

Avoid When

• Enable/disable targets a different entity than the one being iterated — use ECB.SetComponentEnabled
• Only reading enabled state (not writing) — use EnabledRefRO

Senior Pattern

// Main-thread foreach — toggle ALL entities (enabled AND disabled):
foreach (var (posRO, flagEnabled) in
    SystemAPI.Query<RefRO<LocalTransform>, EnabledRefRW<ActiveBehavior>>()
             .WithOptions(EntityQueryOptions.IgnoreComponentEnabledState))
{
    flagEnabled.ValueRW = math.distancesq(posRO.ValueRO.Position, origin) <= radiusSq;
}

// IJobEntity (parallel) — same IgnoreComponentEnabledState requirement:
[BurstCompile]
[WithOptions(EntityQueryOptions.IgnoreComponentEnabledState)]
public partial struct ToggleInRangeJob : IJobEntity
{
    public float3 Origin;
    public float RadiusSq;

    [BurstCompile]
    public void Execute(in LocalTransform t, EnabledRefRW<ActiveBehavior> enabled)
    {
        enabled.ValueRW = math.distancesq(t.Position, Origin) <= RadiusSq;
    }
}

// Schedule:
state.Dependency = new ToggleInRangeJob
{
    Origin = origin,
    RadiusSq = radius * radius
}.ScheduleParallel(state.Dependency);

Anti-Patterns

• Using EnabledRefRW without IgnoreComponentEnabledState when intending to process all entities — default query only returns enabled entities; disabled are silently skipped, enabling them is impossible.
• Writing enabledRef.ValueRW from two parallel workers on the same entity — IJobEntity is safe (each chunk dispatched once); manual parallel splits are not.
• Using ECB.SetComponentEnabled when EnabledRefRW is available in the same job — ECB adds one-frame delay and playback cost unnecessarily.