This documentation is for a prerelease version of O3DE. Click here to switch to the latest release, or select a version from the dropdown.

Version:

System Components in O3DE

System components are similar to other components in the component entity framework of Open 3D Engine (O3DE). However, instead of creating game entity behavior, they control the behavior of the engine itself. System components are first-class elements of the game engine and are included at a deep level early in the initialization process. System components are registered onto the main Az::Module class of a Gem, activated when the Gem is loaded, and deactivated when the Gem is unloaded.

Like any O3DE component, a system component can provide services and can depend on or require other system component services. O3DE provides precise control over the order of engine initialization and system dependencies.

When you author system components, follow the best practices for component authoring. For example, your system components should use:

Important:
Just like game components, system components often provide request and notification buses. However, because system components are global systems, they should not specify IDs for their buses like game components. Game developers should be able to call your system’s EBuses without having to deal with or know about the system entity that contains all system components.

For an example of a Gem that provides system components, the HttpRequestor Gem that O3DE ships with has an implementation of a system component referenced throughout this topic. The Gem source is located at Gems/HttpRequestor/Code in the O3DE source.

Creating a system component in a Gem

O3DE enables the creation of custom system components through Gems and AZ modules. Gems are a specialization of AZ modules. Most O3DE games organize their game code in one or more Gems. These Gems can contain system components that integrate with the game engine in addition to runtime and editor components for use with game entities.

When you create a system component as part of a Gem, follow these requirements:

  • The Gem’s GetRequiredSystemComponents() function must return the system component.
  • The <GemName>Bus.h file goes under the Code/Include/<GemName> directory.
  • The component source files go under the Code/Source directory.

Making a component a system component

After you create the code for your component, add it to your project’s system entity to make it a system component. Use the GetRequiredSystemComponents() function to add your component to the system entity for your project during application startup.

The following example is from HttpRequestorModule.cpp.

#include "HttpRequestorSystemComponent.h"
#include <AzCore/Module/Module.h>

namespace HttpRequestor
{
    class HttpRequestorModule
        : public AZ::Module
    {
    public:
        AZ_RTTI(HttpRequestorModule, "{FD411E40-AF83-4F6B-A5A3-F59AB71150BF}", AZ::Module);

        HttpRequestorModule()
            : AZ::Module()
        {
            // Push results of [MyComponent]::CreateDescriptor() into m_descriptors here.
            m_descriptors.insert(m_descriptors.end(), {
                HttpRequestorSystemComponent::CreateDescriptor(),
            });
        }

        /**
         * Add required SystemComponents to the SystemEntity.
         */
        AZ::ComponentTypeList GetRequiredSystemComponents() const override
        {
            return AZ::ComponentTypeList{
                azrtti_typeid<HttpRequestorSystemComponent>(),
            };
        }
    };
}
...