#include <Entity.h>

Inherited by AZ::EntityUtils::EntityIdAccessor, and AZ::ModuleEntity.

Classes
struct	FailedSortDetails
	Contains a failed DependencySortResult code and a detailed message that can be presented to users. More...

Public Types
enum class	State : u8 { Constructed , Initializing , Init , Activating , Active , Deactivating , Destroying , Destroyed }

enum class	DependencySortResult { Success = 0 , MissingRequiredService , HasCyclicDependency , HasIncompatibleServices , DescriptorNotRegistered , DSR_OK = Success , DSR_MISSING_REQUIRED = MissingRequiredService , DSR_CYCLIC_DEPENDENCY = HasCyclicDependency }

using	ComponentArrayType = AZStd::vector< Component * >

using	StringWarningArray = AZStd::vector< AZStd::string >
	This type of array is used by the warning.

using	EntityStateEvent = Event< State, State >
	An event that signals old state and new state during entity state changes.

using	DependencySortOutcome = AZ::Outcome< void, FailedSortDetails >

Public Member Functions
	AZ_CLASS_ALLOCATOR (Entity, EntityAllocator)
	Specifies that this class should use AZ::SystemAllocator for memory management by default.

	AZ_RTTI (AZ::Entity, "{75651658-8663-478D-9090-2432DFCAFA44}")
	Adds run-time type information to this class.

	Entity (AZStd::string name={})

	Entity (const EntityId &id, AZStd::string name={})

	Entity (const Entity &other)=delete

Entity &	operator= (const Entity &other)=delete

	Entity (Entity &&other)=default

Entity &	operator= (Entity &&other)=default

virtual	~Entity ()

void	Reset ()
	Resets the state to default.

EntityId	GetId () const

const AZStd::string &	GetName () const

void	SetName (AZStd::string name)

State	GetState () const

u32	GetEntitySpawnTicketId () const

void	SetEntitySpawnTicketId (u32 entitySpawnTicketId)

void	AddStateEventHandler (EntityStateEvent::Handler &handler)

void	SetId (const EntityId &id)

virtual void	Init ()

virtual void	Activate ()

virtual void	Deactivate ()

template<class ComponentType , typename... Args>
ComponentType *	CreateComponent (Args &&... args)

Component *	CreateComponent (const Uuid &componentTypeId)

bool	AddComponent (Component *component)

bool	RemoveComponent (Component *component)

const ComponentArrayType &	GetComponents () const

Component *	FindComponent (ComponentId id) const

Component *	FindComponent (const Uuid &typeId) const

template<class ComponentType >
ComponentType *	FindComponent (ComponentId id) const

template<class ComponentType >
ComponentType *	FindComponent () const

ComponentArrayType	FindComponents (const Uuid &typeId) const

template<class ComponentType >
AZStd::vector< ComponentType * >	FindComponents () const
	Return a vector of all the components of the specified type in an entity.

void	InvalidateDependencies ()

DependencySortOutcome	EvaluateDependenciesGetDetails ()

DependencySortResult	EvaluateDependencies ()

void	SetRuntimeActiveByDefault (bool activeByDefault)

bool	IsRuntimeActiveByDefault () const

TransformInterface *	GetTransform () const

Static Public Member Functions
static void	Reflect (ReflectContext *reflection)

static EntityId	MakeId ()

static AZ::u32	GetProcessSignature ()

static DependencySortOutcome	DependencySort (ComponentArrayType &components)

Protected Member Functions
void	SetState (State state)

void	OnNameChanged () const
	Signals to listeners that the entity's name has changed.

bool	CanAddRemoveComponents () const

Static Protected Member Functions
static void	ActivateComponent (Component &component)

static void	DeactivateComponent (Component &component)

Protected Attributes
EntityId	m_id

ComponentArrayType	m_components
	An array of components attached to the entity.

EntityStateEvent	m_stateEvent
	An event used to signal all entity state changes.

TransformInterface *	m_transform

AZStd::string	m_name
	A user-friendly name for the entity. This makes error messages easier to read.

u32	m_entitySpawnTicketId = 0

State	m_state
	The state of the entity.

bool	m_isDependencyReady
	Indicates the component dependencies have been evaluated and sorting was completed successfully. More...

bool	m_isRuntimeActiveByDefault
	Indicates the entity should be activated on initial creation.

Friends
class	JsonEntitySerializer

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

using AZ::Entity::ComponentArrayType = AZStd::vector<Component*>

The type of array that contains the entity's components. Used when iterating over components.

Member Enumeration Documentation

◆ DependencySortResult

enum AZ::Entity::DependencySortResult

strong

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
Success	All component dependency requirements are met. The entity can be activated.
MissingRequiredService	One or more components that provide required services are not in the list of components to activate.
HasCyclicDependency	A cycle in component service dependencies was detected.
HasIncompatibleServices	A component is incompatible with a service provided by another component.
DescriptorNotRegistered	A component descriptor was not registered with the AZ::ComponentApplication.

◆ State

enum AZ::Entity::State : u8

strong

The state of the entity and its components.

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

Enumerator
Constructed	The entity was constructed but is not initialized or active. This is the default state after an entity is created.
Initializing	The entity is initializing itself and its components. This state is the transition between State::Constructed and State::Init.
Init	The entity and its components are initialized. You can add and remove components from the entity when it is in this state.
Activating	The entity is activating itself and its components. This state is the transition between State::Init and State::Active.
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.
Deactivating	The entity is deactivating itself and its components. This state is the transition between State::Active and State::Init.
Destroying	The entity is in the process of being destroyed. This state is the transition between State::Init and State::Destroyed.
Destroyed	The entity has been fully destroyed.

Constructor & Destructor Documentation

◆ Entity() [1/2]

AZ::Entity::Entity ( AZStd::string name = {} )

explicit

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,
		AZStd::string	name = `{}`
	)

explicit

Constructs an entity with the entity ID that you specify.

Parameters

id	An 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

component A pointer to the component to attach to the entity.

Returns: True if the component was successfully attached to the entity. Otherwise, false.

◆ AddStateEventHandler()

void AZ::Entity::AddStateEventHandler ( EntityStateEvent::Handler & handler )

Connects an entity state event handler to the entity. All state changes will be signaled through this event.

Parameters

handler reference to the EntityStateEvent handler to attach to the entities state event.

◆ 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 State::Constructed or State::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

componentTypeId The 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 DependencySortOutcome AZ::Entity::DependencySort ( ComponentArrayType & components )

static

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

components An array of components attached to the entity.

Returns: A successful outcome is returned if the entity can determine an order in which to activate its components. Otherwise the outcome contains details on why the sort failed.

◆ EvaluateDependencies()

DependencySortResult AZ::Entity::EvaluateDependencies ( )

Same as EvaluateDependenciesGetDetails(), but if sort fails only a code is returned, there is no detailed error message.

◆ EvaluateDependenciesGetDetails()

DependencySortOutcome AZ::Entity::EvaluateDependenciesGetDetails ( )

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: A successful outcome is returned if the entity can determine an order in which to activate its components. Otherwise the failed outcome contains details on why the sort failed.

◆ FindComponent() [1/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.

◆ FindComponent() [2/4]

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

Finds a component by component ID.

Parameters

id	The 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() [3/4]

template<class ComponentType >

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

inline

Finds a component by component ID.

Parameters

id	The 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]

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

Finds the first component of the requested component type.

Parameters

typeId The 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.

◆ FindComponents()

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.

◆ 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.

◆ GetEntitySpawnTicketId()

u32 AZ::Entity::GetEntitySpawnTicketId ( ) const

Gets the ticket id used to spawn the entity.

Returns: the ticket id used to spawn the entity. If entity is not spawned, the id will be 0.

◆ GetId()

EntityId AZ::Entity::GetId ( ) const

inline

Gets the ID of the entity.

Returns: The ID of the entity.

◆ GetName()

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

inline

Gets the name of the entity.

Returns: The name of the entity.

◆ GetProcessSignature()

static AZ::u32 AZ::Entity::GetProcessSignature ( )

static

Gets the Process Signature of the local machine.

Returns: The Process Signature of the local machine.

◆ 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.

◆ GetTransform()

TransformInterface* AZ::Entity::GetTransform ( ) const

Gets the TransformInterface for the entity.

Returns: The TransformInterface for the entity.

◆ 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 ( )

Indicates to the entity that dependencies among its components need to be evaluated. Dependencies will be evaluated the next time the entity is activated.

◆ IsRuntimeActiveByDefault()

bool AZ::Entity::IsRuntimeActiveByDefault ( ) const

Returns: true if the entity is marked to activate by default upon creation.

◆ MakeId()

static EntityId AZ::Entity::MakeId ( )

static

Generates a unique entity ID.

Returns: An entity ID.

◆ Reflect()

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

static

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

Parameters

reflection A 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

component A 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.

◆ SetEntitySpawnTicketId()

void AZ::Entity::SetEntitySpawnTicketId ( u32 entitySpawnTicketId )

Sets the ticket id used to spawn the entity. The ticket id in the entity will remain 0 unless it's set using this function.

Parameters

entitySpawnTicketId the ticket id used to spawn the entity.

◆ 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

id	The ID of the entity.

◆ SetName()

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

inline

Sets the name of the entity.

Parameters

name	A name for the entity.

◆ SetRuntimeActiveByDefault()

void AZ::Entity::SetRuntimeActiveByDefault ( bool activeByDefault )

Mark the entity to be activated by default. This is observed automatically by EntityContext, and should be observed by any other custom systems that create and manage entities.

Parameters

activeByDefault whether the entity should be active by default after creation.

◆ SetState()

void AZ::Entity::SetState ( State state )

protected

Sets the entities internal state to the provided value.

Parameters

state the new state for the entity.

Member Data Documentation

◆ 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 the component dependencies have been evaluated and sorting was completed successfully.

Foundational entity properties/flags. To keep AZ::Entity lightweight, one should resist the urge the add flags here unless they're extremely common to AZ::Entity use cases, and inherently fundamental. Furthermore, if more than 4 flags are needed, please consider using a more space-efficient container, such as AZStd::bit_set<>. With just a couple flags, AZStd::bit_set's word-size of 32-bits will actually waste space.

◆ m_transform

TransformInterface* AZ::Entity::m_transform

mutableprotected

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.

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

Code/Framework/AzCore/AzCore/Component/Entity.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ ComponentArrayType

Member Enumeration Documentation

◆ DependencySortResult

◆ State

Constructor & Destructor Documentation

◆ Entity() [1/2]

◆ Entity() [2/2]

◆ ~Entity()

Member Function Documentation

◆ Activate()

◆ AddComponent()

◆ AddStateEventHandler()

◆ CanAddRemoveComponents()

◆ CreateComponent() [1/2]

◆ CreateComponent() [2/2]

◆ Deactivate()

◆ DependencySort()

◆ EvaluateDependencies()

◆ EvaluateDependenciesGetDetails()

◆ FindComponent() [1/4]

◆ FindComponent() [2/4]

◆ FindComponent() [3/4]

◆ FindComponent() [4/4]

◆ FindComponents()

◆ GetComponents()

◆ GetEntitySpawnTicketId()

◆ GetId()

◆ GetName()

◆ GetProcessSignature()

◆ GetState()

◆ GetTransform()

◆ Init()

◆ InvalidateDependencies()

◆ IsRuntimeActiveByDefault()

◆ MakeId()

◆ Reflect()

◆ RemoveComponent()

◆ SetEntitySpawnTicketId()

◆ SetId()

◆ SetName()

◆ SetRuntimeActiveByDefault()

◆ SetState()

Member Data Documentation

◆ m_id

◆ m_isDependencyReady

◆ m_transform