Amazon GameLift Plugin for Unity Engine

Compatible with Unity 2021.3 LTS and 2022.3 LTS.

Overview

Amazon GameLift is a fully managed service that lets game developers to manage and scale dedicated game servers for session-based multiplayer games. The Amazon GameLift plugin for Unity provides tools that makes it quicker and easier to set up your Unity project for hosting on Amazon GameLift. Once the plugin is installed, you can access the plugin from within the Unity editor and start using it to integrate Amazon GameLift functionality into your client and server code. The plugin contains functionality to automatically bootstrap your game runtime environment to the AWS Cloud, fully test your game server integration with Amazon GameLift locally, and deploy your game servers on Amazon GameLift. For more information about using the plugin for Unity, see the Amazon GameLift plugin for Unity guide.

You can use built-in templates to deploy your game for the following common scenarios.

• Single-region fleet: Deploy your game server to one fleet in a single AWS Region. Use this scenario to experiment with your install scripts and runtime deployment, as well as your integration.
• Spot fleet: Deploy your game server to a set of low-cost Spot fleets and a back-up On-Demand fleet. Use this scenario to experiment with a multi-fleet hosting structure that balances cost savings and durable game session availability.
• FlexMatch fleet: Deploy your game server for hosting with a FlexMatch matchmaking solution. Amazon GameLift FlexMatch is a highly scalable and customizable matchmaking service for multiplayer games. Use this scenario to set up basic matchmaking components (including a rule set) that you can customize.

Each scenario uses an AWS CloudFormation template to deploy a resource stack for your game server solution. You can view and manage your resource stacks in the AWS Management Console for CloudFormation.

• Prerequisites
• Install the plugin
• Contributing to this plugin
• FAQ
• Amazon GameLift resources

Prerequisites

• Amazon GameLift plugin for Unity download package. Download a zip file from the GitHub Releases page. Or clone the plugin from the Github repo.
• A compatible Unity editor (2021.3 LTS, 2022.3 LTS)
• (Optional) A C# multiplayer game project with game code.
• An AWS account with access permissions to use Amazon GameLift, Amazon S3, and AWS CloudFormation. See Set up programmatic access with long-term credentials.

Install the plugin

Complete the following steps to install and enable the plugin for your multiplayer game project. For more details, see the Amazon GameLift documentation.

1. Install the Amazon GameLift Plugin for Unity.

   1. Find the com.amazonaws.gamelift-<version>.tgz file within the downloaded release zip or follow the contribution guide to build the tarball yourself.
   2. In your Unity project, open Window > Package Manager.
   3. Click + > Add package from tarball... and select the above tarball.

2. Install the Amazon GameLift C# Server SDK for Unity plugin (aka. lightweight Unity plugin).

   1. Find and unzip the GameLift-CSharp-ServerSDK-UnityPlugin-<version>.zip file within the downloaded release zip or download it from Amazon GameLift's Getting Started.
   2. In your Unity project, open Edit > Project Settings > Package Manager.
   3. Under Scoped Registries, click on the + button and enter the values for the UnityNuGet scoped registry:

      Name: Unity NuGet
      Url: https://unitynuget-registry.azurewebsites.net
      Scope(s): org.nuget
      

   4. In your Unity project, open Window > Package Manager.
   5. Click + > Add package from tarball... and select the tarball within the unzipped folder, com.amazonaws.gameliftserver.sdk-<version>.tgz.

3. (Optional) Import the sample project and configure the build settings.

   1. In your Unity project, select Amazon GameLift > Sample Game > Import Sample Game and import all assets.
   2. In your Unity project, select Amazon GameLift > Sample Game > Initialize Settings.

Contributing to this plugin

Prerequisites

• Administrator rights on a Microsoft Windows OS
• A supported Unity version
  • You also need to add the Unity editor folder (e.g. C:\Program Files\Unity\Hub\Editor\<version>\Editor\ ) to the Windows PATH environment variable.
• Visual Studio 2019 (can be installed with Unity)
• .NET Core 6 to build the core plugin source.
• NodeJS/npm: https://nodejs.org/en/download/ to package the plugin.

Modifying the plugin code

1. Clone the amazon-gamelift-plugin-unity repository from GitHub.
2. Run Scripts~\windows\release.ps1 in PowerShell to build the plugin and dependent libraries (only needed once).
3. In Unity Hub, create a new project.
4. Open Unity Package Manager, import project from disk, and select the package.json located in the plugin's root folder.
5. Setup code debugging in Unity: https://docs.unity3d.com/Manual/ManagedCodeDebugging.html, and change Unity project to Debug Mode.
6. A .sln file should be created in the Unity project root, you can open that with Visual Studio.
7. Make changes to the plugin code, and Unity should recompile after each change.
8. Once changes are made, run the unit tests via Window > General > Test Runner.

Packaging the plugin

Run Scripts~\windows\release.ps1 to clean, build and export the plugin into a tarball with a single command.

Alternatively:

1. Run Scripts~\windows\clean.ps1 to delete all dlls and temp files (If you want to build faster, you can comment out .clean-download-files execution).
2. Run Scripts~\windows\build.ps1 to build dlls and sample game.
3. Run Scripts~\windows\export.ps1 to export the plugin into a tarball (.tgz) file stored in the project root folder.

Testing the plugin

Follow instructions in Unity Docs to enable your project for testing:

1. Open the Project manifest (located at <project>/Packages/manifest.json).
2. Verify com.amazonaws.gamelift is present as a dependency.
3. Add to the bottom of the file:

    "testables": [ "com.amazonaws.gamelift" ]

After enabling testing, the project tests can be run via Unity Test Runner.

FAQ

What Unity versions are supported?

The Amazon GameLift Plug-in for Unity is compatible only with officially supported versions of Unity 2021.3 LTS and 2022.3 LTS for Windows and Mac OS.

Where are the logs?

An additional error log file related to the Unity game project can be found in the following location: logs/amazon-gamelift-plugin-logs[YYYYMMDD].txt. Note that the log file is created once a day.

Amazon GameLift Resources

• About Amazon GameLift
• Amazon GameLift documentation
• AWS Game Tech forum
• AWS for Games blog
• AWS Support Center
• GitHub issues
• Contributing guidelines