Menu
Lumberyard
C++ API Reference (Version 1.10)

Open 3D Engine (O3DE), the successor to Lumberyard, is now available in Developer Preview. Download O3DE or visit the AWS Game Tech blog to learn more.

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 Entity * Create (const char *applicationDescriptorFile, const StartupParameters &startupParameters= StartupParameters ())
Loads the application configuration and system entity from a file. More...
virtual Entity * Create (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...
Entity * FindEntity (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...
ComponentApplication * GetApplication () override
Gets a pointer to the application. More...
SerializeContext * GetSerializeContext () override
Gets the serialize context that was registered with the application. More...
BehaviorContext * GetBehaviorContext () 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...
Descriptor & GetDescriptor ()
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...
SerializeContext * m_serializeContext
A pointer to the SerializeContext . More...
BehaviorContext * m_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
entity A 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
applicationDescriptorFile The name of the file that contains the application configuration and system entity.
startupParameters A 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
descriptor A structure that contains the application configuration.
startupParameters A 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
id A 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
callback A 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
cb A 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
id A 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 ( )
inline override

Gets a pointer to the application.

Returns
A pointer to the application.

GetAppRoot()

const char* AZ::ComponentApplication::GetAppRoot ( )
inline override

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

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

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
id A 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 ( )
inline override

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
descriptorPath The 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 ( )
inline override

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

Initializes all dynamic AZ::Module objects.

InitModule()

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

Initializes one AZ::Module object.

The module can be static or dynamic.

Parameters
module A reference to the module to initialize.

InitStaticModules()

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

Initializes all static AZ::Module objects.

IsModuleLoaded()

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

Determines whether a module is loaded.

Parameters
moduleDescriptor A 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
moduleDescriptor A 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
classPtr A pointer to the system entity instance.
classId The ID of the system entity instance.
sc A pointer to the SerializeContext .
systemEntity A pointer to a pointer to the system entity.

ReflectSerialize()

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

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
descriptor A pointer to a ComponentDescriptor object that contains the details of the component.

RegisterCoreComponents()

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

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
entity A 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
modulePath The path to a module.

ShutdownAllModules()

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

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
descriptor A 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
fileName The 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: