.gui di TA: Kingdoms — Alberi di widget delimitati da spazi bianchi

TA: Kingdoms disegnava il menu principale, la lobby, l'HUD di gioco e le finestre di dialogo a partire da file .gui: un formato piuttosto singolare di descrizione dei widget, delimitato da spazi bianchi. Nonostante la somiglianza visiva con i file dell'interfaccia di TA (anch'essi .gui), il formato di TA:K è strutturalmente diverso e non intercambiabile.

---

Che cosa stai guardando#

Un file .gui è una sequenza piatta di widget. Il widget d'intestazione del file dichiara il numero totale di widget e i metadati globali (immagine di sfondo, scorciatoie da tastiera); ogni widget successivo descrive un singolo elemento dell'interfaccia.

Un widget tipico ha questo aspetto:

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

I token sono separati da spazi bianchi. Il primo token di ogni widget è l'ID del tipo di widget; tutto ciò che segue rispetta uno schema specifico per tipo.

---

Stringhe precedute dalla lunghezza#

Il trucco più importante del formato: ogni stringa è preceduta dalla sua lunghezza in caratteri, come token intero. Questo significa che le stringhe possono contenere spazi, ma il parser deve leggere prima la lunghezza.

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

Una stringa nulla o vuota è 1 0 0 (prefisso, lunghezza zero, e il payload vuoto è "la stringa vuota"). I prefissi 1/0 ripetuti sono facilissimi da interpretare male se ti limiti a dividere in token sugli spazi bianchi e a contare: devi leggere in sequenza, nell'ordine dei widget.

---

Tipi di widget#

ID dei tipi di widget osservati:

Ogni tipo ha uno schema fisso per i token che seguono l'ID del tipo. Lo schema canonico ricavato con il reverse engineering da Dark Rain è conservato nei materiali di partenza che accompagnano questo repository.

---

Forma generica di 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]

Per ogni tipo di widget cambiano la dimensione di [N] e la struttura dell'insieme di stringhe; gli schemi nei materiali di partenza documentano ciascuno di essi.

Codici di allineamento#

All'interno dell'insieme di stringhe:

Per un widget a stato singolo vedrai ad es. 2 0 6 Player; per un pulsante a 3 stati vedrai tutti e tre gli stati concatenati, ad es. 2 0 0 2 0 6 Player 2 3 6 Play2r 3.

---

Esempio svolto — menu principale#

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

Dall'alto in basso:

• 2 1: widget di tipo 2 (intestazione), flag 1.
• 2 0 0 640 480 1 1 0 0: limiti nell'origine, 640×480, più i quattro token di flag.
• 3 255 255 255 255: voce di colore bianco opaco.
• 8 MainMenu 1 2: nome del controllo "MainMenu" (8 caratteri), seguito da 1 2.
• Le due voci TitleScreen.tsf JPGTest sono l'immagine di sfondo (due riferimenti duplicati: il motore li vuole entrambi).
• 2 0 24 #Enter#Play#Esc#Previous: associazioni dei tasti: Enter attiva il controllo chiamato "Play", Esc attiva "Previous".
• 6: il modulo contiene 6 widget figli, che seguono subito dopo.

Sfondi TSF e GAF#

Il widget d'intestazione supporta due fonti per lo sfondo:

• .tsf: la forma testuale di un'animazione truecolor di TA:K, che il caricatore dell'interfaccia legge direttamente. Per un menu statico è un sottile involucro attorno a un JPG (l'esempio TitleScreen.tsf contiene TitleScreen.jpg), ma lo stesso formato descrive anche animazioni complete con più frame. Vedi TAF / TSF per la struttura binaria e testuale, che kbot sa analizzare e riscrivere entrambe in round-trip.
• .gaf: l'animazione standard di TA: Kingdoms. L'intestazione fa riferimento a una sequenza dentro il GAF; il motore la riproduce come sfondo.

In entrambi i casi il formato richiede che la voce dell'immagine sia elencata due volte, una dopo l'altra; solo la seconda copia viene effettivamente disegnata. È una stranezza nota.

---

Insidie#

• Lo spazio bianco conta solo come delimitatore dei token. I file distribuiti da Cavedog usano sia spazi sia tabulazioni; tratta qualsiasi sequenza di spazi bianchi come un unico separatore.
• Il numero di figli deve essere esatto. Un widget cornice (tipo 9) che termina con 4 reclama come figli i quattro widget di primo livello successivi. Sbaglia il numero e il resto del modulo va in pezzi.
• I widget listbox e barra di scorrimento sono in sostanza modelli vuoti nei file distribuiti: il motore li riempie durante l'esecuzione a partire dallo stato degli script. Non ha senso cercare di popolarli in modo statico.
• L'opzione della riga di comando -disablecavedogverification di TA:K è obbligatoria per caricare la maggior parte dei file .gui modificati. Senza di essa il motore rifiuta qualsiasi file il cui hash non corrisponda a un elenco incorporato.
• Alcuni file vanno in crash quando sono estratti, altri quando sono impacchettati. Il formato in sé è stabile; il caricatore del motore si comporta diversamente a seconda che legga dai livelli del filesystem virtuale o direttamente da una directory. Quando moddi, prova entrambe le situazioni.

---

Vedi anche#

• TAF / TSF: l'animazione truecolor e la sua forma testuale .tsf, a cui le intestazioni dei .gui fanno riferimento per gli sfondi dei menu.
• GAF: le animazioni .taf con palette sono richiamate ovunque nei file .gui.
• PCX: la convenzione dei contenitori di palette che TA:K usa per i .taf con palette.
• Le note sulle difficoltà dei formati di TA:K tra i materiali di partenza di questo repository: insidie pratiche quando si portano asset di TA in TA:K.
• Glossario.