Not all gameplay needs to happen immediately. In fact, there are many cases in which deferring commands may offer a better outcome – improved user experience, performance, etc. These slides explore thinking about where deferred commands are needed and provides examples on how to take full advantage of the Entity Command Buffer. Speaker: Elora Krzanich – Unity Watch the session on YouTube: https://youtu.be/SecJibpoTYw

2. Using Entity Command
Buffers
Elora Krzanich
Software Engineer, DOTS

3. Overview
3
— What are Entity Command Buffers?
– Recording Commands
– Playback Order
— Command Playback
– EntityCommandBufferSystems
– Immediate vs Deferred
— Traps to Avoid
— Possible Future Improvements

4. Entity Command Buffers
4

5. Problem They Solve
5
— Structural changes happen on the Main Thread
— Solution for recording changes in parallel through Jobs

6. What are they?
6
— Chains of data transformations that are recorded
– Either from the Main Thread or within Jobs (Concurrent)
— Played back at a specific point in the future
– From an EntityCommandBufferSystem

7. Commands
7
— Some available commands
– Instantiate, Create, or Destroy an Entity
– Add, Set, or Remove Component Data
– Add or Set IBufferElementData to an Entity
– Add or Set SharedComponent Data
– Add or Remove Components to each Entity in an EntityQuery
— Main Thread vs Concurrent Commands
– Main Thread: Managed Data OK
– Concurrent: Subset with No Managed Data Allowed

8. Main Thread Chain
— Single chain
— Played back in order of recording
8

9. Concurrent Chains
— Multiple chains
— Playback in order by JobIndex
– JobIndex unique per batch of work
— Deterministic
– JobIndex becomes a way to sort
commands
– Large continuous chunks of
monotonically increasing numbers
9

10. Concurrent Chains Recording
10
— Multiple threads recording from Concurrent
EntityCommandBuffer to their own chain

11. 11

12. 12

13. 13

14. Concurrent Chains Playback (Today)
14
— Find the batch with the lowest job index
— Start executing commands linearly until the end of the batch
— Repeat looking for the next smallest until done

15. 15

16. 16

17. 17

18. Command Playback
18

19. Deferred vs Immediate Playback
19
— Deferred
– Scheduling Playback later in another EntityCommandBufferSystem
– Systems already there
– Example: BeginInitializationEntityCommandBufferSystem
— Immediate
– Calling myCommandBuffer.Playback(…) right after recording
– PostUpdateCommands: Right after System’s Update()

20. EntityCommandBufferSystem Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// Taken from SpawnFromEntity example
BeginInitializationEntityCommandBufferSystem m_EntityCommandBufferSystem;
protected override void OnCreate()
{
// 1: Set your command buffer system
m_EntityCommandBufferSystem = World.GetOrCreateSystem<BeginInitializationEntityCommandBufferSystem>();
}
protected override JobHandle OnUpdate(JobHandle inputDeps)
{
// 2: Pass a Concurrent Command Buffer into the job
var job = new SpawnJob
{
CommandBuffer = m_EntityCommandBufferSystem.CreateCommandBuffer().ToConcurrent()
}.Schedule(this, inputDeps);
// 3: Add the JobHandle to the Command Buffer System
m_EntityCommandBufferSystem.AddJobHandleForProducer(job);
return job;
}
20

21. 21

22. 22

23. 23

24. 24

25. 25

26. 26

27. 27

28. 28

29. 29

30. 30

31. Traps to Avoid
31

32. Knowing When Data Is Available
32
— Important to know when you will need that data to exist
— Tradeoff: Narrow window for playback vs longer deferment
– Systems running between recording and playback will see the “old”
data

33. Deferred Entities
33
— Instantiate(…) returns an Entity that’s deferred
– It does not exist yet
– Has a negative Entity ID
— During Playback
– Entity gets a positive ID once it’s created
– Future references to that Entity in the chain are fixed up

34. Storing a Reference to a Deferred
Entity ID
— When your ComponentData
stores a reference to some entity
that will be created later
— That Entity will be invalid!
34

35. Too Many Sync Points
35
— Sync points can prevent a lot of work to be done in parallel
— Playing back commands when you need that data
— Consolidate those points to specific times in the frame
– Use the pre-existing ECB Systems or create your own

36. ECB Invalid After Playback
36
— Once it’s played back, can’t record to it again
— Error regarding a Native Container
— Create a new ECB

37. Possible Future
Improvements
37

38. Bursted ECB
38
— Bursted Recording and Bursted Playback
— Recording Available Soon!

39. Bursted ECB Code Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// Taken from SpawnFromEntity example
[BurstCompile(CompileSynchronously = true)]
struct SpawnJob : IJobForEachWithEntity<Spawner_FromEntity, LocalToWorld>
{
public EntityCommandBuffer.Concurrent CommandBuffer;
public void Execute(Entity entity, int index, [ReadOnly] ref Spawner_FromEntity spawnerFromEntity,
[ReadOnly] ref LocalToWorld location)
{
for (var x = 0; x < spawnerFromEntity.CountX; x++) // CountX = 100
{
for (var y = 0; y < spawnerFromEntity.CountY; y++) // CountY = 100
{
var instance = CommandBuffer.Instantiate(index, spawnerFromEntity.Prefab);
// Place the instantiated in a grid with some noise
var position = math.transform(location.Value,
new float3(x * 1.3F, noise.cnoise(new float2(x, y) * 0.21F) * 2, y * 1.3F));
CommandBuffer.SetComponent(index, instance, new Translation {Value = position});
}
}
CommandBuffer.DestroyEntity(index, entity);
}
}
39

40. 40
36.2
Without Burst (in ms)
0.64
With Burst (in ms)*
*Average = 10x speedup
10kEntities

41. Batched Playback
41
— Processing certain commands in bulk for better performance
– Such as Instantiate or AddComponent
— All playback is still happening on the Main Thread

42. Entity Manager Feature Parity
42
— EntityManager has more options for each function
– Such as AddComponent ( NativeArray <Entity>, Component )
— Would like them to be unified

43. Review
43

44. What To Remember
44
— Chains of data transformations
— Played back at a specific point in the future
— Think about the point when you need that data
— No managed data within jobs, therefore no commands with
managed data within jobs

45. Thank you!
45