.gui do TA: Kingdoms — árvores de widgets separados por espaços

O TA: Kingdoms desenhava o menu principal, o lobby, o HUD durante a partida e as caixas de diálogo a partir de ficheiros .gui, um formato peculiar de descrição de widgets separados por espaços em branco. Apesar da semelhança visual com os ficheiros de interface do próprio TA (também .gui), o formato do TA:K tem uma estrutura diferente e não é intercambiável.

---

O que está a ver#

Um ficheiro .gui é uma sequência plana de widgets. O widget de cabeçalho do ficheiro declara o número total de widgets e os metadados globais (imagem de fundo, teclas de atalho); cada widget seguinte descreve um único elemento da interface.

Um widget típico tem este aspeto:

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

Os tokens são separados por espaços em branco. O primeiro token de cada widget é o ID do tipo de widget; tudo o que vem a seguir obedece a um esquema próprio de cada tipo.

---

Cadeias com prefixo de comprimento#

O truque mais importante do formato: cada cadeia de caracteres é precedida do seu comprimento em caracteres, sob a forma de um token inteiro. Isto significa que as cadeias podem conter espaços, mas o analisador tem de ler primeiro o comprimento.

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

Uma cadeia nula/vazia é 1 0 0 (prefixo, comprimento zero, e o payload vazio é "a cadeia vazia"). Os prefixos 1/0 repetidos são muito fáceis de analisar mal se se limitar a dividir o texto em tokens pelos espaços e começar a contar: é preciso ler sequencialmente, pela ordem dos widgets.

---

Tipos de widgets#

IDs de tipos de widgets observados:

Cada tipo tem um esquema fixo para os tokens que vêm depois do ID do tipo. O esquema canónico, obtido por engenharia inversa por Dark Rain, está preservado nos materiais de origem que acompanham este repositório.

---

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

Para cada tipo de widget, o tamanho de [N] e a estrutura do conjunto de cadeias variam; os esquemas nos materiais de origem documentam cada um.

Códigos de alinhamento#

Dentro do conjunto de cadeias:

Num widget de um só estado vê-se, por exemplo, 2 0 6 Player; num botão de 3 estados veem-se os três estados concatenados, por exemplo 2 0 0 2 0 6 Player 2 3 6 Play2r 3.

---

Exemplo comentado — 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

Lendo de cima para baixo:

• 2 1 — widget do tipo 2 (cabeçalho), flag 1.
• 2 0 0 640 480 1 1 0 0 — limites na origem, 640×480, mais os quatro tokens de flags.
• 3 255 255 255 255 — entrada de cor branca opaca.
• 8 MainMenu 1 2 — nome de controlo "MainMenu" (8 caracteres), seguido de 1 2.
• As duas entradas TitleScreen.tsf JPGTest são a imagem de fundo (duas referências duplicadas: o motor quer as duas).
• 2 0 24 #Enter#Play#Esc#Previous — atalhos de teclado: Enter aciona o controlo chamado "Play", Esc aciona "Previous".
• 6 — o formulário contém 6 widgets filhos, que vêm logo a seguir.

Fundos TSF e GAF#

O widget de cabeçalho aceita duas fontes de fundo:

• .tsf — a forma de texto de uma animação truecolor do TA:K, que o carregador da interface lê diretamente. Num menu estático, é um simples invólucro de um JPG (o exemplo TitleScreen.tsf envolve TitleScreen.jpg), mas o mesmo formato descreve animações completas com vários fotogramas. Veja TAF / TSF para a disposição binária e a de texto, que o kbot analisa e reproduz em ida e volta.
• .gaf — a animação normal do TA: Kingdoms. O cabeçalho refere uma sequência dentro do GAF; o motor reprodu-la como fundo.

Em qualquer dos casos, o formato exige que a entrada da imagem apareça duas vezes seguidas; só a segunda cópia é de facto renderizada. É uma peculiaridade conhecida.

---

Armadilhas#

• O espaço em branco só serve para separar tokens. Os ficheiros distribuídos pela Cavedog usam espaços e tabulações; trate qualquer sequência de espaços em branco como um único separador.
• O número de filhos tem de ser exato. Um widget de moldura (tipo 9) que termine em 4 reclama como filhos os quatro widgets de nível superior seguintes. Se errar o número, o resto do formulário desfaz-se.
• Os widgets de caixa de lista e de barra de deslocamento são, no essencial, modelos vazios nos ficheiros distribuídos: o motor preenche-os durante a execução a partir do estado dos scripts. Não vale a pena tentar preenchê-los estaticamente.
• A flag de linha de comandos -disablecavedogverification do TA:K é obrigatória para carregar a maior parte dos ficheiros .gui modificados. Sem ela, o motor rejeita qualquer ficheiro cujo hash não corresponda a uma lista incorporada.
• Alguns ficheiros falham quando estão desempacotados, outros quando estão empacotados. O formato em si é estável; o carregador do motor comporta-se de forma diferente nas camadas do sistema de ficheiros virtual e no acesso direto às pastas. Quando criar mods, teste os dois casos.

---

Ver também#

• TAF / TSF — a animação truecolor e a sua forma de texto .tsf, que os cabeçalhos .gui referem para os fundos dos menus.
• GAF — as animações .taf com paleta são referidas por todo o lado nos ficheiros .gui.
• PCX — a convenção de transporte de paleta que o TA:K usa nos .taf com paleta.
• As notas sobre as dificuldades dos formatos do TA:K, nos materiais de origem deste repositório — armadilhas práticas ao portar recursos do TA para o TA:K.
• Glossário.