.gui de TA: Kingdoms (árboles de widgets separados por espacios)

TA: Kingdoms dibujaba su menú principal, el lobby, el HUD de la partida y los cuadros de diálogo a partir de archivos .gui, un formato peculiar de descripción de widgets separados por espacios en blanco. Aunque a simple vista se parece a los archivos de interfaz del propio TA (también .gui), el formato de TA:K es estructuralmente distinto y no son intercambiables.

---

Qué estás viendo#

Un archivo .gui es una secuencia plana de widgets. El widget de cabecera del archivo declara el número total de widgets y los metadatos globales (imagen de fondo, teclas rápidas); cada widget posterior describe un único elemento de la interfaz.

Un widget típico tiene este aspecto:

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

Los tokens van separados por espacios en blanco. El primer token de cada widget es el ID de tipo de widget; todo lo que sigue se ajusta a un esquema propio de cada tipo.

---

Cadenas con prefijo de longitud#

El truco más importante del formato: cada cadena va precedida de su longitud en caracteres como un token entero. Eso significa que las cadenas pueden contener espacios, pero el analizador tiene que leer primero la longitud.

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

Una cadena nula o vacía es 1 0 0 (prefijo, longitud cero, y el contenido vacío es «la cadena vacía»). Es muy fácil analizar mal los prefijos 1/0 repetidos si te limitas a dividir en tokens por los espacios y empezar a contar: tienes que leer de forma secuencial, en el orden de los widgets.

---

Tipos de widget#

IDs de tipo de widget observados:

Cada tipo tiene un esquema fijo para los tokens que siguen al ID de tipo. El esquema canónico, obtenido por ingeniería inversa por Dark Rain, se conserva en los materiales de origen que acompañan a este repositorio.

---

Forma genérica de 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]

Según el tipo de widget, varían el tamaño de [N] y la estructura del conjunto de cadenas; los esquemas de los materiales de origen documentan cada uno.

Códigos de alineación#

Dentro del conjunto de cadenas:

En un widget de un solo estado verás, por ejemplo, 2 0 6 Player; en un botón de 3 estados verás los tres estados concatenados, por ejemplo, 2 0 0 2 0 6 Player 2 3 6 Play2r 3.

---

Ejemplo desarrollado: el menú 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 arriba abajo:

• 2 1: widget de tipo 2 (cabecera), marca 1.
• 2 0 0 640 480 1 1 0 0: límites en el origen, 640×480, más los cuatro tokens de marcas.
• 3 255 255 255 255: entrada de color blanco opaco.
• 8 MainMenu 1 2: nombre de control «MainMenu» (8 caracteres), seguido de 1 2.
• Las dos entradas TitleScreen.tsf JPGTest son la imagen de fondo (dos referencias duplicadas: el motor quiere las dos).
• 2 0 24 #Enter#Play#Esc#Previous: asignaciones de teclas: Enter activa el control llamado «Play» y Esc activa «Previous».
• 6: el formulario contiene 6 widgets hijos, que siguen a continuación.

Fondos TSF frente a GAF#

El widget de cabecera admite dos fuentes de fondo:

• .tsf: la forma de texto de una animación truecolor de TA:K, que el cargador de la interfaz lee directamente. En un menú estático es un simple envoltorio de un JPG (el ejemplo TitleScreen.tsf envuelve TitleScreen.jpg), pero el mismo formato describe animaciones completas de varios fotogramas. Consulta TAF / TSF para ver la disposición binaria y la de texto; kbot analiza las dos y hace el viaje de ida y vuelta con ambas.
• .gaf: la animación estándar de TA: Kingdoms. La cabecera hace referencia a una secuencia dentro del GAF; el motor la reproduce como fondo.

En los dos casos, el formato exige que la entrada de imagen aparezca dos veces seguidas; solo se renderiza de verdad la segunda copia. Es una peculiaridad conocida.

---

Escollos#

• Los espacios en blanco solo importan como delimitadores de tokens. Los archivos que distribuyó Cavedog usan tanto espacios como tabuladores; trata cualquier secuencia de espacios en blanco como un único separador.
• Los números de hijos tienen que ser exactos. Un widget de marco (tipo 9) que termina en 4 reclama como hijos los cuatro widgets de nivel superior siguientes. Si te equivocas en el número, el resto del formulario se desbarata.
• Los widgets de cuadro de lista y de barra de desplazamiento son, en la práctica, plantillas vacías en los archivos distribuidos: el motor los rellena durante la ejecución a partir del estado del script. No tiene sentido intentar rellenarlos de forma estática.
• La opción de línea de comandos -disablecavedogverification de TA:K es necesaria para cargar la mayoría de los .gui modificados. Sin ella, el motor rechazará cualquier archivo cuyo hash no coincida con una lista incrustada.
• Algunos archivos se cuelgan desempaquetados y otros, empaquetados. El formato en sí es estable; el cargador del motor se comporta de forma distinta con las capas del sistema de archivos virtual y con el acceso directo a directorios. Cuando hagas mods, prueba los dos estados.

---

Véase también#

• TAF / TSF: la animación truecolor y su forma de texto .tsf, a la que hacen referencia las cabeceras .gui para los fondos de los menús.
• GAF: los archivos .gui hacen referencia continuamente a animaciones .taf con paleta.
• PCX: la convención de portador de paleta que usa TA:K para los .taf con paleta.
• Las notas sobre las dificultades del formato de TA:K que hay en los materiales de origen de este repositorio: escollos prácticos al portar recursos de TA a TA:K.
• Glosario.