Install and set up the plugin Test your game locally Deploy a scenario Integrate games with Amazon GameLift in Unity Import and run a sample game

Amazon GameLift plugin for Unity guide for server SDK 4.x

Note

This topic provides information for an earlier version of the Amazon GameLift plugin for Unity. Version 1.0.0 (released in 2021) uses the Amazon GameLift server SDK 4.x or earlier. For documentation on the latest version of the plugin, which uses server SDK 5.x and supports Amazon GameLift Anywhere, see Amazon GameLift plugin for Unity guide for server SDK 5.x.

Amazon GameLift provides tools for preparing your multiplayer game servers to run on Amazon GameLift. The Amazon GameLift plugin for Unity makes it easier to integrate Amazon GameLift into your Unity game projects and deploy Amazon GameLift resources for cloud hosting. Use the plugin for Unity to access Amazon GameLift APIs and deploy AWS CloudFormation templates for common gaming scenarios.

After you've set up the plugin, you can try out the Amazon GameLift Unity sample on GitHub.

Topics

Install and set up the plugin

Note

This topic refers to Amazon GameLift plugin for Unity version 1.0.0, which uses server SDK 4.x or earlier.

This section describes how to download, install, and set up the Amazon GameLift plugin for Unity, version 1.0.0.

Prerequisites

Unity for Windows 2019.4 LTS, Windows 2020.3 LTS, or Unity for MacOS
Current version of Java
Current version of .NET 4.x

To download and install the plugin for Unity

Download the Amazon GameLift plugin for Unity. You can find the latest version on the Amazon GameLift plugin for Unity repository page. Under the latest release, choose Assets, and then download the com.amazonaws.gamelift-version.tgz file.
Launch Unity and choose a project.
In the top navigation bar, under Window choose Package Manager:
Under the Package Manager tab choose +, and then choose Add package from tarball...:
In the Select packages on disk window, navigate to the com.amazonaws.gamelift folder, choose the file com.amazonaws.gamelift-version.tgz, and then choose Open:
After Unity has loaded the plug-in, Amazon GameLift appears as a new item in the Unity menu. It may take a few minutes to install and recompile scripts. The Amazon GameLift Plugin Settings tab automatically opens.
In the SDK pane, choose Use .NET 4.x.

When configured, the status changes from Not Configured to Configured.

Test your game locally

Note

This topic refers to Amazon GameLift plugin for Unity version 1.0.0, which uses server SDK 4.x or earlier.

Use Amazon GameLift Local to run Amazon GameLift on your local device. You can use Amazon GameLift Local to verify code changes in seconds, without a network connection.

Configure local testing

In the plugin for Unity window, choose the Test tab.
In the Test pane, choose Download Amazon GameLift Local. The plugin for Unity opens a browser window and downloads the GameLift_06_03_2021.zip file to your downloads folder.

The download includes the C# Server SDK, .NET source files, and a .NET component compatible with Unity.
Unzip the downloaded file GameLift_06_03_2021.zip.
In the Amazon GameLift Plugin Settings window, choose Amazon GameLift Local Path, navigate to the unzipped folder, choose the file GameLiftLocal.jar, and then choose Open.

When configured, local testing status changes from Not Configured to Configured.
Verify the status of the JRE. If the status is Not Configured, choose Download JRE and install the recommended Java version.

After you install and configure the Java environment, the status changes to Configured.

Run your local game

In the plugin for Unity tab, choose the Test tab.
In the Test pane, choose Open Local Test UI.
In the Local Testing window, specify a Server executable path. Select ... to select the path and executable name of your server application.
In the Local Testing window, specify a GL Local port.
Choose Deploy & Run to deploy and run the server.
To stop your game server, choose Stop or close the game server windows.

Deploy a scenario

Note

This topic refers to Amazon GameLift plugin for Unity version 1.0.0, which uses server SDK 4.x or earlier.

A scenario uses an AWS CloudFormation template to create the resources you need to deploy a cloud hosting solution for your game. This section describes the scenarios Amazon GameLift provides and how to use them.

Prerequisites

To deploy the scenario, you need an IAM role for the Amazon GameLift service. For information on how to create a role for Amazon GameLift, see Set up an AWS account.

Each scenario requires permissions to the following resources:

Amazon GameLift
Amazon S3
AWS CloudFormation
API Gateway
AWS Lambda
AWS WAFV2
Amazon Cognito

Scenarios

Note

This topic refers to Amazon GameLift plugin for Unity version 1.0.0, which uses server SDK 4.x or earlier.

The Amazon GameLift Plug-in for Unity includes the following scenarios:

Auth only

This scenario creates a game backend service that performs player authentication without game server capability. The template creates the following resources in your account:

An Amazon Cognito user pool to store player authentication information.
An Amazon API Gateway REST endpoint-backed AWS Lambda handler that starts games and views game connection information.

Single-Region fleet

This scenario creates a game backend service with a single Amazon GameLift fleet. It creates the following resources:

An Amazon Cognito user pool for a player to authenticate and start a game.
An AWS Lambda handler to search for an existing game session with an open player slot on the fleet. If it can't find a open slot, it creates a new game session.

Multi-Region fleet with a queue and custom matchmaker

This scenario forms matches by using Amazon GameLift queues and a custom matchmaker to group together the oldest players in the waiting pool. It creates the following resources:

An Amazon Simple Notification Service topic that Amazon GameLift publishes messages to. For more information on SNS topics and notifications, see Set up event notification for game session placement.
A Lambda function that's invoked by the message that communicates placement and game connection details.
An Amazon DynamoDB table to store placement and game connection details. GetGameConnection calls read from this table and return the connection information to the game client.

Spot fleets with a queue and custom matchmaker

This scenario forms matches by using Amazon GameLift queues and a custom matchmaker and configures three fleets. It creates the following resources:

Two Spot fleets that contain different instance types to provide durability for Spot unavailability.
An On-Demand fleet that acts as a backup for the other Spot fleets. For more information on designing your fleets, see Amazon GameLift fleet design guide.
A Amazon GameLift queue to keep server availability high and cost low. For more information and best practices about queues, see Design a game session queue.

FlexMatch

This scenario uses FlexMatch, a managed matchmaking service, to match game players together. For more information about FlexMatch, see What is Amazon GameLift FlexMatch. This scenario creates the following resources:

A Lambda function to create a matchmaking ticket after it receives StartGame requests.
A separate Lambda function to listen to FlexMatch match events.

To avoid unnecessary charges on your AWS account, remove the resources created by each scenario after you are done using them. Delete the corresponding AWS CloudFormation stack.

Update AWS credentials

Note

This topic refers to Amazon GameLift plugin for Unity version 1.0.0, which uses server SDK 4.x or earlier.

The Amazon GameLift plugin for Unity requires security credentials to deploy a scenario. You can either create new credentials or use existing credentials.

For more information about configuring credentials, see Understanding and getting your AWS credentials.

To update AWS credentials

In Unity, in the plugin for Unity tab, choose the Deploy tab.
In the Deploy pane, choose AWS Credentials.
You can create new AWS credentials or choose existing credentials.
- To create credentials, choose Create new credentials profile, and then specify the New Profile Name, AWS Access Key ID, AWS Secret Key, and AWS Region.
- To choose existing credentials, choose Choose existing credentials profile and then select a profile name and AWS Region.
In the Update AWS Credentials window, choose Update Credentials Profile.

Update account bootstrap

Note

This topic refers to Amazon GameLift plugin for Unity version 1.0.0, which uses server SDK 4.x or earlier.

The bootstrap location is an Amazon S3 bucket used during deployment. It's used to store game server assets and other dependencies. The AWS Region you choose for the bucket must be the same Region you will use for the scenario deployment.

For more information about Amazon S3 buckets, see Creating, configuring, and working with Amazon Simple Storage Service buckets.

To update the account bootstrap location

In Unity, in the plugin for Unity tab, choose the Deploy tab.
In the Deploy pane, choose Update Account Bootstrap.
In the Account Bootstrapping window, you choose an existing Amazon S3 bucket or create a new Amazon S3 bucket:
- To choose an existing bucket, choose Choose existing Amazon S3 bucket and Update to save your selection.
- Choose Create new Amazon S3 bucket to create a new Amazon Simple Storage Service bucket, then choose a Policy. The policy specifies when the Amazon S3 bucket will be expire. Choose Create to create the bucket.

Deploy a game scenario

Note

This topic refers to Amazon GameLift plugin for Unity version 1.0.0, which uses server SDK 4.x or earlier.

You can use a scenario to test your game with Amazon GameLift. Each scenario uses a AWS CloudFormation template to create a stack with the required resources. Most of the scenarios require a game server executable and build path. When you deploy the scenario, Amazon GameLift copies game assets to the bootstrap location as part of deployment.

You must configure AWS credentials and an AWS account bootstrap to deploy a scenario.

To deploy a scenario

In Unity, in the plugin for Unity tab, choose the Deploy tab.
In the Deploy pane, choose Open Deployment UI.
In the Deployment window, choose a scenario.
Enter a Game Name. It must be unique. The game name is part of the AWS CloudFormation stack name when you deploy the scenario.
Choose the Game Server Build Folder Path. The build folder path points to the folder containing the server executable and dependencies.
Choose the Game Server Build .exe File Path. The build executable file path points to the game server executable.
Choose Start Deployment to begin deploying a scenario. You can follow the status of the update in the Deployment window under Current State.Scenarios can take several minutes to deploy.
When the scenario completes deployment, the Current State updates to include the Cognito Client ID and API Gateway Endpoint that you can copy and paste into the game.
To update game settings, on the Unity menu, choose Go To Client Connection Settings. This displays an Inspector tab on the right side of the Unity screen.
Deselect Local Testing Mode.
Enter the API Gateway Endpoint and the Coginito Client ID. Choose the same AWS Region you used for the scenario deployment. You can then rebuild and run the game client using the deployed scenario resources.

Deleting resources created by the scenario

Note

This topic refers to Amazon GameLift plugin for Unity version 1.0.0, which uses server SDK 4.x or earlier.

To delete the resources created for the scenario, delete the corresponding AWS CloudFormation stack.

To delete resources created by the scenario

In the Amazon GameLift plugin for Unity Deployment window, select View AWS CloudFormation Console to open the AWS CloudFormation console.
In the AWS CloudFormation console, choose Stacks, and then choose the stack that includes the game name specified during deployment.
Choose Delete to delete the stack. It may take a few minutes to delete a stack. After AWS CloudFormation deletes the stack used by the scenario, its status changes to ROLLBACK_COMPLETE.

Integrate games with Amazon GameLift in Unity

Note

This topic refers to Amazon GameLift plugin for Unity version 1.0.0, which uses server SDK 4.x or earlier.

Integrate your Unity game with Amazon GameLift by completing the following tasks:

The following diagram shows an example flow of integrating a game. In the diagram, a fleet with the game server is deployed to Amazon GameLift. The game client communicates with the game server, which communicates with Amazon GameLift.

Architecture diagram of integrating Unity with Amazon GameLift.

Import and run a sample game

Note

This topic refers to Amazon GameLift plugin for Unity version 1.0.0, which uses server SDK 4.x or earlier.

The Amazon GameLift plugin for Unity includes a sample game you can use to explore the basics of integrating your game with Amazon GameLift. In this section, you build the game client and game server and then test locally using Amazon GameLift Local.

Prerequisites

Build and run the sample game server

Note

This topic refers to Amazon GameLift plugin for Unity version 1.0.0, which uses server SDK 4.x or earlier.

Set up the game server files of the sample game.

In Unity, on the menu, choose Amazon GameLift, and then choose Import Sample Game.
In the Import Sample Game window, choose Import to import the game, its assets and dependencies.
Build the game server. In Unity, on the menu, choose Amazon GameLift, and then choose Apply Windows Sample Server Build Settings or Apply MacOS Sample Server Build Settings. After you configure the game server settings, Unity recompiles the assets.
In Unity, on the menu, choose File, and then choose Build. Choose Server Build, choose Build, and then choose a build folder specifically for server files.

Unity builds the sample game server, placing the executable and required assets in the specified build folder.

Build and run the sample game client

Note

This topic refers to Amazon GameLift plugin for Unity version 1.0.0, which uses server SDK 4.x or earlier.

Set up the game client files of the sample game.

In Unity, on the menu, choose Amazon GameLift, and then choose Apply Windows Sample Client Build Settings or Apply MacOS Sample Client Build Settings. After the game client settings are configured, Unity will recompile assets.
In Unity, on the menu, select Go To Client Settings. This will display an Inspector tab on the right side of the Unity screen. In the Amazon GameLift Client Settings tab, select Local Testing Mode.
Build the game client. In Unity, on the menu, choose File. Confirm Server Build is not checked, choose Build, and then select a build folder specifically for client files.

Unity builds the sample game client, placing the executable and required assets in the specified client build folder.
You've no built the game server and client. In the next steps, you run the game and see how it interacts with Amazon GameLift.

Test the sample game locally

Note

This topic refers to Amazon GameLift plugin for Unity version 1.0.0, which uses server SDK 4.x or earlier.

Run the sample game you imported using Amazon GameLift Local.

Launch the game server. In Unity, in the plugin for Unity tab, choose the Deploy tab.
In the Test pane, choose Open Local Test UI.
In the Local Testing window, specify a Game Server .exe File Path. The path must include the executable name. For example, C:/MyGame/GameServer/MyGameServer.exe.
Choose Deploy and Run. The plugin for Unity launches the game server and opens a Amazon GameLift Local log window. The windows contains log messages including messages sent between the game server and Amazon GameLift Local.
Launch the game client. Find the build location with the sample game client and choose the executable file .
In the Amazon GameLift Sample Game, provide an email and password and then choose Log In. The email and password aren't validated or used.
In the Amazon GameLift Sample Game, choose Start. The game client looks for a game session. If it can't find a session, it creates one. The game client then starts the game session. You can see game activity in the logs.


...
2021-09-15T19:55:3495 PID:20728 Log :) GAMELIFT AWAKE 
2021-09-15T19:55:3512 PID:20728 Log :) I AM SERVER 
2021-09-15T19:55:3514 PID:20728 Log :) GAMELIFT StartServer at port 33430. 
2021-09-15T19:55:3514 PID:20728 Log :) SDK VERSION: 4.0.2 
2021-09-15T19:55:3556 PID:20728 Log :) SERVER IS IN A GAMELIFT FLEET 
2021-09-15T19:55:3577 PID:20728 Log :) PROCESSREADY SUCCESS. 
2021-09-15T19:55:3577 PID:20728 Log :) GAMELIFT HEALTH CHECK REQUESTED (HEALTHY)
...
2021-09-15T19:55:3634 PID:20728 Log :) GAMELOGIC AWAKE 
2021-09-15T19:55:3635 PID:20728 Log :) GAMELOGIC START 
2021-09-15T19:55:3636 PID:20728 Log :) LISTENING ON PORT 33430 
2021-09-15T19:55:3636 PID:20728 Log SERVER: Frame: 0 HELLO WORLD! 
...
2021-09-15T19:56:2464 PID:20728 Log :) GAMELIFT SESSION REQUESTED
2021-09-15T19:56:2468 PID:20728 Log :) GAME SESSION ACTIVATED
2021-09-15T19:56:3578 PID:20728 Log :) GAMELIFT HEALTH CHECK REQUESTED (HEALTHY)
2021-09-15T19:57:3584 PID:20728 Log :) GAMELIFT HEALTH CHECK REQUESTED (HEALTHY)
2021-09-15T19:58:0334 PID:20728 Log SERVER: Frame: 8695 Connection accepted: playerIdx 0 joined
2021-09-15T19:58:0335 PID:20728 Log SERVER: Frame: 8696 Connection accepted: playerIdx 1 joined 
2021-09-15T19:58:0338 PID:20728 Log SERVER: Frame: 8697 Msg rcvd from playerIdx 0 Msg: CONNECT: server IP localhost 
2021-09-15T19:58:0338 PID:20728 Log SERVER: Frame: 8697 Msg rcvd from player 0:CONNECT: server IP localhost 
2021-09-15T19:58:0339 PID:20728 Log SERVER: Frame: 8697 CONNECT: player index 0 
2021-09-15T19:58:0339 PID:20728 Log SERVER: Frame: 8697 Msg rcvd from playerIdx 1 Msg: CONNECT: server IP localhost 
2021-09-15T19:58:0339 PID:20728 Log SERVER: Frame: 8697 Msg rcvd from player 1:CONNECT: server IP localhost 
2021-09-15T19:58:0339 PID:20728 Log SERVER: Frame: 8697 CONNECT: player index 1


12:55:26,000  INFO || - [SocketIOServer] main - Session store / pubsub factory used: MemoryStoreFactory (local session store only)
12:55:28,092  WARN || - [ServerBootstrap] main - Unknown channel option 'SO_LINGER' for channel '[id: 0xe23d0a14]'
12:55:28,101  INFO || - [SocketIOServer] nioEventLoopGroup-2-1 - SocketIO server started at port: 5757
12:55:28,101  INFO || - [SDKConnection] main - GameLift SDK server (communicates with your game server) has started on http://localhost:5757
12:55:28,120  INFO || - [SdkWebSocketServer] WebSocketSelector-20 - WebSocket Server started on address localhost/127.0.0.1:5759
12:55:28,166  INFO || - [StandAloneServer] main - GameLift Client server (listens for GameLift client APIs) has started on http://localhost:8080
12:55:28,179  INFO || - [StandAloneServer] main - GameLift server sdk http listener has started on http://localhost:5758
12:55:35,453  INFO || - [SdkWebSocketServer] WebSocketWorker-12 - onOpen socket: /?pID=20728&sdkVersion=4.0.2&sdkLanguage=CSharp and handshake /?pID=20728&sdkVersion=4.0.2&sdkLanguage=CSharp
12:55:35,551  INFO || - [HostProcessManager] WebSocketWorker-12 - client connected with pID 20728
12:55:35,718  INFO || - [GameLiftSdkHttpHandler] GameLiftSdkHttpHandler-thread-0 - GameLift API to use: ProcessReady for pId 20728
12:55:35,718  INFO || - [ProcessReadyHandler] GameLiftSdkHttpHandler-thread-0 - Received API call for processReady from 20728
12:55:35,738  INFO || - [ProcessReadyHandler] GameLiftSdkHttpHandler-thread-0 - onProcessReady data: port: 33430
 12:55:35,739  INFO || - [HostProcessManager] GameLiftSdkHttpHandler-thread-0 - Registered new process with pId 20728
12:55:35,789  INFO || - [GameLiftSdkHttpHandler] GameLiftSdkHttpHandler-thread-0 - GameLift API to use: ReportHealth for pId 20728
12:55:35,790  INFO || - [ReportHealthHandler] GameLiftSdkHttpHandler-thread-0 - Received API call for ReportHealth from 20728
12:55:35,794  INFO || - [ReportHealthHandler] GameLiftSdkHttpHandler-thread-0 - ReportHealth data: healthStatus: true
 12:56:24,098  INFO || - [GameLiftHttpHandler] Thread-12 - API to use: GameLift.DescribeGameSessions
12:56:24,119  INFO || - [DescribeGameSessionsDispatcher] Thread-12 - Received API call to describe game sessions with input: {"FleetId":"fleet-123"}
12:56:24,241  INFO || - [GameLiftHttpHandler] Thread-12 - API to use: GameLift.CreateGameSession
12:56:24,242  INFO || - [CreateGameSessionDispatcher] Thread-12 - Received API call to create game session with input: {"FleetId":"fleet-123","MaximumPlayerSessionCount":4}
12:56:24,265  INFO || - [HostProcessManager] Thread-12 - Reserved process: 20728 for gameSession: arn:aws:gamelift:local::gamesession/fleet-123/gsess-59f6cc44-4361-42f5-95b5-fdb5825c0f3d
12:56:24,266  INFO || - [WebSocketInvoker] Thread-12 - StartGameSessionRequest: gameSessionId=arn:aws:gamelift:local::gamesession/fleet-123/gsess-59f6cc44-4361-42f5-95b5-fdb5825c0f3d, fleetId=fleet-123, gameSessionName=null, maxPlayers=4, properties=[], ipAddress=127.0.0.1, port=33430, gameSessionData?=false, matchmakerData?=false, dnsName=localhost
12:56:24,564  INFO || - [CreateGameSessionDispatcher] Thread-12 - GameSession with id: arn:aws:gamelift:local::gamesession/fleet-123/gsess-59f6cc44-4361-42f5-95b5-fdb5825c0f3d created
12:56:24,585  INFO || - [GameLiftHttpHandler] Thread-12 - API to use: GameLift.DescribeGameSessions
12:56:24,585  INFO || - [DescribeGameSessionsDispatcher] Thread-12 - Received API call to describe game sessions with input: {"FleetId":"fleet-123"}
12:56:24,660  INFO || - [GameLiftSdkHttpHandler] GameLiftSdkHttpHandler-thread-0 - GameLift API to use: GameSessionActivate for pId 20728
12:56:24,661  INFO || - [GameSessionActivateHandler] GameLiftSdkHttpHandler-thread-0 - Received API call for GameSessionActivate from 20728
12:56:24,678  INFO || - [GameSessionActivateHandler] GameLiftSdkHttpHandler-thread-0 - GameSessionActivate data: gameSessionId: "arn:aws:gamelift:local::gamesession/fleet-123/gsess-59f6cc44-4361-42f5-95b5-fdb5825c0f3d"

Shut down server process

Note

This topic refers to Amazon GameLift plugin for Unity version 1.0.0, which uses server SDK 4.x or earlier.

After you're done with your sample game, shut down the server in Unity.

In the game client, choose Quit or close the window to stop the game client.
In Unity, in the Local Testing window, choose Stop or close the game server windows to stop the server.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Deploy your game to managed Amazon EC2 fleets

Integrate a Unity game server