Lumberyard
Guía del usuario (Version 1.21)

Configuración de la canalización de activos

importante

El SDK de Asset Builder es ahora la opción preferida ante el programa heredado rc.exe para agregar tipos de activos a la canalización. En lugar de utilizar el programa rc.exe cree un módulo de compilación derivado del BuilderSDK. Estos módulos se configuran de manera autónoma. Para obtener instrucciones y ejemplos acerca de cómo escribir compiladores que procesen sus propios tipos de activos, consulte Creación de un generador de activos personalizados. Le recomendamos que no dependa de la antigua canalización de rc.exe, aunque sigue estando disponible si tiene código heredado.

Puede configurar la canalización de recursos de Lumberyard editando el archivo \dev\AssetProcessorPlatformConfig.ini que utiliza el programa rc.exe. Puede agregar sus propios tipos de activos modificando las secciones del archivo descritas en este documento. Cuando guarda sus cambios en el archivo de configuración, la versión de los activos se actualiza automáticamente en los equipos de sus colaboradores. Esto hace que no sea necesario actualizar manualmente la caché en el equipo de cada trabajador.

El archivo AssetProcessorPlatformConfig.ini consta de seis secciones. El archivo .ini emplea las normas de formato estándares de los archivos Qt/Windows .ini. Los comentarios van precedidos por un punto y coma, y las secciones con nombre están designadas por corchetes.

importante

Las barras diagonales invertidas en los archivos .ini tienen un significado especial. Para utilizar un carácter de barra diagonal invertida, debe utilizar otra barra igual como prefijo. Para evitar problemas con las rutas de archivo, el procesador de activos y la canalización de activos emplean barras inclinadas para los nombres de ruta. Sin embargo, si necesita utilizar barras diagonales invertidas en expresiones regulares, debe también aplicarles escape para que el sistema regex pueda reconocerlas. Por ejemplo, debe especificar la expresión habitual .*\/Levels\/.* de la siguiente manera:

.*\\/Levels\\/.*

Además del archivo AssetProcessorPlatformConfig.ini (ubicado en el directorio /lumberyard_version/dev), también puede añadir lo siguiente:

  • AssetProcessorGamePlatformConfig.ini: añada este archivo a la carpeta del proyecto del juego para invalidar la configuración específica de un proyecto. La configuración final será el resultado de la combinación de ambos archivos. El archivo AssetProcessorGamePlatformConfig.ini es el último en leerse y, por tanto, tiene prioridad.

  • AssetProcessorGemConfig.ini: añada este archivo a la carpeta de gemas para permitir que la gema habilitada se aplique a la configuración del procesador de recursos. El efecto es similar a editar el archivo raíz pero sin realizar cambios permanentes en dicho archivo. Por ejemplo, puede añadir un archivo AssetProcessorGemConfig.ini para la gema en la nube al directorio /lumberyard_version/dev/Gems/Clouds.

    La configuración final será el resultado de la combinación de los siguientes archivos en orden:

    • dev/AssetProcessorPlatformConfig.ini

    • dev/Gems/GEM_NAME1/AssetProcessorGemConfig.ini

    • dev/Gems/GEM_NAME2/AssetProcessorGemConfig.ini

    • dev/Gems/GEM_NAME3/AssetProcessorGemConfig.ini

    • your_project_folder/AssetProcessorGamePlatformConfig.ini

Sección Platforms

La sección Platforms contiene dos secciones secundarias:

  • Platform Definition: define qué plataformas existen al utilizar el encabezado de sección [Platform platformName].

  • Platforms: define qué plataformas se habilitan de forma predeterminada en su proyecto.

Subsección de definición de plataforma

Utilice las siguientes subsecciones para definir un sistema operativo y sus atributos. El nombre del sistema operativo aparece en el encabezado de la sección, por ejemplo, pc o ios.

[Platform pc] tags=tools,renderer
[Platform ios] tags=mobile,renderer

Puede definir el atributo tags y asignar etiquetas a un sistema operativo. Esto le permite controlar el comportamiento basado en las etiquetas. Por ejemplo, puede optar por compilar texturas en todos los sistemas operativos con la etiqueta móviles en lugar de nombrar sistemas operativos individualmente. En caso de que añada sistemas operativos móviles a la configuración, puede utilizar la etiqueta móvil para incluirlos cuando se modifique el comportamiento. Esto elimina la necesidad de volver a compilar y modificar todas las normas y los constructores para incluir los nuevos sistemas operativos.

Subsección de plataformas

Utilice la subsección Platforms para habilitar y deshabilitar sistemas operativos para todo el proyecto. Tenga en cuenta que "deshabilitar" implica que el proyecto de juego no utiliza el sistema operativo especificado. Al deshabilitar un sistema operativo, los activos relacionados se eliminan y se libera el espacio asociado en su disco duro.

En el siguiente ejemplo, está habilitado PC y otros sistemas operativos aparecen comentados.

[Platforms] pc=enabled ;es3=enabled ;ios=enabled ;osx_gl=enabled

Dado que el valor predeterminado de un sistema operativo es disabled, los sistemas operativos que están comentados en el ejemplo no están habilitados.

Si desea habilitar un sistema operativo que ya está incluido en la subsección [Platforms], solo tiene que eliminar el punto y coma para quitar el comentario de la línea correspondiente.

Si la lista no contiene ninguna entrada para el sistema operativo de juego con el que quiera contar, puede agregarla. Sin embargo, también debe administrar las diferencias entre sistemas operativos, como los formatos de imagen. Para ello, deberá cambiar el código en el procesador de activos (y posiblemente el compilador de imágenes y otros compiladores).

Si está utilizando la canalización rc.exe, los sistemas operativos especificados se pasarán como parámetros al programa rc.exe.

El sistema operativo que ejecuta Lumberyard está habilitado de forma predeterminada, por lo que puede dejar esa línea comentada. Por ejemplo, si Lumberyard se ejecuta en Mac, puede dejar la línea osx_gl=enabled comentada.

Si ejecuta AssetProcessor.exe o AssetProcessorBatch.exe en un servidor de compilación, puede utilizar el siguiente parámetro de línea de comandos para especificar qué sistemas operativos habilitar: /platforms=comma-separated-list

Con este parámetro de línea de comandos solo se habilitan los sistemas operativos especificados, independientemente de la plataforma de host que ejecuta las herramientas.

Puede especificar etiquetas para el parámetro de línea de comandos platforms, por ejemplo: AssetProcessorBatch.exe /platforms=tools,es3

Sección Jobs

Puede usar la sección Jobs para controlar cuántas tareas se ejecutan en paralelo, como en el siguiente ejemplo.

; ---- The number of worker jobs, 0 means use the number of logical cores [Jobs] minJobs=1 maxJobs=0

Si establece maxJobs en cero, estará especificando que se han de usar tantos núcleos como tenga disponibles. Si usa un número diferente a cero, los núcleos empleados se limitarán a la cifra que especifique.

Sección MetaDataTypes

Puede usar la sección MetaDataTypes para decirle al sistema de activos que determinados tipos de archivos se asocian con otros archivos en la misma carpeta. Estas especificaciones controlan la compilación paralela de activos, como en el siguiente ejemplo.

[MetaDataTypes] exportsettings= animsettings=i_caf Animations/SkeletonList.xml=i_caf cbc=abc fbx.assetinfo=fbx

Las entradas del lado izquierdo y derecho del signo igual especifican las extensiones de los archivos de activos que estén en la misma carpeta. Si un archivo que tenga la extensión de la izquierda cambia, el archivo con la extensión de la derecha también debe recompilarse, si tiene el mismo nombre de archivo. Por ejemplo, la línea animsettings=i_caf implica que, si un archivo denominado example.animsettings cambia, example.i_caf se recompilará.

La línea exportsettings= implica que, cuando un archivo que tenga la extensión .exportsettings cambia, cualquier archivo de activo que tenga el mismo nombre que el archivo con la extensión .exportsettings será invalidado. Por ejemplo, un cambio en el archivo MyImage.TIF.exportsettings invalida el archivo MyImage.TIF.

En el ejemplo Animations/SkeletonList.xml=i_caf, el lado izquierdo no especifica una extensión, sino un archivo específico. Cuando el archivo Animations/SkeletonList.xml cambia (tenga en cuenta que la barra inclinada indica una ruta de un directorio), todos los archivos con la extensión .i_caf quedan invalidados.

nota

Si utiliza el SDK de Asset Builder, podrá declarar explícitamente sus dependencias en otros archivos. Esto hace que la sección [MetaDataTypes] sea menos importante.

Sección ScanFolder

Utilice la sección ScanFolder para indicar a Asset Processor que monitorice los recursos en carpetas específicas. En el siguiente ejemplo, se indica a Asset Processor que monitorice la carpeta Editor.

[ScanFolder Editor] watch=@ROOT@/Editor output=editor recursive=1 order=30000

Puede agregar tantas carpetas de análisis como quiera, pero cada una de ellas debe tener un nombre único. Dado que las carpetas de análisis se almacenan en una tabla hash con el nombre especificado entre corchetes, asegúrese de que el nombre que sigue a ScanFolder sea único.

Puede usar los alias @root@ y @gamename@ como marcadores de posición para activar la portabilidad de los equipos de otros usuarios que trabajen en el mismo proyecto.

Para hacer que la carpeta de análisis sea específica del sistema operativo, utilice las palabras clave include y exclude. Ambas palabras clave pueden contener etiquetas de plataforma y/o identificadores de la plataforma. Si no especifica una palabra clave, todos los sistemas operativos habilitados se incluyen de forma predeterminada.

La sección ScanFolder tiene los siguientes parámetros.

Entrada Descripción
watch=<foldername> Observa los activos específicos en esta carpeta.
output=<foldername> Coloca los contenidos de esta carpeta de supervisión en la subcarpeta de la carpeta @assets@ denominada <foldername>.
recursive=1 Se repite en subcarpetas.
order=30000

Declara un orden de prioridad. Cuanto menor sea el número, más "importante" es una carpeta. La carpeta de juego de su proyecto siempre se considera la 0, la más importante.

nota

El parámetro order solo afecta a los activos con el mismo nombre. Por ejemplo, suponga que tiene un activo llamado MyTexture.TIF en dos carpetas de análisis diferentes. Si ambos archivos de activos se asignan al mismo archivo de salida, el archivo de activos con el número ordinal menor sobrescribe al que tenga el número mayor.

include=<comma-separated platform tags or identifiers> Contiene la lista de plataformas o etiquetas de plataformas que se incluyen para la carpeta de análisis. Solo se incluyen las plataformas habilitadas. Si se incluye una plataforma deshabilitada, no se tendrá en cuenta para la carpeta de análisis.
exclude==<comma separated platform tags or identifiers> Contiene la lista de plataformas o etiquetas de plataformas que se excluyen para la carpeta de análisis.

Notas

  • En la mayoría de los casos, no tiene que especificar una carpeta de salida. La carpeta de salida reasigna las carpetas de origen en subcarpetas de la caché. Normalmente, las carpetas que contienen activos van a la caché directamente, sin necesidad de una subcarpeta.

  • Si falta una carpeta de análisis, no se considera un error. Este comportamiento es así por diseño, ya que le permite disponer de carpetas opcionales para activos. Por ejemplo, esto podría ser útil para casos de prueba.

  • Si elimina carpetas de las secciones ScanFolder, eliminará los activos correspondientes de la caché. Si los activos especificados sobrescribían otros activos, los activos sobrescritos se recuperarán y volverán a ser activos principales.

Sección Exclude

Puede utilizar la sección Exclude para agregar patrones de ruta de archivos que quiera pasar por alto. Como en el resto del archivo .ini, las barras diagonales invertidas deben llevar como prefijo una barra diagonal invertida adicional para aplicarles el escape del procesamiento del archivo .ini.

El siguiente ejemplo se excluyen las plantillas de compresión alembic y los archivos de compresión de animación temporales.

[Exclude AlembicCompressionTemplates] pattern=.*Presets\\/GeomCache\\/.* [Exclude TmpAnimationCompression] pattern=.*Editor\\/Tmp\\/AnimationCompression\\/.*

Notas

  • Las expresiones regulares son STD::regex estándares en formato ampliado. Se aplican las normas STD::regex estándares.

  • Las rutas de entrada son siempre rutas absolutas. Si no desea filtrar por rutas absolutas, inicie sus expresiones regulares con .*, como en el ejemplo.

  • Si desea agregar nuevas reglas de exclusión, póngales un nombre único. El nombre en sí no importa, siempre que todos ellos sean únicos.

Sección RC

Utilice la sección RC para especificar los archivos que ha de procesar el programa rc.exe o que deben copiarse tal y como están en la caché de activos sin procesar. La sección RC solo se debe usar por parte de los módulos RC heredados y para especificar copias de archivo simples para almacenar en caché.

La sección RC consiste en una serie de descriptores de reconocedores. Cada descriptor especifica un conjunto de archivos (por glob o patrones) y qué es lo que se debe hacer con los archivos especificados. Si cambia los campos del reconocedor, se invalidarán activos en función del cambio realizado.

importante

Dado que no usan el programa heredado rc.exe los compiladores implementados como módulos de compilación no usan la sección RC. En lugar de ello, derivan su configuración mediante programación o la leen desde un archivo de configuración personalizado. Si crea su propio compilador BuilderSDK, no agregue nada a la sección RC.

El siguiente bloque de código muestra la sintaxis de la sección RC.

[RC (recognizer name)] ; ---- Choose either pattern or glob. You cannot choose both. pattern=(pattern to use to recognize these files) glob=(glob to use to recognize these files) params=(command line params/copy/skip) (platformname)=(params) lockSource=(true/false) priority=(0...n) ; Higher numbers are more important. critical=(true, false) version=(0...n)

En la tabla siguiente se describe cada parámetro y sus opciones.

Parameter Descripción
pattern Una expresión regular que especifica los archivos que se han de procesar. Al utilizar expresiones regulares, recuerde aplicar escape a las barras diagonales invertidas.
glob Una expresión comodín como *.tif que especifica los archivos binarios glob para procesar.
params

El parámetro params puede asumir una de las siguientes tres opciones.

  1. Los parámetros predeterminados que se han de pasar al programa rc.exe para procesar el tipo de activo especificado.

  2. copy: copia el archivo en la caché tal y como está. No invoca a rc.exe.

    nota

    Los trabajos de copia son el tipo de trabajo más habitual. Por ejemplo, en el archivo dev\assetprocessorplatformconfig.ini que se incluye con Lumberyard, la mayoría de las secciones [RC] especifican params=copy.

  3. skip : omite por completo el tipo de archivo especificado. La opción skip suele ser más útil en el parámetro platformname.

Si omite las secciones de parámetros, parámetros de plataforma y parámetros de etiquetas, el programa rc.exe procesa el archivo con las opciones predeterminadas. Para procesar el archivo en los sistemas operativos específicos, defina el parámetro params en skip y, a continuación, especifique las plataformas deseadas.

Si pasa parámetros al programa rc.exe, puede pasar p (como en /p=pc) para obligar al programa a procesar el activo como si fuera el PC. Puede pasar el parámetro adecuado para la plataforma deseada.

(platformname)=(params) Especifica parámetros específicos del sistema operativo. Puede utilizar el parámetro params para especificar parámetros predeterminados, y a continuación, anularlos para sistemas operativos concretos cuando sea necesario mediante platformname=params. Por ejemplo, la declaración pc=/TEST anula los parámetros predeterminados para PC y pasa el parámetro /TEST al programa rc.exe.

Puede ser true o false. Cuando es true, hace que el trabajo espere hasta que pueda obtener un bloqueo de lectoescritura exclusivo sobre el archivo de origen.

(tagname)=(params)

Especifica parámetros específicos de etiqueta, que son generalmente mejores que los parámetros específicos de plataforma. Por ejemplo, la siguiente declaración hace que todas las plataformas utilicen los parámetros predeterminados al procesar archivos .tiff. Sin embargo, una plataforma con la etiqueta server se omite.

[RC tif] pattern=.*\\.tiff? server=skip
lockSource

La siguiente declaración pasa /p=pc a las invocaciones del programa rc.exe: server=/p=pc. Esto permite que el programa procese activos (como texturas) como si fuera el PC, incluso en el servidor.

El comportamiento predeterminado es pasar /p = server, que el programa rc.exe puede que no entienda.

El parámetro lockSource resulta útil para trabajar con aplicaciones que se ciñen a un archivo a introducen lentamente datos en el mismo. Por ejemplo, si un programa crea archivos muy grandes durante un periodo prolongado, puede establecer lockSource=true para evitar el procesamiento de un activo hasta que otra aplicación lo libere.

El uso de este parámetro es relativamente poco común y suele resultar caro, por lo que es mejor que lo evite a no ser que sea absolutamente necesario.

priority

Especifica la prioridad del trabajo. Un número más alto hace que un trabajo tenga más prioridad en la cola. Normalmente, debe asignar un número más alto a activos que, probablemente, serán necesarios desde el inicio o que afecten a la experiencia de juego. Así, se garantiza que se compilen antes.

nota

Los trabajos params copy tienen una prioridad predeterminada de 1.

critical

Puede ser true o false. Los trabajos críticos hacen que la pantalla de presentación del editor se siga mostrando y pause el startup del tiempo de ejecución hasta que se hayan completado todas las tareas críticas. Si se marca un trabajo como crítico, esto garantizará que se complete antes de que se permita iniciar el editor.

Puede especificar como críticos tipos de activos. Esto puede resultar útil en el caso de archivos que se emplean durante el startup, que no se comportan adecuadamente durante el arranque o que no pueden volver a cargarse en vivo.

importante

Dado que los trabajos críticos pueden retrasar el startup del editor por primera vez, no tener trabajos críticos siempre es la opción preferida. Entre los enfoques alternativos se incluyen:

  • Hacer que el editor o el tiempo de ejecución sea capaz de volver a cargar el activo en vivo tras su compilación.

  • Realizar una llamada para compilar el activo bajo demanda con el bus de sistema de activos. Para ello, puede usar la función pública CompileAssetSync. Consulte el código fuente de Lumberyard para ver ejemplos.

nota

Los trabajos params copy son críticos de forma predeterminada.

version

Número de control de versiones arbitrario. El valor predeterminado es 0. Si cambia el número de versión invalidará los activos especificados y hará que se vuelvan a compilar.

El parámetro version proporciona una forma cómoda de recompilar todos los activos de un tipo concreto. Por ejemplo, puede realizar cambios en el compilador que crea un determinado tipo de activo. A continuación, al registrar sus cambios en el archivo .ini, los activos locales de trabajadores que reciben la actualización se recompilan automáticamente.

El siguiente ejemplo especifica cómo se deben procesar los archivos .tiff.

[RC tif] pattern=.*\\.tiff? params=/imagecompressor=CTSquish /streaming=1 es3=/imagecompressor=CTSquish /streaming=0 ios=/imagecompressor=CTSquish /streaming=0 ; Streaming = 1 splits files. lockSource=true

El ejemplo incluye las siguientes características:

  • Declara un recognizer llamado tif (porque [RC tif] es el nombre).

  • El valor pattern especifica todos los archivos que coincidan con la expresión regex .*\.tiff?. Tenga en cuenta que el ejemplo aplica un escape a la barra inclinada inversa.

  • El parámetro params especifica los parámetros predeterminados con los que invocar a rc.exe. En el ejemplo, los archivos .tiff se compilarán en el formato /imagecompressor=CTSquish /streaming=1.

  • Para ES3 e iOS, el streaming está desactivado, por lo que se sobrescribe el valor predeterminado especificado en el parámetro params.

  • lockSource está establecido como true para evitar el conflicto con herramientas externas que creen un archivo de cero bytes, se pausan durante varios segundos y luego lo llenan de datos.

El siguiente ejemplo se especifica cómo se deben procesar los archivos .tiffen la subcarpeta GoldenImages.

; Feature tests use the raw .tif files for the golden image comparison. [RC goldenimages] pattern=.*GoldenImages\\/.*\\.tif params=copy

El ejemplo incluye las siguientes características:

  • Declara un recognizer denominado goldenimages, que se aplica a cualquier archivo .tiff en la subcarpeta GoldenImages.

  • El parámetro params especifica copy, de modo que cualquier archivo .tiff de la subcarpeta GoldenImages se copia en la caché sin procesamiento.

Notas

Las dos secciones de RC de ejemplo se encuentran en el mismo archivo. Esto tiene las siguientes consecuencias importantes:

  • Las diversas reglas que coinciden con los archivos se aplican simultáneamente. No son exclusivas. Si tiene dos reglas que se aplican al mismo archivo, ambas se ejecutan. Por ejemplo, las reglas en los dos ejemplos se aplicarían a un archivo denominado \dev\SamplesProject\textures\GoldenImages\myfile.tif. Ambas reglas producirían una versión comprimida .dds de myfile.tif y un archivo myfile.tif sin comprimir que se copia en la caché.

  • Si quiere especificar una regla de subcarpeta exclusiva, debe usar selectores regex inversos para crear patrones de exclusión.

    El siguiente ejemplo muestra un conjunto de reglas que se aplican exclusivamente a archivos .png. Las dos reglas están escritas de forma que cualquier archivo .png coincida solo con una de las reglas.

    ;Example: Use the specified parameters to process all .png files except those in the libs/ui folder. [RC png-normal] pattern=(?!.*libs\\/ui\\/).*\\.png params=/imagecompressor=CTSquish /streaming=0 lockSource=true
    ;Example: Process all .png files in the libs/ui folder using linear color space. [RC png-ui] pattern=(.*libs\\/ui\\/).*\\.png params=/imagecompressor=CTSquish /streaming=0 /colorspace=linear,linear lockSource=true

    Para ver más ejemplos, consulte el archivo \dev\AssetProcessorPlatformConfig.ini predeterminado.

Problemas comunes

Al solucionar problemas, tenga en cuenta los siguientes inconvenientes:

  • No aplicar escape a sus expresiones regulares con dos barras diagonales invertidas. Recuerde que una de las barras se elimina cuando se procesa el archivo .ini.

  • Duplicar una regla sin cambiar su nombre. La regla [RC png] tiene el nombre png. Estos nombres se insertan en un hash sin orden. Si especifica otra sección con el nombre png, la segunda sección sobrescribe a la otra en un orden aleatorio. Este comportamiento es así por diseño. Por ejemplo, puede utilizarlo para permitir que su versión del juego del archivo .ini anule determinadas secciones o especificar skip para omitirlas. De lo contrario, si desea agregar nuevas reglas, póngales un nombre único. El nombre en sí no importa, siempre que todos ellos sean únicos. Esto es especialmente cierto para secciones con nombre, como las secciones Exclude y ScanFolder.

  • No comprender que todos los reconocedores (all) que coinciden se aplican, y no solo el primero.

  • Olvidar aplicar a las expresiones regulares el prefijo .*. De forma predeterminada, los archivos de entrada que especifique se considerarán rutas absolutas. Este comportamiento es así por diseño, ya que le permite excluir o incluir archivos en función de rutas absolutas, si ese es su objetivo. Puede usar el prefijo .* si desea utilizar rutas relativas.