wave4-ijobchunk-full-anatomy

IJobChunk — Full Anatomy with Enableable Mask

Intent

Low-level parallel chunk iteration with explicit enableable-component mask handling, type handle management, and per-chunk metadata access.

Use When

• Per-chunk metadata needed: unfilteredChunkIndex, DidChange, SharedComponent values, ChunkHeader.
• Fine-grained enableable-component masking required.
• ECB.ParallelWriter sort key must be unfilteredChunkIndex for deterministic parallel playback.
• IJobEntity source generation is insufficient.

Avoid When

Standard entity iteration without per-chunk metadata — use IJobEntity (less boilerplate, identical performance).

Senior Pattern

[BurstCompile]
public struct MyChunkJob : IJobChunk
{
    public ComponentTypeHandle<Velocity> VelocityHandle;
    [ReadOnly] public ComponentTypeHandle<Speed> SpeedHandle;
    public EntityTypeHandle EntityHandle;
    public EntityCommandBuffer.ParallelWriter Ecb;
    public float DeltaTime;

    [BurstCompile]
    public void Execute(in ArchetypeChunk chunk, int unfilteredChunkIndex,
        bool useEnableMask, in v128 chunkEnabledMask)
    {
        var velocities = chunk.GetNativeArray(ref VelocityHandle);
        var speeds     = chunk.GetNativeArray(ref SpeedHandle);
        var entities   = chunk.GetNativeArray(EntityHandle);

        var enumerator = new ChunkEntityEnumerator(useEnableMask, chunkEnabledMask, chunk.Count);
        while (enumerator.NextEntityIndex(out var i))
        {
            velocities[i] = new Velocity { Value = velocities[i].Value + speeds[i].Value * DeltaTime };
            if (speeds[i].Value > 100f)
                Ecb.RemoveComponent<Speed>(unfilteredChunkIndex, entities[i]);
        }
    }
}

// In OnUpdate:
var job = new MyChunkJob
{
    VelocityHandle = state.GetComponentTypeHandle<Velocity>(),
    SpeedHandle    = state.GetComponentTypeHandle<Speed>(true),
    EntityHandle   = state.GetEntityTypeHandle(),
    Ecb            = ecbSystem.CreateCommandBuffer().AsParallelWriter(),
    DeltaTime      = SystemAPI.Time.DeltaTime
};
state.Dependency = job.ScheduleParallel(myQuery, state.Dependency);