IN THIS ARTICLE

Adding the Multiplayer Gem to a Project

Adding the full functionality of the Multiplayer Gem to an Open 3D Engine (O3DE) project requires making edits to the CMake scripts and source code. These changes enable:

Linking against the correct core libraries and Gems.
Building auto-components.
Creating multiplayer component descriptors.
Registering the components with the Multiplayer Gem.

Note:
Because both O3DE Gems and projects use the same CMake build functions, you can use these instructions to create a new Gem that extends the behavior of the Multiplayer Gem.

Build setup

Enable the Multiplayer Gem

Start by adding and enabling the Multiplayer Gem in your project. For help, refer to Adding and Removing Gems in a Project.

Make CMakeList.txt changes

Make sure the <ProjectName>.Static target includes the correct dependencies. Find the CMake file that defines your project’s static target. For example, <ProjectName>/Gem/Code/CMakeList.txt. Edit the <ProjectName>.Static target as follows:

In the FILES_CMAKE section, add <projectname>_autogen_files.cmake. You create this file in a later step.

    ly_add_target(
        NAME <ProjectName>.Static STATIC
        ...
        FILES_CMAKE
            ...
            <projectname>_autogen_files.cmake

In the BUILD_DEPENDENCIES PUBLIC section, add AZ::AzNetworking, Gem::Multiplayer, and AZ::AzFramework.

 ly_add_target(
     NAME <ProjectName>.Static STATIC
     ...
     BUILD_DEPENDENCIES
         PUBLIC
             AZ::AzFramework
             AZ::AzNetworking
             Gem::Multiplayer

Note:
If BUILD_DEPENDENCIES does not contain a PUBLIC section, add it as shown in the previous code example.

In the BUILD_DEPENDENCIES PRIVATE section, add Gem::Multiplayer.Static.

 ly_add_target(
     NAME <ProjectName>.Static STATIC
     ...
     BUILD_DEPENDENCIES
         PRIVATE
             ...
             Gem::Multiplayer.Static

Also add the following AUTOGEN_RULES section to the <ProjectName>.Static target:

 ly_add_target(
     NAME <ProjectName>.Static STATIC
     ...
     AUTOGEN_RULES
         *.AutoComponent.xml,AutoComponent_Header.jinja,$path/$fileprefix.AutoComponent.h
         *.AutoComponent.xml,AutoComponent_Source.jinja,$path/$fileprefix.AutoComponent.cpp
         *.AutoComponent.xml,AutoComponentTypes_Header.jinja,$path/AutoComponentTypes.h
         *.AutoComponent.xml,AutoComponentTypes_Source.jinja,$path/AutoComponentTypes.cpp

At the end of editing the CMake file, your <ProjectName>.Static target should look something like the following:

ly_add_target(
    NAME <ProjectName>.Static STATIC
    NAMESPACE Gem
    FILES_CMAKE
        <projectname>_files.cmake
        <projectname>_autogen_files.cmake
    INCLUDE_DIRECTORIES
        PRIVATE
            Source
            .
        PUBLIC
            Include
    BUILD_DEPENDENCIES
        PUBLIC
            AZ::AzFramework
            AZ::AzNetworking
            Gem::Multiplayer
        PRIVATE
            ...
            Gem::Multiplayer.Static
    AUTOGEN_RULES
        *.AutoComponent.xml,AutoComponent_Header.jinja,$path/$fileprefix.AutoComponent.h
        *.AutoComponent.xml,AutoComponent_Source.jinja,$path/$fileprefix.AutoComponent.cpp
        *.AutoComponent.xml,AutoComponentTypes_Header.jinja,$path/AutoComponentTypes.h
        *.AutoComponent.xml,AutoComponentTypes_Source.jinja,$path/AutoComponentTypes.cpp
)

Add the AutoGen CMake file

Next, create a new file named <projectname>_autogen_files.cmake and place it in the project’s code folder. For example: <ProjectName>/Gem/Code/<projectname>_autogen_files.cmake. The contents of this file add the source templates for auto-components to the project build.

set(FILES
    ${LY_ROOT_FOLDER}/Gems/Multiplayer/Code/Include/Multiplayer/AutoGen/AutoComponent_Common.jinja
    ${LY_ROOT_FOLDER}/Gems/Multiplayer/Code/Include/Multiplayer/AutoGen/AutoComponent_Header.jinja
    ${LY_ROOT_FOLDER}/Gems/Multiplayer/Code/Include/Multiplayer/AutoGen/AutoComponent_Source.jinja
    ${LY_ROOT_FOLDER}/Gems/Multiplayer/Code/Include/Multiplayer/AutoGen/AutoComponentTypes_Header.jinja
    ${LY_ROOT_FOLDER}/Gems/Multiplayer/Code/Include/Multiplayer/AutoGen/AutoComponentTypes_Source.jinja
)

Add a placeholder auto-component

Known issue:
If you’ve enabled multiplayer auto-components but you haven’t created any auto-components, you might experience a build failure. As a workaround, follow the steps in this section to create a placeholder auto-component.
You can find information about this issue here.

Under your project’s Code\Source\ directory, create a new folder named AutoGen.
Note:
This AutoGen directory doesn’t have to be temporary. All future multiplayer auto-components can live here.
Under Code\Source\AutoGen, create a new, placeholder auto-component file named MyFirstNetworkComponent.AutoComponent.xml.
Note:
This guide uses “MyFirstNetworkComponent” as the name for this multiplayer auto-component. You can specify any name for your component, but be sure to use that name consistently.

Modify Code\Source\AutoGen\MyFirstNetworkComponent.AutoComponent.xml to have the following content:

<?xml version="1.0"?>

<Component
    Name="MyFirstNetworkComponent"
    Namespace="<ProjectName>"
    OverrideComponent="false"
    OverrideController="false"
    OverrideInclude=""
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
</Component>

Important:
Replace <ProjectName> with your project’s name and make sure that the value is wrapped in quotes.

set(FILES
    ...
    Source/AutoGen/MyFirstNetworkComponent.AutoComponent.xml
)

Note:
After completing the setup steps in this guide, you can delete the placeholder auto-component and create a new auto-component, or use it as a starting point. There must always be at least one auto-component.
To learn more about multiplayer auto-components, refer to Multiplayer Auto-components or follow the introductory multiplayer tutorial.

Module and system component setup

To use multiplayer functionality, you must make small changes to the source code to generate descriptors for multiplayer components. Then, you must register these components with the Multiplayer Gem.

Module.cpp changes

Make the following changes to your project’s Code/Source/<ProjectName>Module.cpp:

Include AutoComponentTypes.h at the top of the file.
```
#include <Source/AutoGen/AutoComponentTypes.h>
```
Edit the <ProjectName>Module constructor to create the component descriptors, which allows Multiplayer components to be registered.
```
MultiplayerSampleModule()
    : AZ::Module()
{
    ...
    CreateComponentDescriptors(m_descriptors); //< Add this line to register your projects multiplayer components
}
```
Important:
Make sure the call to CreateComponentDescriptors() is the last line of the constructor.

SystemComponent.cpp changes

Make the following changes to your project’s Code/Source/<ProjectName>SystemComponent.cpp file.

Include AutoComponentTypes.h at the top of the file.
```
#include <Source/AutoGen/AutoComponentTypes.h>
```

...
void <ProjectName>SystemComponent::Activate()
{
    ...
    RegisterMultiplayerComponents(); //< Register our gems multiplayer components to assign NetComponentIds
}

Rebuild the project

Configuring and building is always required after editing CMake and C++ files. You can use the Project Manager to rebuild, or configure and build via the command-line interface (CLI).