GUI Format (Panel Layout)

A .gui file describes one screen of the game’s interface: a panel rectangle and a flat list of controls with their tags, positions, borders, text and colours. The in-game HUD, the equipment screen, the main menu and the message boxes each have one.

GUI is built on GFF (Generic File Format), the engine’s labelled key/value tree. If you have not read the GFF page, start there.

This page documents what the shared panel loader reads, why the rest of the file reaches the engine only by name, and what a corpus census of every shipped .gui shows about which paths are structural. Evidence is drawn from Ghidra decompilation of swkotor.exe (K1 GOG build), cross-checked against every .gui in a full install.

At a Glance

Population. The files live in data/gui.bif, indexed by chitin.key, plus a handful in patch.erf. Most of the patch copies shadow resrefs that also exist in gui.bif (abilities, character, equip, inventory, mainmenu), and two appear nowhere else (mipc212x10, tooltip12x10). The type occurs in no module RIM, no lips archive and no texture pack.

Every count on this page is measured over that population, and the census at the end gives it as a denominator, so the numbers there are the finding rather than decoration.

A .gui restyles a panel the binary already knows about

It cannot describe a new one. This is the fact the rest of the page depends on, and the format’s name works against it. There is no generic GUI loader that reads a control list and builds an interface from it.

What the shared panel loader does is narrow. It reads the panel’s extent, colour, border and alpha, stores the CONTROLS list unparsed, and instantiates nothing from it. Every actual screen in the game is a hand-written C++ class with its controls declared as typed members at compile time. Each of those classes asks for the controls it wants one at a time, by literal tag string, and the lookup scans the stored list for an element whose TAG matches, then hands that element to the member’s own loader.

So the file supplies values to a structure the executable already fixed:

• Add a control with a new tag and nothing will ask for it. Nothing in the executable is waiting for that name, and nothing walks the list looking for work. Your control is read into memory, never matched, and never drawn.
• Rename a control and the panel loses it. The screen still asks for the old name, finds nothing, and carries on without it.
• You cannot change what kind of control something is. The kind was decided when the game was built. The file does not get a vote.
• What you can change is real and substantial. Move and resize controls, restyle borders and fills, swap fonts, colours, text and alignment, repoint images. That is exactly what interface mods do, and it works because none of it touches the structure.

Important

No two .gui files have the same read set, so counting how often a label appears tells you nothing about whether it is used Which labels get read depends entirely on which screen opened the file, and each screen asks only for the controls it knows by name. A label sitting in a file that its screen never asks for is untouched in that file, while the same label is load-bearing in another file opened by another screen.

So the census at the end of this page describes what artists wrote, not what the engine reads. The one table you can read as “the engine uses these” is the panel-level one below, because the shared loader takes those from every .gui whatever screen it belongs to.

Field Schema

Every label path any shipped file carries is tabulated at the end of this page. There is no schema to generate it from, so that table is a corpus census rather than a declaration.

Engine Audits & Decompilation

Read from CSWGuiPanel::StartLoadFromLayout at 0x0040a680, with the control lookup and the listbox dispatch traced separately.

(Provenance: traced, except ALIGNMENT’s bitfield split, which is marked inferred below. Corpus figures are measured over the population named above.)

What the shared panel loader reads

These are read for every file, before any panel class gets involved.

A small set of paths is carried by every file in the population: BORDER with its CORNER, EDGE, FILL, DIMENSION and FILLSTYLE; CONTROLS; CONTROLTYPE; EXTENT with its four members; Obj_Locked; and TAG.

Two rows above are observations rather than rules, where every other row gives a value a reader can rely on.

ALPHA has no established default. It holds 1.0 in every file that carries it, and debug in data/gui.bif is the one file that omits it. So a single shipped file exercises the case the table cannot answer, and 1.0 is what the files show rather than what an absent field resolves to.

BACKGROUND is a real label, and it is a flat resref rather than a struct. Where the panel’s BORDER sub-struct is absent, the loader reads BACKGROUND as a CResRef defaulting to the empty string and passes it straight in as the border’s fill image. Where BORDER is present it is never read at all, so this is strictly the fallback rather than a field consulted alongside a full border definition.

No shipped file takes that path. BACKGROUND appears nowhere in the census further down, which covers every .gui in the install. The branch is real and the data never reaches it, which is a different thing from a label that does not exist.

CONTROLTYPE decides nothing except in a listbox item template

After all that, the field has one job and it is a narrow one. The only place the value chooses anything is PROTOITEM, the template a listbox stamps out for each of its rows. Here the file really does pick the kind of control, because a listbox has any number of rows and the game cannot have named them all in advance.

Anything else silently produces nothing. 0 through 3, and 9 upward, make no control and no complaint. The template is left as it was, so a listbox with an unrecognised PROTOITEM type comes out empty rather than broken, and nothing tells you which of the two you are looking at.

Everywhere else the value does nothing. A SCROLLBAR goes into a slot whose kind was already decided, so there is nothing for the value to choose. The files agree: 9 shows up at CONTROLS[]/SCROLLBAR/CONTROLTYPE and nowhere else.

Across the corpus the attested values are 2 at the panel root, 4 through 8, 10 and 11 in the control list, 4 through 7 on PROTOITEM, and 9 on SCROLLBAR. 0, 1 and 3 occur nowhere.

Field results

ALIGNMENT

It packs two axes into one number rather than listing combinations. Every value in the files, 9, 10, 12, 17, 18, 20 and 34, splits into exactly one horizontal bit out of {1, 2, 4} plus exactly one vertical bit out of {8, 16, 32}, and the engine has separate horizontal-only and vertical-only setters beside the combined one.

The loader passes the whole number along untouched, so (provenance: inferred) the split comes from the shape of the values and those setters. Defaults vary by control: 0x12 on images, 9 on text.

TEXT/STRREF and TEXT/TEXT

They are alternatives, and no shipped control uses both. Both labels are populated across the install, which makes it look as though a writer must know which wins. Per control rather than per file: some TEXT structs carry a live STRREF, some a non-empty TEXT string, most neither, and none carries both. The precedence question is not merely undocumented, it is unexercised.

Populate one. A localized string goes in STRREF, a literal in TEXT. Setting both puts the file outside anything the game’s own data does.

ROTATE and ROTATESTYLE

ROTATE wins outright where it is present, and ROTATESTYLE is then never read at all. Where ROTATESTYLE is read, 0, 1, 2 and 3 mean 0, 90, 180 and 270 degrees, and anything else leaves the rotation wherever ROTATE defaulted. Every shipped file holds 0, so this comes from the code rather than the data.

ROTATE is in degrees, and the pairing is what proves it. The float is stored into the image’s angle with no unit conversion anywhere on the path, and ROTATESTYLE writes the same field using the literals 0.0, 90.0, 180.0 and 270.0. Those are unambiguously degrees and nothing scales between the two paths, so the shared destination settles the unit by construction rather than by the usual assumption about angles in a file format.

FLIPSTYLE and DRAWSTYLE

FLIPSTYLE is treated as bits whatever you write in it. The loader masks it into a four-bit slot of the image’s flag word, which is true of the code rather than of the values that ship. Shipped files hold 0.

DRAWSTYLE is read and passed along whole, with nothing masking or splitting it, and is 0 in every file.

Obj_ParentID, and the three labels beside it

Obj_ParentID really does wire controls together. The shared control loader reads it as an INT defaulting to -1, and where it is anything else it looks up another control in the same panel by numeric ID and attaches the two as parent and child. The -1 is an ordinary equality sentinel, compared as signed. Most files carry it.

Important

No reader can exist for Obj_Locked, Obj_Parent or Obj_Layer Search the whole executable and you find Obj_ParentID and not one of the other three. The engine’s GFF readers take a field name as a literal string, so a label appearing nowhere in the executable can never be asked for on any path. That is the strong form set out under the standard of evidence.

Obj_Locked is in every single file, and a field that universal looks important. It is what the toolset writes every time and what the engine has no name for.

What the files look like

The census at the end sounds sprawling and is not. The shape repeats, and most of its length is the same handful of sub-structs recurring under different slots.

Controls nest by named slot, never by list. A panel holds one flat CONTROLS list and no control holds a nested one. Two of the named slots are themselves control-shaped, carrying their own CONTROLTYPE, EXTENT, BORDER and TAG: PROTOITEM and SCROLLBAR. The rest, TEXT, HILIGHT, MOVETO, PROGRESS, THUMB, and PROTOITEM’s own SELECTED and HILIGHTSELECTED, carry no CONTROLTYPE and so are never a control in their own right.

Every CONTROLS element in every file has GFF struct_id 0, so the struct id carries no type information here. Contrast GIT, where it discriminates object kinds.

Value sets small enough to be enumerations rather than ranges:

Panel-level COLOR takes (-1, -1, -1) in some files, which has the shape of a sentinel and is recorded here as a value.

One file carries an empty CONTROLS list, which is why every CONTROLS[]/... path in the census sits one below the population total or lower.

Open questions

• Which of TEXT/STRREF and TEXT/TEXT wins when both are set. No shipped control populates both, so the precedence is unexercised by the corpus as well as untraced. On the reverse-engineering queue.
• Whether DRAWSTYLE is an enumeration or a bitfield. It is read and passed along whole with nothing masking or splitting it, and holds 0 in every file, so neither the code nor the data distinguishes the two readings.
• Whether EXTENT values are rescaled downstream. CSWGuiExtent::Load stores four plain integers and the stored value is a literal pixel count. What a later render stage does with them for the active resolution was not traced.
• ALIGNMENT’s bitfield split is inferred, from the shape of the attested values and the existence of separate per-axis setters, rather than traced through the loader.

Implemented Linter Rules (Rakata-Lint)

None yet. No rule currently reads this format.

Every label path

The complete set, so a reader does not have to infer it from the examples above. Measured across every .gui in data/gui.bif and in patch.erf, which is the population named at the top of this page.

The Files column is how many of those carry the path. One that appears in all of them is structural; one that appears in a single file is that screen’s own peculiarity. Telling those apart is most of what you need before writing a reader, and it is exactly what a list of examples cannot give you.