co_ecs::entity_ref Class Reference

Represents a reference to an entity within a registry. More...

#include <entity_ref.hpp>

Public Member Functions
constexpr	entity_ref (base_registry &registry, entity entity) noexcept
	Constructs an entity reference for a specific entity in the given registry.
constexpr auto	archetype () const noexcept -> const archetype &
	Retrieves a constant reference to the archetype of the entity.
constexpr auto	alive () const noexcept -> bool
	Checks if the entity is currently active in the registry.
template<component... C>
constexpr auto	has () const noexcept -> bool
	Determines if the entity has all specified components.
template<component C>
constexpr auto	get () -> C &
	Retrieves a component of type C from the entity.
template<component C>
constexpr auto	get () const -> const C &
	Retrieves a const-qualified component of type C from the entity in a read-only manner.
template<component C, component O, component... Args>
constexpr auto	get () -> decltype(auto)
	Retrieves multiple components from the underlying registry for the current entity.
template<component C, component O, component... Args>
constexpr auto	get () const -> decltype(auto)
	Retrieves multiple components from the underlying registry for the current entity (const version).
template<component C>
constexpr auto	get_or_insert (auto &&... args) -> C &
	Get reference to component C, or insert it with provided arguments if not present.
template<component C, typename... Args>
constexpr auto	set (Args &&... args) -> entity_ref
	Set component to an entity. It can either override a component value that is already assigned to an entity or it may construct a new once and assign to it.
template<component C>
constexpr auto	remove () -> entity_ref
	Remove component C from an entity. In case entity does not have component attached nothing is done and this method returns.
void	destroy ()
	Destroys the current entity.
constexpr auto	visit (auto &&func)
	Visit all components of an entity and apply a function to them.
constexpr auto	visit (auto &&func) const
	Visit all components of an entity and apply a function to them (const version).
auto	clone () const -> entity_ref
	Creates a duplicate of the current entity.
auto	clone (placeholder_entity placeholder)
	Clones the current entity to a placeholder entity.
auto	copy (base_registry &destination) const -> entity_ref
	Copies the current entity to another registry.
auto	copy (base_registry &destination, placeholder_entity placeholder) const
	Copies the current entity to another registry into a placeholder entity.
auto	move (base_registry &destination) -> entity_ref
	Moves the current entity to another registry.
auto	move (base_registry &destination, placeholder_entity placeholder)
	Moves the current entity to another registry into a placeholder entity.
constexpr	operator entity () const noexcept
	Converts this entity_ref to its underlying entity.
constexpr	operator bool () const noexcept
	Checks if the underlying entity is valid.

Detailed Description

Represents a reference to an entity within a registry.

This class provides an interface to interact with a specific entity managed by a given registry. It encapsulates the entity and the registry it belongs to, allowing for operations such as querying, modifying, or checking the status of the entity in a safe and convenient manner. This reference facilitates access to various functionalities provided by the registry concerning the specific entity.

Constructor & Destructor Documentation

entity_ref()

constexpr co_ecs::entity_ref::entity_ref ( base_registry & registry, entity entity )

inlineconstexprnoexcept

Constructs an entity reference for a specific entity in the given registry.

This constructor initializes an entity_ref object that links an entity to its managing registry. It allows for subsequent operations on the entity through methods provided by this class.

Parameters

registry	Reference to the base_registry that manages the entity.
entity	The entity that this reference will encapsulate.

Member Function Documentation

alive()

constexpr auto co_ecs::entity_ref::alive ( ) const -> bool

inlineconstexprnoexcept

Checks if the entity is currently active in the registry.

This method queries the registry to determine if the entity is still active and has not been destroyed. It is particularly useful for validity checks before performing operations on the entity.

Returns

bool Returns true if the entity is active; otherwise, false.

archetype()

constexpr auto co_ecs::entity_ref::archetype ( ) const -> const archetype&

inlineconstexprnoexcept

Retrieves a constant reference to the archetype of the entity.

This method returns a reference to the archetype associated with the encapsulated entity. An archetype defines the configuration of components that an entity possesses in the entity-component system. Accessing the archetype can be useful for inspecting the structure and component makeup of the entity.

Returns

const archetype& A reference to the archetype of the entity.

clone() [1/2]

auto co_ecs::entity_ref::clone ( ) const -> entity_ref

inline

Creates a duplicate of the current entity.

This method is used to clone the current entity, creating an exact copy with the same components and states, but under a new entity identifier.

Note

Components are copied using their copy constructor.

Exceptions

std::invalid_argument

when copy constructor does not exist for one of components. Entity is left in an undefined state if this occurs.

Returns

entity_ref A reference to the new entity, which is a duplicate of the original.

Example

// Assuming 'entity' is an existing entity_ref object
auto cloned_entity = entity.clone();
// 'cloned_entity' is now a new entity with the same components as 'entity'

clone() [2/2]

auto co_ecs::entity_ref::clone ( placeholder_entity placeholder )

inline

Clones the current entity to a placeholder entity.

This method clones the current entity, creating a copy in a new placeholder entity within the same registry.

Parameters

placeholder

The placeholder entity to clone into.

Returns

The cloned entity reference.

copy() [1/2]

auto co_ecs::entity_ref::copy ( base_registry & destination ) const -> entity_ref

inline

Copies the current entity to another registry.

This method copies the current entity to a specified destination registry, creating a new entity in the destination registry.

Parameters

destination

The destination registry where the entity will be copied.

Returns

The copied entity reference in the destination registry.

copy() [2/2]

auto co_ecs::entity_ref::copy ( base_registry & destination, placeholder_entity placeholder ) const

inline

Copies the current entity to another registry into a placeholder entity.

This method copies the current entity to a specified destination registry, creating a new entity in the destination registry and associating it with a placeholder entity.

Parameters

destination	The destination registry where the entity will be copied.
placeholder	The placeholder entity in the destination registry.

Returns

The copied entity reference in the destination registry.

destroy()

void co_ecs::entity_ref::destroy ( )

inline

Destroys the current entity.

This method is responsible for removing the entity from the registry.

e.destroy();
e.alive() // returns false

get() [1/4]

template<component C>

constexpr auto co_ecs::entity_ref::get ( ) -> C&

inlineconstexpr

Retrieves a component of type C from the entity.

This method template is designed to access a specific component from the entity managed by the registry. It provides direct access to a component, assuming that the entity contains it. If the entity does not have the requested component, it throws a component_not_found exception.

Template Parameters

C	The type of component to retrieve, specified as a non-const reference.

Returns

C A reference to the requested component of the entity.

Exceptions

component_not_found

If the requested component C is not found in the entity.

Example

auto entity = registry.create<position>({});
position& pos = entity.get<position>(); // Accesses position component, succeeds.
// Below line throws component_not_found since the velocity component is not present
velocity& vel = entity.get<velocity>();

get() [2/4]

template<component C, component O, component... Args>

constexpr auto co_ecs::entity_ref::get ( ) -> decltype(auto)

inlineconstexpr

Retrieves multiple components from the underlying registry for the current entity.

This method allows accessing multiple components associated with the current entity from the underlying registry.

Template Parameters

C	The first component type to retrieve.
O	The second component type to retrieve.
Args	Additional component types to retrieve.

Returns

A tuple containing the requested components.

Example

const auto entity = registry.create<position, velocity>({});
auto [pos, vel] = entity.get<position, velocity>();

get() [3/4]

template<component C>

constexpr auto co_ecs::entity_ref::get ( ) const -> const C&

inlineconstexpr

Retrieves a const-qualified component of type C from the entity in a read-only manner.

This const method template is designed for read-only access to a specific component from the entity managed by the registry. It is used when the entity is expected to contain the component and modifications are not intended. If the requested component is not present, it throws a component_not_found exception.

Template Parameters

C	The type of the component to retrieve, specified as a const-qualified reference.

Returns

C A const reference to the requested component of the entity.

Exceptions

component_not_found

If the requested component C is not found in the entity.

Example

const auto entity = registry.create<position>({});
const position pos = entity.get<position>(); // Accesses position component, succeeds.
// Below line throws component_not_found since velocity component is not present
const velocity vel = entity.get<velocity>();

get() [4/4]

template<component C, component O, component... Args>

constexpr auto co_ecs::entity_ref::get ( ) const -> decltype(auto)

inlineconstexpr

Retrieves multiple components from the underlying registry for the current entity (const version).

This method allows accessing multiple components associated with the current entity from the underlying registry in a const context.

Template Parameters

C	The first component type to retrieve.
O	The second component type to retrieve.
Args	Additional component types to retrieve.

Returns

A tuple containing the requested components.

get_or_insert()

template<component C>

constexpr auto co_ecs::entity_ref::get_or_insert ( auto &&... args ) -> C&

inlineconstexpr

Get reference to component C, or insert it with provided arguments if not present.

This function tries to access a component of type C associated with the specified entity. If the component does not exist, it is inserted by forwarding the provided arguments to the constructor of C. This ensures that the component is initialized according to the arguments passed. After insertion, the entity's archetype is updated to include this new component type, and all related entity locations are adjusted accordingly to reflect changes in the archetype structure.

Template Parameters

C	Component type which must be constructible with the provided arguments.

Parameters

args	Arguments to forward to the constructor of C if component C needs to be created.

Returns

C& Reference to the component C.

has()

template<component... C>

constexpr auto co_ecs::entity_ref::has ( ) const -> bool

inlineconstexprnoexcept

Determines if the entity has all specified components.

This template method checks whether the entity has each of the components listed in the template arguments. This can be useful for conditional logic where actions depend on the presence of specific components in an entity. For example, an operation that should only be performed if an entity has both a position and velocity component.

Template Parameters

C	The component types to check for.

Returns

bool Returns true if the entity has all specified components; otherwise, false.

move() [1/2]

auto co_ecs::entity_ref::move ( base_registry & destination ) -> entity_ref

inline

Moves the current entity to another registry.

This method moves the current entity to a specified destination registry, transferring ownership and creating a new entity in the destination registry.

Parameters

destination

The destination registry where the entity will be moved.

Returns

The moved entity reference in the destination registry.

move() [2/2]

auto co_ecs::entity_ref::move ( base_registry & destination, placeholder_entity placeholder )

inline

Moves the current entity to another registry into a placeholder entity.

This method moves the current entity to a specified destination registry, transferring ownership and associating it with a placeholder entity in the destination registry.

Parameters

destination	The destination registry where the entity will be moved.
placeholder	The placeholder entity in the destination registry.

Returns

The moved entity reference in the destination registry.

operator bool()

constexpr co_ecs::entity_ref::operator bool ( ) const

inlineconstexprnoexcept

Checks if the underlying entity is valid.

This conversion operator allows the entity_ref to be used in boolean contexts to check if the underlying entity is valid (i.e., has valid (id, generation) but may not be alive).

Returns

bool True if the underlying entity is valid, false otherwise.

operator entity()

constexpr co_ecs::entity_ref::operator entity ( ) const

inlineconstexprnoexcept

Converts this entity_ref to its underlying entity.

This conversion operator allows entity_ref to be treated as its underlying entity type directly. Useful in contexts where the entity's identifier is needed without explicit method calls.

Returns

entity The underlying entity associated with this entity_ref.

remove()

template<component C>

constexpr auto co_ecs::entity_ref::remove ( ) -> entity_ref

inlineconstexpr

Remove component C from an entity. In case entity does not have component attached nothing is done and this method returns.

Note

Such operation involves an archetype change which is a costly operation.

Example

auto entity = registry.create<position>({ 1, 2 });
 
entity.remove<position>(10, 20);

Template Parameters

C	Component type

Returns

entity_ref Returns this entity to allow method chaining.

set()

template<component C, typename... Args>

constexpr auto co_ecs::entity_ref::set ( Args &&... args ) -> entity_ref

inlineconstexpr

Set component to an entity. It can either override a component value that is already assigned to an entity or it may construct a new once and assign to it.

Note

Such operation involves an archetype change which is a costly operation.

Example

auto entity = registry.create<position>({ 1, 2 });
 
entity
    .set<position>(10, 20)
    .set<velocity>(3, 4);

Template Parameters

C	Component type
Args	Parameter pack, argument types to construct C from

Parameters

args	Arguments to construct C from

Returns

entity_ref Returns this entity to allow method chaining.

visit() [1/2]

constexpr auto co_ecs::entity_ref::visit ( auto && func )

inlineconstexpr

Visit all components of an entity and apply a function to them.

This function visits all components associated with an entity in the registry and applies the provided function to each component.

Parameters

func	A callable object (function, lambda, etc.) that will be applied to each component.

Example

entity.visit([](const component_meta& meta, void* ptr) { std::cout << meta.type->name << '\n'; });

visit() [2/2]

constexpr auto co_ecs::entity_ref::visit ( auto && func ) const

inlineconstexpr

Visit all components of an entity and apply a function to them (const version).

This function visits all components associated with an entity in the registry and applies the provided function to each component. This version is const and can be used in const contexts.

Parameters

func	A callable object (function, lambda, etc.) that will be applied to each component.

Example

entity.visit([](const component_meta& meta, const void* ptr) { std::cout << meta.type->name << '\n'; });

---

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

• include/co_ecs/entity_ref.hpp