unity-technologies/gestionar-sprite-atlas

Unity SpriteAtlas V2

Proporciona conocimiento procedural seguro para el editor para scripting de atlas en proyectos Unity. V2 impone una separación estricta entre la creación en el editor y el acceso en tiempo de ejecución.

⚠️ Principio crítico V2: SpriteAtlas es solo para tiempo de ejecución. SpriteAtlasAsset es solo para el editor. Nunca mezcles contextos. Siempre usa V2.

🚨 CRÍTICO: Verificaciones y entradas de usuario requeridas antes de la implementación

SIEMPRE realiza estas verificaciones y haz estas preguntas ANTES de generar cualquier código:

Lee los recursos incluidos antes de escribir código (REQUERIDO)

Esta habilidad incluye C# funcional en resources/, y el código de atlas que sale mal es casi siempre código escrito sin leerlo primero. Abre los archivos para la ruta que estás tomando, luego escribe.

Tomando esta ruta	Lee primero
Cualquier trabajo con atlas	resources/authoringvsruntime.cs, references/common-errors.md
Generación de precompilación (la predeterminada)	resources/spriteatlasprebuildgenerator.cs, resources/enablespritepacking.cs, resources/savespriteatlasasset.cs
Opción B, enlace tardío de Addressables	resources/buildaddressablespostprocess.cs, resources/spriteatlaslatebinding.cs, resources/handlelatebinding.cs
Cualquier cosa que pueda usar una API anterior	resources/deprecatedmethods.cs, resources/dontscriptspriteatlasineditor.cs, resources/dontpackinruntimebuilds.cs

resources/ contiene 38 archivos en total, que cubren empaquetadores personalizados, variantes, configuraciones de plataforma y acceso en tiempo de ejecución. Navega por el directorio cuando tu tarea no esté en la tabla anterior en lugar de inventar un enfoque. Usar la API de memoria en lugar de leer estos archivos es la causa más común de un atlas que importa limpiamente y luego no hace nada en tiempo de ejecución.

0. Verificar scripts existentes (PRIMER PASO REQUERIDO)

ANTES de generar cualquier código, escanea el proyecto en busca de scripts de SpriteAtlas generados por esta habilidad.

Busca archivos que contengan el identificador: // [UNITY-SKILL:SPRITEATLAS]

Si se encuentran scripts existentes, SIEMPRE pregunta al usuario con este formato:

"Encontré scripts de SpriteAtlas existentes en tu proyecto:

Generador de precompilación:

• Assets/Editor/SpriteAtlas/SpriteAtlasPrebuildGenerator.cs

Constructor de Addressables:

• Assets/Editor/SpriteAtlas/BuildAddressablesPostprocess.cs

Cargador en tiempo de ejecución:

• Assets/Scripts/SpriteAtlas/SpriteAtlasLateBinding.cs

¿Qué te gustaría hacer?"

Luego presenta las opciones:

• Opción A: Actualizar scripts existentes (Recomendado si los requisitos cambiaron)

  • Regenera scripts en las rutas existentes
  • Preserva las ubicaciones de los archivos
  • Actualiza a la versión más reciente
  • ⚠️ Puede sobrescribir modificaciones personalizadas

• Opción B: Crear nuevos scripts con nombres diferentes

  • Genera junto a los scripts existentes
  • Permite múltiples configuraciones de atlas
  • Los scripts originales permanecen sin cambios
  • Necesitarás especificar nuevos nombres/rutas

• Opción C: Abortar (mantener existentes sin cambios)

  • Sin generación de código
  • Sin cambios en el proyecto
  • Úsalo si quieres mantener la configuración actual

Manejo de la elección del usuario:

• Si se elige A: Regenerar en rutas existentes, incrementar versión a 2.0.1+
• Si se elige B: Preguntar por nuevos nombres de script (ej., "SpriteAtlasPrebuild_Custom.cs"), luego generar
• Si se elige C: Detenerse de inmediato, informar al usuario que no se realizaron cambios

1. Mecanismo de entrega (REQUERIDO)

Pregunta: "¿Cómo deseas entregar los atlas de sprites?"

Opción A: Datos incorporados (carga inmediata)

• Los atlas se incluyen en la compilación y se cargan inmediatamente
• Establecer includeInBuild = true
• Adecuado para: UI principal, sprites de juego principales, activos siempre necesarios
• Pros: Simple, sin paquetes adicionales, acceso instantáneo
• Contras: Aumenta el tamaño inicial de la compilación, no se puede actualizar sin una nueva compilación

Opción B: Enlace tardío vía Addressables (carga bajo demanda)

• Los atlas NO están incluidos en la compilación, se cargan bajo demanda mediante Addressables
• Establecer includeInBuild = false
• Crear entradas de Addressables para cada atlas
• Agregar configuración de Addressables como paso de precompilación
• 🚨 REQUERIDO: Construir contenido de Addressables como paso de compilación
• 🚨 REQUERIDO: Crear script de cargador de enlace tardío en tiempo de ejecución
• Adecuado para: Contenido DLC, características opcionales, activos grandes, contenido descargable
• Pros: Compilación inicial más pequeña, se puede actualizar de forma independiente, carga bajo demanda
• Contras: Requiere paquete Addressables, carga asíncrona, dependencia de red

Caso de uso	Recomendado
Sprites de UI principales que siempre están visibles	Opción A: Incorporados
Sprites de tutorial o incorporación	Opción A: Incorporados
Sprites específicos de nivel (100+ niveles)	Opción B: Addressables
Contenido DLC o de temporada	Opción B: Addressables
Sprites de UI localizados (múltiples idiomas)	Opción B: Addressables
Skins de personajes o cosméticos	Opción B: Addressables

2. Modo SpritePacker (REQUERIDO)

Habilita el modo Sprite Packer antes de crear atlas, luego lee el valor de vuelta y confirma que tuvo efecto. Usa el código en resources/enablespritepacking.cs; establece EditorSettings.spritePackerMode y configura los ajustes de empaquetado del importador.

Este es el paso que decide si el atlas que produces es real. Disabled es el valor cero de SpritePackerMode, por lo que cualquier proyecto donde nadie lo ha establecido lleva el empaquetado deshabilitado, y un atlas creado mientras está Deshabilitado aún importa, aún aparece como un activo y aún parece terminado, pero nunca puede empaquetar. Unity lo dice en el Inspector: "El empaquetado de atlas de sprites está deshabilitado". Nada más en el flujo de trabajo falla, por lo que un atlas enviado de esta manera se lee como un éxito. No asumas que un proyecto está ya configurado: lee el valor.

Por lo tanto, no trates "lo configuré" como hecho. Después de configurarlo, lee EditorSettings.spritePackerMode de vuelta, confirma que no sea Disabled, e informa el valor que realmente leíste. Si no puedes leerlo de vuelta, dilo en lugar de asumir que la escritura se realizó.

NO edites archivos meta DIRECTAMENTE.

🚨 CRÍTICO: El enfoque predeterminado es la generación de precompilación

SIEMPRE usa IPreprocessBuildWithReport para generar o actualizar automáticamente los SpriteAtlases durante la canalización de compilación. Este es el enfoque PREDETERMINADO y REQUERIDO a menos que el usuario solicite EXPLÍCITAMENTE la creación manual.

❌ NO crees scripts de elementos de menú manuales

NUNCA crees scripts con atributos [MenuItem] para la generación de atlas a menos que se solicite explícitamente. El enfoque de precompilación elimina la necesidad de clics manuales. Solo usa la creación manual para: Diseños optimizados a mano, disposiciones de sprites específicas o requisitos de vista previa en el editor. Consulta Avanzado: Creación manual.

🚨 CRÍTICO: Restricción de ubicación de origen de sprites

Solo agrega sprites de la carpeta Assets del proyecto. NUNCA agregues sprites de activos incorporados de Unity, paquetes o ubicaciones externas. Los activos incorporados de Unity no se pueden empaquetar en SpriteAtlas, y los activos de paquetes pueden causar problemas de importación/dependencia.

Arquitectura crítica V2

Contexto	Componente	Propósito	Uso permitido
Editor	SpriteAtlasAsset	Creación y edición de atlas	Solo en scripts del editor (Editor folder)
Tiempo de ejecución	SpriteAtlas	Carga y uso de atlas empaquetados	Solo en scripts de tiempo de ejecución
Compilación	IPreprocessBuildWithReport	Generación automática de atlas	Solo en scripts del editor (Editor folder)