AWS gameliftstreams documentation change
Summary
Expanded troubleshooting guide with detailed instructions for optimizing game streaming performance, including shader caching methods (driver-based and Unreal Engine PSO cache) and Windows application load time improvements
Security assessment
The changes focus on performance optimization and technical troubleshooting guidance for streaming applications. While they include detailed instructions for shader caching and file handling, there is no evidence of addressing security vulnerabilities, access controls, encryption, or other security-related concepts. The modifications are operational improvements rather than security fixes or security feature documentation.
Diff
diff --git a/gameliftstreams/latest/developerguide/troubleshoot.md b/gameliftstreams/latest/developerguide/troubleshoot.md index e431f0d74..b8fb36891 100644 --- a//gameliftstreams/latest/developerguide/troubleshoot.md +++ b//gameliftstreams/latest/developerguide/troubleshoot.md @@ -64 +64 @@ Advise your customers to check the following: -If your game is experiencing high latency or poor optimization, it can result in a disappointing gaming experience. Make sure to check that your game streams smoothly with Amazon GameLift Streams. +This section identifies potential causes for poor game streaming performance and offers suggestions for optimizing your streams with Amazon GameLift Streams. @@ -66 +66 @@ If your game is experiencing high latency or poor optimization, it can result in -**Check the connection** +### Game performance is reduced when streaming on Amazon GameLift Streams @@ -68 +68 @@ If your game is experiencing high latency or poor optimization, it can result in -If your game runs well on your own machine but struggles when you stream it on Amazon GameLift Streams, consider the following: +If your game runs well on your own machine but experiences performance issues when you stream it on Amazon GameLift Streams, consider the following: @@ -70 +70 @@ If your game runs well on your own machine but struggles when you stream it on A - * Your machine might have more powerful hardware than Amazon GameLift Streams. Make sure to test the application on a machine with similar performance as the hardware that Amazon GameLift Streams uses, which is similar to a laptop with NVIDIA 2070 GPU. + * Your machine might have more powerful hardware than Amazon GameLift Streams. Make sure to test the application on a machine with similar performance to the hardware that Amazon GameLift Streams uses. For gen4n stream classes, this is comparable to a computer with an NVIDIA RTX 2060 GPU. For gen5n stream classes, this is comparable to a computer with an NVIDIA RTX 3080 GPU. @@ -77,2 +76,0 @@ If your game runs well on your own machine but struggles when you stream it on A -**Optimize your game** - @@ -85,0 +84,113 @@ If your game is slow even when running locally, you'll need to optimize its perf +### Windows applications experience slow load times or stuttering issues + +If your game is experiencing long load times or stuttering behavior, we recommend the following course of action: + + 1. Ensure your application is packaged and optimized for loading performance using your engine vendor’s guidance around optimizing content and shader performance. + + 2. Ensure your application is set to be the [default application](./multi-apps.html#multi-apps-about-linking) in a stream group. + + 3. Optimize application first launch on the service by caching shaders as part of your application packaging. + + + + +There are two approaches to enabling shader caching: + + * **Driver-based caching** – This approach is specific to the runtime environment GPU and driver version. This option can be applied to all applications and is therefore the default recommended approach. The steps for this approach will need to be replicated for every GPU/driver combination. + + * **Engine-based caching** – This approach enables shader caching through the game engine, if available. It places the burden of creating a pre-baked pipeline state object (PSO) cache on the developer. It also assumes that the engine is capable of handling cache support for different drivers on the same GPU hardware. + + + + +As a best practice, we recommend implementing driver-based caching first, because it does not require deep understanding of how PSO caching is implemented for the given engine. + +With these implementations, shader files can be exported and packaged with your application so that they don't have to be generated with every new stream start. + +###### To implement a driver-based caching fix for a Windows runtime application + + 1. Start streaming your default application and play it extensively to generate shaders for the application. + +###### Important + +Be sure to visit all the areas or levels of the environment to generate as many shaders as possible. + + 2. _Before_ closing the stream, enable the export feature in your active stream session. For details, see [Export stream session files](./stream-sessions-export-files.html). + + 3. Download the stream session export .zip file from the Amazon S3 bucket you specified in the previous step. You can find a download link on the Amazon GameLift Streams console on the **Sessions** page. + + 4. Locate the shaders folder within the stream session export. It's usually saved to this location: `AppData\Local\NVIDIA\DXCache`. Upload the generated shader files (`*.nvph`) to your application's Amazon S3 bucket. + + 5. Create a `.bat` file that will copy the shader files into the NVIDIA caching folder at runtime. This folder is usually located at: `C:\Users\Administrator\AppData\Local\NVIDIA\DXCache`. Upload the `.bat` file to the Amazon S3 application bucket. + + 6. Create a new Amazon GameLift Streams application with the `.bat` file as the executable path. + + + + +When your application starts streaming, your `.bat` file will copy the pre-generated shaders to the shader cache before launching the application, improving the stream loading performance. + +###### Note + +You might need to repeat these steps whenever you update your application or link the Amazon GameLift Streams application to a new stream group. Newer stream groups can contain updated GPU drivers from the service. + +The following example `.bat` file assumes that the shader files are stored under the Amazon S3 bucket prefix `Shaders\`. You can use a different folder structure. + + + @echo off + set CURRENT_PATH=%cd% + set DXCACHE_DIR=%CURRENT_PATH%\Shaders + set NVIDIA_DXCACHE_DIR=C:\Users\Administrator\AppData\Local\NVIDIA\DXCache + + if not exist "%NVIDIA_DXCACHE_DIR%" ( + mkdir "%NVIDIA_DXCACHE_DIR%" + ) + + xcopy /s /f "%DXCACHE_DIR%" "%NVIDIA_DXCACHE_DIR%" + + start %CURRENT_PATH%\app.exe + + +###### To implement an engine-based caching fix for an application using Unreal Engine + +For this approach, you can use Unreal Engine features to create a pipeline state object (PSO) cache for your Amazon GameLift Streams application. A PSO cache lets you deliver pre-compiled graphics pipeline states with decreased runtime compilation times, which can reduce hitches during loading and rendering. This requires advanced knowledge of Unreal Engine, and therefore we will not cover all the engine-specific details here. For additional instructions, refer to the guidance from Unreal Engine in [ Creating a Bundled PSO Cache](https://dev.epicgames.com/documentation/en-us/unreal-engine/manually-creating-bundled-pso-caches-in-unreal-engine), "Collection Flow" section. + + 1. Generate shaders for your application that has PSO logging enabled. + + 1. Create a new Amazon GameLift Streams application using the packaged build with the PSO-enabled application. + + 2. Start a stream with `-logPSO` command in your PSO logging app. You can use the command-line arguments option on the **Test stream** configuration page in the Amazon GameLift Streams console. + +###### Important + +Be sure to visit all the areas or levels of the environment to generate as many shaders as possible. + + 3. _Before_ closing the stream, enable the export feature in your active stream session. For details, see [Export stream session files](./stream-sessions-export-files.html). + + 4. Quit the application from the menu or by using Unreal shutdown commands. If you close the stream directly, the Unreal shaders pipeline file won’t be generated. + + 5. Download the stream session export .zip file from the Amazon S3 bucket you specified in the export step. You can find a download link on the Amazon GameLift Streams console on the **Sessions** page. + + 2. Package the Unreal shaders pipeline file into your Amazon GameLift Streams application. + + 1. Locate the recorded PSO files (`rec.pipelinecache`) in the stream session export under `Saved/CollectedPSOs`. Unpack the PSO files using Unreal commands. + + 2. Package a new Unreal build with the generated output from the unpacking. Follow the Unreal guidance, sections [Converting PSO caches](https://dev.epicgames.com/documentation/en-us/unreal-engine/manually-creating-bundled-pso-caches-in-unreal-engine#convertingpsocaches) and [Including PSO caches in your Application](https://dev.epicgames.com/documentation/en-us/unreal-engine/manually-creating-bundled-pso-caches-in-unreal-engine#includingpsocachesinyourapplication). + +###### Important + +When running the Unreal command in the "Converting PSO Caches" section, make sure that you use the same driver's version input files. For example: for DX12, use only the SM6 files as inputs. Otherwise you’ll get an error when packaging the new application. + + 3. Create a new Amazon GameLift Streams application for the new packaged build with the PSO files. + + 4. When starting and testing streams, confirm that PSO cache is being loaded. Check the game logs for the following line: + + Opened FPipelineCacheFile: ../../... + + + + +###### Note + +You might need to repeat these steps whenever you update your application or link the Amazon GameLift Streams application to a new stream group. Newer stream groups can contain updated GPU drivers from the service. +