o3de-multiplayersample

MultiplayerSample Project

The MultiplayerSample Project is a third-person multiplayer game built on Open 3D Engine (O3DE), where robots battle one another for dominance in an under construction, multi-tiered starbase.

NOTE: For Linux setup, see the guide in README_LINUX.md

Game overview

In this sample, players compete for the highest score to win. Over a series of rounds, players race around the starbase to collect gems and rack up points. Each player is armed with a laser pistol and protected by a shield. Taking damage from laser blasts depletes the player's shield. Once the shield is depleted, the player respawns at the cost of some of their collected gems.

Do you risk it all to win?

Game features:

• 3rd-person character setup
• Weapons (laser pistols) with a reticle, projectile, and visual effects
• Environmental dangers, including energy cannons and malfunctioning shield towers
• Jump pads to boost players high into the air
• A configurable number of rounds (default: 3 rounds)
• Configurable gem spawning patterns per round to drive player exploration
• Support for 1 to 10 players
• Rich sounds and visual effects support
• Teleporters to aid player exploration and to demonstrate moving players.
• User Settings screen
• Many points of extensibility

A player can win the whole game early by reaching a score of 400. See the Gameplay Configuration docs.

Player controls

• Move using: W,A,S,D
• Speed toggle (sprint or walk): Tap Shift
• Jump: Space
• Look around: Mouse drag
• Fire primary weapon: Left mouse button
• See scoreboard: Hold Tab
• Open game menu: Esc
• Draw/holster active weapon: E

Prerequisites

This repository uses Git LFS to store large binary files. A GitHub personal access token is required to authenticate with the Git LFS service. You can setup your personal access token and credential manager with the following steps:

1. Create a Git Personal Access Token. Your personal access token credentials are required for authentication when you clone the repository. For more information, refer to Create a personal access token with the \'repo\' scope.

2. Verify you have a credential manager installed and configured. Recent versions of Git install a credential manager so that your credentials are stored and supplied automatically when required.

Conventions used in these instructions

These instructions use the following installation paths. Be sure to substitute your local installation paths:

• O3DE installation root: C:/o3de/
• O3DE 3rd-party packages root: C:/o3de-packages/

Step 1: Clone the repository

NOTE: You can clone the project to any local directory. If you clone the project inside an existing Git repository directory (for example, the directory that contains your local O3DE engine repository) you should add the o3de-multiplayersample project directory to the Git exclude file for the existing Git repository.

Option #1 (Recommended) - Cloning into a directory outside the engine repository directory

1. In a terminal, cd to the local directory where you'd like to clone the project, for example:

   mkdir C:/my-o3de-projects
   cd C:/my-o3de-projects
   

2. Clone the project.

   git clone https://github.com/o3de/o3de-multiplayersample.git
   Cloning into 'o3de-multiplayersample'...
   

3. Clone the assets. In this example the assets are cloned beside the multiplayersample project.

   git clone https://github.com/o3de/o3de-multiplayersample-assets.git
   Cloning into 'o3de-multiplayersample-assets'...
   

4. From inside your clone of o3de-multiplayersample-assets, update the submodules. This step adds some required content such as the PopcornFX Gem.

   cd o3de-multiplayersample-assets
   git submodule update --init --recursive
   

Option #2 - Cloning into the engine repository directory

1. Clone the project into a directory named 'o3de-multiplayersample' in your existing engine repository directory.

   git clone https://github.com/o3de/o3de-multiplayersample.git C:/o3de/o3de-multiplayersample
   Cloning into 'o3de-multiplayersample'...
   

2. Clone the asset Gems into a directory named 'o3de-multiplayersample-assets' in your existing engine Gems directory.

   git clone https://github.com/o3de/o3de-multiplayersample-assets.git C:/o3de/gems/o3de-multiplayersample-assets
   Cloning into 'o3de-multiplayersample-assets'...
   

3. From inside your clone of o3de-multiplayersample-assets, update the submodules. This step adds some required content such as the PopcornFX Gem.

   cd C:/o3de/gems/o3de-multiplayersample-assets
   git submodule update --init --recursive
   

4. Modify the local engine git exclude file to ignore the project directory.

   echo o3de-multiplayersample > C:/o3de/.git/info/exclude
   echo o3de-multiplayersample-assets > C:/o3de/.git/info/exclude
   

Step 1a. Ensure your branches match

Before building the project, ensure that o3de, o3de-multiplayersample and o3de-multiplayersample-assets are all cloned from the same named branches. For example, if you are using the development branch of o3de-multiplayersample, then it must be matched with the development branches of o3de, and o3de-multiplayersample-assets. Ensure that you update the submodules in o3de-multiplayersample-assets when switching branches in that repository.

If you're using a release or installer version of O3DE, then you must checkout versions of the sample repositories that match the release. O3DE uses standard Git tags to identify the release-compatible version of each repository.

For each O3DE release, repositories that have been updated to match the release should have a matching tag for the release. You can see all defined tags using the [Tags](https://github.com/o3de/o3de-multiplayersample/tags] view in each repository.

Branches can be checked out using standard Git commands, for example, git checkout tags/<tag> -b <local branch name>.

Step 1b. Verify you have the LFS files.

Verify that you have all the files from the LFS endpoint. For each cloned repository, run:

git lfs pull

If using your own fork, complete LFS setup by updating the LFS Url.

If you have problems with working with LFS, see the troubleshooting guide: https://github.com/o3de/o3de/wiki/Git-LFS-Troubleshooting.

Step 2. Register the engine, the project, and the Gems

Option #1 - Use the CLI

NOTE: The following steps only need to be performed once.

1. Register the engine.

   C:/o3de/scripts/o3de register --this-engine
   

2. Register the asset Gems.

   C:/o3de/scripts/o3de register --all-gems-path C:/my-o3de-projects/o3de-multiplayersample-assets/Gems
   

3. Register the project.

   C:/o3de/scripts/o3de register -p C:/my-o3de-projects/o3de-multiplayersample
   

The final step prints warnings that the compatibility check for MultiplayerSample and Blast will be skipped. These warnings can be ignored.

Option #2 - Use Project Manager

If you've already built the O3DE engine, use the O3DE project manager to open an existing project.

1. Run o3de.exe. If you used the engine build instructions from the Getting Started guide, o3de.exe can be found at C:/o3de/build/windows/bin/profile/o3de.exe.

2. (Optional) If MultiplayerSample is not in the My Projects view, then click the New Project... drop down and select Open Existing Project. Select the o3de-multiplayersample project. See the Project Manager User Guide for details.

3. You can choose Build in Project Manager to build the project, and skip the following Step 3. Configure and build steps.

Step 3. Configure and build

Option #1 (Recommended) - Project-centric approach

This option outputs all the project binaries in the project's build directory (for example c:/my-o3de-projects/o3de-multiplayersample/build).

1. Example project-centric configure command.

   cmake -S c:/my-o3de-projects/o3de-multiplayersample -B c:/my-o3de-projects/o3de-multiplayersample/build/windows -G "Visual Studio 16" -DLY_3RDPARTY_PATH="c:/o3de-packages"
   

2. Example project-centric build command.

   cmake --build c:/my-o3de-projects/o3de-multiplayersample/build/windows --target Editor MultiplayerSample.GameLauncher MultiplayerSample.ServerLauncher --config profile -- /m /nologo
   

Option #2 - Engine-centric approach to building a project

This option will output all the project and engine binaries in the engine's build directory (for example, c:/o3de/build).

1. Example engine-centric configure command.

   cmake -S C:/o3de -B C:/o3de/build/windows -G "Visual Studio 16" -DLY_3RDPARTY_PATH="C:/o3de-packages" -DLY_PROJECTS="C:/o3de/o3de-multiplayersample"
   

2. Example engine-centric build command.

   cmake --build C:/o3de/build/windows --target Editor MultiplayerSample.GameLauncher MultiplayerSample.ServerLauncher --config profile -- /m /nologo
   

Step 4. Setup the client and server

Under project root, there are two files: launch_client.cfg and launch_server.cfg.

1. launch_client.cfg contains the client connection setting. To connect to a server that is running locally, add the following line:

   connect
   

To connect to a remote server, add the IP address of the server after the connect statement. For example:

   connect 192.168.0.20

1. launch_server.cfg contains the initial level to load:

   LoadLevel Levels/NewStarbase/NewStarbase.spawnable
   

Step 5. Launch the server

Option #1 - Launch the server with arguments

The server launcher can be run with the following command:

build\windows\bin\profile\MultiplayerSample.ServerLauncher.exe --console-command-file=launch_server.cfg 

Note that the launch_server.cfg configuration file is passed with the --console-command-file argument.

Option #2 - Launch the server from a command file

Alternatively, you can run launch_server.cmd (Windows) or launch_server.sh (Unix) which includes the --console-command-file argument.

launch_server.cmd 

Option #3 - Launch a headless server

If you do not need to see rendered output on your server, you can reduce resource usage by launching a headless server that uses the null renderer.

NOTE: Parameters to use null renderer must be passed on the command line as the console-command-file is parsed after rendering is configured.

build\windows\bin\profile\MultiplayerSample.ServerLauncher.exe --console-command-file=launch_server.cfg -rhi=null -NullRenderer

Option #4 - Launch the server in O3DE Editor

By default, launching a local server from the editor during Play Mode is enabled. To disable this behavior, update the editorsv_enabled value in the editor.cfg file to false.

Refer to the O3DE document Test Multiplayer Games in the O3DE Editor for the complete list of console variables (CVARs) which support play in O3DE Editor with servers.

Step 6. Launch the Client

Option #1 - Launch the client with arguments

The client launcher can be run with the following command:

build\windows\bin\profile\MultiplayerSample.GameLauncher.exe --console-command-file=launch_client.cfg

This command starts the client and connects to the server specified in launch_client.cfg.

Option #2 - Launch the client from a command file

Alternatively, you can run launch_client.cmd (Windows) or launch_client.sh (Unix) which includes the --console-command-file argument.

launch_client.cmd 

Debugging in Visual Studio

When you debug MultiplayerSample.GameLauncher and MultiplayerSample.ServerLauncher from Visual Studio, it's helpful to automatically host and connect so that you don't need to open the console (~) and explicitly execute the host and loadlevel commands on server, or the connect command on client.

For convenience, Gem/Code/CMakeLists.txt defines ADDITIONAL_VS_DEBUGGER_COMMAND_ARGUMENTS which allow Visual Studio to automatically populate the debugger with command arguments.

By default, launch_client.cfg is used when debugging the GameLauncher and launch_server.cfg is used when debugging the ServerLauncher.

When debugging set net_UdpTimeoutConnections to false. This prevents connection closures when stopped on breakpoints.

Levels in this Project

This project ships with several levels, the ones of note are:

1. NewStarBase - The main game level (the default level for gameplay).
2. StartMenu - An example menu to join, host, and connect to servers.
3. GamePlayTest - Everything needed for gameplay, but in a tiny, fast-loading level. All game objects (Gems, HUD, and so on) are included.
4. MultiplayerScriptingSample - An example of scripts for Multiplayer.

Other levels in the project are used for testing or performance evaluation purposes and are considered experimental.

How to contribute?

This sample is managed by the O3DE special interest group (SIG), SIG/Network.

O3DE cannot work without the help and input from as many of its community members as possible. You do not need anyone’s permission to get involved and contribute to the project. The #sig-network channel on O3DE Discord is a great entry point to get involved.

You can contribute by reporting issues and making feature requests, fix known issues, or tackle backlogged feature requests.

Documentation

Link	Description
README_LINUX	Linux specific setup instructions
Release Notes	Release notes and known issues per major release
Gameplay Configuration	How to adjust gameplay settings
SettingsScreen	How to use and extend the settings screen
Packaging MPS	How to build and package MPS for distribution or running servers remotely
GameLift Setup	How to enable AWS GameLift integration

O3DE Useful Links

• O3DE Networking
• Multiplayer Tutorials
• Networking/Multiplayer Settings

License

For terms please see the LICENSE*.TXT files included in the root of this distribution.