API por lotes de la herramienta de sprites
El SpriteToolPanel del navegador es donde la mayoría de la gente usa la herramienta de sprites, pero todo lo que guarda pasa por la API HTTP, así que una CLI o un trabajo por lotes con sesión iniciada en la misma instalación puede llamar a los mismos endpoints sin la interfaz del navegador.
Esta página describe cómo usa la herramienta de sprites esos endpoints. La
especificación de la API (app/api/openapi.yaml) es el contrato; las rutas
de abajo cuelgan de /api/v1, y todas exigen un llamante con sesión
iniciada.
Qué hay dónde
Sección titulada «Qué hay dónde»| Operación | Superficie HTTP |
|---|---|
| Diseño de frames (reordenar / eliminar / duplicar / cambiar duración / espejo / voltear / rotar / recortar / anotar) | POST /assets/{id}/companions: JSON de complemento |
| Etiquetas (rangos de frames con nombre) + slices (regiones de Aseprite) | El mismo JSON de complemento |
| Cambio de paleta y otras variantes del asset | POST /assets/{id}/alternates |
| Exportar GIF / hoja PNG empaquetada / zip de PNG | Solo en el cliente: se ejecuta en el navegador mediante OffscreenCanvas + gifenc + fflate. Replícalo en local con cualquier codificador equivalente. |
Los codificadores de exportación no tienen deliberadamente un endpoint en el servidor: cualquier cosa que pueda leer el PNG de origen y el JSON de complemento puede producir la exportación por sí misma, y así se evita el procesamiento de imágenes en el servidor para algo que es, en esencia, una vista de los datos propia de cada usuario.
Estructura del JSON de complemento
Sección titulada «Estructura del JSON de complemento»La herramienta de sprites guarda los datos de sus frames en un complemento
llamado sprites.json y, cuando carga un asset, lee el primer complemento
JSON (o .atlas) que tenga adjunto. El formato es el JSON Hash de
TexturePacker, con nuestros propios campos auxiliares en cada entrada de
frame:
{ "frames": { "frame_000.png": { "frame": { "x": 0, "y": 0, "w": 32, "h": 32 }, "rotated": false, "trimmed": false, "spriteSourceSize": { "x": 0, "y": 0, "w": 32, "h": 32 }, "sourceSize": { "w": 32, "h": 32 }, "duration": 100, "transform": { "flipH": true, "rotate": 90 }, "note": "experimenting with mirror" }, "frame_001.png": { "frame": { "x": 32, "y": 0, "w": 32, "h": 32 }, "rotated": false, "trimmed": false, "spriteSourceSize": { "x": 0, "y": 0, "w": 32, "h": 32 }, "sourceSize": { "w": 32, "h": 32 }, "duration": 100 } }, "meta": { "app": "artist-alley sprite tools", "version": "1", "image": "<asset_id>.png", "size": { "w": 160, "h": 96 }, "scale": "1", "frameTags": [ { "name": "walk", "from": 0, "to": 1, "direction": "forward" } ], "slices": [ { "name": "hitbox", "color": "#00ff00ff", "keys": [{ "frame": 0, "bounds": { "x": 4, "y": 8, "w": 16, "h": 20 } }] } ] }}Extras por frame (todos opcionales):
transform.flipH/flipV: reflejan en espejo el rectángulo de origen al dibujar.transform.rotate: 0 / 90 / 180 / 270 alrededor del centro del frame. Se aplica al renderizar y al exportar; los píxeles de origen no se tocan. Elrotatedde TexturePacker es un concepto de empaquetado (este rectángulo se almacena rotado para encajar mejor), deliberadamente distinto.duration: duración por frame en ms. La exportación a GIF la usa y, si falta, recurre a los FPS de la sesión. La vista previa del navegador se reproduce a los FPS de la sesión. Al cargar, una duración positiva en el primer frame inicializa esa velocidad; en caso contrario se mantienen los FPS actuales.note: breve anotación de lluvia de ideas. Se muestra como marcador al pasar el cursor sobre la miniatura de la línea de tiempo.
Los slices siguen la estructura de Aseprite; la herramienta de sprites
actualmente solo lee la primera entrada de las keys de cada slice.
El orden de los frames sale de la entrada frames. Si frames es un array
(entradas con un filename), la herramienta de sprites mantiene el orden del
array. En la forma hash mostrada arriba, ordena los nombres de los frames de
forma natural (walk 9 antes de walk 10), así que los nombres deciden el
orden, no el orden de las claves en el objeto. Los rangos de las etiquetas
(from, to) son posiciones inclusivas, contadas desde 0, en esa lista
cargada. Un cliente que reordene, elimine o duplique frames debería elegir
nombres que se ordenen en el nuevo orden y reasignar los rangos de las
etiquetas en consecuencia (la sesión de la aplicación reasigna las etiquetas
en la medida de lo posible). El propio panel guarda la forma hash indexada
por nombre de frame, de modo que un reordenamiento hecho en el navegador solo
sobrevive a una recarga si los nombres se ordenan de ese modo.
Para guardar un complemento desde un script, sube el JSON con la ruta que espera la herramienta de sprites:
curl -X POST "$BASE/api/v1/assets/$ID/companions" \ -H "Authorization: Bearer $AA_TOKEN" \ -H "X-Companion-Path: sprites.json" \ -H "X-Content-Type: application/json" \ -H "Content-Type: application/octet-stream" \ --data-binary @sprites.jsonBASE es la URL de tu instalación, ID el UUID del asset y AA_TOKEN un
token de acceso personal de la cuenta que hace el trabajo (consulta
Autenticación); una cookie de
sesión del navegador también sirve. Subir a una ruta que ya tiene un
complemento lo sustituye.
Añadir un cambio de paleta (o cualquier variante hermana)
Sección titulada «Añadir un cambio de paleta (o cualquier variante hermana)»Las alternates son variantes hermanas del propio asset; mientras que los complementos son archivos auxiliares a los que hace referencia el asset principal, las alternates son independientes. Tú produces el archivo de la variante (el panel renderiza un cambio de paleta en el navegador) y subes los bytes finales; las cabeceras de tipo y metadatos describen el archivo, no le piden al servidor que transforme nada.
curl -X POST "$BASE/api/v1/assets/$ID/alternates" \ -H "Authorization: Bearer $AA_TOKEN" \ -H "X-Alternate-Label: walk - team-green palette" \ -H "X-Alternate-Kind: palette_swap" \ -H 'X-Alternate-Metadata: {"remap":[{"from":"#aabbcc","to":"#112233"}]}' \ -H "X-Content-Type: image/png" \ -H "Content-Type: application/octet-stream" \ --data-binary @walk-green.pngX-Content-Type es el tipo MIME propio de la variante; Content-Type sigue
siendo application/octet-stream para la subida en sí.
X-Alternate-Kind es abierto. El manejador elimina los espacios al principio
y al final y limita el tipo proporcionado a 64 bytes UTF-8; si se omite, se
usa authored. La especificación enumera estos valores convencionales; el
panel muestra el tipo de una alternate como una etiqueta en lugar de agrupar
por él:
palette_swap: remapeo de paleta de la herramienta de sprites (el cambio de paleta del panel lo usa)thumbnail: miniatura del pipeline de imágeneslow_res: versión web-res del pipeline de imágenestranscode: cambio de códec / contenedorauthored: una variante creada por una persona; está prevista la pintura de variantes en el navegador
X-Alternate-Metadata es un JSON propio de cada tipo, opaco para el
servidor (cualquier JSON válido de hasta 8 KB). El cambio de paleta registra
su array remap para que los parámetros que produjeron la variante queden
registrados; nada regenera la variante automáticamente a partir de ellos.
Las etiquetas son únicas por asset; el manejador elimina los espacios al principio y al final y exige una etiqueta no vacía de como máximo 256 bytes UTF-8. Subir con una etiqueta existente sustituye esa variante y desancla los bytes antiguos; no se eliminan de inmediato.
Verificación con prueba de humo
Sección titulada «Verificación con prueba de humo»scripts/sprite-batch-smoke.sh es una comprobación rápida de estos
endpoints. Inicia sesión con una cookie, lista, añade y elimina un
complemento, y después lista, añade, descarga y elimina una alternate.
Comprueba que cada subida devuelve un ID, que los bytes descargados coinciden
con los enviados y que ambas eliminaciones devuelven 204. No comprueba el
estado de las llamadas de listado ni sube una imagen real, así que considéralo
una prueba de humo, no una comprobación completa de la API. Ejecútalo después
de cambiar los manejadores de complementos o de alternates.
Escribe un complemento en sprite-smoke.json y una alternate con la etiqueta
sprite-batch-smoke-output, sustituyendo lo que haya allí, y puede dejar
adjuntos de prueba si se detiene a medias. Ejecútalo desde la raíz del
repositorio contra una instancia de prueba y un asset desechable, con tu
cuenta de prueba en AA_SMOKE_USER y AA_SMOKE_PASSWORD. Sin un ID de
asset, usa el primer asset que devuelva la API, que puede no ser un sprite, y
la URL base por defecto es http://localhost:8088.
AA_SMOKE_USER=admin AA_SMOKE_PASSWORD='<test password>' \ ./scripts/sprite-batch-smoke.sh http://localhost:8080 "$ASSET_ID"