Skip to content

Game.EndFrameBarrier

Assembly: Game
Namespace: Game

Type: class

Base: Unity.Entities.SystemBase

Summary:
EndFrameBarrier is a managed Unity Entities system used to produce EntityCommandBuffers that are played back at the end of the frame. It integrates with the DOTS job system via a producer JobHandle so other systems can add dependencies. Game systems use EndFrameBarrier to safely record structural changes (CreateEntity, Add/Set/RemoveComponent, etc.) during update and have them executed after all jobs/updates for the frame have completed. It is commonly acquired with World.GetOrCreateSystemManaged() and used by UI and game logic (for example PoliciesUISystem) to enqueue modifications without applying them immediately.

Fields

  • private System.Diagnostics.Stopwatch m_Stopwatch
    Used internally by the barrier implementation to measure/track execution time for playback and debugging/profiling purposes. Systems may initialize or reference it in OnCreate to monitor performance.

  • private Unity.Jobs.JobHandle <producerHandle>k__BackingField
    Backing field that stores the JobHandle produced when scheduling command buffer playback or recording work. This is used to propagate job dependencies to other systems that must wait on the barrier's work.

Properties

  • public Unity.Jobs.JobHandle producerHandle { get; private set }
    Exposes the current producer JobHandle for the barrier. Other systems can use this handle to add dependencies (e.g., combine with their own jobs) so command buffer recording/playback occurs in the correct order with respect to scheduled jobs.

Constructors

  • public EndFrameBarrier()
    Default constructor. The system is typically created via World.GetOrCreateSystemManaged() rather than being constructed directly by user code.

Methods

  • protected virtual OnCreate() : System.Void
    Called when the system is created. Typical initialization performed here includes retrieving/initializing profiling tools like the stopwatch and setting up any internal state required for creating/playing back command buffers.

  • public Unity.Entities.EntityCommandBuffer CreateCommandBuffer()
    Creates and returns an EntityCommandBuffer that records entity structural changes. Commands recorded into the returned buffer are scheduled to be played back by the barrier at the end of the frame. (Usage shown in example below.)

Notes: - The returned EntityCommandBuffer is safe to use during the frame's update phase; however the structural changes it records are not applied immediately. They are applied when the barrier plays back the buffer (end of frame). - Respect the producerHandle if you are scheduling jobs that read/write the same data — combine JobHandles to ensure correct ordering.

Usage Example

// Acquire the barrier in OnCreate of your system
protected override void OnCreate()
{
    base.OnCreate();
    m_EndFrameBarrier = World.GetOrCreateSystemManaged<EndFrameBarrier>();
}

// Later, when you need to enqueue structural changes:
public void ModifyPolicy(Entity target, Entity policy, bool active, float adjustment)
{
    // Create a command buffer that will be executed at the end of the frame
    EntityCommandBuffer ecb = m_EndFrameBarrier.CreateCommandBuffer();

    // Create an event entity and set a Modify component (archetype assumed created elsewhere)
    Entity e = ecb.CreateEntity(m_PolicyEventArchetype);
    ecb.SetComponent(e, new Modify(target, policy, active, adjustment));

    // Do not call ecb.Playback here — the EndFrameBarrier will play it back at the end of the frame.
}

Additional notes: - Use EndFrameBarrier when you need to safely record structural changes during system updates without causing immediate structural modifications that could invalidate iteration or running jobs. - If you schedule jobs that write to entity data that the command buffer will modify, make sure to chain JobHandles correctly with producerHandle to avoid race conditions.