.gui de TA: Kingdoms — arbres de widgets séparés par des blancs

TA: Kingdoms dessinait son menu principal, son salon, son interface en jeu et ses boîtes de dialogue à partir de fichiers .gui — un format de description de widgets atypique, délimité par des blancs. Malgré la ressemblance visuelle avec les fichiers d'interface de TA (eux aussi en .gui), le format de TA:K a une structure différente et n'est pas interchangeable.

---

Ce que vous avez sous les yeux#

Un fichier .gui est une suite plate de widgets. Le widget d'en-tête du fichier déclare le nombre total de widgets et des métadonnées globales (image de fond, raccourcis clavier) ; chaque widget qui suit décrit un unique élément d'interface.

Un widget typique ressemble à ceci :

4 1                                       ← widget type (4 = button), unused flag (always 1)
1                                         ← unused (always 1 except in headers)
2 196 79 95 20 1 0 0 0                    ← bounds: type, X, Y, W, H, flags…
3 0 0 0 0                                 ← colour: type, R, G, B, A
1 0 0                                     ← unused (always 1 0 0)
1 14 hattfont11.gaf                       ← font: type, len, name
12 PlayerColor 2 12                       ← control name + state count
3                                         ← number of gaf frames that follow
1 17 singlemachine.gaf 14 SingleMachine0 0 18    ← disabled frame
1 17 singlemachine.gaf 14 SingleMachine0 1 18    ← pressed frame
1 17 singlemachine.gaf 14 SingleMachine0 2 18    ← released frame
3                                         ← number of strings that follow
2 0 0 2 0 4 Exit 2 0 4 Exit 3             ← state strings (disabled, pressed, up)
1 7 Default
1 12 skirmish.wav                         ← sound played when activated
1 7 Default
2 0 16 Play the Machine                   ← tooltip / mouseover help
0                                         ← number of child widgets

Les jetons sont séparés par des blancs. Le premier jeton de chaque widget est l'identifiant de son type ; tout ce qui suit obéit à un schéma propre au type.

---

Chaînes préfixées par leur longueur#

L'astuce la plus importante du format : chaque chaîne est précédée de sa longueur en caractères, sous forme de jeton entier. Les chaînes peuvent donc contenir des espaces — mais l'analyseur doit lire la longueur d'abord.

1 14 MainScreen.gaf
^ ^^ ^^^^^^^^^^^^^^
│  │  │
│  │  └─ the string itself (14 characters)
│  └─ length
└─ string-flavour prefix (1 = literal string)

Une chaîne nulle ou vide s'écrit 1 0 0 (préfixe, longueur nulle, et une charge utile vide qui est « la chaîne vide »). Les préfixes 1/0 répétés sont très faciles à mal analyser si l'on se contente de découper sur les blancs et de compter : il faut lire séquentiellement, dans l'ordre des widgets.

---

Types de widgets#

Identifiants de types de widgets observés :

Chaque type a un schéma fixe pour les jetons qui suivent l'identifiant de type. Le schéma de référence, établi par rétro-ingénierie par Dark Rain, est conservé dans les documents sources qui accompagnent ce dépôt.

---

Forme générique d'un widget#

[TYPE] 1
1
2  [X] [Y] [W] [H] 1 0 0 0
3  [colour: A R G B]
1 0 0
1 [font: length name]
[control-name length] [name] 2 3
[N]
1 [len] [gaf]  [len] [seq] [frame] 9     × N
[N]
2 0 0 2 [string set]                     × N entries inline
1 7 Default
1 [len] [activate.wav]
1 7 Default
2 0 [help length] [help text]
[child-count]

Selon le type de widget, la taille de [N] et la structure de l'ensemble de chaînes varient ; les schémas des documents sources décrivent chacun d'eux.

Codes d'alignement#

Dans l'ensemble de chaînes :

Pour un widget à un seul état, vous verrez par ex. 2 0 6 Player ; pour un bouton à 3 états, vous verrez les trois états à la suite, par ex. 2 0 0 2 0 6 Player 2 3 6 Play2r 3.

---

Exemple commenté — menu principal#

2 1
2 0 0 640 480 1 1 0 0
3 255 255 255 255
1 0 0
1 0
8 MainMenu 1 2
2
1 15 TitleScreen.tsf 7 JPGTest 0 9
1 15 TitleScreen.tsf 7 JPGTest 1 9
2
2 0 0 2 0 0 2
1 0
1 0
2 0 24 #Enter#Play#Esc#Previous
6

De haut en bas :

• 2 1 — widget de type 2 (en-tête), flag 1.
• 2 0 0 640 480 1 1 0 0 — limites à l'origine, 640×480, plus les quatre jetons de flags.
• 3 255 255 255 255 — entrée de couleur blanc opaque.
• 8 MainMenu 1 2 — nom de contrôle « MainMenu » (8 caractères), suivi de 1 2.
• Les deux entrées TitleScreen.tsf JPGTest constituent l'image de fond (deux références en double — le moteur veut les deux).
• 2 0 24 #Enter#Play#Esc#Previous — raccourcis clavier : Enter déclenche le contrôle nommé « Play », Esc déclenche « Previous ».
• 6 — le formulaire contient 6 widgets enfants, qui suivent immédiatement.

Fonds TSF et fonds GAF#

Le widget d'en-tête accepte deux sources de fond :

• .tsf — la forme texte d'une animation truecolor de TA:K, que le chargeur d'interface lit directement. Pour un menu statique, c'est une simple enveloppe autour d'un JPG (l'exemple TitleScreen.tsf enveloppe TitleScreen.jpg), mais le même format décrit des animations complètes à plusieurs frames. Voir TAF / TSF pour la disposition binaire et la disposition texte, que kbot sait toutes deux analyser et faire passer par un aller-retour.
• .gaf — l'animation standard de TA: Kingdoms. L'en-tête désigne une séquence du GAF ; le moteur la joue comme fond.

Dans les deux cas, le format exige que l'entrée d'image soit listée deux fois d'affilée ; seule la seconde copie est réellement affichée. C'est une particularité connue.

---

Pièges#

• Les blancs ne comptent que pour délimiter les jetons. Les fichiers livrés par Cavedog utilisent à la fois des espaces et des tabulations ; traitez toute suite de blancs comme un séparateur unique.
• Les nombres d'enfants doivent être exacts. Un widget cadre (type 9) qui se termine par 4 revendique comme enfants les quatre widgets de premier niveau suivants. Si le nombre est faux, le reste du formulaire se désagrège.
• Les widgets liste et barre de défilement sont essentiellement des modèles vides dans les fichiers livrés : le moteur les remplit à l'exécution à partir de l'état des scripts. Inutile d'essayer de les remplir statiquement.
• Le flag de ligne de commande -disablecavedogverification de TA:K est obligatoire pour charger la plupart des fichiers .gui moddés. Sans lui, le moteur rejette tout fichier dont l'empreinte ne correspond pas à une liste intégrée.
• Certains fichiers plantent une fois dépaquetés, d'autres une fois empaquetés. Le format lui-même est stable ; c'est le chargeur du moteur qui se comporte différemment selon qu'il passe par les couches du système de fichiers virtuel ou accède directement au répertoire. Quand vous moddez, testez les deux cas.

---

Voir aussi#

• TAF / TSF — l'animation truecolor et sa forme texte .tsf, auxquelles les en-têtes .gui font référence pour les fonds de menus.
• GAF — des animations .taf à palette sont référencées partout dans les fichiers .gui.
• PCX — la convention des porteurs de palette qu'utilise TA:K pour les .taf à palette.
• Les notes sur les difficultés des formats de TA:K, dans les documents sources de ce dépôt — les pièges pratiques du portage de ressources de TA vers TA:K.
• Glossaire.