The behaviour of EntityCommandBuffer->DestroyEntity( EntityQueryCaptureMode )?

Unity Engine
, , , , ,
1

I am not understand clearly the function of EntityCommandBuffer → DestroyEntity(EntityQuery, EntityQueryCaptureMode )

The param EntityQueryCaptureMode has 2 options AtRecord and AtPlayback.
This is how I understand it:

  • AtRecord means: the EntityCommandBuffer will fetch the list of all entities matched the query, and then destroy them overtime in a worker thread, parallel with the main thread.
  • AtPlayback means: the EntityCommandBuffer will run on a worker thread, iterate through all entitities overtime; with any entity matched the query, the ECB will destroy it.

Am I understand its behaviour correctly?

3

EntityCommandBuffer playback is on the main thread, either with a manual call to Playback (on the main thread) or inside the update of an entity command buffer system (on the main thread). AtRecord captures the query results (list of entities) at the moment you call the method, while AtPlayback checks the query at the point where the ECB is played back. There’s a semantic difference, and you could want either one depending on what you want to do.
Note that AtRecord is deprecated in 1.3. You’ll need to manually get the entity array or list from the EntityQuery itself and pass that all to the ECB explicitly, rather than rely on AtRecord.

1 Like
4

Not entirely. About meaning of AtRecord (gather list of entities from query at a time you call EntityCommandBuffer.DestroyEntity) and AtPlayback (gather list of entities when EntityCommandBuffer.Playback called by you or by EntityCommandBuffer system) you mostly correct. But overall understanding of EntityCommandBuffer (next ECB) process is incorrect. It doesn’t do anything on worker threads by itself, when you create entity command buffer you get memory pool for commands (think about it like mailbox where you put your commands as mails) which you just fill. ECB playback happens on main thread and it is sync point and it can have structural changes.

1 Like
5

So, the ECB runs on the main thread, does it has significantly different from calling EntityManager → Destroy Entity( query ), except that the method from EntityManager execute immediately?

6

ECB allows for deferred execution, but beyond that it’s pretty much the same idea as performing write operations through EntityManager.

EntityManager might have a small amount of execution overhead if you attempt to call its methods a number of times vs. ECB playing back the same number of commands once, as the ECB should only need to have one sync point on the entry to the ECB playback while EntityManager calls would need a check per API call, but that’s just a guess. ECB obviously has overhead for recording commands instead of immediately executing writes anyway.

1 Like