Aller au contenu

API par lots de l'outil sprite

Le SpriteToolPanel, dans le navigateur, est l’endroit où la plupart des gens utilisent l’outil sprite, mais tout ce qu’il enregistre passe par l’API HTTP : une CLI ou une tâche par lots connectée à la même installation peut donc appeler les mêmes points d’accès sans passer par l’interface du navigateur.

Cette page décrit comment l’outil sprite utilise ces points d’accès. La spécification de l’API (app/api/openapi.yaml) fait foi ; les chemins ci-dessous se trouvent sous /api/v1, et chacun d’eux exige un appelant authentifié.

OpérationSurface HTTP
Disposition des frames (réordonner / supprimer / dupliquer / modifier la durée / miroir / retourner / pivoter / rogner / annoter)POST /assets/{id}/companions : JSON de compagnon
Tags (plages de frames nommées) + slices (régions Aseprite)Même JSON de compagnon
Échange de palette et autres variantes de l’assetPOST /assets/{id}/alternates
Export GIF / planche PNG assemblée / zip de PNGCôté client uniquement : s’exécute dans le navigateur via OffscreenCanvas + gifenc + fflate. À reproduire localement avec n’importe quel encodeur équivalent.

Les encodeurs d’export n’ont volontairement pas de point d’accès côté serveur : tout ce qui peut lire le PNG source et le JSON de compagnon peut produire l’export lui-même, et cela évite un traitement d’image côté serveur pour ce qui est fondamentalement une vue des données propre à chaque utilisateur.

L’outil sprite enregistre les données de ses frames dans un compagnon nommé sprites.json et, lorsqu’il charge un asset, il lit le premier compagnon JSON (ou .atlas) qui lui est associé. Le format est le JSON Hash de TexturePacker, avec nos propres champs annexes sur chaque entrée 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 } }] }
]
}
}

Champs supplémentaires par frame (tous facultatifs) :

  • transform.flipH / flipV : retournent en miroir le rectangle source au dessin.
  • transform.rotate : 0 / 90 / 180 / 270 autour du centre de la frame. Appliqué au rendu et à l’export ; les pixels sources ne sont pas modifiés. Le rotated de TexturePacker est une notion d’empaquetage (ce rectangle est stocké pivoté pour mieux s’insérer), volontairement distincte.
  • duration : durée de la frame en ms. L’export GIF l’utilise, avec repli sur les FPS de la session en son absence. L’aperçu dans le navigateur est lu aux FPS de la session. Au chargement, une durée positive sur la première frame initialise cette cadence ; sinon, les FPS actuels sont conservés.
  • note : courte annotation de brainstorming. Affichée sous forme de marqueur au survol de la vignette de la timeline.

Les slices suivent la structure d’Aseprite ; l’outil sprite ne lit actuellement que la première entrée des keys de chaque slice.

L’ordre des frames provient de l’entrée frames. Si frames est un tableau (des entrées portant un filename), l’outil sprite conserve l’ordre du tableau. Dans la forme hash montrée ci-dessus, il trie les noms de frames de façon naturelle (walk 9 avant walk 10) : ce sont donc les noms qui décident de l’ordre, et non l’ordre des clés dans l’objet. Les plages des tags (from, to) sont des positions inclusives, comptées à partir de 0, dans cette liste chargée. Un client qui réordonne, supprime ou duplique des frames doit choisir des noms qui se trient dans le nouvel ordre et remapper les plages des tags en conséquence (la session dans l’application remappe les tags au mieux). Le panneau lui-même enregistre la forme hash indexée par nom de frame ; un réordonnancement fait dans le navigateur ne survit donc à un rechargement que si les noms se trient dans cet ordre.

Pour enregistrer un compagnon depuis un script, envoyez le JSON avec le chemin que l’outil sprite attend :

Fenêtre 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 est l’URL de votre installation, ID l’UUID de l’asset et AA_TOKEN un jeton d’accès personnel du compte qui effectue le travail (voir Authentification) ; un cookie de session de navigateur fonctionne aussi. Envoyer vers un chemin qui a déjà un compagnon le remplace.

Ajouter un échange de palette (ou toute variante sœur)

Section intitulée « Ajouter un échange de palette (ou toute variante sœur) »

Les alternates sont des variantes sœurs de l’asset lui-même ; alors que les compagnons sont des fichiers annexes auxquels l’asset principal fait référence, les alternates existent par elles-mêmes. Vous produisez vous-même le fichier de la variante (le panneau rend un échange de palette dans le navigateur) et vous envoyez les octets finaux ; les en-têtes de type et de métadonnées décrivent le fichier, ils ne demandent pas au serveur de transformer quoi que ce soit.

Fenêtre 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 est le type MIME propre à la variante ; Content-Type reste application/octet-stream pour l’envoi lui-même.

X-Alternate-Kind est ouvert. Le gestionnaire supprime les espaces en début et en fin de valeur et limite un type fourni à 64 octets UTF-8 ; s’il est omis, authored est utilisé. La spécification énumère ces valeurs conventionnelles ; le panneau affiche le type d’une alternate sous forme d’étiquette plutôt que de regrouper par type :

  • palette_swap : remappage de palette de l’outil sprite (l’échange de palette du panneau l’utilise)
  • thumbnail : miniature du pipeline d’images
  • low_res : version web-res du pipeline d’images
  • transcode : changement de codec / conteneur
  • authored : une variante créée par une personne ; la peinture de variantes dans le navigateur est prévue

X-Alternate-Metadata est un JSON propre à chaque type, opaque pour le serveur (tout JSON valide jusqu’à 8 Ko). L’échange de palette y enregistre son tableau remap, afin que les paramètres qui ont produit la variante restent consignés ; rien ne régénère automatiquement la variante à partir d’eux.

Les libellés sont uniques par asset ; le gestionnaire supprime les espaces en début et en fin de valeur et exige un libellé non vide d’au plus 256 octets UTF-8. Envoyer avec un libellé existant remplace cette variante et désépingle les anciens octets ; ils ne sont pas supprimés immédiatement.

scripts/sprite-batch-smoke.sh est une vérification rapide de ces points d’accès. Il se connecte avec une session par cookie, liste, ajoute et supprime un compagnon, puis liste, ajoute, télécharge et supprime une alternate. Il vérifie que chaque envoi renvoie un ID, que les octets téléchargés correspondent à ceux envoyés et que les deux suppressions renvoient 204. Il ne vérifie pas le statut des appels de liste et n’envoie pas de véritable image : considérez-le comme un test de fumée, et non comme une vérification complète de l’API. Exécutez-le après avoir modifié les gestionnaires de compagnons ou d’alternates.

Il écrit un compagnon à sprite-smoke.json et une alternate libellée sprite-batch-smoke-output, en remplaçant ce qui s’y trouve déjà, et peut laisser des pièces jointes de test derrière lui s’il s’arrête en cours de route. Exécutez-le depuis la racine du dépôt, contre une instance de test et un asset jetable, avec votre compte de test dans AA_SMOKE_USER et AA_SMOKE_PASSWORD. Sans ID d’asset, il utilise le premier asset renvoyé par l’API, qui n’est pas forcément un sprite, et l’URL de base vaut par défaut http://localhost:8088.

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