Package your game build files Create a Amazon GameLift build Update your build files Add a build install script

Upload a custom server build to Amazon GameLift

After you integrate your game server with Amazon GameLift, upload the build files to Amazon GameLift. This topic covers how to package your game's build files, create an optional build install script, and then upload the files using the AWS Command Line Interface (AWS CLI) or an AWS SDK.

Package your game build files

Before uploading your configured game server to Amazon GameLift, package the game build files into a build directory. This directory must include all components required to run your game servers and host game sessions, including the following:

Game server binaries – The binary files required to run the game server. A build can include binaries for multiple game servers built to run on the same platform. For a list of supported platforms, see Development support with Amazon GameLift.
Dependencies – Any dependent files that your game server executables require to run. Examples include assets, configuration files, and dependent libraries.

Note
For game builds created with the Amazon GameLift server SDK for C++ (including those created with the Unreal plugin), include the OpenSSL DLL for the same version of OpenSSL that you built the server SDK with. See the server SDK README file for more details.
Install script (Optional) – A script file to handle tasks that install your game build on Amazon GameLift hosting servers. Place this file at the root of the build directory. Amazon GameLift runs the install script as part of fleet creation.

You can set up any application in your build, including your install script, to access your resources securely on other AWS services. For information about ways to do this, see Communicate with other AWS resources from your fleets.

After you've packaged your build files, make sure that your game server can run on a clean installation of your target OS. This verifies that you include all required dependencies in your package and that your install script is accurate.

Create a Amazon GameLift build

When creating a build and uploading your files, you have a couple of options:

Create a build from a file directory. This is the simplest and most commonly used option.
Create a build with files in Amazon Simple Storage Service (Amazon S3). With this option, you can manage your build versions in Amazon S3.

With both methods, Amazon GameLift creates a new build resource with a unique build ID and other metadata. The build starts in the Initialized status. After Amazon GameLift acquires the game server files, the build moves to Ready status.

When the build is ready, you can deploy it to a new Amazon GameLift fleet. For more information, see Create a Amazon GameLift managed fleet.When Amazon GameLift sets up the new fleet, it downloads the build files to each fleet instance and installs the build files.

Create a build from a file directory

To create a game build stored in any location, including a local directory, use the upload-build AWS CLI command. This command creates a new build record in Amazon GameLift and uploads files from a location that you specify.

Send an upload request. In a command line window, enter the following upload-build command and parameters.


aws gamelift upload-build \
    --name user-defined name of build \
    --operating-system supported OS \
    --server-sdk-version Amazon GameLift server SDK version \
    --build-root build path \
    --build-version user-defined build number \
    --region region name

operating-system – The game server build's runtime environment. You must specify an OS value. You can't update this later.
server-sdk-version – The version of the Amazon GameLift server SDK that your game server is integrated with. If you don't provide a value, Amazon GameLift uses the default value 4.0.2. If you specify an incorrect server SDK version, the game server build might fail when calling InitSdk to establish a connection to the Amazon GameLift service.
build-root – The directory path of your build files.
name – A descriptive name for the new build.
build-version – The version details for the build files.
region – The AWS Region where you want to create your build. Create the build in the Region where you plan to deploy fleets. If you're deploying your game in multiple Regions, create a build in each Region.

Note
View your current default Region using the aws configure get region. To change your default Region, use the aws configure set region region name command.

Examples


aws gamelift upload-build \
    --operating-system AMAZON_LINUX_2023 \

    --server-sdk-version "5.0.0" \
    --build-root "~/mygame" \
    --name "My Game Nightly Build" \
    --build-version "build 255" \
    --region us-west-2


aws gamelift upload-build \
    --operating-system WINDOWS_2016 \
    --server-sdk-version "5.0.0" \
    --build-root "C:\mygame" \
    --name "My Game Nightly Build" \
    --build-version "build 255" \
    --region us-west-2

In response to your upload request, Amazon GameLift provides upload progress. On a successful upload, Amazon GameLift returns the new build record ID. Upload time depends on the size of your game files and the connection speed.

Create a build with files in Amazon S3

You can store your build files in Amazon S3 and upload them to Amazon GameLift from there. When you create you build, you specify the S3 bucket location, and Amazon GameLift retrieves the build files directly from Amazon S3.

To create a build resource

Store your build files in Amazon S3. Create a .zip file containing the packaged build files and upload it to an S3 bucket in your AWS account. Take note of the bucket label and the file name, you'll need these when creating a Amazon GameLift build.
Give Amazon GameLift access to your build files. Create an IAM role by following the instructions in Access a game build file in Amazon S3. After you've created the role, take note of the new role's Amazon Resource Name (ARN), you'll need this when creating a build.
Create a build. Use the Amazon GameLift console or the AWS CLI to create a new build record. You must have the PassRole permission, as described in IAM permission examples for Amazon GameLift.

Console

In the Amazon GameLift console, in the navigation pane, choose Hosting, Builds.
On the Builds page, choose Create build.
On the Create build page, under Build settings, do the following:
1. For Name, enter a script name.
2. For Version, enter a version. Because you can update the content of a build, version data can help you track updates.
3. For Operating system (OS), choose the OS of your game server build. You can't update this value later.
4. For Game server build, enter the S3 URI of the build object that you uploaded to Amazon S3, and choose the Object version. If you don't remember the Amazon S3 URI and object version, choose Browse S3 and search for the build object.
5. For IAM role, choose the role that you created that gives Amazon GameLift access to your S3 bucket and build object.
(Optional) Under Tags, add tags to the build by entering Key and Value pairs.
Choose Create.

Amazon GameLift assigns an ID to the new build and uploads the designated .zip file. You can view the new build, including the status, on the Builds page.

AWS CLI

To define the new build and upload your server build files, use the create-build command.

Open a command line window and switch to a directory where you can use the AWS CLI.
Enter the following create-build command:
```
aws gamelift create-build \
    --name user-defined name of build \
    --server-sdk-version Amazon GameLift server SDK version \
    --operating-system supported OS \
    --build-version user-defined build number \
    --storage-location "Bucket"=S3 bucket label,"Key"=Build .zip file name,"RoleArn"=Access role ARN} \
    --region region name
```
- name – A descriptive name for the new build.
- server-sdk-version – The version of the Amazon GameLift server SDK you used to integrate your game server with Amazon GameLift. If you don't provide a value, Amazon GameLift uses the default value 4.0.2.
- operating-system – The game server build's runtime environment. You must specify an OS value. You can't update this later.
- build-version – The version details for the build files. This information can be useful because each new version of your game server requires a new build resource.
- storage-location
  - Bucket – The name of the S3 bucket that contains your build. For example, "my_build_files".
  - Key – The name of the .zip file that contains your build files. For example, "my_game_build_7.0.1, 7.0.2".
  - RoleARN – The ARN assigned to the IAM role that you created. For example, "arn:aws:iam::111122223333:role/GameLiftAccess". For an example policy, see Access a game build file in Amazon S3.
- region – Create the build in the AWS Region where you plan to deploy fleets. If you're deploying your game in multiple Regions, create a build in each Region.
  
  Note
  We recommend checking your current default Region using the configure get command. To change your default Region, use the configure set command.
Example
```
aws gamelift create-build \
    --operating-system WINDOWS_2016 \
    --storage-location "Bucket"="my_game_build_files","Key"="mygame_build_101.zip","RoleArn"="arn:aws:iam::111122223333:role/gamelift" \
    --name "My Game Nightly Build" \
    --build-version "build 101" \
    --region us-west-2
```
To view the new build, use the describe-build command.

Update your build files

You can update the metadata for a build resource using the Amazon GameLift console or the update-build AWS CLI command.

After you've created a Amazon GameLift build, you can't update the build files associated with it. For each new set of files, create a new Amazon GameLift build. Using the upload-build command, Amazon GameLift automatically creates a new build record for each request. If you provide build files using the create-build command, upload a new build .zip file with a different name to Amazon S3 and create a build by referencing the new file name.

Try these tips for deploying updated builds:

Use queues and swap out fleets as needed. When setting up your game client with Amazon GameLift, specify a queue instead of a fleet. With queues, you can add the new fleets with the new build to your queue and remove the old fleets. For more information, see Setting up Amazon GameLift queues for game session placement.
Use aliases to transfer players to a new game build. When integrating your game client with Amazon GameLift, specify a fleet alias instead of a fleet ID. For more information, see Add an alias to a Amazon GameLift fleet.
Set up automated build updates. For sample scripts and information about incorporating Amazon GameLift deployments into your build system, see Automating Deployments to Amazon GameLift on the AWS Game Tech Blog.

Add a build install script

Create an install script for the operating system (OS) of your game build:

Windows: Create a batch file named install.bat.
Linux: Create a shell script file named install.sh.

When creating an install script, keep in mind the following:

The script can't take any user input.
Amazon GameLift installs the build and recreates the file directories in your build package on a hosting server in the following locations:
- Windows fleets: C:\game
- Linux fleets: /local/game
During the installation process for Linux fleets, the run-as user has limited access to the instance file structure. This user has full rights to the directory where your build files are installed. If your install script performs actions that require administrator permissions, then specify admin access using sudo. The run-as user for Windows fleets has administrator permissions by default. Permission failures related to the install script generate an event message that indicates a problem with the script.
On Linux, Amazon GameLift supports common shell interpreter languages such as bash. Add a shebang (such as #!/bin/bash) to the top of your install script. To verify support for your preferred shell commands, remotely access an active Linux instance and open a shell prompt. For more information, see Remotely connect to Amazon GameLift fleet instances.
The install script can't rely on a VPC peering connection. A VPC peering connection isn't available until after Amazon GameLift installs the build on fleet instances.

Example Windows install bash file

This example install.bat file installs Visual C++ runtime components required for the game server and writes the results to a log file. The script includes the component file in the build package at the root.


vcredist_x64.exe /install /quiet /norestart /log c:\game\vcredist_2013_x64.log

Example Linux install shell script

This example install.sh file uses bash in the install script and writes results to a log file.


#!/bin/bash
echo 'Hello World' > install.log

This example install.sh file shows how you can use the Amazon CloudWatch agent to collect system-level and custom metrics, and handle log rotation. Because Amazon GameLift runs in a service VPC, you must grant Amazon GameLift permissions to assume an AWS Identity and Access Management (IAM) role on your behalf. To allow Amazon GameLift to assume a role, create a role that includes the AWS managed policy CloudWatchAgentAdminPolicy, and use that role when you create a fleet.


sudo yum install -y amazon-cloudwatch-agent
sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo yum install -y collectd
cat <<'EOF' > /tmp/config.json
{
    "agent": {
        "metrics_collection_interval": 60,
        "run_as_user": "root",
        "credentials": {
            "role_arn": "arn:aws:iam::account#:role/rolename"
        }
    },
    "logs": {
        "logs_collected": {
            "files": {
                "collect_list": [
                    {
                        "file_path": "/tmp/log",
                        "log_group_name": "gllog",
                        "log_stream_name": "{instance_id}"
                    }
                ]
            }
        }
    },
    "metrics": {
       "namespace": "GL_Metric",
        "append_dimensions": {
            "ImageId": "${aws:ImageId}",
            "InstanceId": "${aws:InstanceId}",
            "InstanceType": "${aws:InstanceType}"
        },
        "metrics_collected": {
            // Configure metrics you want to collect.
            // For more information, see Manually create or edit the CloudWatch agent configuration file.
        }
    }
}
EOF
sudo mv /tmp/config.json /opt/aws/amazon-cloudwatch-agent/bin/config.json
sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -s -c file:/opt/aws/amazon-cloudwatch-agent/bin/config.json
sudo systemctl enable amazon-cloudwatch-agent.service

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

Uploading builds and scripts

Upload a script

Upload a custom server build to Amazon GameLift

Topics

Package your game build files

Note

Create a Amazon GameLift build

Create a build from a file directory

Note

Create a build with files in Amazon S3

To create a build resource

Note

Update your build files

Add a build install script

Example Windows install bash file

Example Linux install shell script