Lumberyard
Guía del usuario (Version 1.21)

Compilador de sombreador remoto

La aplicación del compilador de sombreador remoto de Lumberyard ofrece una forma cómoda de compilar sombreadores durante el desarrollo. Puede instalar el compilador de sombreador en un servidor de red local de PC o Mac que pueda comunicarse a través de TCP. El servidor recibe el archivo de origen del sombreador de un equipo en el que se ejecuta Lumberyard, lo compila y lo vuelve a enviar al sombreador. Casi todos los representadores requieren un compilador remoto de sombreadores. La excepción es un PC que ejecuta DX11, en el que el compilador remoto de sombreadores es opcional para el desarrollo local.

El compilador de sombreador remoto se utiliza para almacenar todas las combinaciones de sombreador solicitadas por el juego hasta el momento. Idealmente, durante el desarrollo, debe configurar un servidor de compilador remoto de sombreadores para todos los diseñadores, desarrolladores y evaluadores para conectarse mientras desarrollan el juego. Esto crea una lista de sombreadores completa (ShaderList.txt), que puede utilizar para generar los sombreadores y comprimirlos en archivos .pak que puede utilizar el juego.

Si lo prefiere, también puede configurar el compilador de sombreadores localmente en un PC en lugar de configurar un servidor central de compilación remota de sombreadores.

Lumberyard también genera su propia ShaderList.txt, que registra todas las combinaciones de sombreador solicitadas en esa instancia concreta de Lumberyard. Cuando prepare el lanzamiento del juego, el uso del archivo ShaderList.txt local de Lumberyard para la generación del sombreador es suficiente si el juego se está desarrollando únicamente en una instancia de Lumberyard. De lo contrario, si un equipo está desarrollando varios niveles o está utilizando un mapa de gran tamaño, podrían omitirse algunos sombreadores utilizando ShaderList.txt en el sistema de archivos de la aplicación Lumberyard.

En un PC, el compilador remoto de sombreadores puede generar sombreadores para Lumberyard que se ejecutan en los siguientes sistemas. Para obtener más información acerca de las opciones que se muestran con los sistemas, consulte Configuración de desarrollo de juegos.

  • PC (DX11) con r_ShadersRemoteCompiler=1

  • Consolas

  • Dispositivo móvil Android OpenGL ES 3.1 con r_ShadersUseLLVMDirectXCompiler=0

  • Dispositivo móvil Android OpenGL ES 3.0 con r_ShadersUseLLVMDirectXCompiler=0

  • Mac con r_ShadersUseLLVMDirectXCompiler=0

  • Mac con r_ShadersUseLLVMDirectXCompiler=1

  • Dispositivo móvil iOS con r_ShadersUseLLVMDirectXCompiler=0

  • Dispositivo móvil iOS con r_ShadersUseLLVMDirectXCompiler=1

En un Mac, el compilador remoto de sombreadores puede generar sombreadores para Lumberyard que se ejecutan en los siguientes sistemas:

  • Mac con r_ShadersUseLLVMDirectXCompiler=1

  • Dispositivo móvil iOS con r_ShadersUseLLVMDirectXCompiler=1

importante

Asegúrese de que el servidor o el equipo que está ejecutando el compilador remoto de sombreadores se encuentra en un entorno controlado que restringe las solicitudes de red entrantes tan solo a dispositivos o usuarios autorizados y de confianza. No ejecute el compilador remoto de sombreadores con privilegios de super usuario, administrador o de raíz escalados.

Ejecución del compilador remoto de sombreadores

Encontrará el compilador remoto de sombreadores en los siguientes directorios:

  • Equipo: lumberyard_version\dev\Tools\CrySCompileServer\x64\profile\

    • Para Visual Studio 2017, utilice CrySCompileServer_vc141x64.exe.

    • Para Visual Studio 2015, utilice CrySCompileServer_vc140x64.exe.

  • Mac lumberyard_version\dev\Tools\CrySCompileServer\osx\profile\CrySCompileServer

También hay un archivo de configuración disponible para configurar el puerto TCP de recepción de la aplicación.

Puede lanzar el compilador remoto de sombreadores iniciando CrySCompileServer_vc140_or_141x64.exe manualmente. Sin embargo, normalmente tiene sentido configurarlo como servicio, de tal forma que siempre se inicie con el sistema operativo.

Dado que las solicitudes de sombreador se ejecutan en paralelo, puede observar importantes retrasos en la adquisición de sombreadores en tiempo de ejecución.

Configuración del compilador remoto de sombreadores

Puede configurar el compilador remoto de sombreadores creando o editando el archivoconfig.ini, situado en los siguientes directorios:

  • PC: lumberyard_version\dev\Tools\CrySCompileServer\x64\profile

  • Mac: lumberyard_version\dev\Tools\CrySCompileServer\osx\profile

Para configurar el compilador remoto de sombreadores, edite los siguientes parámetros.

Nombre del parámetro Descripción
MailError Establezca esta opción en una dirección de correo electrónico interna de la empresa a la que se enviarán las notificaciones sobre errores de compilación.
TempDir

El directorio de la caché en el que se almacenan los sombreadores binarios una vez que se compilan. Este parámetro debe apuntar a una ruta absoluta válida.

La ruta predeterminada es C:\SHADER_CACHE.

port

Puerto TCP, que debe coincidir con la configuración en el archivo system_platform_shader_version.cfg del juego. Para ver ejemplos, consulte el archivo system_windows_pc.cfg, system_osx_metal.cfg o system_android_es3.cfg.

MailServer

Su servidor de correo electrónico.

SCMailAddress

La dirección de correo electrónico utilizada en el campo From del mensaje de correo electrónico enviado por el compilador remoto de sombreadores.

PrintCommands

Si se establece en 1 (habilitada), el compilador remoto de sombreadores imprime los comandos que utiliza para generar sombreadores.

PrintWarnings

Si se establece en 1 (habilitada), el compilador remoto de sombreadores imprime todas las advertencias de compilación cuando se generan los sombreadores.

white_list

Si se establece en 0.0.0.0/0, el compilador remoto de sombreadores autoriza cualquier IP. Cualquier dispositivo puede conectarse al compilador remoto de sombreadores. Dado que esto puede ser un riesgo para la seguridad, utilice este parámetro con precaución.

DumpShaders

Si se establece en 1 (habilitada), vuelca la salida de HLSL, GLSL y los sombreadores de metal. Envía los sombreadores al directorio Shaders/platform-compiler-shader_language, donde:

  • plataforma = PC, Mac, iOS o Android

  • compilador = D3D11_FXC, GLSL_HLSL, METAL_HLSLcc o METAL_LLVM_DXC

  • idioma_sombreador = D3D11, GL_4, GLES3_1, GLES3_0 o METAL

ejemplo

El archivo config.ini completado puede ser similar al siguiente.

MailError = shadererror@your_company.tld MailInterval = 1 port = 61453 TempDir = C:\SHADER_CACHE MailServer = your_email_server SCMailAddress = RemoteShaderCompiler@your_company.tld PrintWarnings = 1

Creación de una lista blanca para el compilador remoto de sombreadores

Puede utilizar una lista blanca para especificar las direcciones IP que tienen permitido conectarse a su compilador remoto de sombreadores. Si un equipo tiene una dirección IP que no está en la lista blanca, el compilador remoto de sombreadores emite un mensaje que indica que un equipo no válido ha intentado conectarse y, a continuación, cierra la conexión. Esto impide que los datos se lean o envíen a una conexión no válida.

Para crear una lista blanca para el compilador remoto de sombreadores

  1. Cree o edite el archivo config.ini en el mismo directorio que el ejecutable del compilador remoto de sombreadores.

  2. Agregue el siguiente parámetro al archivo.

    white_list: proporcione una lista separada por comas con las direcciones IP en formato CIDR. El compilador remoto de sombreadores utiliza esta lista para validar las solicitudes de conexión entrantes. El compilador remoto de sombreadores añade automáticamente la dirección IP (127.0.0.1) de bucle invertido y su propia dirección IP.

    nota

    Para especificar varias direcciones IP, especifique una lista delimitada por comas. No incluya espacios en blanco o líneas vacías.

ejemplo

En el siguiente ejemplo, se permite a equipos o dispositivos que tengan una dirección IP que esté en la lista blanca conectarse al compilador remoto de sombreadores.

white_list=10.53.180.37,10.53.104.220

En el siguiente ejemplo, se permite a equipos o dispositivos que tienen la dirección IP 192.168.0.* conectarse al compilador remoto de sombreadores. El /24 especifica una máscara neta de 24 bits. Si especifica /8, se permitirá cualquier dirección que comience por 192, solo con una máscara neta de 8 bits.

white_list=192.168.0.1/24

Ubicación de compiladores de sombreadores específicos

En el directorio raíz del compilador remoto de sombreadores, cada lenguaje de sombreador o API de representación tiene su propio directorio con subdirectorios adicionales para los diferentes números de versión. Se encuentran en el siguiente directorio:

lumberyard_version\Tools\CrySCompileServer\Compiler

Puede encontrar información sobre la ruta utilizada por el compilador remoto de sombreadores en el archivo ShaderCache.cpp, bajo la función mfGetShaderCompileFlags.

Lumberyard le proporciona todos compiladores de sombreadores apropiados que coinciden con el código de esa versión.

Listas de la caché de sombreador

El compilador remoto de sombreadores contiene diferentes archivos de texto de todas las combinaciones solicitadas hasta ahora por el juego. Estos archivos son importantes, ya que los archivos .pak de sombreador no se pueden generar sin ellos

Los archivos de la lista en caché del sombreador se encuentran en los siguientes directorios:

  • PC: lumberyard_version\dev\Tools\CrySCompileServer\x64\profile\Cache\project_name\platform-compiler-shader_language

  • Mac lumberyard_version\dev\Tools\CrySCompileServer\osx\profile\Cache\project_name\platform-compiler-shader_language

Donde:

  • plataforma = PC, Mac, iOS o Android

  • compilador = D3D11_FXC, GLSL_HLSL, METAL_HLSLcc o METAL_LLVM_DXC

  • idioma_sombreador = D3D11, GL_4, GLES3_1, GLES3_0 o METAL

El juego envía las solicitudes al compilador remoto de sombreadores durante el juego real o durante las fases de carga, incluso cuando la compilación del sombreador remoto está deshabilitada. Esto es así para garantizar que se recopilarán todas las combinaciones de sombreador posibles y que las cachés de sombreador, las cuales se generan durante la fase de generación de caché del sombreador, sean lo más completas posibles.

Lumberyard también genera sombreadores localmente. Estos archivos de texto se denominan ShaderList_platform.txt (por ejemplo, ShaderList_DX11.txt). Encontrará estos archivos en el directorio lumberyard_version\dev\cache\project_name\pc\user\cache\shaders.

Configuración de desarrollo de juegos

Un servidor de compilador remoto de sombreadores puede afectar positivamente al rendimiento, ya que almacena en la caché los resultados y los envía a los miembros del equipo, en lugar de tener que compilar sombreadores cada vez. Además, el servidor hace un seguimiento de todos los sombreadores utilizados por todas las personas, lo que puede ser útil si se desea compilar una versión de lanzamiento que incluya todos los sombreadores.

Puede establecer los siguientes parámetros en el archivo system_platform_shader_version.cfg del directorio raíz de Lumberyard, como system_android_es3.cfg o system_windows_pc.cfg.

Variables de la consola Descripción
r_ShadersUseLLVMDirectXCompiler=1

Active el compilador de sombreador que genera sombreadores de metal en Windows y Mac.

r_ShadersRemoteCompiler=1

Especifica si el juego habilita o deshabilita el compilador remoto de sombreadores.

Si se establece en 0, Lumberyard no compila sombreadores remotos y, en su lugar, compila sombreadores locales.

r_ShaderCompilerServer=IPv4_of_PC_running_the_RemoteShaderCompiler

Especifica la ubicación del compilador remoto de sombreadores. Cuando el compilador remoto de sombreadores está habilitado, el juego necesita conocer la ubicación del compilador remoto de sombreadores.

r_ShaderCompilerServer=localhost Si utiliza un PC, especifique esta variable de consola para utilizar el compilador remoto de sombreadores localmente.
r_ShaderCompilerServer=10.0.0.10;10.0.0.11

Especifica más de un compilador remoto de sombreadores. Separe las direcciones IP con puntos y comas.

nota

No es posible utilizar el nombre de la red del servidor en lugar de la dirección IP, porque no se realiza la resolución de nombres.

r_ShaderCompilerPort=portnumber

Si el servidor del compilador remoto de sombreadores utiliza un número de puerto definido por el usuario, tal y como se especifica en el archivo config.ini, puede configurar el número de puerto con esta variable de consola.

r_shaderssubmitrequestline=0

Deshabilita las líneas de solicitud de envío al compilador remoto de sombreadores. Esta variable de consola resulta útil cuando está experimentando con sombreadores y no desea que estas combinaciones se añadan a la caché del sombreador.

r_AssetProcessorShaderCompiler=1 Puede utilizar Asset Processor para pasar las solicitudes remotas por un proxy al servidor del compilador de sombreadores si un dispositivo no puede conectarse al servidor del compilador de sombreadores. En este caso, establezca r_AssetProcessorShaderCompiler=1. Ahora, en aquellas situaciones en las que el juego habría enviado una solicitud directamente al servidor del compilador de sombreadores, en su lugar envía la solicitud a Asset Processor (esto también puede hacerse a través de una conexión USB), que a continuación la reenvía al servidor del compilador de sombreadores.
r_shadersAsyncCompiling=3

Permite que los sombreadores transmitan de forma asíncrona e impide que el juego se bloquee mientras espera a que los sombreadores se compilen.

r_ShadersAsyncActivation=1

Permite que los sombreadores transmitan de forma asíncrona. Establezca este parámetro en 0 para evitar que los sombreadores transmitan de forma asíncrona.

Creación de archivos PAK para recursos de servidor

Especifique RC.exe para crear un archivo pak que contenga únicamente recursos de servidor. Puede generar estos recursos con el siguiente comando:

AssetProcessorBatch.exe /gamefolder=my_game /platforms=server /server)

Puede actualizar RC.exe para buscar recursos en el directorio lumberyard_version\dev\cache\MyGame\server, en lugar de utilizar los recursos del cliente del equipo.

ejemplo


                    Especificar el directorio del servidor en lugar del directorio del equipo.

Para crear archivos PAK para los recursos de servidor

  1. Vaya al directorio lumberyard_version\dev\Bin64vc140_or_141\rc.

  2. Abra el archivo RCJob_Generic_MakePaks.xml en un editor de texto.

  3. Realice una copia del archivo y asígnele el nombre RCJob_Generic_MakePaks_Server.xml.

  4. Edite el archivo para que el src apunte a los recursos de servidor, en lugar de a los recursos del cliente del equipo.

    BeforeAfter
    Before
    # <DefaultProperties p="pc" game="samplesproject" src="cache\${game}\${p}" trg="${game}_${p}_paks" />
    After
    # <DefaultProperties p="pc" game="samplesproject" src="cache\${game}\server" trg="${game}_server_paks" />
  5. Guarde el archivo.

  6. Ahora, cuando ejecute RC.exe, podrá asignar el trabajo al nuevo archivo xml.

    ejemplo

    rc.exe /job=path\to\RCJob_Generic_MakePaks_Server.xml /p=pc /game=my_game /trg=BinTemp\server_paks