User Guide (Version 1.13)

Building Shaders for Android Games

This feature is in preview release and is subject to change.

Lumberyard uses a versatile shader system to achieve high quality, realistic graphics. Because the shader compilation pipeline depends on the Windows-specific HLSL optimizer, you must connect to a shader compiler on your PC when running a game on an Android device during the development stage. This compiles the subset of shaders required by your game on demand.


You must connect your PC and Android device to the same network and configure any firewalls to allow traffic through port 61453.

When a new shader is compiled, the game waits for the binary shader permutation to compile on your PC and be sent back to your device. Once this occurs, the shader is cached on your device until you delete the game. When you are ready to release your game, you must pack up and include all cached binary shaders.

You can use a whitelist to specify the IP addresses that are allowed to connect to your remote shader compiler. For information, see Creating a Whitelist for the Remote Shader Compiler.

Building the Shader Compiler

Building Lumberyard Editor will also build the shader compiler. Otherwise, you can build the shader compiler by changing to the \lumberyard\dev directory in a command line window and type one of the following:

  • If you are using Visual Studio 2015, run this command:

    lmbr_waf build_win_x64_vs2015_profile -p all --targets=CrySCompileServer
  • If you are using Visual Studio 2013, run this command:

    lmbr_waf build_win_x64_vs2013_profile -p all --targets=CrySCompileServer

The shader compiler executable is created in the \lumberyard\dev\Tools\CrySCompileServer\x64\profile directory.

You must also set up the mobile device system CFG file (system_android_es3.cfg) to connect to the remote shader compiler on the PC.

Running the Shader Compiler

You can run the shader compiler on your PC.

To run the shader compiler on your PC

  1. Edit the system_android_es3.cfg file (located in the \lumberyard\dev directory) to set the localhost for r_ShaderCompilerServer to the IP address of the PC on which you will run the shader compiler.

  2. Run CrySCompileServer.exe (located in the \lumberyard\dev\Tools\CrySCompileServer\x64\profile directory).

Generating and Retrieving Shaders

You can generate and retrieve shaders for your Android game.

To generate and retrieve shaders

  1. Build, deploy, and run your game on an Android device. For information, see Building Android Games

  2. In your game, explore every area in every level to ensure that all shader permutations required for the game are generated. Exit the game when you are finished.

  3. Manually copy the shaders off your Android device onto your PC. Shaders should be saved to the \storage\sdcard0\<Your Game Name>\user\cache\shaders directory.

    For example, to manually copy the Samples Project shaders, type the following in a command line window: adb pull /storage/sdcard0/SamplesProject/user <Lumberyard root directory>\cache\SamplesProject\es3\user


    If you do not see shaders located in the Cache\game project name\es3\user\cache\shaders directory, check the Cache\game project name\es3\user\shaders\cache directory. Move the shaders in this directory to the Cache\game project name\es3\user\cache\shaders directory.

Building Shader .Pak Files

You can use a command line prompt and batch file to build a .pak file that includes your shaders.

To build a shader .pak file

  1. In a command line window, navigate to the dev directory of your build and locate the BuildShaderPak_ES3.bat file.

  2. To use the BuildShaderPak_ES3.bat file, type a command that provides the name of the game project for which to build the shaders as an argument: BuildShaderPak_ES3.bat <game project name>.

    For example, to build the shaders for the Samples Project, type the following in a command line window:

    BuildShaderPak_ES3.bat SamplesProject

Deploying Shader .Pak Files

When the batch file finishes building the shader PAK file for your game project, you will find the following in the \lumberyard_version\dev\Build\es3\game project name\ directory:

  • ShaderCache.pak – Contains all compiled shaders that are used only when the shader cannot be found in the current level's shader cache.

  • ShaderCacheStartup.pak – Contains a subset of compiled shaders that are used to accelerate the startup time of the engine.

To enable your game to run the shaders from the PAK files

  1. Copy the shaders*.pak files to the \lumberyard_version\dev\Cache\game project name\es3\user directory at the root of your Lumberyard installation (\lumberyard\dev).

  2. When the shader PAK files are in the correct cache location, you can deploy the assets to the device. The game will use the shaders and will only connect to the remote shader compiler if it cannot find a shader.