.gui von TA: Kingdoms – durch Leerraum getrennte Widget-Bäume

TA: Kingdoms hat sein Hauptmenü, die Lobby, das HUD im Spiel und die Dialogfenster aus .gui-Dateien gezeichnet – einem eigenwilligen Beschreibungsformat für Widgets, getrennt durch Leerraum. Trotz der optischen Ähnlichkeit zu den Oberflächendateien von TA (ebenfalls .gui) ist das Format von TA:K strukturell anders und nicht austauschbar.

---

Was du hier vor dir hast#

Eine .gui-Datei ist eine flache Folge von Widgets. Das Header-Widget der Datei deklariert die Gesamtzahl der Widgets und globale Metadaten (Hintergrundbild, Tastenkürzel); jedes Widget danach beschreibt ein einzelnes Element der Oberfläche.

Ein typisches Widget sieht so aus:

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

Die Tokens sind durch Leerraum getrennt. Das erste Token jedes Widgets ist die ID des Widget-Typs; alles danach folgt einem Schema, das vom Typ abhängt.

---

Strings mit Längenpräfix#

Der wichtigste Kniff des Formats: Vor jedem String steht seine Länge in Zeichen als Ganzzahl-Token. Strings können also Leerzeichen enthalten – aber der Parser muss zuerst die Länge lesen.

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

Ein leerer String ist 1 0 0 (Präfix, Länge null, die leeren Nutzdaten sind „der leere String“). Die wiederholten Präfixe 1/0 lassen sich sehr leicht falsch parsen, wenn du einfach an Leerraum in Tokens zerlegst und anfängst zu zählen – du musst der Reihe nach in der Reihenfolge der Widgets lesen.

---

Widget-Typen#

Beobachtete IDs der Widget-Typen:

Jeder Typ hat ein festes Schema für die Tokens nach der Typ-ID. Das kanonische Schema, das Dark Rain per Reverse Engineering ermittelt hat, ist in den Quellmaterialien dieses Repos aufbewahrt.

---

Allgemeine Form eines Widgets#

[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]

Je nach Widget-Typ unterscheiden sich die Größe von [N] und die Struktur des String-Satzes; die Schemata in den Quellmaterialien dokumentieren jeden einzelnen.

Ausrichtungscodes#

Innerhalb des String-Satzes:

Bei einem Widget mit einem einzigen Zustand siehst du z. B. 2 0 6 Player; bei einer Schaltfläche mit 3 Zuständen siehst du alle drei Zustände aneinandergereiht, z. B. 2 0 0 2 0 6 Player 2 3 6 Play2r 3.

---

Beispiel im Detail – Hauptmenü#

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

Von oben nach unten gelesen:

• 2 1 – Widget-Typ 2 (Header), Flag 1.
• 2 0 0 640 480 1 1 0 0 – Begrenzung am Ursprung, 640×480, dazu die vier Flag-Tokens.
• 3 255 255 255 255 – deckender weißer Farbeintrag.
• 8 MainMenu 1 2 – Steuerelementname „MainMenu“ (8 Zeichen), gefolgt von 1 2.
• Die beiden Einträge TitleScreen.tsf JPGTest sind das Hintergrundbild (zwei doppelte Verweise – die Engine will beide).
• 2 0 24 #Enter#Play#Esc#Previous – Tastenbelegungen: Enter löst das Steuerelement namens „Play“ aus, Esc löst „Previous“ aus.
• 6 – das Formular enthält 6 Kind-Widgets, die unmittelbar folgen.

Hintergründe aus TSF und GAF#

Das Header-Widget unterstützt zwei Quellen für den Hintergrund:

• .tsf – die Textform einer Truecolor-Animation von TA:K, die der Oberflächenlader direkt liest. Für ein statisches Menü ist sie ein schlanker Träger für ein JPG (das Beispiel TitleScreen.tsf umhüllt TitleScreen.jpg), aber dasselbe Format beschreibt auch vollständige Animationen mit mehreren Frames. Den binären und den textuellen Aufbau, die kbot beide parst und im Round-Trip verarbeitet, beschreibt TAF / TSF.
• .gaf – die übliche Animation von TA: Kingdoms. Der Header verweist auf eine Sequenz im GAF; die Engine spielt sie als Hintergrund ab.

So oder so verlangt das Format, dass der Bildeintrag zweimal direkt hintereinander aufgeführt wird; nur die zweite Kopie wird tatsächlich gerendert. Das ist eine bekannte Eigenheit.

---

Stolperfallen#

• Leerraum hat über das Trennen von Tokens hinaus keine Bedeutung. Cavedogs ausgelieferte Dateien verwenden sowohl Leerzeichen als auch Tabs; behandle jede Folge von Leerraum als ein einziges Trennzeichen.
• Die Anzahl der Kinder muss exakt stimmen. Ein Rahmen-Widget (Typ 9), das mit 4 endet, beansprucht die nächsten vier Widgets der obersten Ebene als Kinder. Ist die Zahl falsch, zerfällt der Rest des Formulars.
• Listenfeld- und Bildlaufleisten-Widgets sind in den ausgelieferten Dateien im Grunde leere Vorlagen – die Engine füllt sie zur Laufzeit aus dem Skriptzustand. Es hat keinen Sinn, sie statisch zu befüllen.
• Der Kommandozeilenschalter -disablecavedogverification von TA:K ist nötig, um die meisten gemoddeten .gui-Dateien zu laden. Ohne ihn weist die Engine jede Datei ab, deren Hash nicht zu einer eingebetteten Liste passt.
• Manche Dateien stürzen entpackt ab, andere gepackt. Das Format selbst ist stabil; der Lader der Engine verhält sich zwischen den Schichten des virtuellen Dateisystems und dem direkten Verzeichniszugriff unterschiedlich. Teste beim Modding beide Zustände.

---

Siehe auch#

• TAF / TSF – die Truecolor-Animation und ihre Textform .tsf, auf die .gui-Header für Menühintergründe verweisen.
• GAF – auf .taf-Animationen mit Palette wird in .gui-Dateien durchgehend verwiesen.
• PCX – die Konvention der Palettenträger, die TA:K für .taf mit Palette verwendet.
• Die Notizen zu den Format-Herausforderungen von TA:K in den Quellmaterialien dieses Repos – praktische Stolperfallen beim Übertragen von TA-Assets nach TA:K.
• Glossar.