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 |
A destructor.
Member Function Documentation
◆ AddEntity()
|
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()
|
protected |
- Deprecated:
- Use GetRequiredSystemComponents() instead.
◆ CalculateExecutablePath()
|
protected |
Calculates the directory that contains the application executable.
◆ Create() [1/2]
|
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 |
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()
|
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 |
Destroys the component application.
This includes deactivating all entities and system components, unloading dynamic modules, freeing memory, and disconnecting from EBuses.
◆ EnumerateEntities()
|
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()
|
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()
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()
|
inline override |
Gets a pointer to the application.
- Returns
- A pointer to the application.
◆ 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()
|
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()
|
inline |
Gets a reference to the Descriptor instance that configures the component application.
- Returns
- A reference to the component application descriptor.
◆ 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()
|
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()
|
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()
|
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 |
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()
|
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()
|
override |
Gets the latest time between ticks.
◆ GetTimeAtCurrentTick()
|
override |
Gets the time in seconds since the epoch.
◆ InitDynamicModules()
|
protected virtual |
Initializes all dynamic
AZ::Module
objects.
◆ InitModule()
|
protected virtual |
Initializes one
AZ::Module
object.
The module can be static or dynamic.
- Parameters
-
module A reference to the module to initialize.
◆ 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 |
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()
|
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()
|
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()
|
override |
Registers a component descriptor with the application.
- Parameters
-
descriptor A pointer to a ComponentDescriptor object that contains the details of the component.
◆ 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()
|
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 |
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()
|
protected virtual |
Shuts down all modules and unloads any loaded DLLs.
◆ Tick()
|
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 |
Ticks all components using the AZ::SystemTickBus at all times, even if the application is not active.
◆ UnregisterComponentDescriptor()
|
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
|
protected |
A pointer to the BehaviorContext .
◆ m_currentTime
|
protected |
The time, which is sampled once at the beginning of each tick.
◆ m_deltaTime
|
protected |
The delta (in seconds) between the previous tick and the current time.
◆ m_descriptor
|
protected |
The descriptor, which configures the component application.
◆ m_drillerManager
|
protected |
A pointer to the driller manager, if Driller is enabled.
◆ 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
|
protected |
The path of the application's executable.
◆ m_isOSAllocatorOwner
|
protected |
True if the component application created the OS memory allocator. False if it used an existing instance.
◆ m_isStarted
|
protected |
True when ComponentApplication::Create() has been called.
◆ m_isSystemAllocatorOwner
|
protected |
True if the component application created the system memory allocator. False if it used an existing instance.
◆ m_memoryBlock
|
protected |
A pointer to the preallocated memory that is used to feed the OS Allocator when necessary.
◆ m_modules
|
protected |
Dynamic modules used by the application.
◆ m_osAllocator
|
protected |
A pointer to the OS memory allocator.
◆ m_serializeContext
|
protected |
A pointer to the SerializeContext .
◆ m_startupParameters
|
protected |
A structure that contains additional application settings.
The documentation for this class was generated from the following file:
- C:/lumberyard-root/dev/Code/Framework/AzCore/AzCore/Component/ ComponentApplication.h