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

Component *	CreateComponent (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 ComponentArrayType &	GetComponents () const
	Gets all components registered with the entity. More...

Component *	FindComponent ( ComponentId id) const
	Finds a component by component ID. More...

Component *	FindComponent (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...

TransformInterface *	m_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

enum AZ::Entity::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

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.

◆ AZ_CLASS_ALLOCATOR()

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

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

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

static protected

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: 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

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() [2/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.

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

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

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.

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

◆ 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

machineId An ID for the local machine.

◆ SetName()

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

inline

Sets the name of the entity.

Parameters

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

static protected

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

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

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

◆ AZ_CLASS_ALLOCATOR()

◆ AZ_RTTI()

◆ CanAddRemoveComponents()

◆ CreateComponent() [1/2]

◆ CreateComponent() [2/2]

◆ Deactivate()

◆ DependencySort()

◆ EvaluateDependencies()

◆ FindComponent() [1/4]

◆ FindComponent() [2/4]

◆ FindComponent() [3/4]

◆ FindComponent() [4/4]

◆ FindComponents() [1/2]

◆ FindComponents() [2/2]

◆ GetComponents()

◆ GetId()

◆ GetLocalMachineId()

◆ GetName()

◆ GetState()

◆ Init()

◆ InvalidateDependencies()

◆ MakeId()

◆ OnNameChanged()

◆ Reflect()

◆ RemoveComponent()

◆ SetId()

◆ SetLocalMachineId()

◆ SetName()

Member Data Documentation

◆ m_components

◆ m_id

◆ m_isDependencyReady

◆ m_name

◆ m_state

◆ m_transform

◆ s_machineId