Creating a Component
Open 3D Engine (O3DE), the successor to Lumberyard, is now available in Developer Preview. Download O3DE |
A component in Lumberyard is a simple class that inherits from Lumberyard's
AZ::Component
. A component's behavior is determined by its reflected data
and the actions it takes when it is activated. This section shows you how to create Lumberyard
components programmatically. For information about adding and customizing the components
available in Lumberyard Editor, see Working with component entities.
Component Example
An example component class skeleton follows:
#include <AzCore/Component/Component.h> class MyComponent : public AZ::Component { public: AZ_COMPONENT(MyComponent, "{0C09F774-DECA-40C4-8B54-3A93033EC381}", AZ::Component); // AZ::Component interface implementation. void Init() override {} void Activate() override {} void Deactivate() override {} // Required Reflect function. static void Reflect(AZ::ReflectContext* context); // Optional functions for defining provided and dependent services. static void GetProvidedServices(AZ::ComponentDescriptor::DependencyArrayType& provided); static void GetDependentServices(AZ::ComponentDescriptor::DependencyArrayType& dependent); static void GetRequiredServices(AZ::ComponentDescriptor::DependencyArrayType& required); static void GetIncompatibleServices(AZ::ComponentDescriptor::DependencyArrayType& incompatible); };
Component Members
The required and optional members that a component comprises are as follows:
- AZ::Component
-
Every component must include
AZ::Component
somewhere in its inheritance ancestry. Noneditor components generally inherit directly fromAZ::Component
, as in the following example:class MyComponent : public AZ::Component
You can also create your own component class hierarchies.
- AZ_COMPONENT Macro
-
Every component must specify the
AZ_COMPONENT
macro in its class definition. The macro takes two arguments:-
The component type name.
-
A unique UUID. You may use any UUID generator to produce the value. Visual Studio provides this functionality through Tools, Create GUID. Use the Registry Format setting, and then copy and paste the value that is generated.
A sample
AZ_COMPONENT
macro follows:AZ_COMPONENT(MyComponent, "{0C09F774-DECA-40C4-8B54-3A93033EC381}", AZ::Component);
-
- AZ::Component Functions
-
To define a component's behavior, you generally override three
AZ::Component
functions:Init
,Activate
, andDeactivate
:void Init() override {} void Activate() override {} void Deactivate() override {}
These functions are as described as follows:
- Init()
-
(Optional) Called only once for a given entity. It requires minimal construction or setup work, since the component may not be activated anytime soon. An important best practice is to minimize your component's CPU and memory overhead while the component is inactive.
- Activate()
-
(Required) Called when the owning entity is being activated. The system calls your component's
Activate()
function only if all dependent or required services are present. YourActivate
function is always called after any components that it depends on. In addition, the component makeup of an entity never changes while the entity is active. Consequently, it is safe to cache pointers or references to other components on the entity when performance is critical. - Deactivate()
-
(Required) Called when the owning entity is being deactivated. The order of deactivation is the reverse of activation, so your component is deactivated before the components it depends on. As a best practice, make sure your component returns to a minimal footprint when it is deactivated. In general, deactivation should be symmetric to activation.
Note Destruction does not necessarily follow deactivation. An entity can be deactivated and then activated again without being destroyed, so ensure that your components support this efficiently. However, when you do destroy your entity, Lumberyard ensures that your
Deactivate()
function is called first. Components must be authored with this in mind.
- Reflect()
-
(Required) All components are AZ reflected classes. Because all components must be serializable and editable, they must contain a
Reflect()
function, as in the following example:// Required Reflect function. static void Reflect(AZ::ReflectContext* context);
For more information, see Reflecting a Component for Serialization and Editing.
- Logical Services
-
(Optional) Components can define any combination of logical services that they provide, depend on, require, or are incompatible with. To define these logical services, use the following functions:
// Optional functions for defining provided and dependent services. static void GetProvidedServices(AZ::ComponentDescriptor::DependencyArrayType& provided); static void GetDependentServices(AZ::ComponentDescriptor::DependencyArrayType& dependent); static void GetRequiredServices(AZ::ComponentDescriptor::DependencyArrayType& required); static void GetIncompatibleServices(AZ::ComponentDescriptor::DependencyArrayType& incompatible);