Menu
Lumberyard
C++ API Reference (Version 1.10)

An addressable container for a group of components. More...

Public Types

enum  State
 The state of the entity and its components. More...
 
enum  DependencySortResult
 Represents whether an entity can be activated. More...
 
typedef  ComponentArrayType
 The type of array that contains the entity's components. More...
 

Public Member Functions

 AZ_CLASS_ALLOCATOR (Entity, SystemAllocator, 0)
 Specifies that this class should use AZ::SystemAllocator for memory management by default. More...
 
 AZ_RTTI (AZ::Entity, "{75651658-8663-478D-9090-2432DFCAFA44}")
 Adds run-time type information to this class. More...
 
 Entity (const char *name=nullptr)
 Constructs an entity and automatically generates an entity ID. More...
 
 Entity (const EntityId &id, const char *name=nullptr)
 Constructs an entity with the entity ID that you specify. More...
 
virtual ~Entity ()
 Destroys an entity and its components. More...
 
EntityId GetId () const
 Gets the ID of the entity. More...
 
const AZStd::string & GetName () const
 Gets the name of the entity. More...
 
void SetName (AZStd::string name)
 Sets the name of the entity. More...
 
State GetState () const
 Gets the state of the entity. More...
 
void SetId (const EntityId &id)
 Sets the ID of the entity. More...
 
virtual void Init ()
 Initializes the entity and its components. More...
 
virtual void Activate ()
 Activates the entity and its components. More...
 
virtual void Deactivate ()
 Deactivates the entity and its components. More...
 
template<class ComponentType , typename... Args>
ComponentType * CreateComponent (Args &&... args)
 Creates a component and attaches the component to the entity. More...
 
ComponentCreateComponent (const Uuid &componentTypeId)
 Creates a component and attaches the component to the entity. More...
 
bool AddComponent (Component *component)
 Attaches an existing component to the entity. More...
 
bool RemoveComponent (Component *component)
 Removes a component from the entity. More...
 
const ComponentArrayTypeGetComponents () const
 Gets all components registered with the entity. More...
 
ComponentFindComponent (ComponentId id) const
 Finds a component by component ID. More...
 
ComponentFindComponent (const Uuid &typeId) const
 Finds the first component of the requested component type. More...
 
template<class ComponentType >
ComponentType * FindComponent (ComponentId id) const
 Finds a component by component ID. More...
 
template<class ComponentType >
ComponentType * FindComponent () const
 Finds the first component of the requested component type. More...
 
ComponentArrayType FindComponents (const Uuid &typeId) const
 Return a vector of all the components of the specified type in an entity. More...
 
template<class ComponentType >
AZStd::vector< ComponentType * > FindComponents () const
 Return a vector of all the components of the specified type in an entity. More...
 
void InvalidateDependencies ()
 Indicates to the entity that dependencies among its components need to be evaluated. More...
 
DependencySortResult EvaluateDependencies ()
 Calls DependencySort() to sort an entity's components based on the dependencies among components. More...
 

Static Public Member Functions

static void Reflect (ReflectContext *reflection)
 Reflects the entity into a variety of contexts (script, serialize, edit, and so on). More...
 
static EntityId MakeId ()
 Generates a unique entity ID. More...
 
static void SetLocalMachineId (AZ::u32 machineId)
 Sets an ID for the local machine. More...
 
static AZ::u32 GetLocalMachineId ()
 Gets the ID of the local machine. More...
 

Protected Member Functions

void OnNameChanged () const
 Signals to listeners that the entity's name has changed. More...
 
bool CanAddRemoveComponents () const
 Finds whether the entity is in a state in which components can be added or removed. More...
 

Static Protected Member Functions

static DependencySortResult DependencySort (ComponentArrayType &components)
 Sorts an entity's components based on the dependencies between components. More...
 

Protected Attributes

EntityId m_id
 The ID that the system uses to identify and address the entity. More...
 
ComponentArrayType m_components
 An array of components attached to the entity. More...
 
State m_state
 The state of the entity. More...
 
TransformInterfacem_transform
 A cached pointer to the transform interface. More...
 
bool m_isDependencyReady
 Indicates whether dependencies between components have been evaluated. More...
 
AZStd::string m_name
 A user-friendly name for the entity. More...
 

Static Protected Attributes

static AZ::u32 s_machineId
 Local machine ID. More...
 

Detailed Description

An addressable container for a group of components.

An entity creates, initializes, activates, and deactivates its components. An entity has an ID and, optionally, a name.

Member Typedef Documentation

◆ ComponentArrayType

typedef AZStd::vector<Component*> AZ::Entity::ComponentArrayType

The type of array that contains the entity's components.

Used when iterating over components.

Member Enumeration Documentation

◆ DependencySortResult

Represents whether an entity can be activated.

An entity cannot be activated unless all component dependency requirements are met, and components are sorted so that each can be activated before the components that depend on it.

Enumerator
DSR_OK 

All component dependency requirements are met. The entity can be activated.

DSR_MISSING_REQUIRED 

One or more components that provide required services are not in the list of components to activate.

DSR_CYCLIC_DEPENDENCY 

A cycle in component service dependencies was detected.

◆ State

enum AZ::Entity::State : u8

The state of the entity and its components.

Note
An entity is only initialized once. It can be activated and deactivated multiple times.
Enumerator
ES_CONSTRUCTED 

The entity was constructed but is not initialized or active. This is the default state after an entity is created.

ES_INITIALIZING 

The entity is initializing itself and its components. This state is the transition between ES_CONSTRUCTED and ES_INIT.

ES_INIT 

The entity and its components are initialized. You can add and remove components from the entity when it is in this state.

ES_ACTIVATING 

The entity is activating itself and its components. This state is the transition between ES_INIT and ES_ACTIVE.

ES_ACTIVE 

The entity and its components are active and fully operational. You cannot add or remove components from the entity unless you first deactivate the entity.

ES_DEACTIVATING 

The entity is deactivating itself and its components. This state is the transition between ES_ACTIVE and ES_INIT.

Constructor & Destructor Documentation

◆ Entity() [1/2]

AZ::Entity::Entity ( const char *  name = nullptr)

Constructs an entity and automatically generates an entity ID.

Parameters
name(Optional) A name for the entity. The entity ID is used for addressing and identification, but a name is useful for debugging.

◆ Entity() [2/2]

AZ::Entity::Entity ( const EntityId id,
const char *  name = nullptr 
)

Constructs an entity with the entity ID that you specify.

Parameters
idAn ID for the entity.
name(Optional) A name for the entity. The entity ID is used for addressing and identification, but a name is useful for debugging.

◆ ~Entity()

virtual AZ::Entity::~Entity ( )
virtual

Destroys an entity and its components.

Do not destroy an entity when it is in a transition state. If the entity is in a transition state, this function asserts.

Member Function Documentation

◆ Activate()

virtual void AZ::Entity::Activate ( )
virtual

Activates the entity and its components.

This function can be called multiple times throughout the lifetime of an entity. Before activating the components, this function verifies that all component dependency requirements are met, and that components are sorted so that each can be activated before the components that depend on it. If these requirements are met, this function calls the Activate function of each component.

◆ AddComponent()

bool AZ::Entity::AddComponent ( Component component)

Attaches an existing component to the entity.

You cannot attach a component to an entity when the entity is active or in a transition state. After the component is attached to the entity, the entity owns the component. If you destroy the entity, the component is destroyed along with the entity. To release ownership without destroying the component, use RemoveComponent(). The component can be attached to only one entity at a time. If the component is already attached to an entity, this code asserts.

Parameters
componentA pointer to the component to attach to the entity.
Returns
True if the component was successfully attached to the entity. Otherwise, false.

◆ AZ_CLASS_ALLOCATOR()

AZ::Entity::AZ_CLASS_ALLOCATOR ( Entity  ,
SystemAllocator  ,
 
)

Specifies that this class should use AZ::SystemAllocator for memory management by default.

◆ AZ_RTTI()

AZ::Entity::AZ_RTTI ( AZ::Entity  ,
"{75651658-8663-478D-9090-2432DFCAFA44}"   
)

Adds run-time type information to this class.

◆ CanAddRemoveComponents()

bool AZ::Entity::CanAddRemoveComponents ( ) const
protected

Finds whether the entity is in a state in which components can be added or removed.

Components can be added or removed when the entity is in the ES_CONSTRUCTED or ES_INIT state.

Returns
True if the entity is in a state in which that components can be added or removed. Otherwise, false.

◆ CreateComponent() [1/2]

template<class ComponentType , typename... Args>
ComponentType * AZ::Entity::CreateComponent ( Args &&...  args)
inline

Creates a component and attaches the component to the entity.

You cannot add a component to an entity when the entity is active or in a transition state. After the component is attached to the entity, the entity owns the component. If you destroy the entity, the component is destroyed along with the entity. To release ownership without destroying the component, use RemoveComponent().

Returns
A pointer to the component. Returns a null pointer if the component could not be created.

◆ CreateComponent() [2/2]

Component* AZ::Entity::CreateComponent ( const Uuid &  componentTypeId)

Creates a component and attaches the component to the entity.

You cannot add a component to an entity when the entity is active or in a transition state. After the component is attached to the entity, the entity owns the component. If you destroy the entity, the component is destroyed along with the entity. To release ownership without destroying the component, use RemoveComponent().

Parameters
componentTypeIdThe UUID of the component type.
Returns
A pointer to the component. Returns a null pointer if the component could not be created.

◆ Deactivate()

virtual void AZ::Entity::Deactivate ( )
virtual

Deactivates the entity and its components.

This function can be called multiple times throughout the lifetime of an entity. This function calls the Deactivate function of each component.

◆ DependencySort()

static DependencySortResult AZ::Entity::DependencySort ( ComponentArrayType components)
staticprotected

Sorts an entity's components based on the dependencies between components.

If all dependencies are met, the required services can be activated before the components that depend on them.

Parameters
componentsAn array of components attached to the entity.
Returns
Indicates whether the entity can determine an order in which to activate its components.

◆ EvaluateDependencies()

DependencySortResult AZ::Entity::EvaluateDependencies ( )

Calls DependencySort() to sort an entity's components based on the dependencies among components.

If all dependencies are met, the required services can be activated before the components that depend on them. An entity will not be activated unless the sort succeeds.

Returns
Indicates whether the entity can determine an order in which to activate its components.

◆ FindComponent() [1/4]

Component* AZ::Entity::FindComponent ( ComponentId  id) const

Finds a component by component ID.

Parameters
idThe ID of the component to find.
Returns
A pointer to the component with the specified component ID. If a component with the specified ID cannot be found, the return value is a null pointer.

◆ FindComponent() [2/4]

Component* AZ::Entity::FindComponent ( const Uuid &  typeId) const

Finds the first component of the requested component type.

Parameters
typeIdThe type of component to find.
Returns
A pointer to the first component of the requested type. Returns a null pointer if a component of the requested type cannot be found.

◆ FindComponent() [3/4]

template<class ComponentType >
ComponentType* AZ::Entity::FindComponent ( ComponentId  id) const
inline

Finds a component by component ID.

Parameters
idThe ID of the component to find.
Returns
A pointer to the component with the specified component ID. If a component with the specified ID cannot be found or the component type does not exist, the return value is a null pointer.

◆ FindComponent() [4/4]

template<class ComponentType >
ComponentType* AZ::Entity::FindComponent ( ) const
inline

Finds the first component of the requested component type.

Returns
A pointer to the first component of the requested type. Returns a null pointer if a component of the requested type cannot be found.

◆ FindComponents() [1/2]

ComponentArrayType AZ::Entity::FindComponents ( const Uuid &  typeId) const

Return a vector of all the components of the specified type in an entity.

Returns
a vector of all the components of the specified type.

◆ FindComponents() [2/2]

template<class ComponentType >
AZStd::vector<ComponentType*> AZ::Entity::FindComponents ( ) const
inline

Return a vector of all the components of the specified type in an entity.

◆ GetComponents()

const ComponentArrayType& AZ::Entity::GetComponents ( ) const
inline

Gets all components registered with the entity.

Returns
An array of all components registered with the entity.

◆ GetId()

EntityId AZ::Entity::GetId ( ) const
inline

Gets the ID of the entity.

Returns
The ID of the entity.

◆ GetLocalMachineId()

static AZ::u32 AZ::Entity::GetLocalMachineId ( )
static

Gets the ID of the local machine.

Returns
The ID of the local machine.

◆ GetName()

const AZStd::string& AZ::Entity::GetName ( ) const
inline

Gets the name of the entity.

Returns
The name of the entity.

◆ GetState()

State AZ::Entity::GetState ( ) const
inline

Gets the state of the entity.

Returns
The state of the entity. For example, the entity has been initialized, the entity is active, and so on.

◆ Init()

virtual void AZ::Entity::Init ( )
virtual

Initializes the entity and its components.

This function is called only once in an entity's lifetime, whereas an entity can be activated and deactivated multiple times. This function calls each component's Init function and provides its entity ID to each component.

◆ InvalidateDependencies()

void AZ::Entity::InvalidateDependencies ( )
inline

Indicates to the entity that dependencies among its components need to be evaluated.

Dependencies will be evaluated the next time the entity is activated.

◆ MakeId()

static EntityId AZ::Entity::MakeId ( )
static

Generates a unique entity ID.

Returns
An entity ID.

◆ OnNameChanged()

void AZ::Entity::OnNameChanged ( ) const
protected

Signals to listeners that the entity's name has changed.

◆ Reflect()

static void AZ::Entity::Reflect ( ReflectContext reflection)
static

Reflects the entity into a variety of contexts (script, serialize, edit, and so on).

Parameters
reflectionA pointer to the reflection context.

◆ RemoveComponent()

bool AZ::Entity::RemoveComponent ( Component component)

Removes a component from the entity.

After the component is removed from the entity, you are responsible for destroying the component.

Parameters
componentA pointer to the component to remove from the entity.
Returns
True if the component was removed from the entity. False if the component could not be removed.

◆ SetId()

void AZ::Entity::SetId ( const EntityId id)

Sets the ID of the entity.

You can only change the ID of the entity when the entity has been constructed but is not yet active or initialized.

Parameters
idThe ID of the entity.

◆ SetLocalMachineId()

static void AZ::Entity::SetLocalMachineId ( AZ::u32  machineId)
static

Sets an ID for the local machine.

By default, Lumberyard generates a unique ID. You call this function to override the default value. If you want to use the ID on the Internet, you must call this function.

Parameters
machineIdAn ID for the local machine.

◆ SetName()

void AZ::Entity::SetName ( AZStd::string  name)
inline

Sets the name of the entity.

Parameters
nameA name for the entity.

Member Data Documentation

◆ m_components

ComponentArrayType AZ::Entity::m_components
protected

An array of components attached to the entity.

◆ m_id

EntityId AZ::Entity::m_id
protected

The ID that the system uses to identify and address the entity.

The serializer determines whether this is an entity ID or an entity reference ID.

IMPORTANT: This must be the only EntityId member of the Entity class.

◆ m_isDependencyReady

bool AZ::Entity::m_isDependencyReady
protected

Indicates whether dependencies between components have been evaluated.

◆ m_name

AZStd::string AZ::Entity::m_name
protected

A user-friendly name for the entity.

This makes error messages easier to read.

◆ m_state

State AZ::Entity::m_state
protected

The state of the entity.

◆ m_transform

TransformInterface* AZ::Entity::m_transform
protected

A cached pointer to the transform interface.

We recommend using AZ::TransformBus and caching locally instead of accessing the transform interface directly through this pointer.

◆ s_machineId

AZ::u32 AZ::Entity::s_machineId
staticprotected

Local machine ID.

This is used for ID generation.


The documentation for this class was generated from the following file:
  • C:/lumberyard-root/dev/Code/Framework/AzCore/AzCore/Component/Entity.h