# Testing and troubleshooting compatibility with Proton for Amazon GameLift Streams
If your Amazon GameLift Streams application runs on a Proton runtime environment, this section can help you troubleshoot compatibility issues between your application and the Proton layer. These instructions include a set of scripts that installs Proton to your own machine, simulating the environment that Amazon GameLift Streams would use. By troubleshooting without the Amazon GameLift Streams service, you can focus on troubleshooting issues specific to your application and the runtime environment.
## High-level steps to test and troubleshoot
1. Acquire an Ubuntu 22.04 LTS machine. You can use either a local machine or an Amazon EC2 cloud-based desktop. Choose from the following topics for instructions:
+ [Set up a local machine](troubleshoot-compatibility-setup-local.md)
+ [Set up a remote machine](troubleshoot-compatibility-setup-remote.md)
1. Install the Proton runtime environment to test and debug your application. Refer to [Troubleshoot on Proton](troubleshoot-compatibility-wp-proton.md) for guidance.
## Known issues with Proton
Refer to the [Proton GitHub wiki](https://github.com/ValveSoftware/Proton/wiki) for the latest compatibility and troubleshooting resources. You can also search for issues in the Proton GitHub [issue tracker](https://github.com/ValveSoftware/Proton/issues). Following are some specific issues to be aware of that our customers have encountered when running Windows applications on Proton:
**Godot applications on Proton**
+ Godot-based applications running on Proton might encounter a black screen if the Amazon Vulkan capture layer is enabled. To mitigate this issue, disable shared textures when streaming by setting the environment variable `VK_LAYER_AMZN_BLITSURFACE_SHARED_TEXTURES=0`.
**Unreal Engine applications on Proton**
+ If you run into problems on Proton 8.x with Electra Media Player, (an Unreal Engine plugin) we recommend using the fixes found in [https://github.com/ValveSoftware/wine/pull/257](https://github.com/ValveSoftware/wine/pull/257).
# Set up a local machine to troubleshoot Proton
Proton is a compatibility layer that enables Windows applications to run on Linux. As such, you must have an Ubuntu machine to test and troubleshoot with. If you don't have a local Ubuntu machine, you can set up a remote machine using Amazon EC2. To do so, follow the steps in [Set up a remote machine](troubleshoot-compatibility-setup-remote.md) instead.
## Prerequisites
+ [Ubuntu 22.04 LTS](https://releases.ubuntu.com/jammy/). For installation instructions, you can use Ubuntu's [Install Ubuntu Desktop](https://ubuntu.com/tutorials/install-ubuntu-desktop) tutorial.
+ NVIDIA GPU
## Install GPU drivers
Installing the latest GPU drivers can prevent your application from poor performance and crashes.
**To check what GPU driver your system uses**
1. Run the following command in a terminal:
```
lshw -C display | grep driver
```
1. If the correct drivers are installed, you should see the following output, or similar, where ** is `nvidia` for NVIDIA: `configuration: driver= latency=0`
**To install the latest NVIDIA GPU drivers**
Follow the instructions in [NVIDIA drivers installation](https://documentation.ubuntu.com/server/how-to/graphics/install-nvidia-drivers/).
## Verify GPU drivers
Verify that GPU drivers are installed and working correctly. One way to verify this is by running the [vkcube](https://github.com/krh/vkcube) application in a terminal.
1. Install the `vulkan-tools` apt package using the following command.
```
sudo apt install -y vulkan-tools
```
1. Run `vkcube`.
1. Review the output.
+ If your system is properly using the correct GPU, you will see output similar to the following, with the name of your GPU: `Selected GPU 0: AMD Radeon Pro V520 (RADV NAVI12), type: 2`
+ If your application isn&t able to use the GPU correctly, you might see different output similar to the following: `Selected GPU 0: llvmpipe (LLVM 15.0.7, 256 bits), type: 4`
In this case, check the GPU drivers and re-install if needed.
## Next step
With your local Ubuntu machine ready, the next step is to set up Proton. For instructions, refer to [Troubleshoot on Proton](troubleshoot-compatibility-wp-proton.md).
# Set up a remote Amazon EC2 machine to troubleshoot Proton
If you don't have a local Ubuntu machine, follow these instructions to set up a remote machine instead.
In this step, you will set up your remote Ubuntu machine using Amazon Elastic Compute Cloud (Amazon EC2), which you will use to troubleshoot your application's compatibility with Proton for Amazon GameLift Streams. This topic describes how to set up an Amazon EC2 instance with Ubuntu 22.04 LTS, necessary GPU drivers, and the Amazon DCV Server for a visual remote desktop.
## Launch an Amazon EC2 Instance with Ubuntu 22.04 LTS AMI
1. Navigate to Amazon EC2 in the AWS Management Console.
1. Select **Launch Instances**.
1. Enter "Amazon GameLift Streams Testing" for **Name**.
1. Select **Ubuntu Server 22.04 LTS (HVM)** for **Application and OS Images (Amazon Machine Image)**.
1. Select **g4dn.2xlarge** for **Instance Type**.
1. For **Key pair (login)**, choose a key pair if you want to use SSH to access the instance. We recommend using an instance profile with the `AmazonSSMManagedInstanceCore` policy to connect to your instances using AWS Systems Manager Session Manager. For more details, follow [Adding Session Manager permissions to an existing IAM role](https://docs.aws.amazon.com/systems-manager/latest/userguide/getting-started-add-permissions-to-existing-profile.html).
1. For **Network settings**, create a new security group:
1. For **Security Group Name**, enter **DCV.**
1. Add **Inbound Security Group Rules** with **Type** `Custom TCP`, **Port Range** `8443`, and **Source Type** `Anywhere` to allow access using Amazon DCV.
1. Increase storage to at least **256 GiB** and choose **gp3** as the storage type.
1. Choose **Launch Instance**.
Your instance should now be launched.
Follow the instructions in [Connect to your Linux instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstances.html) to connect to the instance using SSH or AWS Systems Manager Session Manager.
## Install GPU drivers
### G4dn - NVIDIA GPU
Install additional modules and Linux firmware by running the following commands:
```
sudo apt install linux-modules-extra-aws linux-firmware
# Install the AWS CLI required for NVIDIA driver installation
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
sudo apt install unzip
unzip awscliv2.zip
sudo ./aws/install
```
Follow the instructions on the NVIDIA GRID drivers for Ubuntu and Debian in [Install NVIDIA drivers on Linux](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/install-nvidia-driver.html).
## Set up user environment
Set up your user environment so it can use the GPU by running the following commands. This does the following things:
+ Add you to the `video` groups to give you access to a video device, and the `render` group to give you access to a rendering device.
+ Install the AWS CLI, which is required for NVIDIA drivers and for downloading your applications or games from Amazon S3.
```
sudo adduser user
# Add the current user to the video and render group
sudo usermod -a -G video user
sudo usermod -a -G render user
sudo adduser user sudo
# Install the AWS CLI
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
sudo apt install unzip
unzip awscliv2.zip
sudo ./aws/install
sudo reboot
```
## Installation and configuration of Amazon DCV
Reconnect to the instance using SSH or AWS Systems Manager Session Manager and follow the instructions from [Installing the Amazon DCV Server on Linux for Ubuntu](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux.html).
+ Verify that the server is correctly configured as described in the documentation.
+ Follow the steps in [Install and configure NVIDIA drivers](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux-prereq.html#linux-prereq-gpu) for NVIDIA GPU.
+ Add the Amazon DCV user to video group, as explained in [step 7 of the Installing the Server guide](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing-linux-server.html) (navigate to the Ubuntu tab).
There is no need to install any optional parts of the Amazon DCV Server.
When you're done, run the following command to start the Amazon DCV Server:
```
sudo systemctl start dcvserver
sudo systemctl enable dcvserver
```
## Connecting to the Ubuntu Server using the Amazon DCV client
Reconnect to your Ubuntu instance and create a session for a user by running:
```
sudo dcv create-session --owner user --user user my-session --type console
```
You can now use the Amazon DCV Client to access your Ubuntu instance using its public IP address. When you launch a Amazon DCV client, a window appears, allowing you to access your Ubuntu instance through a visual display.
![\[When you launch a Amazon DCV client, a window appears, allowing you to access your Ubuntu instance through a visual display.\]](http://docs.aws.amazon.com/gameliftstreams/latest/developerguide/images/troubleshoot-compatibility-setup-remote-dcv.png)
## Verify GPU drivers
Verify that GPU drivers are installed and working correctly. One way to verify this is by running the [vkcube](https://github.com/krh/vkcube) application in a terminal.
1. Install the `vulkan-tools` apt package using the following command.
```
sudo apt install -y vulkan-tools
```
1. Run `vkcube`.
1. Review the output.
+ If your system is properly using the correct GPU, you will see output similar to the following, with the name of your GPU: `Selected GPU 0: AMD Radeon Pro V520 (RADV NAVI12), type: 2`
+ If your application isn&t able to use the GPU correctly, you might see different output similar to the following: `Selected GPU 0: llvmpipe (LLVM 15.0.7, 256 bits), type: 4`
In this case, check the GPU drivers and re-install if needed.
## Set up Podman (Proton only)
If you're using a Proton runtime, you must install [Podman](https://wiki.debian.org/Podman), a container that's used by Proton's build process. Complete the following steps in a terminal.
1. Install Podman, a container that Proton's build process uses.
```
sudo apt install podman
```
1. In the files `/etc/subgid` and `/etc/subgid`
1. Verify that the files list your Linux machine user name and ID. You can either open the files or use the `cat` command to see what's in the files. Format example: `test:165536:65536`, where `test` corresponds to your user name.
1. If they're not listed, add them in. Format example: `test:165536:65536`, where `test` corresponds to your user name.
```
$ cat /etc/subuid
ceadmin:100000:65536
test:165536:65536
$ cat /etc/subgid
ceadmin:100000:65536
test:165536:65536
```
For more information, refer to [Basic Setup and Use of Podman in a Rootless environment](https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md#basic-setup-and-use-of-podman-in-a-rootless-environment) in Podman's documentation.
## Next step
You now have an Amazon EC2 instance and environment setup to troubleshoot compatibility issues with Amazon GameLift Streams. The next step is to set up Proton. For instructions, refer to [Troubleshoot on Proton](troubleshoot-compatibility-wp-proton.md).
# Troubleshoot compatibility on Proton
In this step, you will set up Proton on your own machine, so you can troubleshoot compatibility issues between your Amazon GameLift Streams application and Proton. Running your application in a simulated environment without the Amazon GameLift Streams server can help you identify issues specific to your application and runtime environment.
## Prerequisites
+ Ubuntu 22.04 LTS with GPU drivers installed. For instructions, refer to [Set up a local machine](troubleshoot-compatibility-setup-local.md) or [Set up a remote machine](troubleshoot-compatibility-setup-remote.md).
## Install Proton
To install Proton on your Ubuntu 22.04 LTS machine, use the following script to clone, build, and configure the version of Proton you want to test from the [Proton GitHub repository](https://github.com/ValveSoftware/Proton/).
1. Copy and paste the following code into a file called `proton-setup.sh` on your Ubuntu 22.04 LTS machine.
```
#!/bin/bash
# This is a script to build Proton. The default build is a tag from the
# experimental_9.0 branch of Proton, but can be changed as a parameter to this script.
#
# Usage: ./proton-setup.sh [optional proton_branch_name {default: experimental-9.0-20241121b}]
set -e
sudo apt install -y podman make git
# clone proton from github, recurse submodules
# if no proton git link is supplied, use a default tag from the experimental_8.0 branch
PROTON_BRANCH=${1:-"experimental-9.0-20241121b"}
PROTON_BUILD_DIR=protonBuild
PROTON_DIR=$(pwd)/proton
if git clone https://github.com/ValveSoftware/Proton.git --recurse-submodules --branch $PROTON_BRANCH proton;
then
echo "Successfully cloned Proton and its submodules."
else
echo "Warning: a proton directory/repository already exists. It is recommended to delete this folder and re-run this script unless it is a valid repository with initialized submodules."
fi
if [ -d $PROTON_BUILD_DIR ];
then
echo "Error: protonBuild directory already exists. Delete this folder first to create a fresh build of Proton before re-running this script."
exit 1
fi
mkdir $PROTON_BUILD_DIR
cd $PROTON_BUILD_DIR
$PROTON_DIR/configure.sh --enable-ccache --container-engine=podman
# build proton
echo "Building Proton"
make
echo "Done building Proton!"
# prepare proton for execution
cd dist
mkdir compatdata
if [ -e ./dist ]; then
PROTON_FILES=dist
elif [ -e ./files ]; then
PROTON_FILES=files
fi
cp version $PROTON_FILES/
echo "Finished installing proton. Proton binary location: $(pwd)/proton"
echo "STEAM_COMPAT_DATA_PATH: $(pwd)/compatdata"
echo "STEAM_COMPAT_CLIENT_INSTALL_PATH: anything"
```
1. In this step you will run the Proton setup script to clone and install Proton and additional dependencies. The script accepts as an argument the tag or branch name for the Proton version you want to install. To simulate one of the custom builds of Proton that Amazon GameLift Streams provides, use the instructions for that version, below.
**Note**
Expect the cloning from GitHub to take some time. There are many submodules to download, totalling several gigabytes.
In your terminal, run the `proton-setup.sh` script and specify the Proton version branch:
+ **Built-in Proton versions**
+ For Proton 9.0-2 (`PROTON-20250516`), use [experimental-9.0-20241121b](https://github.com/ValveSoftware/Proton/tree/experimental-9.0-20241121b).
```
proton-setup.sh experimental-9.0-20241121b
```
+ For Proton 8.0-5 (`PROTON-20241007`), use [experimental-8.0-20240205](https://github.com/ValveSoftware/Proton/tree/experimental-8.0-20240205).
```
proton-setup.sh experimental-8.0-20240205
```
Typically, no additional source code is needed. However, if you run into problems with Electra Media Player, (an Unreal Engine plugin) we recommend using the fixes found in [https://github.com/ValveSoftware/wine/pull/257](https://github.com/ValveSoftware/wine/pull/257).
**Note**
For Proton 8.0-2c (`PROTON-20230704`), Amazon GameLift Streams uses a proprietary build, which is not available to buld locally.
+ **Recommended custom Proton version**
For a custom Proton version, we recommend using the Proton experimental\$18.0 branch.
```
proton-setup.sh experimental_8.0
```
+ **Other custom Proton versions**
For other Proton versions, use an exact branch or tag name listed in [Proton releases](https://github.com/ValveSoftware/Proton/releases).
```
proton-setup.sh branch-or-tag-name
```
If your installation is successful, the output in your terminal should be similar to the following:
```
...
Done building Proton!
Finished preparing proton. Proton binary location: /home/test/protonBuild/dist/proton
STEAM_COMPAT_DATA_PATH: /home/test/protonBuild/dist/compatdata
STEAM_COMPAT_CLIENT_INSTALL_PATH: anything
```
Take note of the following variables from the output because you will need them to run Proton in the next step:
+ Proton binary location
+ `STEAM_COMPAT_DATA_PATH`
+ `STEAM_COMPAT_CLIENT_INSTALL_PATH`
## Run your application on Proton
The following steps assume that the application executable is located in `path/myapplication/bin/application.exe`. Replace it with the path and file name for your application.
+ In a terminal, navigate to the folder where your application executable is located.
```
cd path/myapplication/bin/application.exe
```
+ Run your application on Proton. Use the Proton binary location and the environment variables that you got in the previous step.
```
STEAM_COMPAT_DATA_PATH=/home/test/protonBuild/dist/compatdata STEAM_COMPAT_CLIENT_INSTALL_PATH=anything /home/test/protonBuild/dist/proton run application.exe
```
The application should now attempt to start. If the application starts locally, but not on Amazon GameLift Streams, it may be due to a configuration issue when calling Amazon GameLift Streams APIs. Verify that the API call parameters are correct. Otherwise, continue to the next step for debugging.
## Debug the application through log files
If your application has issues running on the local Proton environment, check the output log. The log contains output from your application and runtime environment. Trace where your application is failing to discover issues on the application side.
To dump the log output into a text file, such as `proton.log`, use the following command:
```
STEAM_COMPAT_DATA_PATH=/home/test/protonBuild/dist/compatdata STEAM_COMPAT_CLIENT_INSTALL_PATH=anything /home/test/protonBuild/dist/proton run application.exe &>proton.log
```
Proton also indicates if the issue is due to a Wine plugin, unimplemented function, missing dlls, and so on. For more information, see [Wine HQ's Debugging Wine](https://wiki.winehq.org/Wine_Developers_Guide/Debugging_Wine) guide. If you find a Proton or Wine error in the logs that you can't fix on the application side, reach out to your AWS Account Manager or post a question in [AWS re:Post](https://repost.aws/tags/TAOU7EpUOuTQSSWmIHCfb2fQ/amazon-gamelift-streams) for help with further debugging.