Class EntityManager
The EntityManager manages entities and components in a World.
Namespace: Unity.Entities
Syntax
public sealed class EntityManager
Remarks
The EntityManager provides an API to create, read, update, and destroy entities.
A World has one EntityManager, which manages all the entities for that World.
Many EntityManager operations result in structural changes that change the layout of entities in memory. Before it can perform such operations, the EntityManager must wait for all running Jobs to complete, an event called a sync point. A sync point both blocks the main thread and prevents the application from taking advantage of all available cores as the running Jobs wind down.
Although you cannot prevent sync points entirely, you should avoid them as much as possible. To this end, the ECS framework provides the EntityCommandBuffer, which allows you to queue structural changes so that they all occur at one time in the frame.
Properties
Debug
An object providing debugging information and operations.
Declaration
public EntityManager.EntityManagerDebug Debug { get; }
Property Value
Type | Description |
---|---|
EntityManager.EntityManagerDebug |
EntityCapacity
The capacity of the internal entities array.
Declaration
public int EntityCapacity { get; }
Property Value
Type | Description |
---|---|
Int32 | The number of entities the array can hold before it must be resized. |
Remarks
The entities array automatically resizes itself when the entity count approaches the capacity. You should rarely need to set this value directly.
Important: when you set this value (or when the array automatically resizes), the EntityManager first ensures that all Jobs finish. This can prevent the Job scheduler from utilizing available CPU cores and threads, resulting in a temporary performance drop.
ExclusiveEntityTransactionDependency
The Job dependencies of the exclusive entity transaction.
Declaration
public JobHandle ExclusiveEntityTransactionDependency { get; set; }
Property Value
Type | Description |
---|---|
JobHandle |
GlobalSystemVersion
A counter that increments after every system update.
Declaration
public uint GlobalSystemVersion { get; }
Property Value
Type | Description |
---|---|
UInt32 |
Remarks
The ECS framework uses the GlobalSystemVersion to track changes in a conservative, efficient fashion. Changes are recorded per component per chunk.
See Also
IsCreated
Reports whether the EntityManager has been initialized yet.
Declaration
public bool IsCreated { get; }
Property Value
Type | Description |
---|---|
Boolean | True, if the EntityManager's OnCreateManager() function has finished. |
UniversalQuery
A EntityQuery instance that matches all components.
Declaration
public EntityQuery UniversalQuery { get; }
Property Value
Type | Description |
---|---|
EntityQuery |
Version
The latest entity generational version.
Declaration
public int Version { get; }
Property Value
Type | Description |
---|---|
Int32 | This is the version number that is assigned to a new entity. See Version. |
World
The World of this EntityManager.
Declaration
public World World { get; }
Property Value
Type | Description |
---|---|
World | A World has one EntityManager and an EntityManager manages the entities of one World. |
Methods
AddBuffer<T>(Entity)
Adds a dynamic buffer component to an entity.
Declaration
public DynamicBuffer<T> AddBuffer<T>(Entity entity)
where T : struct, IBufferElementData
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity. |
Returns
Type | Description |
---|---|
DynamicBuffer<T> | The buffer. |
Type Parameters
Name | Description |
---|---|
T | The type of buffer element. Must implement IBufferElementData. |
Remarks
A buffer component stores the number of elements inside the chunk defined by the [InternalBufferCapacity] attribute applied to the buffer element type declaration. Any additional elements are stored in a separate memory block that is managed by the EntityManager.
Adding a component changes an entity's archetype and results in the entity being moved to a different chunk.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before adding the buffer and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
See Also
AddChunkComponentData<T>(Entity)
Adds a chunk component to the specified entity. Returns true if the chunk component was added, false if the entity already had the chunk component. (The chunk component's data is set either way.)
Declaration
public bool AddChunkComponentData<T>(Entity entity)
where T : struct, IComponentData
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity. |
Returns
Type | Description |
---|---|
Boolean |
Type Parameters
Name | Description |
---|---|
T | The type of component, which must implement IComponentData. |
Remarks
Adding a chunk component to an entity changes that entity's archetype and results in the entity being moved to a different chunk, either one that already has an archetype containing the chunk component or a new chunk.
A chunk component is common to all entities in a chunk. You can access a chunk IComponentData instance through either the chunk itself or through an entity stored in that chunk. In either case, getting or setting the component reads or writes the same data.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before adding the component and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
AddChunkComponentData<T>(EntityQuery, T)
Adds a component to each of the chunks identified by a EntityQuery and set the component values.
Declaration
public void AddChunkComponentData<T>(EntityQuery entityQuery, T componentData)
where T : struct, IComponentData
Parameters
Type | Name | Description |
---|---|---|
EntityQuery | entityQuery | The EntityQuery identifying the chunks to modify. |
T | componentData | The data to set. |
Type Parameters
Name | Description |
---|---|
T | The type of component, which must implement IComponentData. |
Remarks
This function finds all chunks whose archetype satisfies the EntityQuery and adds the specified component to them.
A chunk component is common to all entities in a chunk. You can access a chunk IComponentData instance through either the chunk itself or through an entity stored in that chunk.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before adding the component and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
AddComponent(NativeArray<Entity>, ComponentType)
Adds a component to a set of entities.
Declaration
public void AddComponent(NativeArray<Entity> entities, ComponentType componentType)
Parameters
Type | Name | Description |
---|---|---|
NativeArray<Entity> | entities | An array of Entity objects. |
ComponentType | componentType | The type of component to add. |
Remarks
Adding a component changes an entity's archetype and results in the entity being moved to a different chunk.
The added components have the default values for the type.
If an Entity object in the entities
array refers to an entity that has been destroyed, this function
throws an ArgumentError exception.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before creating these chunks and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
AddComponent(Entity, ComponentType)
Adds a component to an entity.
Declaration
public bool AddComponent(Entity entity, ComponentType componentType)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The Entity object. |
ComponentType | componentType | The type of component to add. |
Returns
Type | Description |
---|---|
Boolean |
Remarks
Adding a component changes the entity's archetype and results in the entity being moved to a different chunk.
The added component has the default values for the type.
If the Entity object refers to an entity that has been destroyed, this function throws an ArgumentError exception.
If the Entity object refers to an entity that already has the specified ComponentType, the function returns false without performing any modifications.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before adding the component and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
AddComponent(EntityQuery, ComponentType)
Adds a component to a set of entities defined by a EntityQuery.
Declaration
public void AddComponent(EntityQuery entityQuery, ComponentType componentType)
Parameters
Type | Name | Description |
---|---|---|
EntityQuery | entityQuery | The EntityQuery defining the entities to modify. |
ComponentType | componentType | The type of component to add. |
Remarks
Adding a component changes an entity's archetype and results in the entity being moved to a different chunk.
The added components have the default values for the type.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before adding the component and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
AddComponent<T>(NativeArray<Entity>)
Adds a component to a set of entities.
Declaration
public void AddComponent<T>(NativeArray<Entity> entities)
Parameters
Type | Name | Description |
---|---|---|
NativeArray<Entity> | entities | An array of Entity objects. |
Type Parameters
Name | Description |
---|---|
T | The type of component to add. |
Remarks
Adding a component changes an entity's archetype and results in the entity being moved to a different chunk.
The added components have the default values for the type.
If an Entity object in the entities
array refers to an entity that has been destroyed, this function
throws an ArgumentError exception.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before creating these chunks and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
AddComponent<T>(Entity)
Adds a component to an entity.
Declaration
public bool AddComponent<T>(Entity entity)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The Entity object. |
Returns
Type | Description |
---|---|
Boolean |
Type Parameters
Name | Description |
---|---|
T | The type of component to add. |
Remarks
Adding a component changes the entity's archetype and results in the entity being moved to a different chunk.
The added component has the default values for the type.
If the Entity object refers to an entity that has been destroyed, this function throws an ArgumentError exception.
If the Entity object refers to an entity that already has the specified ComponentType of type T, the function returns false without performing any modifications.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before adding the component and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
AddComponent<T>(EntityQuery)
Adds a component to a set of entities defined by a EntityQuery.
Declaration
public void AddComponent<T>(EntityQuery entityQuery)
Parameters
Type | Name | Description |
---|---|---|
EntityQuery | entityQuery | The EntityQuery defining the entities to modify. |
Type Parameters
Name | Description |
---|---|
T | The type of component to add. |
Remarks
Adding a component changes an entity's archetype and results in the entity being moved to a different chunk.
The added components have the default values for the type.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before adding the component and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
AddComponentData<T>(Entity, T)
Adds a component to an entity and set the value of that component. Returns true if the component was added, false if the entity already had the component. (The component's data is set either way.)
Declaration
public bool AddComponentData<T>(Entity entity, T componentData)
where T : struct, IComponentData
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity. |
T | componentData | The data to set. |
Returns
Type | Description |
---|---|
Boolean |
Type Parameters
Name | Description |
---|---|
T | The type of component. |
Remarks
Adding a component changes an entity's archetype and results in the entity being moved to a different chunk.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before adding the component and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
AddComponentData<T>(EntityQuery, NativeArray<T>)
Adds a component to a set of entities defines by the EntityQuery and sets the component of each entity in the query to the value in the component array. componentArray.Length must match entityQuery.ToEntityArray().Length.
Declaration
public void AddComponentData<T>(EntityQuery entityQuery, NativeArray<T> componentArray)
where T : struct, IComponentData
Parameters
Type | Name | Description |
---|---|---|
EntityQuery | entityQuery | THe EntityQuery defining the entities to add component to |
NativeArray<T> | componentArray |
Type Parameters
Name | Description |
---|---|
T |
AddComponentObject(Entity, Object)
Adds a managed UnityEngine.Component object to an entity.
Declaration
public void AddComponentObject(Entity entity, object componentData)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity to modify. |
Object | componentData | An object inheriting UnityEngine.Component. |
Remarks
Accessing data in a managed object forfeits many opportunities for increased performance. Adding managed objects to an entity should be avoided or used sparingly.
Adding a component changes an entity's archetype and results in the entity being moved to a different chunk.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before adding the object and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
Exceptions
Type | Condition |
---|---|
ArgumentNullException | If the componentData object is not an instance of UnityEngine.Component. |
AddComponents(Entity, ComponentTypes)
Adds a set of component to an entity.
Declaration
public void AddComponents(Entity entity, ComponentTypes types)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity to modify. |
ComponentTypes | types | The types of components to add. |
Remarks
Adding components changes the entity's archetype and results in the entity being moved to a different chunk.
The added components have the default values for the type.
If the Entity object refers to an entity that has been destroyed, this function throws an ArgumentError exception.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before adding these components and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
AddSharedComponentData<T>(Entity, T)
Adds a shared component to an entity. Returns true if the shared component was added, false if the entity already had the shared component. (The shared component's data is set either way.)
Declaration
public bool AddSharedComponentData<T>(Entity entity, T componentData)
where T : struct, ISharedComponentData
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity. |
T | componentData | An instance of the shared component having the values to set. |
Returns
Type | Description |
---|---|
Boolean |
Type Parameters
Name | Description |
---|---|
T | The shared component type. |
Remarks
The fields of the componentData
parameter are assigned to the added shared component.
Adding a component to an entity changes its archetype and results in the entity being moved to a different chunk. The entity moves to a chunk with other entities that have the same shared component values. A new chunk is created if no chunk with the same archetype and shared component values currently exists.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before adding the component and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
AddSharedComponentData<T>(EntityQuery, T)
Adds a shared component to a set of entities defined by a EntityQuery.
Declaration
public void AddSharedComponentData<T>(EntityQuery entityQuery, T componentData)
where T : struct, ISharedComponentData
Parameters
Type | Name | Description |
---|---|---|
EntityQuery | entityQuery | The EntityQuery defining a set of entities to modify. |
T | componentData | The data to set. |
Type Parameters
Name | Description |
---|---|
T | The data type of the shared component. |
Remarks
The fields of the componentData
parameter are assigned to all of the added shared components.
Adding a component to an entity changes its archetype and results in the entity being moved to a different chunk. The entity moves to a chunk with other entities that have the same shared component values. A new chunk is created if no chunk with the same archetype and shared component values currently exists.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before adding the component and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
BeginExclusiveEntityTransaction()
Declaration
public ExclusiveEntityTransaction BeginExclusiveEntityTransaction()
Returns
Type | Description |
---|---|
ExclusiveEntityTransaction |
CompleteAllJobs()
Waits for all Jobs to complete.
Declaration
public void CompleteAllJobs()
Remarks
Calling CompleteAllJobs() blocks the main thread until all currently running Jobs finish.
CopyAndReplaceEntitiesFrom(EntityManager)
Declaration
public void CopyAndReplaceEntitiesFrom(EntityManager srcEntityManager)
Parameters
Type | Name | Description |
---|---|---|
EntityManager | srcEntityManager |
CreateArchetype(ComponentType[])
Creates an archetype from a set of component types.
Declaration
public EntityArchetype CreateArchetype(params ComponentType[] types)
Parameters
Type | Name | Description |
---|---|---|
ComponentType[] | types | The component types to include as part of the archetype. |
Returns
Type | Description |
---|---|
EntityArchetype | The EntityArchetype object for the archetype. |
Remarks
Creates a new archetype in the ECS framework's internal type registry, unless the archetype already exists.
CreateChunk(EntityArchetype, NativeArray<ArchetypeChunk>, Int32)
Creates a set of chunks containing the specified number of entities having the specified archetype.
Declaration
public void CreateChunk(EntityArchetype archetype, NativeArray<ArchetypeChunk> chunks, int entityCount)
Parameters
Type | Name | Description |
---|---|---|
EntityArchetype | archetype | The archetype for the chunk and entities. |
NativeArray<ArchetypeChunk> | chunks | An empty array to receive the created chunks. |
Int32 | entityCount | The number of entities to create. |
Remarks
The EntityManager creates enough chunks to hold the required number of entities.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before creating these chunks and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
CreateEntity()
Declaration
public Entity CreateEntity()
Returns
Type | Description |
---|---|
Entity |
CreateEntity(ComponentType[])
Creates an entity having components of the specified types.
Declaration
public Entity CreateEntity(params ComponentType[] types)
Parameters
Type | Name | Description |
---|---|---|
ComponentType[] | types | The types of components to add to the new entity. |
Returns
Type | Description |
---|---|
Entity | The Entity object that you can use to access the entity. |
Remarks
The EntityManager creates the entity in the first available chunk with the matching archetype that has enough space.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before creating the entity and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
CreateEntity(EntityArchetype)
Creates an entity having the specified archetype.
Declaration
public Entity CreateEntity(EntityArchetype archetype)
Parameters
Type | Name | Description |
---|---|---|
EntityArchetype | archetype | The archetype for the new entity. |
Returns
Type | Description |
---|---|
Entity | The Entity object that you can use to access the entity. |
Remarks
The EntityManager creates the entity in the first available chunk with the matching archetype that has enough space.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before creating the entity and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
CreateEntity(EntityArchetype, NativeArray<Entity>)
Creates a set of entities of the specified archetype.
Declaration
public void CreateEntity(EntityArchetype archetype, NativeArray<Entity> entities)
Parameters
Type | Name | Description |
---|---|---|
EntityArchetype | archetype | The archetype defining the structure for the new entities. |
NativeArray<Entity> | entities | An array to hold the Entity objects needed to access the new entities. The length of the array determines how many entities are created. |
Remarks
Fills the NativeArray
object assigned to the entities
parameter with the Entity objects of the created entities. Each entity
has the components specified by the EntityArchetype object assigned
to the archetype
parameter. The EntityManager adds these entities to the World entity list. Use the
Entity objects in the array for further processing, such as setting the component values.
CreateEntity(EntityArchetype, Int32, Allocator)
Creates a set of entities of the specified archetype.
Declaration
public NativeArray<Entity> CreateEntity(EntityArchetype archetype, int entityCount, Allocator allocator)
Parameters
Type | Name | Description |
---|---|---|
EntityArchetype | archetype | The archetype defining the structure for the new entities. |
Int32 | entityCount | The number of entities to create with the specified archetype. |
Allocator | allocator | How the created native array should be allocated. |
Returns
Type | Description |
---|---|
NativeArray<Entity> | A NativeArray of entities with the given archetype. |
Remarks
Creates a NativeArray of entities,
each of which has the components specified by the EntityArchetype object assigned
to the archetype
parameter. The EntityManager adds these entities to the World entity list.
CreateEntityQuery(ComponentType[])
Creates a EntityQuery from an array of component types.
Declaration
public EntityQuery CreateEntityQuery(params ComponentType[] requiredComponents)
Parameters
Type | Name | Description |
---|---|---|
ComponentType[] | requiredComponents | An array containing the component types. |
Returns
Type | Description |
---|---|
EntityQuery | The EntityQuery derived from the specified array of component types. |
See Also
CreateEntityQuery(EntityQueryDesc[])
Creates a EntityQuery from an EntityQueryDesc.
Declaration
public EntityQuery CreateEntityQuery(params EntityQueryDesc[] queriesDesc)
Parameters
Type | Name | Description |
---|---|---|
EntityQueryDesc[] | queriesDesc | A queryDesc identifying a set of component types. |
Returns
Type | Description |
---|---|
EntityQuery | The EntityQuery corresponding to the queryDesc. |
CreateEntityRemapArray(Allocator)
Creates a remapping array with one element for each entity in the World.
Declaration
public NativeArray<EntityRemapUtility.EntityRemapInfo> CreateEntityRemapArray(Allocator allocator)
Parameters
Type | Name | Description |
---|---|---|
Allocator | allocator | The type of memory allocation to use when creating the array. |
Returns
Type | Description |
---|---|
NativeArray<EntityRemapUtility.EntityRemapInfo> | An array containing a no-op identity transformation for each entity. |
DestroyEntity(NativeArray<Entity>)
Destroys all entities in an array.
Declaration
public void DestroyEntity(NativeArray<Entity> entities)
Parameters
Type | Name | Description |
---|---|---|
NativeArray<Entity> | entities | An array containing the Entity objects of the entities to destroy. |
Remarks
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before destroying the entity and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
DestroyEntity(NativeSlice<Entity>)
Destroys all entities in a slice of an array.
Declaration
public void DestroyEntity(NativeSlice<Entity> entities)
Parameters
Type | Name | Description |
---|---|---|
NativeSlice<Entity> | entities | The slice of an array containing the Entity objects of the entities to destroy. |
Remarks
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before destroying the entity and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
DestroyEntity(Entity)
Destroys an entity.
Declaration
public void DestroyEntity(Entity entity)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The Entity object of the entity to destroy. |
Remarks
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before destroying the entity and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
DestroyEntity(EntityQuery)
Destroy all entities having a common set of component types.
Declaration
public void DestroyEntity(EntityQuery entityQuery)
Parameters
Type | Name | Description |
---|---|---|
EntityQuery | entityQuery |
Remarks
Since entities in the same chunk share the same component structure, this function effectively destroys
the chunks holding any entities identified by the entityQueryFilter
parameter.
EndExclusiveEntityTransaction()
Ends an exclusive entity transaction.
Declaration
public void EndExclusiveEntityTransaction()
See Also
Exists(Entity)
Reports whether an Entity object is still valid.
Declaration
public bool Exists(Entity entity)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The Entity object to check. |
Returns
Type | Description |
---|---|
Boolean | True, if Version matches the version of the current entity at Index in the entities array. |
Remarks
An Entity object does not contain a reference to its entity. Instead, the Entity struct contains an index and a generational version number. When an entity is destroyed, the EntityManager increments the version of the entity within the internal array of entities. The index of a destroyed entity is recycled when a new entity is created.
After an entity is destroyed, any existing Entity objects will still contain the older version number. This function compares the version numbers of the specified Entity object and the current version of the entity recorded in the entities array. If the versions are different, the Entity object no longer refers to an existing entity and cannot be used.
GetAllArchetypes(NativeList<EntityArchetype>)
Gets all the archetypes.
Declaration
public void GetAllArchetypes(NativeList<EntityArchetype> allArchetypes)
Parameters
Type | Name | Description |
---|---|---|
NativeList<EntityArchetype> | allArchetypes | A native list to receive the EntityArchetype objects. |
Remarks
The function adds the archetype objects to the existing contents of the list. The list is not cleared.
GetAllChunks(Allocator)
Gets all the chunks managed by this EntityManager.
Declaration
public NativeArray<ArchetypeChunk> GetAllChunks(Allocator allocator = null)
Parameters
Type | Name | Description |
---|---|---|
Allocator | allocator | The type of allocation for creating the NativeArray to hold the ArchetypeChunk objects. |
Returns
Type | Description |
---|---|
NativeArray<ArchetypeChunk> | An array of ArchetypeChunk objects referring to all the chunks in the World. |
Remarks
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before getting these chunks and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
GetAllEntities(Allocator)
Gets all the entities managed by this EntityManager.
Declaration
public NativeArray<Entity> GetAllEntities(Allocator allocator = null)
Parameters
Type | Name | Description |
---|---|---|
Allocator | allocator | The type of allocation for creating the NativeArray to hold the Entity objects. |
Returns
Type | Description |
---|---|
NativeArray<Entity> | An array of Entity objects referring to all the entities in the World. |
Remarks
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before getting the entities and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
GetAllUniqueSharedComponentData<T>(List<T>)
Declaration
public void GetAllUniqueSharedComponentData<T>(List<T> sharedComponentValues)
where T : struct, ISharedComponentData
Parameters
Type | Name | Description |
---|---|---|
List<T> | sharedComponentValues |
Type Parameters
Name | Description |
---|---|
T |
GetAllUniqueSharedComponentData<T>(List<T>, List<Int32>)
Gets a list of all unique shared components of the same type and a corresponding list of indices into the internal shared component list.
Declaration
public void GetAllUniqueSharedComponentData<T>(List<T> sharedComponentValues, List<int> sharedComponentIndices)
where T : struct, ISharedComponentData
Parameters
Type | Name | Description |
---|---|---|
List<T> | sharedComponentValues | |
List<Int32> | sharedComponentIndices |
Type Parameters
Name | Description |
---|---|
T |
Remarks
All entities with the same archetype and the same values for a shared component are stored in the same set of chunks. This function finds the unique shared components existing across chunks and archetype and fills a list with copies of those components and fills in a separate list with the indices of those components in the internal shared component list. You can use the indices to ask the same shared components directly by calling GetSharedComponentData<T>(Int32), passing in the index. An index remains valid until the shared component order version changes. Check this version using GetSharedComponentOrderVersion<T>(T).
GetArchetypeChunkBufferType<T>(Boolean)
Gets the dynamic type object required to access a chunk buffer containing elements of type T.
Declaration
public ArchetypeChunkBufferType<T> GetArchetypeChunkBufferType<T>(bool isReadOnly)
where T : struct, IBufferElementData
Parameters
Type | Name | Description |
---|---|---|
Boolean | isReadOnly | Specify whether the access to the component through this object is read only or read and write. |
Returns
Type | Description |
---|---|
ArchetypeChunkBufferType<T> | The run-time type information of the buffer component. |
Type Parameters
Name | Description |
---|---|
T | The compile-time type of the buffer elements. |
Remarks
To access a component stored in a chunk, you must have the type registry information for the component. This function provides that information for buffer components. Use the returned ArchetypeChunkComponentType<T> object with the functions of an ArchetypeChunk object to get information about the components in that chunk and to access the component values.
GetArchetypeChunkComponentType<T>(Boolean)
Gets the dynamic type object required to access a chunk component of type T.
Declaration
public ArchetypeChunkComponentType<T> GetArchetypeChunkComponentType<T>(bool isReadOnly)
Parameters
Type | Name | Description |
---|---|---|
Boolean | isReadOnly | Specify whether the access to the component through this object is read only or read and write. For managed components isReadonly will always be treated as false. |
Returns
Type | Description |
---|---|
ArchetypeChunkComponentType<T> | The run-time type information of the component. |
Type Parameters
Name | Description |
---|---|
T | The compile-time type of the component. |
Remarks
To access a component stored in a chunk, you must have the type registry information for the component. This function provides that information. Use the returned ArchetypeChunkComponentType<T> object with the functions of an ArchetypeChunk object to get information about the components in that chunk and to access the component values.
GetArchetypeChunkComponentTypeDynamic(ComponentType)
Gets the dynamic type object required to access a chunk component of dynamic type acquired from reflection.
Declaration
public ArchetypeChunkComponentTypeDynamic GetArchetypeChunkComponentTypeDynamic(ComponentType componentType)
Parameters
Type | Name | Description |
---|---|---|
ComponentType | componentType | Type of the component |
Returns
Type | Description |
---|---|
ArchetypeChunkComponentTypeDynamic | The run-time type information of the component. |
Remarks
To access a component stored in a chunk, you must have the type registry information for the component. This function provides that information. Use the returned ArchetypeChunkComponentTypeDynamic object with the functions of an ArchetypeChunk object to get information about the components in that chunk and to access the component values.
GetArchetypeChunkEntityType()
Gets the dynamic type object required to access the Entity component of a chunk.
Declaration
public ArchetypeChunkEntityType GetArchetypeChunkEntityType()
Returns
Type | Description |
---|---|
ArchetypeChunkEntityType | The run-time type information of the Entity component. |
Remarks
All chunks have an implicit Entity component referring to the entities in that chunk.
To access any component stored in a chunk, you must have the type registry information for the component. This function provides that information for the implicit Entity component. Use the returned ArchetypeChunkComponentType<T> object with the functions of an ArchetypeChunk object to access the component values.
GetArchetypeChunkSharedComponentType<T>()
Gets the dynamic type object required to access a shared component of type T.
Declaration
public ArchetypeChunkSharedComponentType<T> GetArchetypeChunkSharedComponentType<T>()
where T : struct, ISharedComponentData
Returns
Type | Description |
---|---|
ArchetypeChunkSharedComponentType<T> | The run-time type information of the shared component. |
Type Parameters
Name | Description |
---|---|
T | The compile-time type of the shared component. |
Remarks
To access a component stored in a chunk, you must have the type registry information for the component. This function provides that information for shared components. Use the returned ArchetypeChunkComponentType<T> object with the functions of an ArchetypeChunk object to get information about the components in that chunk and to access the component values.
GetAssignableComponentTypes(Type)
Gets a list of the types of components that can be assigned to the specified component.
Declaration
public List<Type> GetAssignableComponentTypes(Type interfaceType)
Parameters
Type | Name | Description |
---|---|---|
Type | interfaceType | The type to check. |
Returns
Type | Description |
---|---|
List<Type> | A new List object containing the System.Types that can be assigned to |
Remarks
Assignable components include those with the same compile-time type and those that inherit from the same compile-time type.
GetBuffer<T>(Entity)
Gets the dynamic buffer of an entity.
Declaration
public DynamicBuffer<T> GetBuffer<T>(Entity entity)
where T : struct, IBufferElementData
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity. |
Returns
Type | Description |
---|---|
DynamicBuffer<T> | The DynamicBuffer object for accessing the buffer contents. |
Type Parameters
Name | Description |
---|---|
T | The type of the buffer's elements. |
Exceptions
Type | Condition |
---|---|
ArgumentException | Thrown if T is an unsupported type. |
GetChunk(Entity)
Gets the chunk in which the specified entity is stored.
Declaration
public ArchetypeChunk GetChunk(Entity entity)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity. |
Returns
Type | Description |
---|---|
ArchetypeChunk | The chunk containing the entity. |
GetChunkComponentData<T>(ArchetypeChunk)
Gets the value of a chunk component.
Declaration
public T GetChunkComponentData<T>(ArchetypeChunk chunk)
where T : struct, IComponentData
Parameters
Type | Name | Description |
---|---|---|
ArchetypeChunk | chunk | The chunk. |
Returns
Type | Description |
---|---|
T | A struct of type T containing the component value. |
Type Parameters
Name | Description |
---|---|
T | The component type. |
Remarks
A chunk component is common to all entities in a chunk. You can access a chunk IComponentData instance through either the chunk itself or through an entity stored in that chunk.
Exceptions
Type | Condition |
---|---|
ArgumentException | Thrown if the ArchetypeChunk object is invalid. |
GetChunkComponentData<T>(Entity)
Gets the value of chunk component for the chunk containing the specified entity.
Declaration
public T GetChunkComponentData<T>(Entity entity)
where T : struct, IComponentData
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity. |
Returns
Type | Description |
---|---|
T | A struct of type T containing the component value. |
Type Parameters
Name | Description |
---|---|
T | The component type. |
Remarks
A chunk component is common to all entities in a chunk. You can access a chunk IComponentData instance through either the chunk itself or through an entity stored in that chunk.
GetComponentCount(Entity)
Gets the number of component types associated with an entity.
Declaration
public int GetComponentCount(Entity entity)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity. |
Returns
Type | Description |
---|---|
Int32 | The number of components. |
GetComponentData<T>(Entity)
Gets the value of a component for an entity.
Declaration
public T GetComponentData<T>(Entity entity)
where T : struct, IComponentData
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity. |
Returns
Type | Description |
---|---|
T | A struct of type T containing the component value. |
Type Parameters
Name | Description |
---|---|
T | The type of component to retrieve. |
Exceptions
Type | Condition |
---|---|
ArgumentException | Thrown if the component type has no fields. |
GetComponentObject<T>(Entity)
Gets the managed UnityEngine.Component object from an entity.
Declaration
public T GetComponentObject<T>(Entity entity)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity. |
Returns
Type | Description |
---|---|
T | The managed object, cast to type T. |
Type Parameters
Name | Description |
---|---|
T | The type of the managed object. |
GetComponentObject<T>(Entity, ComponentType)
Declaration
public T GetComponentObject<T>(Entity entity, ComponentType componentType)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | |
ComponentType | componentType |
Returns
Type | Description |
---|---|
T |
Type Parameters
Name | Description |
---|---|
T |
GetComponentOrderVersion<T>()
Gets the version number of the specified component type.
Declaration
public int GetComponentOrderVersion<T>()
Returns
Type | Description |
---|---|
Int32 | The current version number. |
Type Parameters
Name | Description |
---|---|
T | The component type. |
Remarks
This version number is incremented each time there is a structural change involving the specified type of component. Such changes include creating or destroying entities that have this component and adding or removing the component type from an entity. Shared components are not covered by this version; see GetSharedComponentOrderVersion<T>(T).
Version numbers can overflow. To compare if one version is more recent than another use a calculation such as:
bool VersionBisNewer = (VersionB - VersionA) > 0;
GetComponentTypes(Entity, Allocator)
Gets an entity's component types.
Declaration
public NativeArray<ComponentType> GetComponentTypes(Entity entity, Allocator allocator = null)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity. |
Allocator | allocator | The type of allocation for creating the NativeArray to hold the ComponentType objects. |
Returns
Type | Description |
---|---|
NativeArray<ComponentType> | An array of ComponentType containing all the types of components associated with the entity. |
GetEnabled(Entity)
Declaration
public bool GetEnabled(Entity entity)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity |
Returns
Type | Description |
---|---|
Boolean |
GetEntityQueryMask(EntityQuery)
Gets an EntityQueryMask that can be used to quickly match if an entity belongs to an EntityQuery. There is a maximum limit of 1024 EntityQueryMasks that can be created. EntityQueryMasks cannot be created from EntityQueries with filters.
Declaration
public EntityQueryMask GetEntityQueryMask(EntityQuery query)
Parameters
Type | Name | Description |
---|---|---|
EntityQuery | query | The EntityQuery that describes the EntityQueryMask. |
Returns
Type | Description |
---|---|
EntityQueryMask | The EntityQueryMask corresponding to the EntityQuery. |
GetSharedComponentCount()
Gets the number of shared components managed by this EntityManager.
Declaration
public int GetSharedComponentCount()
Returns
Type | Description |
---|---|
Int32 | The shared component count |
GetSharedComponentData<T>(Int32)
Gets a shared component by index.
Declaration
public T GetSharedComponentData<T>(int sharedComponentIndex)
where T : struct, ISharedComponentData
Parameters
Type | Name | Description |
---|---|---|
Int32 | sharedComponentIndex | The index of the shared component in the internal shared component list. |
Returns
Type | Description |
---|---|
T | A copy of the shared component. |
Type Parameters
Name | Description |
---|---|
T | The data type of the shared component. |
Remarks
The ECS framework maintains an internal list of unique shared components. You can get the components in this list, along with their indices using GetAllUniqueSharedComponentData<T>(List<T>, List<Int32>). An index in the list is valid and points to the same shared component index as long as the shared component order version from GetSharedComponentOrderVersion<T>(T) remains the same.
GetSharedComponentData<T>(Entity)
Gets a shared component from an entity.
Declaration
public T GetSharedComponentData<T>(Entity entity)
where T : struct, ISharedComponentData
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity. |
Returns
Type | Description |
---|---|
T | A copy of the shared component. |
Type Parameters
Name | Description |
---|---|
T | The type of shared component. |
GetSharedComponentDataIndex<T>(Entity)
Declaration
public int GetSharedComponentDataIndex<T>(Entity entity)
where T : struct, ISharedComponentData
Parameters
Type | Name | Description |
---|---|---|
Entity | entity |
Returns
Type | Description |
---|---|
Int32 |
Type Parameters
Name | Description |
---|---|
T |
GetSharedComponentOrderVersion<T>(T)
Gets the version number of the specified shared component.
Declaration
public int GetSharedComponentOrderVersion<T>(T sharedComponent)
where T : struct, ISharedComponentData
Parameters
Type | Name | Description |
---|---|---|
T | sharedComponent | The shared component instance. |
Returns
Type | Description |
---|---|
Int32 | The current version number. |
Type Parameters
Name | Description |
---|---|
T | The shared component type. |
Remarks
This version number is incremented each time there is a structural change involving entities in the chunk of the specified shared component. Such changes include creating or destroying entities or anything that changes the archetype of an entity.
Version numbers can overflow. To compare if one version is more recent than another use a calculation such as:
bool VersionBisNewer = (VersionB - VersionA) > 0;
HasChunkComponent<T>(Entity)
Checks whether the chunk containing an entity has a specific type of component.
Declaration
public bool HasChunkComponent<T>(Entity entity)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The Entity object. |
Returns
Type | Description |
---|---|
Boolean | True, if the chunk containing the specified entity has the component. |
Type Parameters
Name | Description |
---|---|
T | The data type of the chunk component. |
Remarks
Always returns false for an entity that has been destroyed.
HasComponent(Entity, ComponentType)
Checks whether an entity has a specific type of component.
Declaration
public bool HasComponent(Entity entity, ComponentType type)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The Entity object. |
ComponentType | type | The data type of the component. |
Returns
Type | Description |
---|---|
Boolean | True, if the specified entity has the component. |
Remarks
Always returns false for an entity that has been destroyed.
HasComponent<T>(Entity)
Checks whether an entity has a specific type of component.
Declaration
public bool HasComponent<T>(Entity entity)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The Entity object. |
Returns
Type | Description |
---|---|
Boolean | True, if the specified entity has the component. |
Type Parameters
Name | Description |
---|---|
T | The data type of the component. |
Remarks
Always returns false for an entity that has been destroyed.
Instantiate(Entity)
Clones an entity.
Declaration
public Entity Instantiate(Entity srcEntity)
Parameters
Type | Name | Description |
---|---|---|
Entity | srcEntity | The entity to clone |
Returns
Type | Description |
---|---|
Entity | The Entity object for the new entity. |
Remarks
The new entity has the same archetype and component values as the original.
If the source entity was converted from a prefab and thus has a LinkedEntityGroup component, the entire group is cloned as a new set of entities.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before creating the entity and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
Instantiate(Entity, NativeArray<Entity>)
Makes multiple clones of an entity.
Declaration
public void Instantiate(Entity srcEntity, NativeArray<Entity> outputEntities)
Parameters
Type | Name | Description |
---|---|---|
Entity | srcEntity | The entity to clone. |
NativeArray<Entity> | outputEntities | An array to receive the Entity objects of the root entity in each clone. The length of this array determines the number of clones. |
Remarks
The new entities have the same archetype and component values as the original.
If the source entity has a LinkedEntityGroup component, the entire group is cloned as a new set of entities.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before creating these entities and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
Instantiate(Entity, Int32, Allocator)
Makes multiple clones of an entity.
Declaration
public NativeArray<Entity> Instantiate(Entity srcEntity, int instanceCount, Allocator allocator)
Parameters
Type | Name | Description |
---|---|---|
Entity | srcEntity | The entity to clone. |
Int32 | instanceCount | The number of entities to instantiate with the same components as the source entity. |
Allocator | allocator | How the created native array should be allocated. |
Returns
Type | Description |
---|---|
NativeArray<Entity> | A NativeArray of entities. |
Remarks
The new entities have the same archetype and component values as the original.
If the source entity has a LinkedEntityGroup component, the entire group is cloned as a new set of entities.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before creating these entities and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
LockChunk(NativeArray<ArchetypeChunk>)
Locks a set of chunks.
Declaration
public void LockChunk(NativeArray<ArchetypeChunk> chunks)
Parameters
Type | Name | Description |
---|---|---|
NativeArray<ArchetypeChunk> | chunks | An array of chunks to lock. |
See Also
LockChunk(ArchetypeChunk)
Protects a chunk, and the entities within it, from structural changes.
Declaration
public void LockChunk(ArchetypeChunk chunk)
Parameters
Type | Name | Description |
---|---|---|
ArchetypeChunk | chunk | The chunk to lock. |
Remarks
When locked, entities cannot be added to or removed from the chunk; components cannot be added to or removed from the entities in the chunk; the values of shared components cannot be changed; and entities in the chunk cannot be destroyed. You can change the values of components, other than shared components.
Call UnlockChunk(ArchetypeChunk) to unlock the chunk.
You can lock a chunk temporarily and then unlock it, or you can lock it for the lifespan of your application. For example, if you have a gameboard with a fixed number of tiles, you may want the entities representing those tiles in a specific order. Locking the chunk prevents the ECS framework from rearranging them once you have set the desired order.
Use SwapComponents(ArchetypeChunk, Int32, ArchetypeChunk, Int32) to re-order entities in a chunk.
MoveEntitiesFrom(out NativeArray<Entity>, EntityManager)
Moves all entities managed by the specified EntityManager to the World of this EntityManager and fills an array with their Entity objects.
Declaration
public void MoveEntitiesFrom(out NativeArray<Entity> output, EntityManager srcEntities)
Parameters
Type | Name | Description |
---|---|---|
NativeArray<Entity> | output | An array to receive the Entity objects of the transferred entities. |
EntityManager | srcEntities | The EntityManager whose entities are appropriated. |
Remarks
After the move, the entities are managed by this EntityManager. Use the output
array to make post-move
changes to the transferred entities.
Each world has one EntityManager, which manages all the entities in that world. This function allows you to transfer entities from one World to another.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before moving the entities and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
MoveEntitiesFrom(out NativeArray<Entity>, EntityManager, NativeArray<EntityRemapUtility.EntityRemapInfo>)
Moves all entities managed by the specified EntityManager to the World of this EntityManager and fills an array with their Entity objects.
Declaration
public void MoveEntitiesFrom(out NativeArray<Entity> output, EntityManager srcEntities, NativeArray<EntityRemapUtility.EntityRemapInfo> entityRemapping)
Parameters
Type | Name | Description |
---|---|---|
NativeArray<Entity> | output | An array to receive the Entity objects of the transferred entities. |
EntityManager | srcEntities | The EntityManager whose entities are appropriated. |
NativeArray<EntityRemapUtility.EntityRemapInfo> | entityRemapping | A set of entity transformations to make during the transfer. |
Remarks
After the move, the entities are managed by this EntityManager. Use the output
array to make post-move
changes to the transferred entities.
Each world has one EntityManager, which manages all the entities in that world. This function allows you to transfer entities from one World to another.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before moving the entities and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
Exceptions
Type | Condition |
---|---|
ArgumentException |
MoveEntitiesFrom(out NativeArray<Entity>, EntityManager, EntityQuery, NativeArray<EntityRemapUtility.EntityRemapInfo>)
Moves a selection of the entities managed by the specified EntityManager to the World of this EntityManager and fills an array with their Entity objects.
Declaration
public void MoveEntitiesFrom(out NativeArray<Entity> output, EntityManager srcEntities, EntityQuery filter, NativeArray<EntityRemapUtility.EntityRemapInfo> entityRemapping)
Parameters
Type | Name | Description |
---|---|---|
NativeArray<Entity> | output | An array to receive the Entity objects of the transferred entities. |
EntityManager | srcEntities | The EntityManager whose entities are appropriated. |
EntityQuery | filter | A EntityQuery that defines the entities to move. Must be part of the source World. |
NativeArray<EntityRemapUtility.EntityRemapInfo> | entityRemapping | A set of entity transformations to make during the transfer. |
Remarks
After the move, the entities are managed by this EntityManager. Use the output
array to make post-move
changes to the transferred entities.
Each world has one EntityManager, which manages all the entities in that world. This function allows you to transfer entities from one World to another.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before moving the entities and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
Exceptions
Type | Condition |
---|---|
ArgumentException |
MoveEntitiesFrom(EntityManager)
Moves all entities managed by the specified EntityManager to the world of this EntityManager.
Declaration
public void MoveEntitiesFrom(EntityManager srcEntities)
Parameters
Type | Name | Description |
---|---|---|
EntityManager | srcEntities | The EntityManager whose entities are appropriated. |
Remarks
The entities moved are owned by this EntityManager.
Each World has one EntityManager, which manages all the entities in that world. This function allows you to transfer entities from one World to another.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before moving the entities and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
MoveEntitiesFrom(EntityManager, NativeArray<EntityRemapUtility.EntityRemapInfo>)
Moves all entities managed by the specified EntityManager to the World of this EntityManager.
Declaration
public void MoveEntitiesFrom(EntityManager srcEntities, NativeArray<EntityRemapUtility.EntityRemapInfo> entityRemapping)
Parameters
Type | Name | Description |
---|---|---|
EntityManager | srcEntities | The EntityManager whose entities are appropriated. |
NativeArray<EntityRemapUtility.EntityRemapInfo> | entityRemapping | A set of entity transformations to make during the transfer. |
Remarks
After the move, the entities are managed by this EntityManager.
Each World has one EntityManager, which manages all the entities in that world. This function allows you to transfer entities from one world to another.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before moving the entities and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
Exceptions
Type | Condition |
---|---|
ArgumentException | Thrown if you attempt to transfer entities to the EntityManager that already owns them. |
MoveEntitiesFrom(EntityManager, EntityQuery, NativeArray<EntityRemapUtility.EntityRemapInfo>)
Moves a selection of the entities managed by the specified EntityManager to the World of this EntityManager.
Declaration
public void MoveEntitiesFrom(EntityManager srcEntities, EntityQuery filter, NativeArray<EntityRemapUtility.EntityRemapInfo> entityRemapping)
Parameters
Type | Name | Description |
---|---|---|
EntityManager | srcEntities | The EntityManager whose entities are appropriated. |
EntityQuery | filter | A EntityQuery that defines the entities to move. Must be part of the source World. |
NativeArray<EntityRemapUtility.EntityRemapInfo> | entityRemapping | A set of entity transformations to make during the transfer. |
Remarks
After the move, the entities are managed by this EntityManager.
Each world has one EntityManager, which manages all the entities in that world. This function allows you to transfer entities from one World to another.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before moving the entities and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
Exceptions
Type | Condition |
---|---|
ArgumentException | Thrown if the EntityQuery object used as the |
PrepareForDeserialize()
Prepares an empty World to load serialized entities.
Declaration
public void PrepareForDeserialize()
RemoveChunkComponent<T>(Entity)
Removes a chunk component from the specified entity. Returns false if the entity did not have the component.
Declaration
public bool RemoveChunkComponent<T>(Entity entity)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity. |
Returns
Type | Description |
---|---|
Boolean |
Type Parameters
Name | Description |
---|---|
T | The type of component to remove. |
Remarks
A chunk component is common to all entities in a chunk. Removing the chunk component from an entity changes that entity's archetype and results in the entity being moved to a different chunk (that does not have the removed component).
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before removing the component and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
RemoveChunkComponentData<T>(EntityQuery)
Removes a component from the chunks identified by a EntityQuery.
Declaration
public void RemoveChunkComponentData<T>(EntityQuery entityQuery)
Parameters
Type | Name | Description |
---|---|---|
EntityQuery | entityQuery | The EntityQuery identifying the chunks to modify. |
Type Parameters
Name | Description |
---|---|
T | The type of component to remove. |
Remarks
A chunk component is common to all entities in a chunk. You can access a chunk IComponentData instance through either the chunk itself or through an entity stored in that chunk.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before removing the component and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
RemoveComponent(NativeArray<Entity>, ComponentType)
Remove a component from a set of entities.
Declaration
public void RemoveComponent(NativeArray<Entity> entities, ComponentType componentType)
Parameters
Type | Name | Description |
---|---|---|
NativeArray<Entity> | entities | An array of Entity objects. |
ComponentType | componentType | The type of component to remove. |
Remarks
Removing a component changes an entity's archetype and results in the entity being moved to a different chunk.
If an Entity object in the entities
array refers to an entity that has been destroyed, this function
throws an ArgumentError exception.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before creating these chunks and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
RemoveComponent(Entity, ComponentType)
Removes a component from an entity. Returns false if the entity did not have the component.
Declaration
public bool RemoveComponent(Entity entity, ComponentType componentType)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity to modify. |
ComponentType | componentType | The type of component to remove. |
Returns
Type | Description |
---|---|
Boolean |
Remarks
Removing a component changes an entity's archetype and results in the entity being moved to a different chunk.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before removing the component and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
RemoveComponent(EntityQuery, ComponentType)
Removes a component from a set of entities defined by a EntityQuery.
Declaration
public void RemoveComponent(EntityQuery entityQuery, ComponentType componentType)
Parameters
Type | Name | Description |
---|---|---|
EntityQuery | entityQuery | The EntityQuery defining the entities to modify. |
ComponentType | componentType | The type of component to remove. |
Remarks
Removing a component changes an entity's archetype and results in the entity being moved to a different chunk.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before removing the component and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
RemoveComponent(EntityQuery, ComponentTypes)
Removes a set of components from a set of entities defined by a EntityQuery.
Declaration
public void RemoveComponent(EntityQuery entityQuery, ComponentTypes types)
Parameters
Type | Name | Description |
---|---|---|
EntityQuery | entityQuery | The EntityQuery defining the entities to modify. |
ComponentTypes | types | The types of components to add. |
Remarks
Removing a component changes an entity's archetype and results in the entity being moved to a different chunk.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before removing the component and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
RemoveComponent<T>(NativeArray<Entity>)
Removes a component from a set of entities.
Declaration
public void RemoveComponent<T>(NativeArray<Entity> entities)
Parameters
Type | Name | Description |
---|---|---|
NativeArray<Entity> | entities | An array identifying the entities to modify. |
Type Parameters
Name | Description |
---|---|
T | The type of component to remove. |
Remarks
Removing a component changes an entity's archetype and results in the entity being moved to a different chunk.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before removing the component and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
RemoveComponent<T>(Entity)
Removes a component from an entity. Returns false if the entity did not have the component.
Declaration
public bool RemoveComponent<T>(Entity entity)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity. |
Returns
Type | Description |
---|---|
Boolean |
Type Parameters
Name | Description |
---|---|
T | The type of component to remove. |
Remarks
Removing a component changes an entity's archetype and results in the entity being moved to a different chunk.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before removing the component and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
RemoveComponent<T>(EntityQuery)
Removes a component from a set of entities defined by a EntityQuery.
Declaration
public void RemoveComponent<T>(EntityQuery entityQuery)
Parameters
Type | Name | Description |
---|---|---|
EntityQuery | entityQuery | The EntityQuery defining the entities to modify. |
Type Parameters
Name | Description |
---|---|
T | The type of component to remove. |
Remarks
Removing a component changes an entity's archetype and results in the entity being moved to a different chunk.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before removing the component and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
SetArchetype(Entity, EntityArchetype)
Declaration
public void SetArchetype(Entity entity, EntityArchetype archetype)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | |
EntityArchetype | archetype |
SetChunkComponentData<T>(ArchetypeChunk, T)
Sets the value of a chunk component.
Declaration
public void SetChunkComponentData<T>(ArchetypeChunk chunk, T componentValue)
where T : struct, IComponentData
Parameters
Type | Name | Description |
---|---|---|
ArchetypeChunk | chunk | The chunk to modify. |
T | componentValue | The component data to set. |
Type Parameters
Name | Description |
---|---|
T | The component type. |
Remarks
A chunk component is common to all entities in a chunk. You can access a chunk IComponentData instance through either the chunk itself or through an entity stored in that chunk.
Exceptions
Type | Condition |
---|---|
ArgumentException | Thrown if the ArchetypeChunk object is invalid. |
SetComponentData<T>(Entity, T)
Sets the value of a component of an entity.
Declaration
public void SetComponentData<T>(Entity entity, T componentData)
where T : struct, IComponentData
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity. |
T | componentData | The data to set. |
Type Parameters
Name | Description |
---|---|
T | The component type. |
Exceptions
Type | Condition |
---|---|
ArgumentException | Thrown if the component type has no fields. |
SetEnabled(Entity, Boolean)
Enabled entities are processed by systems, disabled entities are not. Adds or removes the Disabled component. By default EntityQuery does not include entities containing the Disabled component.
If the entity was converted from a prefab and thus has a LinkedEntityGroup component, the entire group will enabled or disabled.
Declaration
public void SetEnabled(Entity entity, bool enabled)
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity to enable or disable |
Boolean | enabled | True if the entity should be enabled |
SetSharedComponentData<T>(Entity, T)
Sets the shared component of an entity.
Declaration
public void SetSharedComponentData<T>(Entity entity, T componentData)
where T : struct, ISharedComponentData
Parameters
Type | Name | Description |
---|---|---|
Entity | entity | The entity |
T | componentData | A shared component object containing the values to set. |
Type Parameters
Name | Description |
---|---|
T | The shared component type. |
Remarks
Changing a shared component value of an entity results in the entity being moved to a different chunk. The entity moves to a chunk with other entities that have the same shared component values. A new chunk is created if no chunk with the same archetype and shared component values currently exists.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before setting the component and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
SetSharedComponentData<T>(EntityQuery, T)
Sets the shared component of all entities in the query.
Declaration
public void SetSharedComponentData<T>(EntityQuery query, T componentData)
where T : struct, ISharedComponentData
Parameters
Type | Name | Description |
---|---|---|
EntityQuery | query | |
T | componentData | A shared component object containing the values to set. |
Type Parameters
Name | Description |
---|---|
T | The shared component type. |
Remarks
The component data stays in the same chunk, the internal shared component data indices will be adjusted.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before setting the component and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
SwapComponents(ArchetypeChunk, Int32, ArchetypeChunk, Int32)
Swaps the components of two entities.
Declaration
public void SwapComponents(ArchetypeChunk leftChunk, int leftIndex, ArchetypeChunk rightChunk, int rightIndex)
Parameters
Type | Name | Description |
---|---|---|
ArchetypeChunk | leftChunk | A chunk containing one of the entities to swap. |
Int32 | leftIndex | The index within the |
ArchetypeChunk | rightChunk | The chunk containing the other entity to swap. This chunk can be the same as
the |
Int32 | rightIndex | The index within the |
Remarks
The entities must have the same components. However, this function can swap the components of entities in different worlds, so they do not need to have identical archetype instances.
Important: This function creates a sync point, which means that the EntityManager waits for all currently running Jobs to complete before swapping the components and no additional Jobs can start before the function is finished. A sync point can cause a drop in performance because the ECS framework may not be able to make use of the processing power of all available cores.
UnlockChunk(NativeArray<ArchetypeChunk>)
Unlocks a set of chunks.
Declaration
public void UnlockChunk(NativeArray<ArchetypeChunk> chunks)
Parameters
Type | Name | Description |
---|---|---|
NativeArray<ArchetypeChunk> | chunks | An array of chunks to unlock. |
UnlockChunk(ArchetypeChunk)
Unlocks a chunk
Declaration
public void UnlockChunk(ArchetypeChunk chunk)
Parameters
Type | Name | Description |
---|---|---|
ArchetypeChunk | chunk | The chunk to unlock. |