Official DOTS Best Practices Guide 1.0 is here

The DOTS Best Practices guide has been updated to match the latest Entities 1.0 pre-release. The old versions of the guide have been removed from Learn to avoid confusion, so only the 2022.3 version is available.

Here's where to find the Guide:

https://learn.unity.com/course/dots-best-practices

The revised version of the guide covers a number of changes from previous versions, including:

• A new section about ISystem, and why we recommend it over SystemBase for new systems
• Updated code samples throughout, demonstrating usage of the newer API
• Freshly-recorded performance data comparing different methods for structural changes, with a pretty new graph and an overhaul to the advice about structural changes.
• Lots of minor tweaks and clarifications

I hope you find it useful. And, as always, feedback is welcome.

 

As far as I know, there are no versions of the guide that we've produced in any language other than English. I assume that the German translations are being auto-generated by Chrome itself. All of this content should definitely render properly as English and not rely on US English. I'll pass this on to the Learn team who are responsible for this kind of thing.

 

I've been asked to pass this on by a Project Manager on the Learn team. Let me know if it helps.

Here are the images they shared of where to set the preferences:

 

Okay, thanks. I've passed that on. But I guess it's also an interesting data point that I tried to reproduce this by copying your language settings (on Chrome, on a MacBook), clearing site data and visiting the site in incognito mode, and it's all in English for me. So I guess something else is at play here?

 

More from the Learn team:

For the record, I tried setting my language settings in Chrome to be the same as yours and opened the site in an incognito window and it rendered in English, which is what we'd expect. If Learn is trying to set a default by asking the browser its location and making assumptions based on that, that's unexpected and they'd need to investigate more.

 

Ah, yes. I had a conversation with the Learn team recently about how the listed version should be 2022.3 to coincide with the full DOTS 1.0 release, and about how the older versions should be taken off-line to avoid confusion (because the experimental and pre-release versions were all surprisingly different in their APIs and the recommended best practices, and I don't want anyone to end up on the wrong version of the guide and getting bad advice as a result).

Looks like some of those changes have been made, which has bumped the most recent update date to June 6th, but in reality the content hasn't changed since the version I announced back in March. I've edited the top post on this thread to better reflect the current versioning situation.

 

FYI, the Learn team removed all the old versions, so only the 2022.3 (i.e. DOTS 1.0) version is available now. I've edited the initial post in this thread again.

 

As with anything else in DOD/DOTS, the answer really depends on your data and how you access it. How many pizzas do you have at any one time? How many of them are in the process of cooking on any given frame? How does the PizzaOven system know which pizzas are in the process of being cooked and which ones are in other states (being delivered, eaten, prepared, etc.)? How many pizzas, on average become cooked every frame? What does "Removing the pizza" actually involve? Does it involve an additional structural change?

In a VERY general sense, unless you feel that the benefit of the structural change outweighs the cost (i.e. if you have many systems/jobs that will perform significantly better if they can use a query to include/exclude pizzas that are currently in an oven), I think an enableable component seems likely to be a good approach here. In fact in any general scenario where I don't know enough about the specific data or access patterns involved in a problem but I'm asked my gut feeling on whether introducing structural changes are a good idea or a bad idea, my default answer is that they're probably a bad idea. But the devil is in the details.

If, for some reason, enableable components seem likely to cause you some specific problem (see "When IEnableableComponent is not the answer"), you should refer to "Build NativeArray<Entity> in a chunk-friendly way". Your job that advances the cooked state (or a job that follows it checking to see what's finished cooking) could be an IJobChunk that generates a NativeArray<Entity> with the entities to be tagged in the order they appear in their chunks, for the EntityCommandBuffer to execute as efficiently as possible.

 

It sounds like you're describing a state machine for the pizzas. A pizza (presumably) can't simultaneously be "baking" and "burnt" at the same time, it will progress from one state to the next at certain transition points. So instead of multiple enableable components, it probably makes sense to have a single component called something like PizzaState.

The next question is what to do with that PizzaState component. Our internal tests show that except in unusual edge-cases, the fastest way to process multiple entities with state machines represented in this way is just a single job with a switch statement inside it:

Code (CSharp):

1. switch(pizzaState)
2. {
3.    case PizzaState.Baking:
4.      // Do baking logic
5.      break;
6.  
7.    case PizzaState.Baked:
8.      // Do baked logic
9.      break;
10.  
11.    case PizzaState.Burnt:
12.      // Do burnt logic
13.      break;
14. }

You said that you need different jobs for the different states, but didn't really explain why. It's probably worth examining that requirement, because if they really do have to be different jobs you'd want to implement them as IJobChunk and have your system launch a job for each state with an EntityQuery matching all of the pizzas, and then have each job check each pizza to see if it's the required state for processing. This might be fine, but launching multiple jobs over the same set of entities seems kind of redundant in terms of job scheduling overhead and managing dependencies to guarantee job safety. To mitigate that, you would ideally combine states into as few jobs as possible, so perhaps you absolutely need BurntPizzaJob to be its own thing, but perhaps you can combine BakingOrBakedPizzaJob into one job that can process both states, and only launch 2 jobs rather than 3.

As you point out, Burst vectorization failing due to branches is a potential issue in all of the approaches that avoid structural changes. Whether it's actually a problem will depend quite a lot on the nature of the work done in the jobs, whether it's heavy number-crunching or just incrementing timers, etc... In situations where the profiler tells you that the lack of vectorization is hurting performance, perhaps it would be possible to refactor the jobs such that the logic happens inside a branchless job that applies to all of the pizzas regardless of what state they're in. Whether or not the savings from removing branches and enabling vectorization (and/or explicitly making use of SIMD intrinsics) outweigh the redundant work that will be performed for pizzas in states that don't need the data will be very specific to your use-case, and something that really only a profiler can tell you.

Finding a good solution to these sorts of problems is always going to be a fundamentally profiler-driven process. You make a best guess at a first approach, profile, and refine if the performance is not what you were hoping. That's why the Key Principles say you should embrace iteration. If I were building the first attempt at this, I'd probably use a PizzaState, and the smallest number of jobs required to process all of the states - ideally just one job, with the switch statement. I wouldn't worry too much about vectorization to begin with, unless the profiler showed that the initial approach needed improvement.

 

I've been discussing this with colleagues and one of them had an interesting thought about this scenario:

With a million pizza ovens on the go at once, it's not unreasonable to imagine that on any given frame, there could be an entire chunk (or more than one chunk, or close enough to a whole chunk that we can tolerate bit of wasted memory) of pizzas being put into ovens at the same time. If the baking process is deterministic then those entire chunks will change state at the same time, and that assumption can lead to a number of interesting optimizations.

 

I'm not quite sure what the new question is. Are you asking whether "ExplodeTrigger" should be:

• A component that gets added to an Entity to indicate that it should explode this frame, or
  
• An enableable component whose presence means than an Entity can explode, but which is disabled until it's time for the explosion to actually happen?

If that's the question, I'd say go with the second option. You avoid the problem of introducing many new archetypes, you avoid the performance cost of the structural changes from adding the ExplodeTrigger component at runtime, and all it costs you is 16 bytes of memory per chunk and a small performance hit in your "MakeStuffExplode" System, or whatever you call it.

What I'm saying is: Yes, do this. Make the flag you check be the whether or not the component is enabled. In cases where there's nothing about to explode in a chunk, the job will skip over the whole chunk in a single check. In the (I guess pretty rare) cases where everything in a chunk should explode, that's maximally efficient as well. In other cases, as the guide says:

A system/query being (at worst) 2x slower because it uses enableable components compared to one that doesn't is a drop in the ocean compared to the cost of the structural changes you'd likely need to make in order to avoid that cost. If it turns out your MakeStuffExplode system is actually a performance bottleneck, the code can always be refactored: perhaps instead of enabling components you just populate some NativeArray<Entity> with the entities to be exploded in a given frame and have MakeStuffExplode iterate over that instead of running queries - although it's conceivable that the cache misses you'd introduce with that approach might make things worse.

Honestly, life's too short to fret over every system unless the profiler tells you that you need to. Software development is always about compromises, and it's simply not possible to make every single system in a non-trivial ECS project all operate at maximum efficiency. So you design for the common case, focus on the hot code paths, and do whatever's going to move your project forward now, even if you have to revisit and optimize your solution later. DOD is about building something that's comparatively easy to optimize compared to OOP, but it's not about agonizing over every decision trying to get everything maximally optimal first time, because that's basically impossible.

 

Warning: This is a pretty speculative response. Please take it with a pinch of salt, and correct me if you know I'm wrong.

I'm not super familiar with the archetype memory handling, but certainly in older versions of Entities, every time a new archetype was encountered at runtime it would have to register itself in a data structure of all known EntityQueries in order to quickly identify which archetypes (and therefore which chunks) matched a particular query, so every archetype would occupy some memory for the rest of the runtime duration even if it was only ever used once.

I don't know whether or not that's still the case with Entities 1.0, but if it is, perhaps those messages are warning about the high water mark rather than the number of archetypes that are actually present at any given moment?