Entity command buffer playback

If you split the recording of commands in an entity command buffer (ECB) across multiple threads in a parallel job it means that the order of the commands is non-deterministic because they depend on job scheduling.

Determinism isn't always essential, but code which produces deterministic results is easier to debug. There are also networking scenarios which require consistent results across different machines. However, determinism can have an impact on performance, so you might want to accept non-determinism in some projects.

Deterministic playback in parallel jobs

You can't avoid the non-deterministic order of recording in parallel jobs, but you can make the playback order of the commands deterministic in the following way:

  1. Record an int sort key passed as the first argument to each ECB method.
  2. Use the sort keys to sort the commands on playback, before Unity performs the commands.

If the recorded sort keys are independent from the scheduling, then the sorting makes the playback order deterministic. Also, Unity always plays back commands with larger sort keys after commands with smaller sort keys.

In a parallel job, the sort key you need for each entity is a number that has a fixed and unique association with that chunk in the job's query. You can use the ChunkIndexInQuery value in a parallel job as an index. The index has a zero-based numbering system, so in the list of archetype chunks that match the job's query, the first chunk has index 0, the second chunk has index 1, and the third chunk has index 2.

The following example code shows an ECB used in a parallel job:


[RequireMatchingQueriesForUpdate]
partial struct MultiThreadedSchedule_ECB : ISystem
{
    partial struct ParallelRecordingJob : IJobEntity
    {
        internal EntityCommandBuffer.ParallelWriter ecbParallel;

        // The ChunkIndexInQuery is unique for each chunk in the query and will be
        // consistent regardless of scheduling. This will result in deterministic
        // playback of the ECB.
        void Execute(Entity e, [ChunkIndexInQuery] int sortKey, in FooComp foo)
        {
            if (foo.Value > 0)
            {
                // The first arg is the 'sort key' recorded with the command.
                ecbParallel.AddComponent<BarComp>(sortKey, e);
            }
        }
    }

    public void OnUpdate(ref SystemState state)
    {
        EntityCommandBuffer ecb = new EntityCommandBuffer(Allocator.TempJob);

        // We need to write to the ECB concurrently across threads.
        new ParallelRecordingJob { ecbParallel = ecb.AsParallelWriter() }.Schedule();

        // Playback is single-threaded as normal. Note that explicitly completing
        // adds a sync point, and is only done here for demonstration purposes.
        // (Having an existing EntityCommandBufferSystem do the playback would not
        // introduce an extra sync point.)
        state.Dependency.Complete();

        // To ensure deterministic playback order,
        // the commands are first sorted by their sort keys.
        ecb.Playback(state.EntityManager);

        ecb.Dispose();
    }
}

Multi playback

If you call the Playback method more than once, it throws an exception. To avoid this, create an EntityCommandBuffer instance with the PlaybackPolicy.MultiPlayback option:


// ... in a system update

EntityCommandBuffer ecb =
    new EntityCommandBuffer(Allocator.TempJob, PlaybackPolicy.MultiPlayback);

// ... record commands

ecb.Playback(state.EntityManager);

// Additional playbacks are OK because this ECB is MultiPlayback.
ecb.Playback(state.EntityManager);

ecb.Dispose();

You can use multi-playback if you want to repeatedly spawn a set of entities. To do this, create and configure a set of new entities with an EntityCommandBuffer, and then repeat playback to respawn another matching set of entities.

Additional resources