The EntityComponentManager constructs, deletes, and returns components and entities. A component can be of any class which inherits from components::BaseComponent. More...

#include <gz/sim/EntityComponentManager.hh>

Public Member Functions
	EntityComponentManager ()
	Constructor. More...

	~EntityComponentManager ()
	Destructor. More...

msgs::SerializedState	ChangedState () const
	Get a message with the serialized state of all entities and components that are changing in the current iteration. More...

void	ChangedState (msgs::SerializedStateMap &_state) const
	Get a message with the serialized state of all entities and components that are changing in the current iteration. More...

template<typename ... ComponentTypeTs>
std::vector< Entity >	ChildrenByComponents (Entity _parent, const ComponentTypeTs &..._desiredComponents) const
	Get all entities which match the value of all the given components and are immediate children of a given parent entity. For example, the following will return a child of entity `parent` which has an int component equal to 123, and a string component equal to "name": More...

Entity	Clone (Entity _entity, Entity _parent, const std::string &_name, bool _allowRename)
	Clone an entity and its components. If the entity has any child entities, they will also be cloned. When cloning entities, the following rules apply: More...

template<typename ComponentTypeT >
ComponentTypeT *	Component (const Entity _entity)
	Get a mutable component assigned to an entity based on a component type. More...

template<typename ComponentTypeT >
const ComponentTypeT *	Component (const Entity _entity) const
	Get a component assigned to an entity based on a component type. More...

template<typename ComponentTypeT >
std::optional< typename ComponentTypeT::Type >	ComponentData (const Entity _entity) const
	Get the data from a component. More...

template<typename ComponentTypeT >
ComponentTypeT *	ComponentDefault (Entity _entity, const typename ComponentTypeT::Type &_default=typename ComponentTypeT::Type())
	Get a mutable component assigned to an entity based on a component type. If the component doesn't exist, create it and initialize with the given default value. More...

sim::ComponentState	ComponentState (const Entity _entity, const ComponentTypeId _typeId) const
	Get a component's state. More...

std::unordered_set< ComponentTypeId >	ComponentTypes (Entity _entity) const
	Get the type IDs of all components attached to an entity. More...

std::unordered_set< ComponentTypeId >	ComponentTypesWithPeriodicChanges () const
	Get the components types that are marked as periodic changes. More...

void	CopyFrom (const EntityComponentManager &_fromEcm)
	Copies the contents of `_from` into this object. More...

template<typename ComponentTypeT >
ComponentTypeT *	CreateComponent (const Entity _entity, const ComponentTypeT &_data)
	Create a component of a particular type. This will copy the _data parameter. More...

Entity	CreateEntity ()
	Creates a new Entity. More...

std::unordered_set< Entity >	Descendants (Entity _entity) const
	Get all entities which are descendants of a given entity, including the entity itself. More...

template<typename ... ComponentTypeTs>
void	Each (typename identity< std::function< bool(const Entity &_entity, ComponentTypeTs *...)>>::type _f)
	Get all entities which contain given component types, as well as the mutable components. Note that an entity marked for removal (but not processed yet) will be included in the list of entities iterated by this call. More...

template<typename ... ComponentTypeTs>
void	Each (typename identity< std::function< bool(const Entity &_entity, const ComponentTypeTs *...)>>::type _f) const
	Get all entities which contain given component types, as well as the components. Note that an entity marked for removal (but not processed yet) will be included in the list of entities iterated by this call. More...

template<typename... ComponentTypeTs>
void	EachNew (typename identity< std::function< bool(const Entity &_entity, ComponentTypeTs *...)>>::type _f)
	Get all newly created entities which contain given component types, as well as the components. This "newness" is cleared at the end of a simulation step. More...

template<typename... ComponentTypeTs>
void	EachNew (typename identity< std::function< bool(const Entity &_entity, const ComponentTypeTs *...)>>::type _f) const
	Get all newly created entities which contain given component types, as well as the components. This "newness" is cleared at the end of a simulation step. This is the const version. More...

template<typename ... ComponentTypeTs>
void	EachNoCache (typename identity< std::function< bool(const Entity &_entity, ComponentTypeTs *...)>>::type _f)
	A version of Each() that doesn't use a cache. The cached version, Each(), is preferred. Get all entities which contain given component types, as well as the mutable components. More...

template<typename ... ComponentTypeTs>
void	EachNoCache (typename identity< std::function< bool(const Entity &_entity, const ComponentTypeTs *...)>>::type _f) const
	A version of Each() that doesn't use a cache. The cached version, Each(), is preferred. Get all entities which contain given component types, as well as the components. More...

template<typename ... ComponentTypeTs>
void	EachRemoved (typename identity< std::function< bool(const Entity &_entity, const ComponentTypeTs *...)>>::type _f) const
	Get all entities which contain given component types and are about to be removed, as well as the components. More...

const EntityGraph &	Entities () const
	Get a graph with all the entities. Entities are vertices and edges point from parent to children. More...

template<typename ... ComponentTypeTs>
std::vector< Entity >	EntitiesByComponents (const ComponentTypeTs &..._desiredComponents) const
	Get all entities which match the value of all the given components. For example, the following will return the entities which have a name component equal to "camera" and a sensor component: More...

template<typename ... ComponentTypeTs>
Entity	EntityByComponents (const ComponentTypeTs &..._desiredComponents) const
	Get an entity which matches the value of all the given components. For example, the following will return the entity which has a name component equal to "name" and has a model component: More...

std::optional< Entity >	EntityByName (const std::string &_name) const
	Get an Entity based on a name component that is associated with the entity. More...

size_t	EntityCount () const
	Get the number of entities on the server. More...

bool	EntityHasComponentType (const Entity _entity, const ComponentTypeId &_typeId) const
	Check whether an entity has a specific component type. More...

bool	EntityMatches (Entity _entity, const std::set< ComponentTypeId > &_types) const
	Get whether an entity has all the given component types. More...

bool	HasComponentType (const ComponentTypeId _typeId) const
	Get whether a component type has ever been created. More...

bool	HasEntitiesMarkedForRemoval () const
	Get whether there are any entities marked to be removed. More...

bool	HasEntity (const Entity _entity) const
	Get whether an Entity exists. More...

bool	HasNewEntities () const
	Get whether there are new entities. More...

bool	HasOneTimeComponentChanges () const
	Get whether there are one-time component changes. These changes do not happen frequently and should be processed immediately. More...

bool	HasPeriodicComponentChanges () const
	Get whether there are periodic component changes. These changes may happen frequently and are processed periodically. More...

bool	HasRemovedComponents () const
	Return true if there are components marked for removal. More...

Entity	ParentEntity (const Entity _entity) const
	Get the first parent of the given entity. More...

void	PeriodicStateFromCache (msgs::SerializedStateMap &_state, const std::unordered_map< ComponentTypeId, std::unordered_set< Entity >> &_cache) const
	Populate a message with relevant changes to the state given a periodic change cache. More...

void	PinEntity (const Entity _entity, bool _recursive=true)
	Prevent an entity and optionally its children from being removed. More...

void	RebuildViews ()
	Rebuild all the views. This could be an expensive operation. More...

bool	RemoveComponent (const Entity _entity, const ComponentTypeId &_typeId)
	Remove a component from an entity based on a type id. More...

template<typename ComponentTypeT >
bool	RemoveComponent (Entity _entity)
	Remove a component from an entity based on a type. More...

void	RequestRemoveEntities ()
	Request to remove all entities. This will insert the request into a queue. The queue is processed toward the end of a simulation update step. More...

void	RequestRemoveEntity (const Entity _entity, bool _recursive=true)
	Request an entity deletion. This will insert the request into a queue. The queue is processed toward the end of a simulation update step. More...

void	ResetTo (const EntityComponentManager &_other)
	Given a diff, apply it to this ECM. Note that for removed entities, this would mark them for removal instead of actually removing the entities. More...

void	SetChanged (const Entity _entity, const ComponentTypeId _type, sim::ComponentState _c=ComponentState::OneTimeChange)
	Set the changed state of a component. More...

template<typename ComponentTypeT >
bool	SetComponentData (const Entity _entity, const typename ComponentTypeT::Type &_data)
	Set the data from a component. More...

void	SetEntityCreateOffset (uint64_t _offset)
	All future entities will have an id that starts at _offset. This can be used to avoid entity id collisions, such as during log playback. More...

bool	SetParentEntity (const Entity _child, const Entity _parent)
	Set the parent of an entity. More...

void	SetState (const msgs::SerializedState &_stateMsg)
	Set the absolute state of the ECM from a serialized message. Entities / components that are in the new state but not in the old one will be created. Entities / components that are marked as removed will be removed, but they won't be removed if they're not present in the state. More...

void	SetState (const msgs::SerializedStateMap &_stateMsg)
	Set the absolute state of the ECM from a serialized message. Entities / components that are in the new state but not in the old one will be created. Entities / components that are marked as removed will be removed, but they won't be removed if they're not present in the state. More...

msgs::SerializedState	State (const std::unordered_set< Entity > &_entities={}, const std::unordered_set< ComponentTypeId > &_types={}) const
	Get a message with the serialized state of the given entities and components. More...

void	State (msgs::SerializedStateMap &_state, const std::unordered_set< Entity > &_entities={}, const std::unordered_set< ComponentTypeId > &_types={}, bool _full=false) const
	Get a message with the serialized state of the given entities and components. More...

void	UnpinAllEntities ()
	Allow all previously pinned entities to be removed. More...

void	UnpinEntity (const Entity _entity, bool _recursive=true)
	Allow an entity, and optionally its children, previously marked as pinned to be removed. More...

void	UpdatePeriodicChangeCache (std::unordered_map< ComponentTypeId, std::unordered_set< Entity >> &) const
	Get a cache of components with periodic changes. More...

Static Public Member Functions
template<class Function , class... ComponentTypeTs>
static void	ForEach (Function _f, const ComponentTypeTs &... _components)
	Call a function for each parameter in a pack. More...

Protected Member Functions
void	ApplyEntityDiff (const EntityComponentManager &_other, const EntityComponentManagerDiff &_diff)
	Given an entity diff, apply it to this ECM. Note that for removed entities, this would mark them for removal instead of actually removing the entities. More...

void	ClearNewlyCreatedEntities ()
	Clear the list of newly added entities so that a call to EachAdded after this will have no entities to iterate. This function is protected to facilitate testing. More...

void	ClearRemovedComponents ()
	Clear the list of removed components so that a call to RemoveComponent doesn't make the list grow indefinitely. More...

EntityComponentManagerDiff	ComputeEntityDiff (const EntityComponentManager &_other) const

void	ProcessRemoveEntityRequests ()
	Process all entity remove requests. This will remove entities and their components. This function is protected to facilitate testing. More...

void	SetAllComponentsUnchanged ()
	Mark all components as not changed. More...

Detailed Description

The EntityComponentManager constructs, deletes, and returns components and entities. A component can be of any class which inherits from components::BaseComponent.

Constructor & Destructor Documentation

◆ EntityComponentManager()

EntityComponentManager ( )

Constructor.

◆ ~EntityComponentManager()

~EntityComponentManager ( )

Destructor.

Member Function Documentation

◆ ApplyEntityDiff()

void ApplyEntityDiff	(	const EntityComponentManager &	_other,
		const EntityComponentManagerDiff &	_diff
	)

protected

Given an entity diff, apply it to this ECM. Note that for removed entities, this would mark them for removal instead of actually removing the entities.

Parameters

[in] _other Original EntityComponentManager from which the diff was computed.

◆ ChangedState() [1/2]

msgs::SerializedState ChangedState ( ) const

Get a message with the serialized state of all entities and components that are changing in the current iteration.

This includes:

New entities and all of their components
Removed entities and all of their components
Entities which had a component added
Entities which had a component removed
Entities which had a component modified

The header of the message will not be populated, it is the responsibility of the caller to timestamp it before use.

◆ ChangedState() [2/2]

void ChangedState ( msgs::SerializedStateMap & _state ) const

Get a message with the serialized state of all entities and components that are changing in the current iteration.

This includes:

New entities and all of their components
Removed entities and all of their components
Entities which had a component added
Entities which had a component removed
Entities which had a component modified

Parameters

[in] _state New serialized state.

The header of the message will not be populated, it is the responsibility of the caller to timestamp it before use.

◆ ChildrenByComponents()

std::vector<Entity> ChildrenByComponents	(	Entity	_parent,
		const ComponentTypeTs &...	_desiredComponents
	)		const

Get all entities which match the value of all the given components and are immediate children of a given parent entity. For example, the following will return a child of entity parent which has an int component equal to 123, and a string component equal to "name":

auto entity = ChildrenByComponents(parent, 123, std::string("name"));

Component type must have inequality operator.

Parameters

[in]	_parent	Entity which should be an immediate parent of the returned entity.
[in]	_desiredComponents	All the components which must match.

Returns: All matching entities, or an empty vector if no child entity has the exact components.

◆ ClearNewlyCreatedEntities()

void ClearNewlyCreatedEntities ( )

protected

Clear the list of newly added entities so that a call to EachAdded after this will have no entities to iterate. This function is protected to facilitate testing.

◆ ClearRemovedComponents()

void ClearRemovedComponents ( )

protected

Clear the list of removed components so that a call to RemoveComponent doesn't make the list grow indefinitely.

◆ Clone()

Entity Clone	(	Entity	_entity,
		Entity	_parent,
		const std::string &	_name,
		bool	_allowRename
	)

Clone an entity and its components. If the entity has any child entities, they will also be cloned. When cloning entities, the following rules apply:

The name component of a cloned entity will consist of a unique name, since all entities should have a unique name.
Cloned entities that have a canonical link will have their canonical link set to the cloned canonical link, not the original canonical link.
Child entities that are cloned will have their parent set to the cloned parent entity.
Cloned joints with parent/child links will have their parent and child links set to the cloned parent/child links.

Aside from the changes listed above, all other cloned components remain unchanged. Currently, cloning detachable joints is not supported.

Parameters

[in]	_entity	The entity to clone.
[in]	_parent	The parent of the cloned entity. Set this to kNullEntity if the cloned entity should not have a parent.
[in]	_name	The name that should be given to the cloned entity. Set this to an empty string if the cloned entity name should be auto-generated to something unique.
[in]	_allowRename	True if _name can be modified to be a unique name if it isn't already a unique name. False if _name cannot be modified to be a unique name. If _allowRename is set to False, and _name is not unique, _entity will not be cloned. If _name is an empty string, _allowRename is ignored since the cloned entity will have an auto-generated unique name.

Returns: The cloned entity, which will have a unique name. kNullEntity is returned if cloning failed. Failure could occur if _entity does not exist, or if a unique name could not be generated for the entity to be cloned.

See also: Clone

◆ Component() [1/2]

ComponentTypeT* Component ( const Entity _entity )

Get a mutable component assigned to an entity based on a component type.

Parameters

[in] _entity The entity.

Returns: The component of the specified type assigned to specified Entity, or nullptr if the component could not be found.

◆ Component() [2/2]

const ComponentTypeT* Component ( const Entity _entity ) const

Get a component assigned to an entity based on a component type.

Parameters

[in] _entity The entity.

Returns: The component of the specified type assigned to specified Entity, or nullptr if the component could not be found.

Referenced by gz::sim::enableComponent(), and Pose3d::UpdateView().

◆ ComponentData()

std::optional<typename ComponentTypeT::Type> ComponentData ( const Entity _entity ) const

Get the data from a component.

If the component type doesn't hold any data, this won't compile.
If the entity doesn't have that component, it will return nullopt.
If the entity has the component, return its data.
Parameters

[in] _entity The entity.

Template Parameters

ComponentTypeT Component type

Returns
The data of the component of the specified type assigned to specified Entity, or nullptr if the component could not be found.

◆ ComponentDefault()

ComponentTypeT* ComponentDefault	(	Entity	_entity,
		const typename ComponentTypeT::Type &	_default = `typename ComponentTypeT::Type()`
	)

Get a mutable component assigned to an entity based on a component type. If the component doesn't exist, create it and initialize with the given default value.

Parameters

[in]	_entity	The entity.
[in]	_default	The value that should be used to construct the component in case the component doesn't exist.

Returns: The component of the specified type assigned to the specified entity. If _entity does not exist, nullptr is returned.

◆ ComponentState()

sim::ComponentState ComponentState	(	const Entity	_entity,
		const ComponentTypeId	_typeId
	)		const

Get a component's state.

Parameters

[in]	_entity	Entity that contains the component.
[in]	_typeId	Component type ID.

Returns: Component's current state

◆ ComponentTypes()

std::unordered_set<ComponentTypeId> ComponentTypes ( Entity _entity ) const

Get the type IDs of all components attached to an entity.

Parameters

[in] _entity Entity to check.

Returns: All the component type IDs.

◆ ComponentTypesWithPeriodicChanges()

std::unordered_set<ComponentTypeId> ComponentTypesWithPeriodicChanges ( ) const

Get the components types that are marked as periodic changes.

Returns: All the components that at least one entity marked as periodic changes.

◆ ComputeEntityDiff()

EntityComponentManagerDiff ComputeEntityDiff ( const EntityComponentManager & _other ) const

protected

Compute the diff between this EntityComponentManager and _other at the entity level. This does not compute the diff between components of an entity.

If an entity is in _other, but not in this, insert the entity as an "added" entity.
If an entity is in this, but not in other, insert the entity as a "removed" entity.
Returns
Data structure containing the added and removed entities

◆ CopyFrom()

void CopyFrom ( const EntityComponentManager & _fromEcm )

Copies the contents of _from into this object.

Note: This is a member function instead of a copy constructor so that it can have additional parameters if the need arises in the future. Additionally, not every data member is copied making its behavior different from what would be expected from a copy constructor.

Parameters

[in] _from Object to copy from

◆ CreateComponent()

ComponentTypeT* CreateComponent	(	const Entity	_entity,
		const ComponentTypeT &	_data
	)

Create a component of a particular type. This will copy the _data parameter.

Parameters

[in]	_entity	The entity that will be associated with the component.
[in]	_data	Data used to construct the component.

Returns: A pointer to the component that was created. nullptr is returned if the component was not able to be created. If _entity does not exist, nullptr will be returned.

Referenced by gz::sim::enableComponent().

◆ CreateEntity()

Entity CreateEntity ( )

Creates a new Entity.

Returns: An id for the Entity, or kNullEntity on failure.

◆ Descendants()

std::unordered_set<Entity> Descendants ( Entity _entity ) const

Get all entities which are descendants of a given entity, including the entity itself.

Parameters

[in] _entity Entity whose descendants we want.

Returns: All child entities recursively, including _entity. It will be empty if the entity doesn't exist.

◆ Each() [1/2]

void Each ( typename identity< std::function< bool(const Entity &_entity, ComponentTypeTs *...)>>::type _f )

Get all entities which contain given component types, as well as the mutable components. Note that an entity marked for removal (but not processed yet) will be included in the list of entities iterated by this call.

Parameters

[in] _f Callback function to be called for each matching entity. The function parameter are all the desired component types, in the order they're listed on the template. The callback function can return false to stop subsequent calls to the callback, otherwise a true value should be returned.

Template Parameters

ComponentTypeTs All the desired mutable component types.

Warning: This function should not be called outside of System's PreUpdate, Update, or PostUpdate callbacks.

◆ Each() [2/2]

void Each ( typename identity< std::function< bool(const Entity &_entity, const ComponentTypeTs *...)>>::type _f ) const

Get all entities which contain given component types, as well as the components. Note that an entity marked for removal (but not processed yet) will be included in the list of entities iterated by this call.

Parameters

[in] _f Callback function to be called for each matching entity. The function parameter are all the desired component types, in the order they're listed on the template. The callback function can return false to stop subsequent calls to the callback, otherwise a true value should be returned.

Template Parameters

ComponentTypeTs All the desired component types.

Warning: This function should not be called outside of System's PreUpdate, Update, or PostUpdate callbacks.

Referenced by CanonicalLinkModelTracker::AddAllModels().

◆ EachNew() [1/2]

void EachNew ( typename identity< std::function< bool(const Entity &_entity, ComponentTypeTs *...)>>::type _f )

Get all newly created entities which contain given component types, as well as the components. This "newness" is cleared at the end of a simulation step.

Parameters

[in] _f Callback function to be called for each matching entity. The function parameter are all the desired component types, in the order they're listed on the template. The callback function can return false to stop subsequent calls to the callback, otherwise a true value should be returned.

Template Parameters

ComponentTypeTs All the desired component types.

Warning: Since entity creation occurs during PreUpdate, this function should not be called in a System's PreUpdate callback (it's okay to call this function in the Update callback). If you need to call this function in a system's PostUpdate callback, you should use the const version of this method.

Referenced by CanonicalLinkModelTracker::AddNewModels().

◆ EachNew() [2/2]

void EachNew ( typename identity< std::function< bool(const Entity &_entity, const ComponentTypeTs *...)>>::type _f ) const

Get all newly created entities which contain given component types, as well as the components. This "newness" is cleared at the end of a simulation step. This is the const version.

Parameters

[in] _f Callback function to be called for each matching entity. The function parameter are all the desired component types, in the order they're listed on the template. The callback function can return false to stop subsequent calls to the callback, otherwise a true value should be returned.

Template Parameters

ComponentTypeTs All the desired component types.

Warning: Since entity creation occurs during PreUpdate, this function should not be called in a System's PreUpdate callback (it's okay to call this function in the Update or PostUpdate callback).

◆ EachNoCache() [1/2]

void EachNoCache ( typename identity< std::function< bool(const Entity &_entity, ComponentTypeTs *...)>>::type _f )

A version of Each() that doesn't use a cache. The cached version, Each(), is preferred. Get all entities which contain given component types, as well as the mutable components.

Parameters

[in] _f Callback function to be called for each matching entity. The function parameter are all the desired component types, in the order they're listed on the template. The callback function can return false to stop subsequent calls to the callback, otherwise a true value should be returned.

Template Parameters

ComponentTypeTs All the desired mutable component types.

Warning: This function should not be called outside of System's PreUpdate, Update, or PostUpdate callbacks.

◆ EachNoCache() [2/2]

void EachNoCache ( typename identity< std::function< bool(const Entity &_entity, const ComponentTypeTs *...)>>::type _f ) const

A version of Each() that doesn't use a cache. The cached version, Each(), is preferred. Get all entities which contain given component types, as well as the components.

Parameters

[in] _f Callback function to be called for each matching entity. The function parameter are all the desired component types, in the order they're listed on the template. The callback function can return false to stop subsequent calls to the callback, otherwise a true value should be returned.

Template Parameters

ComponentTypeTs All the desired component types.

Warning: This function should not be called outside of System's PreUpdate, Update, or PostUpdate callbacks.

◆ EachRemoved()

void EachRemoved ( typename identity< std::function< bool(const Entity &_entity, const ComponentTypeTs *...)>>::type _f ) const

Get all entities which contain given component types and are about to be removed, as well as the components.

Parameters

[in] _f Callback function to be called for each matching entity. The function parameter are all the desired component types, in the order they're listed on the template. The callback function can return false to stop subsequent calls to the callback, otherwise a true value should be returned.

Template Parameters

ComponentTypeTs All the desired component types.

Warning: This function should not be called outside of System's PostUpdate callback.

◆ Entities()

const EntityGraph& Entities ( ) const

Get a graph with all the entities. Entities are vertices and edges point from parent to children.

Returns: Entity graph.

◆ EntitiesByComponents()

std::vector<Entity> EntitiesByComponents ( const ComponentTypeTs &... _desiredComponents ) const

Get all entities which match the value of all the given components. For example, the following will return the entities which have a name component equal to "camera" and a sensor component:

auto entities = EntitiesByComponents(components::Name("camera"), components::Sensor());

Component type must have inequality operator.

Parameters

[in] _desiredComponents All the components which must match.

Returns: All matching entities, or an empty vector if no child entity has the exact components.

◆ EntityByComponents()

Entity EntityByComponents ( const ComponentTypeTs &... _desiredComponents ) const

Get an entity which matches the value of all the given components. For example, the following will return the entity which has a name component equal to "name" and has a model component:

auto entity = EntityByComponents(components::Name("name"), components::Model());

Component type must have inequality operator.

Parameters

[in] _desiredComponents All the components which must match.

Returns: Entity or kNullEntity if no entity has the exact components.

◆ EntityByName()

std::optional<Entity> EntityByName ( const std::string & _name ) const

Get an Entity based on a name component that is associated with the entity.

Parameters

[in] _name Name associated with the Entity

Returns: The Entity, if an Entity with the given name exists, otherwise return std::nullopt.

◆ EntityCount()

size_t EntityCount ( ) const

Get the number of entities on the server.

Returns: Entity count.

◆ EntityHasComponentType()

bool EntityHasComponentType	(	const Entity	_entity,
		const ComponentTypeId &	_typeId
	)		const

Check whether an entity has a specific component type.

Parameters

[in]	_entity	The entity to check.
[in]	_typeId	Component type id to check.

Returns: True if the entity exists and has at least one component with the provided type.

◆ EntityMatches()

bool EntityMatches	(	Entity	_entity,
		const std::set< ComponentTypeId > &	_types
	)		const

Get whether an entity has all the given component types.

Parameters

[in]	_entity	The entity to check.
[in]	_types	Component types to check that the Entity has.

Returns: True if the given entity has all the given types.

◆ ForEach()

static void ForEach	(	Function	_f,
		const ComponentTypeTs &...	_components
	)

static

Call a function for each parameter in a pack.

Parameters

[in]	_f	Function to be called.
[in]	_components	Parameters which should be passed to the function.

◆ HasComponentType()

bool HasComponentType ( const ComponentTypeId _typeId ) const

Get whether a component type has ever been created.

Parameters

[in] _typeId ID of the component type to check.

Returns: True if the provided _typeId has been created.

◆ HasEntitiesMarkedForRemoval()

bool HasEntitiesMarkedForRemoval ( ) const

Get whether there are any entities marked to be removed.

Returns: True if there are entities marked to be removed.

◆ HasEntity()

bool HasEntity ( const Entity _entity ) const

Get whether an Entity exists.

Parameters

[in] _entity Entity to confirm.

Returns: True if the Entity exists.

◆ HasNewEntities()

bool HasNewEntities ( ) const

Get whether there are new entities.

Returns: True if there are new entities.

◆ HasOneTimeComponentChanges()

bool HasOneTimeComponentChanges ( ) const

Get whether there are one-time component changes. These changes do not happen frequently and should be processed immediately.

Returns: True if there are any components with one-time changes.

◆ HasPeriodicComponentChanges()

bool HasPeriodicComponentChanges ( ) const

Get whether there are periodic component changes. These changes may happen frequently and are processed periodically.

Returns: True if there are any components with periodic changes.

◆ HasRemovedComponents()

bool HasRemovedComponents ( ) const

Return true if there are components marked for removal.

Returns: True if there are components marked for removal.

◆ ParentEntity()

Entity ParentEntity ( const Entity _entity ) const

Get the first parent of the given entity.

Entities are not expected to have multiple parents. TODO(louise) Either prevent multiple parents or provide full support for multiple parents.

Parameters

[in] _entity Entity.

Returns: The parent entity or kNullEntity if there's none.

◆ PeriodicStateFromCache()

void PeriodicStateFromCache	(	msgs::SerializedStateMap &	_state,
		const std::unordered_map< ComponentTypeId, std::unordered_set< Entity >> &	_cache
	)		const

Populate a message with relevant changes to the state given a periodic change cache.

The header of the message will not be populated, it is the responsibility of the caller to timestamp it before use. Additionally, changes such as addition or removal will not be populated.

Parameters

[in,out]	_state	The serialized state message to populate.
[in]	_cache	A map of entities and components to serialize.

See also: EntityComponenetManager::UpdatePeriodicChangeCache

◆ PinEntity()

void PinEntity	(	const Entity	_entity,
		bool	_recursive = `true`
	)

Prevent an entity and optionally its children from being removed.

This function can be useful when seek operations during log playback are used in conjunction with spawned entities. For example, you may want to record a video based on a log file using a headless simulation instance. This requires a camera sensor which would be spawned during log playback. If a seek backward in time is performed during log playback, then the spawned camera would be removed. Use this function to prevent the camera from automatic removal.

Parameters

[in]	_entity	Entity to be pinned.
[in]	_recursive	Whether to recursively pin all child entities. True by default.

◆ ProcessRemoveEntityRequests()

void ProcessRemoveEntityRequests ( )

protected

Process all entity remove requests. This will remove entities and their components. This function is protected to facilitate testing.

◆ RebuildViews()

void RebuildViews ( )

Rebuild all the views. This could be an expensive operation.

◆ RemoveComponent() [1/2]

bool RemoveComponent	(	const Entity	_entity,
		const ComponentTypeId &	_typeId
	)

Remove a component from an entity based on a type id.

Parameters

[in]	_entity	The entity.
[in]	_typeId	Component's type Id.

Returns: True if the entity and component existed and the component was removed.

Referenced by gz::sim::enableComponent().

◆ RemoveComponent() [2/2]

bool RemoveComponent ( Entity _entity )

Remove a component from an entity based on a type.

Parameters

[in] _entity The entity.

Template Parameters

Component type.

Returns: True if the entity and component existed and the component was removed.

◆ RequestRemoveEntities()

void RequestRemoveEntities ( )

Request to remove all entities. This will insert the request into a queue. The queue is processed toward the end of a simulation update step.

◆ RequestRemoveEntity()

void RequestRemoveEntity	(	const Entity	_entity,
		bool	_recursive = `true`
	)

Request an entity deletion. This will insert the request into a queue. The queue is processed toward the end of a simulation update step.

It is recommended that systems don't call this function directly, and instead use the sim::SdfEntityCreator class to remove entities.

Parameters

[in]	_entity	Entity to be removed.
[in]	_recursive	Whether to recursively delete all child entities. True by default.

◆ ResetTo()

void ResetTo ( const EntityComponentManager & _other )

Given a diff, apply it to this ECM. Note that for removed entities, this would mark them for removal instead of actually removing the entities.

Parameters

[in] _other Original EntityComponentManager from which the diff was computed.

◆ SetAllComponentsUnchanged()

void SetAllComponentsUnchanged ( )

protected

Mark all components as not changed.

◆ SetChanged()

void SetChanged	(	const Entity	_entity,
		const ComponentTypeId	_type,
		sim::ComponentState	_c = `ComponentState::OneTimeChange`
	)

Set the changed state of a component.

Parameters

[in]	_entity	The entity.
[in]	_type	Type of the component.
[in]	_c	Changed state value, defaults to one-time-change.

◆ SetComponentData()

bool SetComponentData	(	const Entity	_entity,
		const typename ComponentTypeT::Type &	_data
	)

Set the data from a component.

If the component type doesn't hold any data, this won't compile.
If the entity doesn't have that component, the component will be created.
If the entity has the component, its data will be updated.
Parameters

[in] _entity The entity.

[in] _data New component data

Template Parameters

ComponentTypeT Component type

Returns
True if data has changed. It will always be true if the data type doesn't have an equality operator.

◆ SetEntityCreateOffset()

void SetEntityCreateOffset ( uint64_t _offset )

All future entities will have an id that starts at _offset. This can be used to avoid entity id collisions, such as during log playback.

Parameters

[in] _offset Offset value.

◆ SetParentEntity()

bool SetParentEntity	(	const Entity	_child,
		const Entity	_parent
	)

Set the parent of an entity.

It is recommended that systems don't call this function directly, and instead use the sim::SdfEntityCreator class to create entities that have the correct parent-child relationship.

Parameters

[in]	_child	Entity to set the parent
[in]	_parent	Entity which should be an immediate parent _child entity.

Returns: True if successful. Will fail if entities don't exist.

◆ SetState() [1/2]

void SetState ( const msgs::SerializedState & _stateMsg )

Set the absolute state of the ECM from a serialized message. Entities / components that are in the new state but not in the old one will be created. Entities / components that are marked as removed will be removed, but they won't be removed if they're not present in the state.

The header of the message will not be handled, it is the responsibility of the caller to use the timestamp.

Parameters

[in] _stateMsg Message containing state to be set.

◆ SetState() [2/2]

void SetState ( const msgs::SerializedStateMap & _stateMsg )

Set the absolute state of the ECM from a serialized message. Entities / components that are in the new state but not in the old one will be created. Entities / components that are marked as removed will be removed, but they won't be removed if they're not present in the state.

The header of the message will not be handled, it is the responsibility of the caller to use the timestamp.

Parameters

[in] _stateMsg Message containing state to be set.

◆ State() [1/2]

msgs::SerializedState State	(	const std::unordered_set< Entity > &	_entities = `{}`,
		const std::unordered_set< ComponentTypeId > &	_types = `{}`
	)		const

Get a message with the serialized state of the given entities and components.

The header of the message will not be populated, it is the responsibility of the caller to timestamp it before use.

Parameters

[in]	_entities	Entities to be serialized. Leave empty to get all entities.
[in]	_types	Type ID of components to be serialized. Leave empty to get all components.

◆ State() [2/2]

void State	(	msgs::SerializedStateMap &	_state,
		const std::unordered_set< Entity > &	_entities = `{}`,
		const std::unordered_set< ComponentTypeId > &	_types = `{}`,
		bool	_full = `false`
	)		const

Get a message with the serialized state of the given entities and components.

The header of the message will not be populated, it is the responsibility of the caller to timestamp it before use.

Parameters

[out]	_state	The serialized state message to populate.
[in]	_entities	Entities to be serialized. Leave empty to get all entities.
[in]	_types	Type ID of components to be serialized. Leave empty to get all components.
[in]	_full	True to get all the entities and components. False will get only components and entities that have changed.

◆ UnpinAllEntities()

void UnpinAllEntities ( )

Allow all previously pinned entities to be removed.

See also: void PinEntity(const Entity, bool)

◆ UnpinEntity()

void UnpinEntity	(	const Entity	_entity,
		bool	_recursive = `true`
	)

Allow an entity, and optionally its children, previously marked as pinned to be removed.

Parameters

[in]	_entity	Entity to be unpinned.
[in]	_recursive	Whether to recursively unpin all child entities. True by default.

See also: void PinEntity(const Entity, bool)

◆ UpdatePeriodicChangeCache()

void UpdatePeriodicChangeCache ( std::unordered_map< ComponentTypeId, std::unordered_set< Entity >> & ) const

Get a cache of components with periodic changes.

Parameters

[in,out] _changes A list of components with the latest periodic changes. If a component has a periodic change, it is added to the hash map. It the component or entity was removed, it is removed from the hashmap. This way the hashmap stores a list of components and entities which have had periodic changes in the past and still exist within the ECM.

See also: EntityComponentManager::PeriodicStateFromCache

The documentation for this class was generated from the following file:

gz/sim/EntityComponentManager.hh

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ EntityComponentManager()

◆ ~EntityComponentManager()

Member Function Documentation

◆ ApplyEntityDiff()

◆ ChangedState() [1/2]

◆ ChangedState() [2/2]

◆ ChildrenByComponents()

◆ ClearNewlyCreatedEntities()

◆ ClearRemovedComponents()

◆ Clone()

◆ Component() [1/2]

◆ Component() [2/2]

◆ ComponentData()

◆ ComponentDefault()

◆ ComponentState()

◆ ComponentTypes()

◆ ComponentTypesWithPeriodicChanges()

◆ ComputeEntityDiff()

◆ CopyFrom()

◆ CreateComponent()

◆ CreateEntity()

◆ Descendants()

◆ Each() [1/2]

◆ Each() [2/2]

◆ EachNew() [1/2]

◆ EachNew() [2/2]

◆ EachNoCache() [1/2]

◆ EachNoCache() [2/2]

◆ EachRemoved()

◆ Entities()

◆ EntitiesByComponents()

◆ EntityByComponents()

◆ EntityByName()

◆ EntityCount()

◆ EntityHasComponentType()

◆ EntityMatches()

◆ ForEach()

◆ HasComponentType()

◆ HasEntitiesMarkedForRemoval()

◆ HasEntity()

◆ HasNewEntities()

◆ HasOneTimeComponentChanges()

◆ HasPeriodicComponentChanges()

◆ HasRemovedComponents()

◆ ParentEntity()

◆ PeriodicStateFromCache()

◆ PinEntity()

◆ ProcessRemoveEntityRequests()

◆ RebuildViews()

◆ RemoveComponent() [1/2]

◆ RemoveComponent() [2/2]

◆ RequestRemoveEntities()

◆ RequestRemoveEntity()

◆ ResetTo()

◆ SetAllComponentsUnchanged()

◆ SetChanged()

◆ SetComponentData()

◆ SetEntityCreateOffset()

◆ SetParentEntity()

◆ SetState() [1/2]

◆ SetState() [2/2]

◆ State() [1/2]

◆ State() [2/2]

◆ UnpinAllEntities()

◆ UnpinEntity()

◆ UpdatePeriodicChangeCache()