Skip to content

Game.EndFrameBarrier

Assembly: Assembly-CSharp (Game)
Namespace: Game

Type: class EndFrameBarrier

Base: Unity.Entities.EntityCommandBufferSystem

Summary:
EndFrameBarrier is a frame-end EntityCommandBuffer system used to collect entity command operations from jobs and apply them at the end of the frame. Modders use it to safely record structural changes (create/destroy entities, add/remove components, set buffers, etc.) from parallel jobs by creating an EntityCommandBuffer (or a ParallelWriter) via CreateCommandBuffer(), scheduling jobs that use it, and then registering those job handles with the barrier via AddJobHandleForProducer so the system can ensure the commands are played back only after producers complete. It also tracks timing/profiling information to help with simulation/job scheduling and may expose a producerHandle to integrate with other job dependencies.

Fields

  • private System.Diagnostics.Stopwatch m_Stopwatch
    Used internally for profiling/timing of barrier work (measuring durations across frames or operations). This can help the system determine performance characteristics of end-of-frame command playback.

  • private Unity.Jobs.JobHandle <producerHandle>k__BackingField
    Backing field for the producerHandle property. Tracks combined JobHandle(s) from producer jobs that recorded commands into the barrier's buffers so playback waits for those jobs to complete.

Properties

  • public Unity.Jobs.JobHandle producerHandle { get; private set }
    Exposes the JobHandle that represents work scheduled by producers (jobs that write to the command buffer). Users can read it to chain dependencies; the barrier updates this handle when AddJobHandleForProducer is called. The setter is private — producer handles should be added through the provided API (e.g., AddJobHandleForProducer).

Constructors

  • public EndFrameBarrier()
    Constructs the system and performs any internal initialization. In practice you obtain an instance via World.GetOrCreateSystemManaged() rather than constructing manually.

Methods

  • protected virtual OnCreate() : System.Void
    Called when the system is created. Initializes internal state (for example, creating internal command buffers or stopwatch) and registers the system with the world. Subclasses or game systems that rely on the barrier expect it to be ready after OnCreate.

  • public Unity.Entities.EntityCommandBuffer CreateCommandBuffer() (typical usage)
    Creates an EntityCommandBuffer that will be played back by the barrier at the end of the frame. For parallel jobs use CreateCommandBuffer().AsParallelWriter().

  • public void AddJobHandleForProducer(Unity.Jobs.JobHandle handle) (typical usage)
    Registers a JobHandle from a job that produced commands for this barrier. The barrier will combine these handles so playback waits until all producers finish.

  • public void AddJobHandleForProducer(Unity.Jobs.JobHandle handle, int producerIndex) (overloads may exist)
    Some implementations accept additional parameters to track parallel producer writers; check the available overloads in your version of the API.

  • public void AddJobHandleForConsumer(Unity.Jobs.JobHandle handle) / public Unity.Jobs.JobHandle Complete() (implementation details vary)
    Utility methods to combine consumer dependencies or force completion can exist — consult the concrete API in your assembly.

Usage Example

[Preserve]
protected override void OnCreate()
{
    base.OnCreate();
    m_Stopwatch = new Stopwatch();
}

Additional typical usage pattern (showing how TransportCarAISystem uses EndFrameBarrier):

// Acquire the barrier system
m_EndFrameBarrier = World.GetOrCreateSystemManaged<EndFrameBarrier>();

// In OnUpdate:
// - create command buffer (parallel writer when scheduling parallel job)
var ecb = m_EndFrameBarrier.CreateCommandBuffer().AsParallelWriter();

// - schedule a job that records into ecb
JobHandle jobHandle = JobChunkExtensions.ScheduleParallel(myJobWithEcb, myQuery, Dependency);

// - inform the barrier about the producer job so playback waits for it
m_EndFrameBarrier.AddJobHandleForProducer(jobHandle);

// - assign Dependency if needed (so subsequent systems wait)
Dependency = jobHandle;

Notes for modders: - Always register the JobHandle of jobs that write into a barrier's command buffer using AddJobHandleForProducer. Failing to register will cause playback to run while producers are still running and can lead to race conditions and data corruption. - When creating parallel writers (AsParallelWriter), make sure your scheduled job uses the correct producer index pattern required by the command buffer writer (e.g., use the job index for parallel writing if required). - EndFrameBarrier is commonly used in simulation systems to collect structural changes safely and defer them until after physics/pathfinding or other simulation jobs complete for the frame. TransportCarAISystem demonstrates this pattern by creating a parallel EntityCommandBuffer, scheduling a vehicle tick job that records entity commands, and then calling m_EndFrameBarrier.AddJobHandleForProducer(jobHandle).