Tutorial: Building Shaders for your Mobile Game
Tutorial: Building Shaders for your Mobile Game Before running the game on the mobile device (Android or iOS) you will need to have the remote Shader Compiler running on a PC. The mobile device system CFG files (system_android_es3.cfg and system_ios_ios.cfg) also need to be setup to connect to the remote shader compiler on the PC. Build, deploy and run the game on the mobile device. Every area of every level needs to be explored to ensure that all shader permutations that are needed for the game are generated. Once all areas are explored the game can be exited.
Getting the Shaders Once the game has been run and all shaders have been generated the next step is to get the shaders off of the mobile device.
Getting the Shaders on Android On Android the shaders will be located in the user directory in the top level directory where the game assets are stored. This is generally in /storage/sdcard0/[Game Project Name]. You will want to execute the adb pull command to get the shaders off of the device onto a PC machine. Example of the command is: adb pull /storage/sdcard0/[Game Project Name]/user [Lumberyard Root Directory]\User
Getting the Shaders on iOS In Xcode select the “Window” menu and select the devices option.
Click on the settings wheel to bring up the container menu and select the download the container option.
Then go into the container package (it is the file that has the xcappdata extension) in the Mac finder, right click on it and select the “Show Package Contents” option. This will open the container for browsing in the finder.
Copy the shaders folder from the AppData/Documents folder onto a PC in the [Lumberyard Root Directory]\User directory.
Building the Shader PAK files Once the shaders have been copied to the PC into the [Lumberyard Root Directory]\User directory you can edit the batch file that generates the shader pak files: BuildShaderPak_GL4.bat.
Edit the first xcopy line to point to the location of your remote shader compiler. If you are using the default one then the path should be changed to: Tools\CrySCompileServer\x64\profile\Cache\[Game Project Name]\ShaderList_[type].txt. The final line using the default location would be: xcopy /y Tools\CrySCompileServer\x64\profile\cache\[Game Project Name]\ShaderList_[type].txt USER\Shaders\shaderlist.txt* Where [Game Project Name] is the name of your project and [type] is based on the platform. For Android type will be gles3 and for iOS it will be metal. Modify the PakShaders.bat command line to use the shader type instead of GL4. For android the type is gles3 and for iOS it is metal.
After all the edits you can run the batch file from a command prompt. You could double click the .bat file from windows explorer but you will lose any type of output from the bat file that could be useful in diagnosing any runtime issues. When the .bat file is done there should be three shader pak files in the [Lumberyard Root Directory]:
ShaderCache.pak – Contains all compiled shaders; used only when the shader cannot be found in the current level’s shader cache. ShaderCacheStartup.pak – Contains subset of compiled shaders that are needed to speed up startup of the engine. ShadersBin.pak – Contains binary parsed information of the shader source code
Deploying the Shaders Copy the shaders*.pak file to the directory [Lumberyard Root Directory]\cache\[Game Project Name]\es3 for android or [Lumberyard Root Directory]\cache\[Game Project Name]\ios for iOS platforms. Once the shader pak files are in the correct cache location the game will use those shaders and not connect to the remote shader compiler unless it cannot find a shader. If this happens then the whole process to get the shaders from the device and create the pak files needs to be repeated.
Getting the Shaders Once the game has been run and all shaders have been generated the next step is to get the shaders off of the mobile device.
Getting the Shaders on Android On Android the shaders will be located in the user directory in the top level directory where the game assets are stored. This is generally in /storage/sdcard0/[Game Project Name]. You will want to execute the adb pull command to get the shaders off of the device onto a PC machine. Example of the command is: adb pull /storage/sdcard0/[Game Project Name]/user [Lumberyard Root Directory]\User
Getting the Shaders on iOS In Xcode select the “Window” menu and select the devices option.
Click on the settings wheel to bring up the container menu and select the download the container option.
Then go into the container package (it is the file that has the xcappdata extension) in the Mac finder, right click on it and select the “Show Package Contents” option. This will open the container for browsing in the finder.
Copy the shaders folder from the AppData/Documents folder onto a PC in the [Lumberyard Root Directory]\User directory.
Building the Shader PAK files Once the shaders have been copied to the PC into the [Lumberyard Root Directory]\User directory you can edit the batch file that generates the shader pak files: BuildShaderPak_GL4.bat.
Edit the first xcopy line to point to the location of your remote shader compiler. If you are using the default one then the path should be changed to: Tools\CrySCompileServer\x64\profile\Cache\[Game Project Name]\ShaderList_[type].txt. The final line using the default location would be: xcopy /y Tools\CrySCompileServer\x64\profile\cache\[Game Project Name]\ShaderList_[type].txt USER\Shaders\shaderlist.txt* Where [Game Project Name] is the name of your project and [type] is based on the platform. For Android type will be gles3 and for iOS it will be metal. Modify the PakShaders.bat command line to use the shader type instead of GL4. For android the type is gles3 and for iOS it is metal.
After all the edits you can run the batch file from a command prompt. You could double click the .bat file from windows explorer but you will lose any type of output from the bat file that could be useful in diagnosing any runtime issues. When the .bat file is done there should be three shader pak files in the [Lumberyard Root Directory]:
ShaderCache.pak – Contains all compiled shaders; used only when the shader cannot be found in the current level’s shader cache. ShaderCacheStartup.pak – Contains subset of compiled shaders that are needed to speed up startup of the engine. ShadersBin.pak – Contains binary parsed information of the shader source code
Deploying the Shaders Copy the shaders*.pak file to the directory [Lumberyard Root Directory]\cache\[Game Project Name]\es3 for android or [Lumberyard Root Directory]\cache\[Game Project Name]\ios for iOS platforms. Once the shader pak files are in the correct cache location the game will use those shaders and not connect to the remote shader compiler unless it cannot find a shader. If this happens then the whole process to get the shaders from the device and create the pak files needs to be repeated.
