CeresEngine 0.2.0
A game development framework
Loading...
Searching...
No Matches
CeresEngine::Entity Class Reference

The base entity class. More...

#include <CeresEngine/Entity/Entity.hpp>

Inheritance diagram for CeresEngine::Entity:
CeresEngine::EntityObject< TransformComponent, Cs... > CeresEngine::EntityObject< EnvironmentComponent > CeresEngine::EntityObject< NetworkEntityComponent > CeresEngine::EntityObject< PhysicsWorldComponent > CeresEngine::EntityObject< RigidBodyComponent, Motion, TransformComponent > CeresEngine::EntityObject< ScriptComponent > CeresEngine::EntityObject< SoftBodyComponent, Motion, TransformComponent > CeresEngine::EntityObject< RigidBodyComponent, TransformComponent > CeresEngine::EntityObject< Components >

Public Member Functions

 Entity () noexcept=default
 Creates a new empty entity.
 
 Entity (EntityManager &entityManager, EntityID id) noexcept
 Creates a new entity attached to a entity manager.
 
 Entity (std::nullptr_t) noexcept
 Creates a new empty entity.
 
Entityoperator= (std::nullptr_t) noexcept
 Empties a EntityObject. The entity is not deallocated.
 
 Entity (const Entity &other) noexcept=default
 Creates a new entity by copying another.
 
Entityoperator= (const Entity &other) noexcept=default
 Assing the contents of the entity by copying the contents of another.
 
bool valid () const noexcept
 Checks if the entity is still valid.
 
Entity copy () const
 Copies the entity and all its components.
 
template<typename Block >
Entity copy (Block &&block) const
 Copies the entity and all its components. Executes block as.
 
void destroy () const
 Destroys the entity.
 
AbstractComponentadd (const ComponentType &type, const Box &initialValue=nullptr) const
 Adds a new component of the given type.
 
template<CComponent C, typename... Args>
Cadd (Args &&... args) const noexcept(std::is_nothrow_constructible_v< C, Args... >)
 Adds a new component.
 
template<CComponent C, typename Block , typename... Args>
CaddWith (Block &&block, Args &&... args) const noexcept(std::is_nothrow_constructible_v< C, Args... >)
 Adds a new component and calls block with the added component.
 
template<CComponent C, typename... Args>
Cset (Args &&... args) const noexcept(std::is_nothrow_constructible_v< C, Args... >)
 Sets a component.
 
void remove (const ComponentType &type) const
 Removes a component of the given type from the entity.
 
template<CComponent C>
void remove () const noexcept(std::is_nothrow_destructible_v< C >)
 Removes a component of type C from the entity.
 
AbstractComponentget (const ComponentType &type) const
 Gets a component of the given type.
 
template<CComponent C>
Cget () const noexcept
 Gets a component of type C.
 
template<CComponent C0, CComponent C1, CComponent... Cs>
Tuple< C0 &, C1 &, Cs &... > get () const noexcept
 Gets a set of components of types C0, C1 and Cs.
 
AbstractComponentgetOr (const ComponentType &type) const
 Gets a component of the given type.
 
template<CComponent C>
CgetOr () const noexcept(std::is_nothrow_constructible_v< C >)
 Gets a component of type C.
 
template<CComponent C0, CComponent C1, CComponent... Cs>
Tuple< C0 &, C1 &, Cs &... > getOr () const noexcept
 Gets a set of components of types C0, C1 and Cs.
 
AbstractComponentgetIf (const ComponentType &type) const
 Gets a component of the given type.
 
template<CComponent C>
CgetIf () const noexcept
 Gets a component of type C.
 
template<CComponent C0, CComponent C1, CComponent... Cs>
Tuple< C0 *, C1 *, Cs *... > getIf () const noexcept
 Gets a set of components of types C0, C1 and Cs.
 
Vector< AbstractComponent * > getComponents () const
 
bool has (const ComponentType &type) const noexcept
 Checks if the entity has all components of the given type.
 
template<CComponent C, CComponent... Cs>
bool has () const noexcept
 Checks if the entity has all components of types Cs.
 
void clear () const
 Removes all components attached to the entity, without destroying the entity itself.
 
bool empty () const noexcept
 Checks if the entity is empty (i.e.
 
template<typename E >
bool is () const noexcept
 Checks if the entity matches the criteria to be considered a E entity object.
 
template<typename E >
E as () const
 Converts the entity handle type into a E entity object.
 
template<typename... Cs>
EntityObject< Cs... > having () const
 Converts the entity handle type into a EntityObject<Cs...> object.
 
template<typename E >
E being () const noexcept
 Converts the entity handle type into a E entity object.
 
Entity getParent () const noexcept
 Gets the parent entity.
 
template<typename P >
P getParent () const noexcept
 Gets the parent entity of type T.
 
void setParent (Entity parent) const
 Sets the parent entity.
 
const Vector< Entity > & getChildren () const noexcept
 Gets the list of children entities.
 
template<typename T >
Generator< TgetChildren () const noexcept
 Gets the list of children entities.
 
void setChildren (const Vector< Entity > &children)
 Sets all entities as children of this entity.
 
StringView getName () const noexcept
 Gets the name for the entity.
 
void setName (String name) const
 Sets the name for the entity.
 
template<CEntityEvent E, typename... Args>
void emit (Args &&... args) const
 Emits a event of type E to all event listeners.
 
template<CEntityEvent E>
void emit (const E &event) const
 Emits a event of type E to all event listeners.
 
template<CEntityEvent E, typename Listener >
WeakEventConnection on (Listener &&listener) const
 Subscribes a listener that waits for events from the entity.
 
template<CEntityAction A, typename... Args>
bool canAct (Args &&... args) const
 Checks if the the entity is capable of acting on the given action A.
 
template<CEntityAction A, typename... Args>
decltype(autoact (Args &&... args) const
 Orders the entity to act on the action A.
 
template<typename T , CComponent Component>
auto mutate (T Component::*ptr) const
 Accesses an element from an existing Component.
 
template<typename MutateFunc , typename T , CComponent Component>
decltype(automutate (MutateFunc &&func, T Component::*ptr) const
 Accesses an element from an existing Component.
 
template<typename T , CComponent Component>
const Tread (const T Component::*ptr) const
 Accesses an element from an existing Component.
 
EntityID getEntityID () const noexcept
 
EntityManagergetEntityManager () const noexcept
 
 operator bool () const noexcept
 Checks if the entity is still valid.
 
Entity operator[] (const EntityIndex childIndex) const
 
Entity operator[] (const StringView childName) const
 

Public Attributes

EntityManagerentityManager = nullptr
 The owning entity manager.
 
EntityID entityID = {}
 The entity ID.
 

Friends

template<typename T , typename Component >
struct ComponentFieldMutator
 
bool operator== (const Entity &a, const Entity &b) noexcept
 Compares two entities for equality.
 
bool operator!= (const Entity &a, const Entity &b) noexcept
 Compares two entities for inequality.
 
bool operator== (const Entity &a, const EntityID &b) noexcept
 Compares two entities for equality.
 
bool operator!= (const Entity &a, const EntityID &b) noexcept
 Compares two entities for inequality.
 
bool operator== (const Entity &a, std::nullptr_t b) noexcept
 Checks if a entity is empty.
 
bool operator!= (const Entity &a, std::nullptr_t b) noexcept
 Checks if a entity is not empty.
 
std::ostream & operator<< (std::ostream &os, const Entity &entity)
 Prints a string representation of the Entity.
 
template<typename E >
E unsafeCastEntityObject (EntityManager &entityManager, EntityID entityID) noexcept
 

Detailed Description

The base entity class.

The entity acts as an identifier that can be used as an entrypoint for querying data from a set of components stored in an entity manager.

Typically you don't interact directly with the Entity class and instead use the typed EntityObject or aliases provided by the engine like Light, Camera and SceneObject.

Constructor & Destructor Documentation

◆ Entity() [1/4]

CeresEngine::Entity::Entity ( )
defaultnoexcept

Creates a new empty entity.

◆ Entity() [2/4]

CeresEngine::Entity::Entity ( EntityManager entityManager,
EntityID  id 
)
noexcept

Creates a new entity attached to a entity manager.

Parameters
entityManagerThe entity manager that owns the entity
idThe entity ID

◆ Entity() [3/4]

CeresEngine::Entity::Entity ( std::nullptr_t  )
noexcept

Creates a new empty entity.

◆ Entity() [4/4]

CeresEngine::Entity::Entity ( const Entity other)
defaultnoexcept

Creates a new entity by copying another.

NOTE: this will only copy the entity handle, the components and the entity ID will still be the same.

Parameters
otherThe entity to copy from

Member Function Documentation

◆ act()

template<CEntityAction A, typename... Args>
decltype(auto) CeresEngine::Entity::act ( Args &&...  args) const
inline

Orders the entity to act on the action A.

Template Parameters
Athe action type
Argsthe action constructor argument types
Parameters
argsThe action constructor arguments
Returns
The value returned by the action handler.

◆ add() [1/2]

template<CComponent C, typename... Args>
C & CeresEngine::Entity::add ( Args &&...  args) const
inlinenoexcept

Adds a new component.

If a component of type C is already present, this method throws.

Template Parameters
Cthe component type to be added
Argsthe component constructor argument types
Parameters
argsThe component constructor arguments
Returns
A reference to the newly added component

◆ add() [2/2]

AbstractComponent & CeresEngine::Entity::add ( const ComponentType type,
const Box initialValue = nullptr 
) const

Adds a new component of the given type.

If a component of the given type is already present, this method throws.

Parameters
typeThe component type to be added.
Returns
A reference to the added component.

◆ addWith()

template<CComponent C, typename Block , typename... Args>
C & CeresEngine::Entity::addWith ( Block &&  block,
Args &&...  args 
) const
inlinenoexcept

Adds a new component and calls block with the added component.

If a component of type C is already present, this method throws.

Template Parameters
Cthe component type to be added
Blockthe block type
Argsthe component constructor argument types
Parameters
blockThe block to be called
argsThe component constructor arguments
Returns
A reference to the newly added component

◆ as()

template<typename E >
E CeresEngine::Entity::as ( ) const
inline

Converts the entity handle type into a E entity object.

Template Parameters
Ethe entity object type
Returns
A entity of type E

◆ being()

template<typename E >
E CeresEngine::Entity::being ( ) const
inlinenoexcept

Converts the entity handle type into a E entity object.

This method is similar to as but instead of throwing in case the entity cannot be E, it returns a nullptr entity.

Template Parameters
Ethe entity object type
Returns
A entity of type E

◆ canAct()

template<CEntityAction A, typename... Args>
bool CeresEngine::Entity::canAct ( Args &&...  args) const
inline

Checks if the the entity is capable of acting on the given action A.

Template Parameters
Athe action type
Argsthe action constructor argument types
Parameters
argsThe action constructor arguments
Returns
true if act can be called, false otherwise.

◆ clear()

void CeresEngine::Entity::clear ( ) const

Removes all components attached to the entity, without destroying the entity itself.

◆ copy() [1/2]

Entity CeresEngine::Entity::copy ( ) const

Copies the entity and all its components.

Returns
The copied entity

◆ copy() [2/2]

template<typename Block >
Entity CeresEngine::Entity::copy ( Block &&  block) const

Copies the entity and all its components. Executes block as.

Template Parameters
Blockthe block type
Parameters
blockThe block to be executed after copying
Returns
The copied entity

◆ destroy()

void CeresEngine::Entity::destroy ( ) const

Destroys the entity.

◆ emit() [1/2]

template<CEntityEvent E, typename... Args>
void CeresEngine::Entity::emit ( Args &&...  args) const
inline

Emits a event of type E to all event listeners.

The event E is constructed by forwarding args to the event constructor.

Template Parameters
Ethe event type to be emitted
Argsthe event constructor argument types
Parameters
argsThe event constructor arguments

◆ emit() [2/2]

template<CEntityEvent E>
void CeresEngine::Entity::emit ( const E event) const
inline

Emits a event of type E to all event listeners.

Template Parameters
Ethe event type to be emitted
Parameters
eventThe event to be emitted

◆ empty()

bool CeresEngine::Entity::empty ( ) const
noexcept

Checks if the entity is empty (i.e.

has no components attached).

Returns
True if the entity has no components

◆ get() [1/3]

template<CComponent C>
C & CeresEngine::Entity::get ( ) const
inlinenoexcept

Gets a component of type C.

If a component of type C is not present, this method throws.

Template Parameters
Cthe component type to be retrieved
Returns
A reference to the existing component

◆ get() [2/3]

template<CComponent C0, CComponent C1, CComponent... Cs>
Tuple< C0 &, C1 &, Cs &... > CeresEngine::Entity::get ( ) const
inlinenoexcept

Gets a set of components of types C0, C1 and Cs.

If any of the components are not present, this method throws.

Template Parameters
C0The type of the first component to be retrieved
C1The type of the second component to be retrieved
CsThe remaining types of the components to be retrieved
Returns
A reference to the existing components

◆ get() [3/3]

AbstractComponent & CeresEngine::Entity::get ( const ComponentType type) const

Gets a component of the given type.

If a component of the given type is not present, this method throws.

Parameters
typeThe component type to be retrieved.
Returns
A reference to the existing component.

◆ getChildren() [1/2]

const Vector< Entity > & CeresEngine::Entity::getChildren ( ) const
noexcept

Gets the list of children entities.

Returns
A vector of children entities

◆ getChildren() [2/2]

template<typename T >
Generator< T > CeresEngine::Entity::getChildren ( ) const
noexcept

Gets the list of children entities.

Returns
A vector of children entities

◆ getComponents()

Vector< AbstractComponent * > CeresEngine::Entity::getComponents ( ) const

◆ getEntityID()

EntityID CeresEngine::Entity::getEntityID ( ) const
inlinenoexcept
Returns
The entity ID.

◆ getEntityManager()

EntityManager & CeresEngine::Entity::getEntityManager ( ) const
inlinenoexcept
Returns
The entity manager.

◆ getIf() [1/3]

template<CComponent C>
C * CeresEngine::Entity::getIf ( ) const
inlinenoexcept

Gets a component of type C.

If a component of type C is not present, nullptr is returned

Template Parameters
Cthe component type to be retrieved
Returns
A pointer to the existing component

◆ getIf() [2/3]

template<CComponent C0, CComponent C1, CComponent... Cs>
Tuple< C0 *, C1 *, Cs *... > CeresEngine::Entity::getIf ( ) const
inlinenoexcept

Gets a set of components of types C0, C1 and Cs.

If any of the components are not present, nullptr is returned.

Template Parameters
C0The type of the first component to be retrieved
C1The type of the second component to be retrieved
CsThe remaining types of the components to be retrieved
Returns
A reference to the existing components

◆ getIf() [3/3]

AbstractComponent * CeresEngine::Entity::getIf ( const ComponentType type) const

Gets a component of the given type.

If a component of the given type is not present, nullptr is returned.

Parameters
typeThe component type to be retrieved.
Returns
A pointer to the existing component.

◆ getName()

StringView CeresEngine::Entity::getName ( ) const
noexcept

Gets the name for the entity.

Returns
The entity name

◆ getOr() [1/3]

template<CComponent C0, CComponent C1, CComponent... Cs>
Tuple< C0 &, C1 &, Cs &... > CeresEngine::Entity::getOr ( ) const
inlinenoexcept

Gets a set of components of types C0, C1 and Cs.

If any of the components are not present, a new component is created.

Template Parameters
C0The type of the first component to be retrieved
C1The type of the second component to be retrieved
CsThe remaining types of the components to be retrieved
Returns
A reference to the existing components

◆ getOr() [2/3]

template<CComponent C>
C & CeresEngine::Entity::getOr ( ) const
inlinenoexcept

Gets a component of type C.

If a component of type C is not present, a new component is created.

Template Parameters
Cthe component type to be retrieved
Returns
A reference to the existing component

◆ getOr() [3/3]

AbstractComponent & CeresEngine::Entity::getOr ( const ComponentType type) const

Gets a component of the given type.

If a component of the given type is not present, a new component is created and returned.

Parameters
typeThe component type to be retrieved.
Returns
A reference to the existing component.

◆ getParent() [1/2]

Entity CeresEngine::Entity::getParent ( ) const
noexcept

Gets the parent entity.

If the entity has not parent, a nullptr entity is returned.

Returns
The parent entity

◆ getParent() [2/2]

template<typename P >
P CeresEngine::Entity::getParent ( ) const
noexcept

Gets the parent entity of type T.

If the entity has no parent of type T, a nullptr entity is returned.

Template Parameters
Pthe entity parent type
Returns
The parent entity

◆ has() [1/2]

template<CComponent C, CComponent... Cs>
bool CeresEngine::Entity::has ( ) const
inlinenoexcept

Checks if the entity has all components of types Cs.

Template Parameters
Csthe component types to be checked
Returns
True if the components are present, false otherwise

◆ has() [2/2]

bool CeresEngine::Entity::has ( const ComponentType type) const
noexcept

Checks if the entity has all components of the given type.

Parameters
typeThe component type to be checked.
Returns
true if the components are present, false otherwise.

◆ having()

template<typename... Cs>
EntityObject< Cs... > CeresEngine::Entity::having ( ) const
inline

Converts the entity handle type into a EntityObject<Cs...> object.

Template Parameters
Csthe component types
Returns
A entity of type EntityObject<Cs...>

◆ is()

template<typename E >
bool CeresEngine::Entity::is ( ) const
inlinenoexcept

Checks if the entity matches the criteria to be considered a E entity object.

Template Parameters
Ethe entity object type
Returns
True if the entity can be viewed as a E entity object.

◆ mutate() [1/2]

template<typename MutateFunc , typename T , CComponent Component>
decltype(auto) CeresEngine::Entity::mutate ( MutateFunc &&  func,
T Component::*  ptr 
) const

Accesses an element from an existing Component.

If the component does not exists, it is undefined behavior.

Template Parameters
MutateFuncA function to be called with the component property.
TThe component member type.
ComponentThe component type.
Parameters
funcA function to be called with the component property.
ptrThe component element pointer to member.
Returns
A reference to the component element.

◆ mutate() [2/2]

template<typename T , CComponent Component>
auto CeresEngine::Entity::mutate ( T Component::*  ptr) const

Accesses an element from an existing Component.

If the component does not exists, it is undefined behavior.

Template Parameters
Tthe component member type
Componentthe component type
Parameters
ptrThe component element pointer to member
Returns
A reference to the component element

◆ on()

template<CEntityEvent E, typename Listener >
WeakEventConnection CeresEngine::Entity::on ( Listener &&  listener) const
inline

Subscribes a listener that waits for events from the entity.

Template Parameters
Ethe event type to be subscribed
Listenerthe listener type
Parameters
listenerThe listener
Returns
A connection to the subscribed event. Calling disconnect on the connection will cancel further event calls.

◆ operator bool()

CeresEngine::Entity::operator bool ( ) const
inlineexplicitnoexcept

Checks if the entity is still valid.

Returns
True if the entity is still valid, false otherwise

◆ operator=() [1/2]

Entity & CeresEngine::Entity::operator= ( const Entity other)
defaultnoexcept

Assing the contents of the entity by copying the contents of another.

NOTE: this will only copy the entity handle, the components and the entity ID will still be the same.

Parameters
otherThe entity to copy from
Returns
This

◆ operator=() [2/2]

Entity & CeresEngine::Entity::operator= ( std::nullptr_t  )
noexcept

Empties a EntityObject. The entity is not deallocated.

◆ operator[]() [1/2]

Entity CeresEngine::Entity::operator[] ( const EntityIndex  childIndex) const
inline
Parameters
childIndexThe child index (from 0)
Returns
The child given by index childIndex

◆ operator[]() [2/2]

Entity CeresEngine::Entity::operator[] ( const StringView  childName) const
inline
Parameters
childNameThe child name
Returns
The child given by name childName

◆ read()

template<typename T , CComponent Component>
const T & CeresEngine::Entity::read ( const T Component::*  ptr) const

Accesses an element from an existing Component.

If the component does not exists, it is undefined behavior.

Template Parameters
Tthe component member type
Componentthe component type
Parameters
ptrThe component element pointer to member
Returns
A reference to the component element

◆ remove() [1/2]

template<CComponent C>
void CeresEngine::Entity::remove ( ) const
inlinenoexcept

Removes a component of type C from the entity.

Template Parameters
Cthe component type to be removed

◆ remove() [2/2]

void CeresEngine::Entity::remove ( const ComponentType type) const

Removes a component of the given type from the entity.

Parameters
typeThe component type to be removed.

◆ set()

template<CComponent C, typename... Args>
C & CeresEngine::Entity::set ( Args &&...  args) const
inlinenoexcept

Sets a component.

If a component of type C is already present, a new component is created and added. If the component already exists, its contents are replaced.

Template Parameters
Cthe component type to be set
Argsthe component constructor argument types
Parameters
argsthe component constructor arguments
Returns
A reference to the newly added or replaced component

◆ setChildren()

void CeresEngine::Entity::setChildren ( const Vector< Entity > &  children)

Sets all entities as children of this entity.

All entities must belong to the same entity manager.

◆ setName()

void CeresEngine::Entity::setName ( String  name) const

Sets the name for the entity.

Parameters
nameThe entity name

◆ setParent()

void CeresEngine::Entity::setParent ( Entity  parent) const

Sets the parent entity.

Setting the parent entity will automatically add *this entity as a children of parent.

Parameters
parentThe parent to be set

◆ valid()

bool CeresEngine::Entity::valid ( ) const
noexcept

Checks if the entity is still valid.

Returns
True if the entity is still valid, false otherwise

Friends And Related Symbol Documentation

◆ ComponentFieldMutator

◆ operator!= [1/3]

bool operator!= ( const Entity a,
const Entity b 
)
friend

Compares two entities for inequality.

Two entity are considered equal iff their index and version match and they are managed by the same entity manager.

Parameters
aThe left hand side operator argument
bThe right hand side operator argument
Returns
True if the two IDs can be considered equal

◆ operator!= [2/3]

bool operator!= ( const Entity a,
const EntityID b 
)
friend

Compares two entities for inequality.

Two entity are considered equal iff their index and version match and they are managed by the same entity manager.

Parameters
aThe left hand side operator argument
bThe right hand side operator argument
Returns
True if the two IDs can be considered equal

◆ operator!= [3/3]

bool operator!= ( const Entity a,
std::nullptr_t  b 
)
friend

Checks if a entity is not empty.

Parameters
aThe left hand side operator argument
bThe right hand side operator argument
Returns
True if the entity is not empty

◆ operator<<

std::ostream & operator<< ( std::ostream &  os,
const Entity entity 
)
friend

Prints a string representation of the Entity.

Parameters
osThe output stream to print to
entityThe entity ID to be printed
Returns
The given os

◆ operator== [1/3]

bool operator== ( const Entity a,
const Entity b 
)
friend

Compares two entities for equality.

Two entity are considered equal iff their index and version match and they are managed by the same entity manager.

Parameters
aThe left hand side operator argument
bThe right hand side operator argument
Returns
True if the two entities can be considered equal

◆ operator== [2/3]

bool operator== ( const Entity a,
const EntityID b 
)
friend

Compares two entities for equality.

Two entity are considered equal iff their index and version match and they are managed by the same entity manager.

Parameters
aThe left hand side operator argument
bThe right hand side operator argument
Returns
True if the two entities can be considered equal

◆ operator== [3/3]

bool operator== ( const Entity a,
std::nullptr_t  b 
)
friend

Checks if a entity is empty.

Parameters
aThe left hand side operator argument
bThe right hand side operator argument
Returns
True if the entity is empty

◆ unsafeCastEntityObject

template<typename E >
E unsafeCastEntityObject ( EntityManager entityManager,
EntityID  entityID 
)
friend

Member Data Documentation

◆ entityID

EntityID CeresEngine::Entity::entityID = {}

The entity ID.

◆ entityManager

EntityManager* CeresEngine::Entity::entityManager = nullptr

The owning entity manager.


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