TAF / TSF — animations truecolor de TA: Kingdoms

Le TAF stocke les animations de sprites truecolor de Total Annihilation: Kingdoms : effets de sorts, explosions, boules de feu, anneaux magiques, sprites d'eau et fonds de menus animés. Il reprend la disposition du conteneur GAF de Total Annihilation, mais remplace les pixels 8 bits indexés dans une palette par de l'ARGB 16 bits : un TAF porte donc ses propres couleurs et un vrai canal alpha, sans palette externe. Le TSF est la forme texte lisible de la même animation : un script délimité par des accolades que le chargeur de l'interface lit directement.

kbot taf list   anims/manabomb_1555.taf                                 # sequence + frame count
kbot taf export anims/fireballa_1555.taf --format gif -o fireball.gif    # animated preview
kbot taf sheet  anims/manabomb_1555.taf --cols 5 -o manabomb-sheet.png   # contact sheet
kbot taf decompile anims/manabomb_1555.taf --target ./manabomb           # → TSF + PNG layers

import "github.com/coreprime/kbot/formats/tsf"

data, _ := os.ReadFile("anims/manabomb_1555.taf")
taf, _ := tsf.ParseTAF(data)
fmt.Println(taf.Name, len(taf.Frames))
img, _ := taf.FrameImage(0)   // *image.NRGBA, full alpha preserved

Vue d'ensemble#

┌─ Header (12B) ─┐
│ ver  1  pad    │   ver = 0x00010100, exactly one sequence
└────────┬───────┘
         ▼
┌─ Entry pointer ─┐  1 × uint32 absolute offset → SequenceHeader
└───┬─────────────┘
    ▼
┌─ SequenceHeader (40B) ─┐
│ frameCount, name[32]   │
└─────────┬──────────────┘
          ▼
┌─ FrameListItem (8B) × frameCount ─┐  ptr + tick duration
└───┬───────────────────────────────┘
    ▼
┌─ FrameInfo (24B) ─┐
│ size, origin,     │
│ format(4/5),      │   ← the GAF "compressed" byte, repurposed
│ layers=0, flag,   │
│ ptrPixelData      │
└─────┬─────────────┘
      ▼
┌─ Pixel data: Width×Height × uint16 ─┐  raw ARGB4444 or ARGB1555
└──────────────────────────────────────┘

Un TAF est une séquence d'animation unique — un tableau de frames, chacune étant un rectangle largeur × hauteur de pixels truecolor 16 bits en little-endian, avec un point d'origine et une durée en ticks. Il n'y a ni compression ni calques au niveau binaire : chaque frame est une image plate, non compressée.

En-tête (12 octets)#

typedef struct {
    uint32 Version;        // 0x00010100 — identical to the GAF version word
    uint32 SequenceCount;  // Always 1 for a truecolor TAF
    uint32 Unknown1;       // Always 0
} TAFHeader;

Séquence (40 octets)#

typedef struct {
    uint16 FrameCount;
    uint16 Unknown1;       // Always 1
    uint32 Unknown2;       // Always 0
    char   Name[32];       // NUL-padded, case-preserved
} TAFSequence;

Suivi de FrameCount × FrameListItem :

typedef struct {
    uint32 PtrFrameInfo;   // → FrameInfo
    uint32 Duration;       // Game ticks (30 ticks = 1 second)
} FrameListItem;

Frame (info de 24 octets + charge utile)#

typedef struct {
    uint16 Width;
    uint16 Height;
    int16  OriginX;        // Render anchor, may be negative
    int16  OriginY;
    uint8  Transparency;   // 0x08: always 0 (alpha lives in the pixels)
    uint8  Format;         // 0x09: 4 = ARGB4444, 5 = ARGB1555
    uint8  LayerCount;     // 0x0A: always 0 (no sub-frames)
    uint8  Flag;           // 0x0B: 0x00 or 0xFF, meaning unconfirmed
    uint32 Unknown2;       // 0x0C: always 0
    uint32 PtrPixelData;   // 0x10: → raw pixel bytes
    uint32 Unknown3;       // 0x14: always 0
} FrameInfo;

C'est ici que le TAF s'écarte du GAF. Dans un FrameInfo de GAF, l'offset 0x09 est le flag Compressed et les offsets 0x0A–0x0B forment un LayerCount de 16 bits. Un TAF truecolor réutilise ces mêmes octets avec le sens suivant :

OriginX / OriginY sont le point d'ancrage utilisé pour copier la frame à l'écran — en général le centre de l'effet : une explosion de 50×48 a donc pour origine 25,24. kbot conserve l'octet Flag tel quel pour des allers-retours exacts à l'octet près, bien que son sens ne soit pas confirmé sur l'ensemble des ressources d'origine.

Données de pixels#

PtrPixelData pointe sur exactement Width × Height valeurs uint16 en little-endian — 2 octets par pixel, de haut en bas et de gauche à droite, sans compression ni en-têtes de ligne. Les 16 bits se décodent selon le Format de la frame :

ARGB4444 (Format == 4)#

 bit 15 ──────────────────────────── bit 0
┌─────┬─────┬─────┬─────┐
│  A  │  R  │  G  │  B  │   4 bits each
└─────┴─────┴─────┴─────┘
  15-12  11-8   7-4   3-0

Chaque canal de 4 bits est étendu à 8 bits par réplication des bits (v<<4 | v) : 0xF → 0xFF et 0x0 → 0x00. L'extension est exactement inversible, ce qui permet à kbot de faire l'aller-retour des pixels sans perte.

ARGB1555 (Format == 5)#

 bit 15 ──────────────────────────── bit 0
┌─┬───────┬───────┬───────┐
│A│   R   │   G   │   B   │   1 + 5 + 5 + 5
└─┴───────┴───────┴───────┘
 15  14-10   9-5    4-0

L'unique bit alpha est en tout ou rien (0 → entièrement transparent, 1 → entièrement opaque) ; chaque canal de couleur de 5 bits est étendu par réplication (v<<3 | v>>2). Utilisez l'ARGB1555 pour les sprites aux bords nets qui n'ont besoin que d'un détourage sur 1 bit, et l'ARGB4444 quand il vous faut 16 niveaux d'alpha progressif (fumée, halos, fondus).

Distinguer les TAF à palette des TAF truecolor#

Les deux sortes de .taf partagent l'en-tête et le mot de version du GAF : impossible donc de les distinguer sur les 12 premiers octets. Le critère est l'octet Format/Compressed de la frame, à l'offset 0x09 du FrameInfo :

kbot taf vérifie cet octet et refuse un fichier à palette avec une erreur claire ; dans ce cas, tournez-vous vers kbot gaf. La plupart des TAF truecolor de TA:K suivent aussi une convention de nommage — un suffixe _4444 ou _1555 (manabomb_1555.taf, bluefire_4444.taf) —, mais c'est l'octet de format qui fait foi, pas le nom.

TSF — la forme texte#

Le TSF (TAF Source Format) est la même animation exprimée sous forme de script de style INI, délimité par des accolades. Le chargeur d'interface de TA: Kingdoms lit le TSF directement pour les fonds de menus, et c'est le format d'échange que produit kbot quand vous décompilez un TAF : une section par animation, une sous-section Frame par frame, et un Layer par frame qui renvoie à un fichier image externe.

/* anims/titlescreen.tsf — abridged */
[JPGTest]
{
    Looping = 0;
    [Frame0]
    {
        Delay = 0;
        [Layer0]
        {
            AnchorX = 0;
            AnchorY = 0;
            Filename = TitleScreen.jpg;
        }
    }
    [Frame1] { /* … */ }
}

Un TAF compilé aplatit l'unique calque de chaque frame en une seule image truecolor. kbot attend exactement un calque par frame (la composition de plusieurs calques est une commodité de création d'interface que le compilateur résout à la construction) ; kbot tsf lint signale tout ce qui ne se compilera pas proprement.

kbot tsf info anims/titlescreen.tsf   # animation, frames, layer filenames
kbot tsf lint anims/titlescreen.tsf   # shape check; non-zero exit on errors

Exemple commenté — manabomb_1555.taf#

$ kbot taf info anims/manabomb_1555.taf
TAF: anims/manabomb_1555.taf
Sequence:  "manabomb"
Frames:    10
Duration:  20 ticks (0.67s)

#  Size   Origin  Format    Duration  Flag
─  ────   ──────  ──────    ────────  ────
0  50x48  25,24   ARGB1555  2         0x00
1  50x48  25,24   ARGB1555  2         0x00
...
9  50x48  25,24   ARGB1555  2         0x00

Dix frames de 50×48, chacune ancrée en son centre (25,24) et affichée pendant 2 ticks : une étoile d'explosion de ⅔ de seconde. Le fichier entier fait 48 376 octets : 50 × 48 × 2 = 4,800 octets de pixels par frame × 10, plus l'en-tête, l'en-tête de séquence, la liste des frames et dix enregistrements d'info de 24 octets.

Utilisation en ligne de commande#

L'arborescence kbot taf couvre l'inspection, le rendu, la conversion et le cycle de compilation TAF↔TSF ; kbot tsf couvre la forme texte. Chaque commande résout son entrée via le contexte kbot actif ou un montage --vfs explicite, exactement comme kbot gaf et kbot studio : des noms de fichiers nus comme manabomb_1555.taf sont donc cherchés dans toutes les archives montées.

Inspecter et rendre#

kbot taf info   anims/bluefire_4444.taf            # per-frame table
kbot taf list   anims/bluefire_4444.taf            # one-line summary
kbot taf render anims/bluefire_4444.taf --frame 4 -o frame4.png
kbot taf sheet  anims/bluefire_4444.taf --cols 6 --bg "#202830" -o sheet.png
kbot taf export anims/bluefire_4444.taf --format apng -o bluefire.png   # or --format gif

export produit par défaut de l'APNG, qui conserve tout le canal alpha ; --format gif quantifie vers une table de 255 couleurs plus un emplacement transparent (un détourage sur 1 bit), pour les aperçus et les clients de messagerie.

Aller-retour décompilation ↔ compilation#

kbot taf decompile anims/manabomb_1555.taf --target ./manabomb
#   → manabomb/manabomb.tsf  +  manabomb_0.png … manabomb_9.png

kbot taf compile ./manabomb/manabomb.tsf --images ./manabomb -o rebuilt.taf
kbot taf diff anims/manabomb_1555.taf rebuilt.taf      # exits 0 — identical

decompile écrit un TSF plus un PNG par frame ; compile les relit pour produire un TAF binaire. Pour tout TAF que kbot a analysé, l'aller-retour est identique à l'octet près — kbot taf roundtrip et kbot taf diff le vérifient tous deux.

Importer depuis des formats courants#

kbot taf from-gif   boom.gif   --format argb4444 --name Boom        -o boom.taf
kbot taf from-sheet strip.png  --frame-width 64 --frame-height 64 \
                               --count 8 --delay 3 --format argb1555 -o strip.taf

from-gif aplatit un GIF animé (en respectant ses modes de disposition et ses délais par frame) en un TAF truecolor ; from-sheet découpe en frames une bande de sprites PNG/JPG à grille fixe. Les deux vous laissent choisir le format de pixel cible.

Valider#

kbot taf lint anims/manabomb_1555.taf   # structural findings; non-zero exit on errors

Outils MCP#

Les mêmes fonctions sont exposées par le serveur MCP, pour qu'un agent puisse inspecter et montrer les animations directement :

taf_render et taf_sheet renvoient un bloc de contenu image : un modèle peut ainsi prévisualiser un effet de sort sans aller-retour supplémentaire de lecture de fichier. Les chemins sont résolus par rapport au dossier game-data configuré, comme pour tous les autres outils MCP de kbot.

Pièges#

• Exactement une séquence. Un TAF truecolor contient toujours une seule animation ; un SequenceCount différent de 1 signifie que vous avez affaire à un autre fichier (probablement à palette).
• Jamais de compression. Chaque frame est une image plate de Width×Height en 16 bits. Il n'existe pas de chemin RLE comme dans le GAF : les grands effets de flammes (composite02flame) atteignent ~600 Ko justement parce que rien n'est compacté.
• Le champ de nom peut contenir des déchets. Dans plusieurs fichiers d'origine, les octets qui suivent le NUL final ne sont pas initialisés ; conservez les 32 octets pour un aller-retour exact, mais ne lisez que jusqu'au NUL.
• L'octet de flag 0x0B reste inexpliqué. On l'observe à 0x00 ou à 0xFF. kbot le conserve tel quel ; ne le normalisez pas, sinon les allers-retours ne correspondent plus.
• L'export GIF perd de l'information. Le GIF ne peut contenir qu'un détourage sur 1 bit et 255 couleurs : l'alpha progressif de l'ARGB4444 devient des bords nets. Utilisez l'APNG pour conserver le vrai canal alpha.
• Un Delay / Duration de 0 est valide. Comme dans le GAF, une frame de zéro tick est pilotée par les événements (l'exemple de menu JPGTest utilise Delay = 0 pour un fond statique). Ne le « corrigez » pas en une valeur par défaut.

Tailles typiques#

Voir aussi#

• GAF — le conteneur à palette sur lequel repose le TAF ; à lire en premier, et à utiliser pour les fichiers .taf à palette.
• PCX — comment les ressources à palette de TA:K obtiennent leurs couleurs (le TAF truecolor n'en a pas besoin).
• Interface de TA:K — le système de menus dont le chargeur utilise directement le TSF pour les fonds animés.
• Formats TA et TA:K — ce que les deux jeux ont en commun et où ils divergent.
• Glossaire — origine, tick, sous-frame.