Version:

Multiplayer Auto-components

Auto-components provide a convenient way to create Open 3D Engine (O3DE) multiplayer components. These components define states that are relevant to network synchronization. Using the AzAutoGen system, you can process auto-component files that are found in your project during a build to automatically generate C++ classes for components and to create controllers that provide network replication and remote function calls. Auto-components also manage edit and behavior context bindings so that the bound component shows in O3DE Editor and works with O3DE scripting.

To enable auto-component builds for your project, follow the instructions in Multiplayer: Project Configuration.

Auto-component file structure

Auto-components are defined in XML files and placed in the Code\Source\Autogen directory of the Multiplayer Gem. According to naming convention, auto-component filenames must end with the suffix .AutoComponent.xml.

Component attributes

The Component tag defines the name, namespace, include path, and override behavior for the multiplayer component that’s being described.

PropertyDescriptionType
NameThe class name of the generated auto-component.string: Must be a valid C++ class name.
NamespaceThe namespace the generated auto-component will be placed within. For a given Gem, all defined auto-components must be defined within the same namespace. Mixing namespaces inside a Gem will result in compiler errors.string: Must be a valid C++ namespace name.
OverrideComponentIf true, the generated component will be a base class and the developer implementing the multiplayer component will be responsible for supplying the final derived component used in the editor and at runtime.bool
OverrideControllerIf true, the generated controller will be a base class, and the developer implementing the multiplayer component will be responsible for supplying the final derived controller used in the runtime.bool
OverrideIncludeIf either OverrideComponent or OverrideController are true, this value is required and must be the path (relative to the Gem root) of the header containing the concrete implementations.string: The developer implementing the final component or controller classes must provide the class header that the final classes are declared within.

ComponentRelation

The ComponentRelation tag indicates this component’s relationship with other components. Use this to define whether or not this component requires or is incompatible with sibling components on the same entity. For example, the NetworkCharacterComponent requires a NetworkTransformComponent on the same entity to properly function.

PropertyDescriptionType
NameThe name of the related component.string: Must be a valid C++ class name.
NamespaceThe namespace the related component is declared within.string: Must be a valid C++ namespace.
IncludeThe include path of the related component.string
ConstraintThe type of relation this entry has with the component being described. The allowed values are:Required, Weak, Incompatible
Required: The related component must be present on the entity. These components are displayed in the Editor as a hard requirement for adding this autocomponent.
Weak: The related component isn’t required, but will be activated on the entity (if present) before this auto-component.
Incompatible: The related component isn’t compatible with this auto-component. Attempting to place both components on an entity will result in an error.
HasControllerIf true, the related component must have a multiplayer controller associated with it. Setting this value to true will cause controller accessors to be generated on the controller being described.bool

For components that have a relation constraint of Required or Weak, accessors are generated on the auto-component with the name Get<ComponentName>(). These accessors return a cached pointer to the related component that’s created on entity activation.

Include

The Include tag is used to generate the #includes of the C++ code. Use an Include tag for each header that your generated classes will use.

PropertyDescriptionType
FileThe path to a header to add as an #include of the generated source.string

Example

NetworkWeaponsComponent.AutoComponent.xml is an example of an auto-component that synchronizes a component that represents weapon state across a multiplayer session.

<?xml version="1.0"?>

<Component
    Name="NetworkWeaponsComponent"
    Namespace="MultiplayerSample"
    OverrideComponent="true"
    OverrideController="true"
    OverrideInclude="Source/Components/NetworkWeaponsComponent.h"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <ComponentRelation Constraint="Required" HasController="true" Name="NetworkAnimationComponent" Namespace="MultiplayerSample" Include="Source/Components/NetworkAnimationComponent.h" />

    <Include File="Source/Weapons/WeaponTypes.h" />

    <NetworkInput Type="bool" Name="Draw" Init="false" />
    <NetworkInput Type="WeaponActivationBitset" Name="Firing"  Init="" />

    <NetworkProperty Type="AZ::Vector3"  Name="TargetPosition"   Init="AZ::Vector3::CreateZero()" Container="Object"       ReplicateFrom="Authority" ReplicateTo="Client"     IsPublic="false" IsRewindable="false" IsPredictable="false" ExposeToEditor="false" GenerateEventBindings="false" Description="Target position the weapons component is currently aiming at" />
    <NetworkProperty Type="FireParams"   Name="ActivationParams" Init=""  Container="Array" Count="MaxWeaponsPerComponent" ReplicateFrom="Authority" ReplicateTo="Client"     IsPublic="false" IsRewindable="false" IsPredictable="false" ExposeToEditor="false" GenerateEventBindings="false" Description="Parameters for the current weapon activation" />
    <NetworkProperty Type="uint8_t"      Name="ActivationCounts" Init="0" Container="Array" Count="MaxWeaponsPerComponent" ReplicateFrom="Authority" ReplicateTo="Client"     IsPublic="false" IsRewindable="false" IsPredictable="false" ExposeToEditor="false" GenerateEventBindings="false" Description="The number of activations" />
    <NetworkProperty Type="WeaponState"  Name="WeaponStates"     Init=""  Container="Array" Count="MaxWeaponsPerComponent" ReplicateFrom="Authority" ReplicateTo="Autonomous" IsPublic="false" IsRewindable="false" IsPredictable="true"  ExposeToEditor="false" GenerateEventBindings="false" Description="The predictable states of the weapons" />

    <ArchetypeProperty Type="WeaponParams" Name="WeaponParams"  Init=""           Container="Array" Count="MaxWeaponsPerComponent" ExposeToEditor="true" Description="Parameters for the weapons attached to this NetworkWeaponsComponent" />
    <ArchetypeProperty Type="AZ::Name"     Name="FireBoneNames" Init="AZ::Name()" Container="Array" Count="MaxWeaponsPerComponent" ExposeToEditor="true" Description="Name of the bone to attach to for fire events" />

    <RemoteProcedure Name="SendConfirmHit" InvokeFrom="Authority" HandleOn="Client" IsPublic="false" IsReliable="false" GenerateEventBindings="false" Description="Single hit event confirmed by the server" >
        <Param Type="WeaponIndex" Name="WeaponIndex" />
        <Param Type="HitEvent"    Name="HitEvent" />
    </RemoteProcedure>

    <RemoteProcedure Name="SendConfirmProjectileHit" InvokeFrom="Authority" HandleOn="Client" IsPublic="false" IsReliable="false" GenerateEventBindings="false" Description="Fired by projectile entities on confirmed hit" >
        <Param Type="WeaponIndex" Name="WeaponIndex" />
        <Param Type="HitEvent"    Name="HitEvent" />
    </RemoteProcedure>
</Component>

Building auto-components

Auto-components are processed when you compile and build your project. Whenever you update an auto-component XML file, you must reconfigure and recompile O3DE Editor, Game Launcher, and Server Launcher. This is because the XML is used to generate a C++ file, and the C++ file must be compiled. For more information about configuring builds, refer to Configure and Build.

Like other O3DE components, make sure to add your auto-component files inside your project’s CMake file so that they can be built. Similarly, you must reconfigure and recompile after updating any CMake file.

The following example of <your-project>_files.cmake lists the auto-component files:

set(FILES
    ...
    Source/AutoGen/NetworkTestPlayerComponent.AutoComponent.xml
    Source/AutoGen/MySimpleNetPlayerComponent.AutoComponent.xml    
)