Guía de Formatos de Exportación de Sprite Sheet
El sprite sheet en sí es un PNG. El archivo de metadata le dice al loader, importer o script personalizado dónde está cada frame y cómo se llama. Si eliges el formato equivocado, aparecen desajustes de coordenadas, errores de nombres o trabajo extra de parser. Esta guía muestra qué formato encaja con Phaser, PixiJS, Unity, Godot y animación web.
Por Qué Importa el Formato
La mayoría de exportaciones incluyen un PNG y un archivo de metadata. Los motores no leen todos la misma estructura. Phaser y PixiJS suelen consumir JSON estilo TexturePacker, los proyectos CSS usan background-position, y Unity o Godot a menudo requieren slicing nativo, un addon o un paso de importación personalizado.
El archivo de imagen es universal
El PNG del sprite sheet es el mismo independientemente del formato de exportación. Obtienes una imagen de alta calidad con todos los frames organizados en tu diseño de cuadrícula o inteligente elegido.
Los metadatos determinan la compatibilidad
El archivo acompañante contiene coordenadas de frame (x, y, ancho, alto), nombres de frame y propiedades opcionales como recortado o rotado. Esto es lo que diferencia los formatos.
Mapa de compatibilidad de formatos
Formato JSON Hash
JSON Hash usa los nombres de frames como claves del objeto. Es la estructura atlas estilo TexturePacker estándar para Phaser 3 y también común en loaders de PixiJS cuando el runtime busca frames por nombre.
Estructura
Cada frame se almacena como una clave de nivel superior en el objeto JSON. El valor incluye posición x, y dentro del sprite sheet, ancho, alto y bandera opcional isTrimmed.
Opción inicial segura para loaders atlas de Phaser y PixiJS
Phaser 3 carga JSON Hash con this.load.atlas(...). PixiJS también funciona bien con JSON Hash estilo TexturePacker mediante su spritesheet loader o Assets pipeline. Úsalo cuando el runtime referencia frames por nombre.
Acceso rápido a frames
El formato Hash proporciona búsqueda O(1) por nombre de frame. Cuando tu código conoce el nombre exacto del frame (idle_0001, walk_left_0005), accedes directamente sin iterar a través de un array.
Formato JSON Array
JSON Array guarda los frames como una lista secuencial. Es útil para pipelines personalizados, conversores y código de animación que necesita orden estable, pero no debe tratarse como el formato atlas por defecto de PixiJS salvo que tu parser espere exactamente ese schema.
Estructura
Los frames se almacenan en un array bajo la clave frames. Cada elemento del array contiene los mismos datos de rectángulo más la cadena de nombre de archivo. El orden coincide con tu secuencia de frames subida o generada.
Mejor para workflows personalizados con orden estable
Elige JSON Array cuando tu importer propio recorre frames por índice, cuando transformas metadata o cuando un plugin documenta input en array. Para atlas loading en PixiJS/Phaser, JSON Hash suele ser la primera opción más segura.
Acceso basado en índice
Aunque todavía puedes usar nombres de frames, el formato de array te da un ordenamiento predecible. Esto ayuda cuando tu lógica de juego itera a través de frames secuencialmente (animaciones con orden de paso fijo).
Formato XML TextureAtlas
XML TextureAtlas es un formato de metadata estilo TexturePacker/Sparrow. Puede ser útil si una herramienta o addon lo soporta explícitamente, pero Unity y Godot no convierten automáticamente cualquier XML genérico en frames listos para animar.
Estructura
La raíz XML es TextureAtlas con atributo imagePath. Cada SubTexture tiene name, x, y, width y height, con frameX/frameY/frameWidth/frameHeight opcionales para datos de recorte.
Workflow de Unity
Unity normalmente empieza desde el PNG: Sprite Mode en Multiple, slicing en Sprite Editor o Unity Sprite Atlas para empaquetar. XML TextureAtlas requiere un importer compatible de terceros o un editor script personalizado.
Workflow de Godot
Godot 4 funciona mejor desde el PNG con SpriteFrames, regiones de Sprite2D o recursos AtlasTexture. Las coordenadas XML/JSON solo ayudan mediante addon, plugin o parser GDScript personalizado.
Integración dependiente del importer
Trata XML como archivo de intercambio de metadata, no como importación nativa universal. Antes de exportar XML, confirma que tu versión, plugin o pipeline documenta soporte para TextureAtlas/SubTexture.
Formato CSS Sprites
El formato CSS sprites genera una hoja de estilos con reglas de background-position para cada frame. Esto es ideal para animaciones web, íconos de UI y juegos basados en CSS donde no necesitas un motor de juego en absoluto.
Estructura
El archivo CSS define una clase para cada nombre de frame con background-image establecido en la URL de tu sprite sheet y background-position establecido en el desplazamiento de píxel correcto. Los valores negativos desplazan la imagen de fondo a la izquierda o hacia arriba.
Mejor para animaciones web
Usa CSS sprites para estados hover, animaciones de botones o animaciones de personajes simples en proyectos web puros. Añade la clase a un elemento, luego alterna o anima background-position con transiciones CSS.
No se requiere JavaScript
La reproducción básica de sprite funciona solo con HTML y CSS. No necesitas cargar un sprite sheet vía JavaScript o analizar JSON. Solo aplica la clase de frame y opcionalmente anima la posición.
Flujo de selección de formato
Problemas Comunes de Formato
La mayoría de los errores de importación de sprite sheet son desajustes de formato. Tu motor espera una estructura pero exportaste otra. Estas son las señales de advertencia y soluciones.
Error de nombre de frame no encontrado
Esto sucede cuando tu código referencia el frame walk_left_0001 pero el JSON usa walkLeft0001. Verifica tu archivo de metadatos exportado y actualiza el nombre de frame en código o regenera el sprite sheet con la convención de nomenclatura correcta.
Las coordenadas no coinciden con lo visual
Si tu sprite aparece desplazado o recortado, puede que hayas exportado JSON pero lo cargaste como XML (o viceversa) en un motor que por defecto usa un analizador diferente. Asegúrate de que tu código de importación coincida con el formato de exportación.
Las animaciones reproducen frames incorrectos
Cuando los frames se reproducen fuera de orden, el formato de exportación puede no estar preservando tu secuencia deseada. Verifica si tu motor espera formato hash donde el orden no está garantizado, luego cambia a formato de array si tu juego depende del acceso secuencial a frames.
El motor no puede cargar metadatos
Si Unity o Godot no pueden cargar metadata, el problema suele ser soporte del importer, no el PNG. Usa primero slicing nativo/SpriteFrames o añade el importer XML/JSON documentado que tu proyecto requiere.
FAQ de Formatos de Exportación de Sprite Sheet
Exporta en el Formato Correcto
Crea tu sprite sheet una vez en Sprite Sheet Maker. Selecciona el formato que coincide con tu loader o importer real y usa los enlaces de troubleshooting cuando coordenadas, nombres o slicing no encajen.