Menu
Lumberyard
C++ API Reference (Version 1.10)

A class that you use directly or as a base class to create a component-based Lumberyard application. More...

Inherits AZ::Internal::EBusEventHandler< EBus, IsNotUsingId >, and AZ::Internal::EBusEventHandler< EBus, IsNotUsingId >.

Classes

struct  Descriptor
 Configures the component application. More...
 
struct  StartupParameters
 The component application settings. More...
 

Public Types

using CreateStaticModulesCallback
 The expected signature of the callback that is used when creating modules from static libraries. More...
 
using LoadModuleOutcome
 A type that represents the outcome of loading and initializing a module. More...
 

Public Member Functions

 ComponentApplication ()
 A constructor. More...
 
virtual ~ComponentApplication ()
 A destructor. More...
 
virtual EntityCreate (const char *applicationDescriptorFile, const StartupParameters &startupParameters=StartupParameters())
 Loads the application configuration and system entity from a file. More...
 
virtual EntityCreate (const Descriptor &descriptor, const StartupParameters &startupParameters=StartupParameters())
 Creates a system allocator and system entity. More...
 
virtual void Destroy ()
 Destroys the component application. More...
 
void RegisterComponentDescriptor (const ComponentDescriptor *descriptor) override
 Registers a component descriptor with the application. More...
 
void UnregisterComponentDescriptor (const ComponentDescriptor *descriptor) override
 Unregisters a component descriptor with the application. More...
 
bool AddEntity (Entity *entity) override
 Adds an entity to the application's registry. More...
 
bool RemoveEntity (Entity *entity) override
 Removes the specified entity from the application's registry. More...
 
bool DeleteEntity (const EntityId &id) override
 Unregisters and deletes the specified entity. More...
 
EntityFindEntity (const EntityId &id) override
 Returns the entity with the matching ID, if the entity is registered with the application. More...
 
AZStd::string GetEntityName (const EntityId &id) override
 Returns the name of the entity that has the specified entity ID. More...
 
void EnumerateEntities (const ComponentApplicationRequests::EntityCallback &callback) override
 Enumerates all registered entities and invokes the specified callback for each entity. More...
 
ComponentApplicationGetApplication () override
 Gets a pointer to the application. More...
 
SerializeContextGetSerializeContext () override
 Gets the serialize context that was registered with the application. More...
 
BehaviorContextGetBehaviorContext () override
 Gets the behavior context that was registered with the application. More...
 
const char * GetAppRoot () override
 Gets the name of the working root folder that was registered with the application. More...
 
const char * GetExecutableFolder () override
 Gets the path to the directory that contains the application's executable. More...
 
Debug::DrillerManager * GetDrillerManager () override
 Returns a pointer to the driller manager, if driller is enabled. More...
 
void EnumerateModules (EnumerateModulesCallback cb) override
 Enumerates all loaded modules and invokes the specified callback for each module. More...
 
float GetTickDeltaTime () override
 Gets the latest time between ticks. More...
 
ScriptTimePoint GetTimeAtCurrentTick () override
 Gets the time in seconds since the epoch. More...
 
DescriptorGetDescriptor ()
 Gets a reference to the Descriptor instance that configures the component application. More...
 
virtual void Tick (float deltaOverride=-1.f)
 Ticks all components using the AZ::TickBus during simulation time. More...
 
virtual void TickSystem ()
 Ticks all components using the AZ::SystemTickBus at all times, even if the application is not active. More...
 
bool WriteApplicationDescriptor (const char *fileName)
 Stores the full state of the descriptor and system entity. More...
 
virtual LoadModuleOutcome LoadDynamicModule (const Descriptor::DynamicModuleDescriptor &moduleDescriptor)
 Loads and initializes a dynamic module. More...
 
virtual ComponentTypeList GetRequiredSystemComponents () const
 Enables you to require the system entity to have certain components. More...
 
virtual void ResolveModulePath (AZ::OSString &modulePath)
 This function is called whenever LoadDynamicModule() must resolve a module in order to load it. More...
 
bool IsModuleLoaded (const Descriptor::DynamicModuleDescriptor &moduleDescriptor)
 Determines whether a module is loaded. More...
 

Protected Member Functions

virtual void RegisterCoreComponents ()
 Registers all core component factories that participate in loading the bootstrap file. More...
 
virtual void ReflectSerialize ()
 Reflects all data structures to the SerializeContext. More...
 
virtual void InitStaticModules ()
 Initializes all static AZ::Module objects. More...
 
virtual void InitDynamicModules ()
 Initializes all dynamic AZ::Module objects. More...
 
virtual void InitModule (AZ::Module &module)
 Initializes one AZ::Module object. More...
 
virtual void ShutdownAllModules ()
 Shuts down all modules and unloads any loaded DLLs. More...
 
void AddRequiredSystemComponents (AZ::Entity *systemEntity)
 
void CalculateExecutablePath ()
 Calculates the directory that contains the application executable. More...
 
AZ::OSString GetFullPathForDescriptor (const char *descriptorPath)
 Adjusts an input descriptor path to the application's root path. More...
 
void OnEntityLoaded (void *classPtr, const AZ::Uuid &classId, const AZ::SerializeContext *sc, AZ::Entity **systemEntity)
 Called when the system entity is loaded. More...
 

Protected Attributes

AZStd::chrono::system_clock::time_point m_currentTime
 The time, which is sampled once at the beginning of each tick. More...
 
float m_deltaTime
 The delta (in seconds) between the previous tick and the current time. More...
 
SerializeContextm_serializeContext
 A pointer to the SerializeContext. More...
 
BehaviorContextm_behaviorContext
 A pointer to the BehaviorContext. More...
 
Descriptor m_descriptor
 The descriptor, which configures the component application. More...
 
bool m_isStarted
 True when ComponentApplication::Create() has been called. More...
 
bool m_isSystemAllocatorOwner
 True if the component application created the system memory allocator. False if it used an existing instance. More...
 
bool m_isOSAllocatorOwner
 True if the component application created the OS memory allocator. False if it used an existing instance. More...
 
void * m_memoryBlock
 A pointer to the preallocated memory that is used to feed the OS Allocator when necessary. More...
 
IAllocatorAllocate * m_osAllocator
 A pointer to the OS memory allocator. More...
 
EntitySetType m_entities
 A pointer to a map that contains the entity IDs and pointers to all the entities attached to the application. More...
 
char m_exeDirectory [AZ_MAX_PATH_LEN]
 The path of the application's executable. More...
 
Debug::DrillerManager * m_drillerManager
 A pointer to the driller manager, if Driller is enabled. More...
 
StartupParameters m_startupParameters
 A structure that contains additional application settings. More...
 
AZStd::vector< AZStd::unique_ptr< ModuleData > > m_modules
 Dynamic modules used by the application. More...
 

Detailed Description

A class that you use directly or as a base class to create a component-based Lumberyard application.

This class bootstraps the application and manages entities. It dispatches events using the AZ::ComponentApplicationEventBus and handles requests to the AZ::ComponentApplicationBus and the AZ::TickBus.

Only one application can exist at a time.

IMPORTANT: If you use this as a base class, do not add data that allocates memory when this class is instantiated. The memory managers are not ready until they are initialized during the Create() call.

Member Typedef Documentation

◆ CreateStaticModulesCallback

using AZ::ComponentApplication::CreateStaticModulesCallback = void(*)(AZStd::vector<AZ::Module*>&)

The expected signature of the callback that is used when creating modules from static libraries.

◆ LoadModuleOutcome

using AZ::ComponentApplication::LoadModuleOutcome = AZ::Outcome<ModuleData*, AZStd::string>

A type that represents the outcome of loading and initializing a module.

A successful outcome contains a pointer to the loaded module. A failed outcome contains an error message.

Constructor & Destructor Documentation

◆ ComponentApplication()

AZ::ComponentApplication::ComponentApplication ( )

A constructor.

◆ ~ComponentApplication()

virtual AZ::ComponentApplication::~ComponentApplication ( )
virtual

A destructor.

Member Function Documentation

◆ AddEntity()

bool AZ::ComponentApplication::AddEntity ( Entity entity)
override

Adds an entity to the application's registry.

Calling Init() on an entity automatically performs this operation.

Parameters
entityA pointer to the entity to add to the application's registry.
Returns
True if the operation succeeded. False if the operation failed.

◆ AddRequiredSystemComponents()

void AZ::ComponentApplication::AddRequiredSystemComponents ( AZ::Entity systemEntity)
protected

◆ CalculateExecutablePath()

void AZ::ComponentApplication::CalculateExecutablePath ( )
protected

Calculates the directory that contains the application executable.

◆ Create() [1/2]

virtual Entity* AZ::ComponentApplication::Create ( const char *  applicationDescriptorFile,
const StartupParameters startupParameters = StartupParameters() 
)
virtual

Loads the application configuration and system entity from a file.

The path is relative to AppRoot. This operation expects the first node in the file to be the descriptor, which is used to create a memory manager.

Parameters
applicationDescriptorFileThe name of the file that contains the application configuration and system entity.
startupParametersA structure that contains additional application settings.
Returns
A pointer to the system entity.

◆ Create() [2/2]

virtual Entity* AZ::ComponentApplication::Create ( const Descriptor descriptor,
const StartupParameters startupParameters = StartupParameters() 
)
virtual

Creates a system allocator and system entity.

No components are added to the system node. You must set up all system components manually.

Parameters
descriptorA structure that contains the application configuration.
startupParametersA structure that contains additional application settings.
Returns
A pointer to the system entity.

◆ DeleteEntity()

bool AZ::ComponentApplication::DeleteEntity ( const EntityId id)
override

Unregisters and deletes the specified entity.

Parameters
idA reference to the entity that will be unregistered and deleted.
Returns
True if the operation succeeded. False if the operation failed.

◆ Destroy()

virtual void AZ::ComponentApplication::Destroy ( )
virtual

Destroys the component application.

This includes deactivating all entities and system components, unloading dynamic modules, freeing memory, and disconnecting from EBuses.

◆ EnumerateEntities()

void AZ::ComponentApplication::EnumerateEntities ( const ComponentApplicationRequests::EntityCallback callback)
override

Enumerates all registered entities and invokes the specified callback for each entity.

Parameters
callbackA reference to the callback that is invoked for each entity.

◆ EnumerateModules()

void AZ::ComponentApplication::EnumerateModules ( EnumerateModulesCallback  cb)
override

Enumerates all loaded modules and invokes the specified callback for each module.

Parameters
cbA reference to the callback that is invoked for each module.

◆ FindEntity()

Entity* AZ::ComponentApplication::FindEntity ( const EntityId id)
override

Returns the entity with the matching ID, if the entity is registered with the application.

Parameters
idA reference to the entity that you are searching for.
Returns
A pointer to the entity with the specified entity ID.

◆ GetApplication()

ComponentApplication* AZ::ComponentApplication::GetApplication ( )
inlineoverride

Gets a pointer to the application.

Returns
A pointer to the application.

◆ GetAppRoot()

const char* AZ::ComponentApplication::GetAppRoot ( )
inlineoverride

Gets the name of the working root folder that was registered with the application.

Returns
A pointer to the name of the app's root folder, if a root folder was registered.

◆ GetBehaviorContext()

BehaviorContext* AZ::ComponentApplication::GetBehaviorContext ( )
inlineoverride

Gets the behavior context that was registered with the application.

BehaviorContext is a class that reflects classes, methods, and EBuses for runtime interaction.

Returns
A pointer to the behavior context, if there is one.

◆ GetDescriptor()

Descriptor& AZ::ComponentApplication::GetDescriptor ( )
inline

Gets a reference to the Descriptor instance that configures the component application.

Returns
A reference to the component application descriptor.

◆ GetDrillerManager()

Debug::DrillerManager* AZ::ComponentApplication::GetDrillerManager ( )
inlineoverride

Returns a pointer to the driller manager, if driller is enabled.

The driller manager manages all active driller sessions and driller factories.

Returns
A pointer to the driller manager. If driller is not enabled, this function returns null.

◆ GetEntityName()

AZStd::string AZ::ComponentApplication::GetEntityName ( const EntityId id)
override

Returns the name of the entity that has the specified entity ID.

Entity names are not unique. This method exists to facilitate better debugging messages.

Parameters
idA reference to the entity whose name you are seeking.
Returns
The name of the entity with the specified entity ID. If no entity is found for the specified ID, it returns an empty string.

◆ GetExecutableFolder()

const char* AZ::ComponentApplication::GetExecutableFolder ( )
inlineoverride

Gets the path to the directory that contains the application's executable.

Returns
A pointer to the name of the path that contains the application's executable.

◆ GetFullPathForDescriptor()

AZ::OSString AZ::ComponentApplication::GetFullPathForDescriptor ( const char *  descriptorPath)
protected

Adjusts an input descriptor path to the application's root path.

Parameters
descriptorPathThe original path to the descriptor.
Returns
The adjusted path to the descriptor.

◆ GetRequiredSystemComponents()

virtual ComponentTypeList AZ::ComponentApplication::GetRequiredSystemComponents ( ) const
virtual

Enables you to require the system entity to have certain components.

When you override this function, the components that you specify are added to the system entity if they were not already provided by the application descriptor.

Returns
The type IDs of the required components.

◆ GetSerializeContext()

SerializeContext* AZ::ComponentApplication::GetSerializeContext ( )
inlineoverride

Gets the serialize context that was registered with the application.

SerializeContext is a class that contains reflection data for serialization and construction of objects.

Returns
A pointer to the serialize context, if there is one.

◆ GetTickDeltaTime()

float AZ::ComponentApplication::GetTickDeltaTime ( )
override

Gets the latest time between ticks.

◆ GetTimeAtCurrentTick()

ScriptTimePoint AZ::ComponentApplication::GetTimeAtCurrentTick ( )
override

Gets the time in seconds since the epoch.

◆ InitDynamicModules()

virtual void AZ::ComponentApplication::InitDynamicModules ( )
protectedvirtual

Initializes all dynamic AZ::Module objects.

◆ InitModule()

virtual void AZ::ComponentApplication::InitModule ( AZ::Module &  module)
protectedvirtual

Initializes one AZ::Module object.

The module can be static or dynamic.

Parameters
moduleA reference to the module to initialize.

◆ InitStaticModules()

virtual void AZ::ComponentApplication::InitStaticModules ( )
protectedvirtual

Initializes all static AZ::Module objects.

◆ IsModuleLoaded()

bool AZ::ComponentApplication::IsModuleLoaded ( const Descriptor::DynamicModuleDescriptor moduleDescriptor)

Determines whether a module is loaded.

Parameters
moduleDescriptorA reference to the descriptor object that describes the module.
Returns
Returns true if the module is loaded. Otherwise, false.

◆ LoadDynamicModule()

virtual LoadModuleOutcome AZ::ComponentApplication::LoadDynamicModule ( const Descriptor::DynamicModuleDescriptor moduleDescriptor)
virtual

Loads and initializes a dynamic module.

The application owns the new module and frees its memory when the application terminates.

Parameters
moduleDescriptorA reference to an object that describes the dynamic module.
Returns
On success, returns the module. On failure, returns a string that explains the error.

◆ OnEntityLoaded()

void AZ::ComponentApplication::OnEntityLoaded ( void *  classPtr,
const AZ::Uuid &  classId,
const AZ::SerializeContext sc,
AZ::Entity **  systemEntity 
)
protected

Called when the system entity is loaded.

Parameters
classPtrA pointer to the system entity instance.
classIdThe ID of the system entity instance.
scA pointer to the SerializeContext.
systemEntityA pointer to a pointer to the system entity.

◆ ReflectSerialize()

virtual void AZ::ComponentApplication::ReflectSerialize ( )
protectedvirtual

Reflects all data structures to the SerializeContext.

This function is called when a new serialize context is created. You can use this function to implement custom modifications to the serialize context before it is filled with data.

IMPORTANT: Do not call this function directly. It is called by the system.

◆ RegisterComponentDescriptor()

void AZ::ComponentApplication::RegisterComponentDescriptor ( const ComponentDescriptor descriptor)
override

Registers a component descriptor with the application.

Parameters
descriptorA pointer to a ComponentDescriptor object that contains the details of the component.

◆ RegisterCoreComponents()

virtual void AZ::ComponentApplication::RegisterCoreComponents ( )
protectedvirtual

Registers all core component factories that participate in loading the bootstrap file.

This function is called immediately after the memory manager is created. When you create your own application, call ComponentApplication::RegisterCoreComponents() first. Then call this function to register application-specific core components.

◆ RemoveEntity()

bool AZ::ComponentApplication::RemoveEntity ( Entity entity)
override

Removes the specified entity from the application's registry.

Deleting an entity automatically performs this operation.

Parameters
entityA pointer to the entity that will be removed from the application's registry.
Returns
True if the operation succeeded. False if the operation failed.

◆ ResolveModulePath()

virtual void AZ::ComponentApplication::ResolveModulePath ( AZ::OSString &  modulePath)
virtual

This function is called whenever LoadDynamicModule() must resolve a module in order to load it.

Override this function if you need to load modules from a different path or modify module loading in some other way.

If you modify this function, ensure that you use platform-specific conventions because multiple platforms call this function.

The default implementation adds the executable path to the beginning of the module path, but you can override this behavior. Call the base class if you want the behavior to persist in overrides.

Parameters
modulePathThe path to a module.

◆ ShutdownAllModules()

virtual void AZ::ComponentApplication::ShutdownAllModules ( )
protectedvirtual

Shuts down all modules and unloads any loaded DLLs.

◆ Tick()

virtual void AZ::ComponentApplication::Tick ( float  deltaOverride = -1.f)
virtual

Ticks all components using the AZ::TickBus during simulation time.

Might not tick if the application is not active (for example, not in focus).

Parameters
deltaOverride(Optional) Value to override the delta (in seconds) between the previous tick and the current time.

◆ TickSystem()

virtual void AZ::ComponentApplication::TickSystem ( )
virtual

Ticks all components using the AZ::SystemTickBus at all times, even if the application is not active.

◆ UnregisterComponentDescriptor()

void AZ::ComponentApplication::UnregisterComponentDescriptor ( const ComponentDescriptor descriptor)
override

Unregisters a component descriptor with the application.

Parameters
descriptorA pointer to a ComponentDescriptor object that contains the details of the component.

◆ WriteApplicationDescriptor()

bool AZ::ComponentApplication::WriteApplicationDescriptor ( const char *  fileName)

Stores the full state of the descriptor and system entity.

This is useful if you want to save the state before you make changes.

Parameters
fileNameThe file to store the information in.
Returns
True if the operation succeeded. Otherwise, false.

Member Data Documentation

◆ m_behaviorContext

BehaviorContext* AZ::ComponentApplication::m_behaviorContext
protected

A pointer to the BehaviorContext.

◆ m_currentTime

AZStd::chrono::system_clock::time_point AZ::ComponentApplication::m_currentTime
protected

The time, which is sampled once at the beginning of each tick.

◆ m_deltaTime

float AZ::ComponentApplication::m_deltaTime
protected

The delta (in seconds) between the previous tick and the current time.

◆ m_descriptor

Descriptor AZ::ComponentApplication::m_descriptor
protected

The descriptor, which configures the component application.

◆ m_drillerManager

Debug::DrillerManager* AZ::ComponentApplication::m_drillerManager
protected

A pointer to the driller manager, if Driller is enabled.

◆ m_entities

EntitySetType AZ::ComponentApplication::m_entities
protected

A pointer to a map that contains the entity IDs and pointers to all the entities attached to the application.

◆ m_exeDirectory

char AZ::ComponentApplication::m_exeDirectory[AZ_MAX_PATH_LEN]
protected

The path of the application's executable.

◆ m_isOSAllocatorOwner

bool AZ::ComponentApplication::m_isOSAllocatorOwner
protected

True if the component application created the OS memory allocator. False if it used an existing instance.

◆ m_isStarted

bool AZ::ComponentApplication::m_isStarted
protected

True when ComponentApplication::Create() has been called.

◆ m_isSystemAllocatorOwner

bool AZ::ComponentApplication::m_isSystemAllocatorOwner
protected

True if the component application created the system memory allocator. False if it used an existing instance.

◆ m_memoryBlock

void* AZ::ComponentApplication::m_memoryBlock
protected

A pointer to the preallocated memory that is used to feed the OS Allocator when necessary.

◆ m_modules

AZStd::vector<AZStd::unique_ptr<ModuleData> > AZ::ComponentApplication::m_modules
protected

Dynamic modules used by the application.

◆ m_osAllocator

IAllocatorAllocate* AZ::ComponentApplication::m_osAllocator
protected

A pointer to the OS memory allocator.

◆ m_serializeContext

SerializeContext* AZ::ComponentApplication::m_serializeContext
protected

A pointer to the SerializeContext.

◆ m_startupParameters

StartupParameters AZ::ComponentApplication::m_startupParameters
protected

A structure that contains additional application settings.


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