Ir al contenido

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.

OperaciónSuperficie 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 assetPOST /assets/{id}/alternates
Exportar GIF / hoja PNG empaquetada / zip de PNGSolo 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.

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. El rotated de 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:

Ventana de terminal
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.json

BASE 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.

Ventana de terminal
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.png

X-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ágenes
  • low_res: versión web-res del pipeline de imágenes
  • transcode: cambio de códec / contenedor
  • authored: 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.

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.

Ventana de terminal
AA_SMOKE_USER=admin AA_SMOKE_PASSWORD='<test password>' \
./scripts/sprite-batch-smoke.sh http://localhost:8080 "$ASSET_ID"