Archetype and query memory budgets
Each world stores the data that describes its archetypes and its entity queries in two separate areas of memory. Each area has a maximum size, called a budget:
- The archetype budget limits the memory for archetype data, such as the component types of each archetype.
- The query budget limits the memory for entity query data, such as the archetypes that each query matches.
Each world has its own archetype budget and query budget, and both are 16 MB by default. A budget is a maximum, not an allocation. Unity allocates the data in 64 KB blocks when the world needs it. A higher budget increases only the memory that Unity uses to keep track of the blocks, which is about 3 KB for each budget at the default size and about 400 KB at 2047 MB. The Entities Memory Profiler doesn't include this memory in the budget values that it displays.
The budgets don't include component data. Unity stores component data in chunks, and the Allocated and Unused columns of the Entities Memory Profiler module display chunk memory, not budget use.
When a world reaches the limit of one of its budgets, the world can't create more archetypes or queries, and in the Editor Unity throws an exception.
Conditions that cause a world to reach its archetype budget limit
A world keeps every archetype that it creates until the world is destroyed, including archetypes that entities don't have anymore. Every combination of components that an entity had during the lifetime of the world uses the archetype budget, not only the combinations that exist now.
When you add components to an entity or remove components from it, the entity's archetype changes to the archetype that matches its new set of components. If that archetype doesn't exist, the world creates it. As a result, the following patterns create archetypes that no entity has afterwards:
- Code that adds components to an entity one at a time creates an archetype for each intermediate set of components.
- Code that adds and removes tag components at runtime creates an archetype for each combination of tags.
Bakers add components to an entity one at a time, so the worlds that bake subscenes can reach the limit of their archetype budget even when the worlds at runtime don't. In this case, Unity throws the exception when it imports the subscene.
The number of archetypes that fit in a budget depends on the number of component types in each archetype, there's no fixed maximum number of archetypes.
To reduce the number of archetypes, refer to Reducing the number of archetypes.
Check how much of the budgets a world uses
In the Entities Memory Profiler module, each world row in the details pane displays the percentage of the archetype budget or the query budget that the world uses, whichever is higher. To display the use of both budgets, select the world row.
Archetypes that have no entities also use the archetype budget, but the module hides them by default. To list them, select the More menu (⋮) at the right of the search field, and then select Show Empty Archetypes.
Change the budgets
To change the archetype budget or the query budget:
- Go to Edit > Project Settings > Memory Settings.
- To change the budgets for the Editor, select the Editor tab. To change the budgets for builds on a platform, select the Players tab, and then select the platform.
- Expand Entities Allocators.
- Next to Archetype Allocator Budget or Query Allocator Budget, select the lock icon, and then enter the budget in MB. Valid range: 1 to 2047 MB.
The Entities Allocators section is available only in projects that use the Entities package.
Unity applies a new value from the Editor tab to the worlds that it creates after the next code reload. The Editor processes that import subscenes in the background read the value when they start, so to make sure that baking uses the new value, restart the Editor. Unity applies new values from the Players tab to the builds that you make after the change.
You can also set the budgets with the memorysetup-entities-archetype-allocator-budget and memorysetup-entities-query-allocator-budget command line arguments, in bytes.