wave5-stateful-physics-event-buffers

Stateful Physics Event Buffers

Intent

Detect Enter, Stay, and Exit states for trigger and collision events using Unity Physics's built-in stateful event buffer systems, which maintain per-entity DynamicBuffer.

Use When

• Trigger zones (enter/exit): pickups, portals, damage volumes
• Collision events with Enter/Stay/Exit semantics: landing detection, impact response

Avoid When

• Only "something is overlapping this frame" is needed — use SimulationSingleton.ScheduleCallbacks directly (cheaper, stateless)
• Event count is very high (>10,000/frame) — the clear+collect+convert chain adds per-frame overhead

Setup Requirements

• Add StatefulTriggerEventBufferAuthoring component to entities needing trigger event tracking.
• Set PhysicsShapeAuthoring Collision Response = "Raise Trigger Events" on the trigger collider.
• Unity Physics includes StatefulTriggerEventBufferSystem and StatefulCollisionEventBufferSystem built-in.

Senior Pattern

[UpdateInGroup(typeof(FixedStepSimulationSystemGroup))]
[UpdateAfter(typeof(StatefulTriggerEventBufferSystem))]
[BurstCompile]
public partial struct TriggerZoneSystem : ISystem
{
    [BurstCompile]
    public void OnUpdate(ref SystemState state)
    {
        state.Dependency = new ProcessTriggerJob().ScheduleParallel(state.Dependency);
    }
}

[BurstCompile]
public partial struct ProcessTriggerJob : IJobEntity
{
    [BurstCompile]
    public void Execute(ref TriggerZoneState zone,
                        in DynamicBuffer<StatefulTriggerEvent> events)
    {
        for (int i = 0; i < events.Length; i++)
        {
            switch (events[i].State)
            {
                case StatefulEventState.Enter: zone.EnteredCount++; break;
                case StatefulEventState.Exit:  zone.EnteredCount--; break;
                // StatefulEventState.Stay: fires every frame overlap persists — handle if needed
            }
        }
    }
}

Event states:

• StatefulEventState.Enter — first frame of overlap
• StatefulEventState.Stay — overlap continues (fires every frame)
• StatefulEventState.Exit — first frame overlap ends