Class entity_handle

Class Documentation

class legion::core::ecs::entity_handle

Serializable handle for executing operations on entities. This class only stores a reference to the registry and the id of the entity.

Public Functions

inline entity_handle(id_type id) noexcept

Main constructor for constructing a valid entity handle.

inline entity_handle() noexcept

Constructor for constructing an invalid entity handle.

Note

Should only be used to create temporary handles. Allows use of entity handle in containers together with copy constructor.

inline entity_handle(const entity_handle &other) noexcept

Copy constructor (DOES NOT CREATE NEW ENTITY, both handles will reference the same entity).

Note

Allows use of entity handle in containers together with default invalid entity constructor.

entity_handle &operator=(const entity_handle &other) noexcept

Copy assignment. Exists for the same reasons as the copy constructor. legion::core::ecs::entity_handle::entity_handle(const legion::core::ecs::entity& other)

std::string get_name() const noexcept
void set_name(const std::string &name)
entity_handle clone(bool keep_parent = true, bool clone_children = true, bool clone_components = true) const

Clones an entity.

Return

entity_handle A handle to the copied entity.

Parameters
  • keep_parent: If true sets the parent of the cloned entity to the same parent as the source [default: true]

  • clone_children: If true copies all the children of the entity as well. [default: true]

  • clone_components: If true copies all the components of the entity. [default: true]

hashed_sparse_set<id_type> component_composition() const

Returns the type id’s of the components this entity contains.

Return

hashed_sparse_set<id_type>& Sparse map with component type id as both the key as well as the value. (behaves as sparse_set with hash table)

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

inline operator id_type() const

Cast to id_type returns the id of the entity this handle references.

Return

id_type If the handle is valid it will return the entity id, otherwise invalid_id.

inline bool operator==(const entity_handle &other) const
inline bool operator!=(const entity_handle &other) const
inline operator bool() const
id_type get_id() const

Returns the id of the entity this handle references.

Return

id_type If the handle is valid it will return the entity id, otherwise invalid_id.

entity_set children() const

Returns hashed sparse set with all children of this entity.

entity_handle get_parent() const

Returns entity handle to parent entity.

Return

entity_handle Entity handle that either points to the parent entity or is invalid if the entity doesn’t have a parent.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

void set_parent(id_type newParent, bool addHierarchyIfAbsent = true)

Set parent of entity.

Note

Will remove as child from parent.

Parameters
  • newParent: Id of the entity you wish to set as the parent. (invalid_id if you wish to remove parent)

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

void serialize(cereal::JSONOutputArchive &oarchive)

serializes the entity depending on its archive

Note

Will only be called when said entity is serializes through an archive.

Parameters
  • oarchive: template<typename Archive>

void serialize(cereal::BinaryOutputArchive &oarchive)
void serialize(cereal::JSONInputArchive &oarchive)
void serialize(cereal::BinaryInputArchive &oarchive)
entity_handle operator[](index_type index) const

Get child of the entity at a certain index.

Exceptions
  • std::out_of_range: Thrown when index is more than or equal to the child count.

  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

entity_handle get_child(index_type index) const

Get child of the entity at a certain index.

Exceptions
  • std::out_of_range: Thrown when index is more than or equal to the child count.

  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

size_type child_count() const

Get amount of children the referenced entity has.

Return

size_type

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

void add_child(id_type childId)

Add child to entity.

Note

Will change parent of the entity to add as child.

Parameters
  • childId: Id of the entity you wish to add as a child.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

void remove_child(id_type childId)

Remove child from entity.

Note

Will remove parent of the entity to remove as child.

Parameters
  • childId: Id of the entity you wish to remove as a child.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

template<typename component_type>
inline bool has_component() const

Check if entity contains a certain component.

Template Parameters
  • component_type: Type of component to check for.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

template<typename component_type, typename ...component_types, typename = doesnt_inherit_from<component_type, archetype_base>>
bool has_components() const

Check if entity contains a certain components.

Template Parameters
  • component_type: First type of component to check for.

  • component_types: The rest of the types of components to check for.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

template<typename archetype_type, typename = inherits_from<archetype_type, archetype_base>>
bool has_components() const

Check if entity contains the components of a certain archetype.

Template Parameters
  • archetype_type: The type of archetype to check for.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

bool has_component(id_type componentTypeId) const

Check if entity contains a certain component.

Parameters
  • componentTypeId: Type id of component to check for.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

component_handle_base get_component_handle(id_type componentTypeId)

Get component handle of a certain component.

Return

component_handle_base Valid component handle if the entity has the component, invalid handle if the entity doesn’t have the component.

Note

component_handle_base needs to be force_cast to component_handle<T> in order to be usable.

Parameters
  • componentTypeId: Type id of component to fetch.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

const component_handle_base get_component_handle(id_type componentTypeId) const
template<typename component_type>
inline component_handle<component_type> get_component_handle()

Get component handle of a certain component.

Return

component_handle<component_type> Valid component handle if the entity has the component, invalid handle if the entity doesn’t have the component.

Template Parameters
  • component_type: Type of component to fetch.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

template<typename component_type>
inline const component_handle<component_type> get_component_handle() const
template<typename component_type, typename ...component_types, typename = doesnt_inherit_from<component_type, archetype_base>>
auto get_component_handles() const

Get component handles of certain components.

Return

Tuple with all the handles.

Template Parameters
  • component_type: First type of component to fetch.

  • component_types: The rest of the types of components to fetch.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

template<typename archetype_type, typename = inherits_from<archetype_type, archetype_base>>
auto get_component_handles() const

Get component handles of all components of a certain archetype.

Return

Tuple with all the handles.

Template Parameters
  • archetype_type: The type of archetype to fetch the components of.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

template<typename component_type>
inline component_type read_component() const

Shortcut to component_handle::read.

template<typename component_type>
inline void write_component(component_type &&value)

Shortcut to component_handle::write.

template<typename component_type>
inline void write_component(const component_type &value)

Shortcut to component_handle::write.

component_handle_base add_component(id_type componentTypeId)

Add component to the entity.

Return

component_handle_base Valid component handle base for the newly created component.

Note

component_handle_base needs to be force_cast to component_handle<T> in order to be usable.

Parameters
  • componentTypeId: Type id of component to add.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

  • legion_unknown_component_error: Thrown when the component type is unknown.

component_handle_base add_component(id_type componentTypeId, void *value)

Add component to the entity.

Return

component_handle_base Valid component handle base for the newly created component.

Note

component_handle_base needs to be force_cast to component_handle<T> in order to be usable.

Parameters
  • componentTypeId: Type id of component to add.

  • value: Pointer to component_type that has the starting value you require.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

  • legion_unknown_component_error: Thrown when the component type is unknown.

template<typename component_type>
inline component_handle<component_type> add_component()

Add component to the entity.

Return

component_handle<component_type> Valid component handle for the newly created component.

Template Parameters
  • component_type: Type of component to add.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

  • legion_unknown_component_error: Thrown when the component type is unknown.

template<typename component_type>
inline component_handle<std::remove_reference_t<component_type>> add_component(component_type &&value)

Add component to the entity.

Return

component_handle<component_type> Valid component handle for the newly created component.

Parameters
  • value: Starting value of the component.

Template Parameters
  • component_type: Type of component to add.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

  • legion_unknown_component_error: Thrown when the component type is unknown.

template<typename component_type>
inline component_handle<std::remove_reference_t<component_type>> add_component(const component_type &value)

Add component to the entity.

Return

component_handle<component_type> Valid component handle for the newly created component.

Parameters
  • value: Starting value of the component.

Template Parameters
  • component_type: Type of component to add.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

  • legion_unknown_component_error: Thrown when the component type is unknown.

template<typename component_type, typename ...component_types, typename = doesnt_inherit_from<component_type, archetype_base>>
auto add_components()

Add multiple components to the entity.

Return

Tuple with all the handles.

Template Parameters
  • component_type: First type of component to add.

  • component_types: The rest of the types of components to add.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

  • legion_unknown_component_error: Thrown when the component type is unknown.

template<typename archetype_type, typename = inherits_from<archetype_type, archetype_base>>
auto add_components()

Add multiple components to the entity through the use of an archetype.

Return

Tuple with all the handles.

Template Parameters
  • archetype_type: The type of archetype to add the components of.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

  • legion_unknown_component_error: Thrown when the component type is unknown.

template<typename component_type, typename ...component_types, typename = doesnt_inherit_from<component_type, archetype_base>>
auto add_components(component_type &&value, component_types&&... values)

Add multiple components to the entity.

Return

Tuple with all the handles.

Template Parameters
  • component_type: First type of component to add.

  • component_types: The rest of the types of components to add.

Parameters
  • value: Starting value of the first component.

  • values...: Starting values of the other components.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

  • legion_unknown_component_error: Thrown when the component type is unknown.

template<typename component_type, typename ...component_types, typename = doesnt_inherit_from<component_type, archetype_base>>
auto add_components(component_type &value, component_types&... values)

Add multiple components to the entity.

Return

Tuple with all the handles.

Template Parameters
  • component_type: First type of component to add.

  • component_types: The rest of the types of components to add.

Parameters
  • value: Starting value of the first component.

  • values...: Starting values of the other components.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

  • legion_unknown_component_error: Thrown when the component type is unknown.

template<typename archetype_type, typename ...component_types, typename = inherits_from<archetype_type, archetype_base>>
auto add_components(component_types&&... values)

Add multiple components to the entity through the use of an archetype.

Return

Tuple with all the handles.

Template Parameters
  • archetype_type: The type of archetype to add the components of.

Parameters
  • values...: Starting values of the components.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

  • legion_unknown_component_error: Thrown when the component type is unknown.

void remove_component(id_type componentTypeId)

Remove component from entity.

Note

Nothing will happen if the entity doesn’t have this component.

Parameters
  • componentTypeId: Type id of component to remove.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

  • legion_unknown_component_error: Thrown when the component type is unknown.

template<typename component_type>
inline void remove_component()

Remove component from entity.

Note

Nothing will happen if the entity doesn’t have this component.

Template Parameters
  • component_type: Type of component to remove.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

  • legion_unknown_component_error: Thrown when the component type is unknown.

template<typename component_type, typename ...component_types, typename = doesnt_inherit_from<component_type, archetype_base>>
void remove_components()

Remove multiple components from entity.

Note

Nothing will happen if the entity doesn’t have a component.

Template Parameters
  • component_type: Type of the first component to remove.

  • component_types: Types of the other components to remove.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

  • legion_unknown_component_error: Thrown when the component type is unknown.

template<typename archetype_type, typename = inherits_from<archetype_type, archetype_base>>
void remove_components()

Remove multiple components from entity through an archetype.

Note

Nothing will happen if the entity doesn’t have a component.

Template Parameters
  • archetype_type: Type of the archetype with the components to remove.

Exceptions
  • legion_invalid_entity_error: Thrown when handle’s registry reference is invalid.

  • legion_entity_not_found_error: Thrown when handle’s id is invalid.

  • legion_unknown_component_error: Thrown when the component type is unknown.

template<class component_type, class Func, typename = doesnt_inherit_from<component_type, archetype_base>>
void modify_component(Func &&f)
void destroy(bool recurse = true)

Destroy this entity. Destroys entity and invalidates handle. (also destroys all of it’s components)

Parameters
  • recurse: Destroy all children and children of children as well? Default value is true.

bool valid() const

Check whether this entity handle is valid or not.

Return

bool True if the handle is pointing to valid entity and the registry reference is also valid.