Rakata

Rakata is a clean-room Rust implementation of Knights of the Old Republic (KotOR) data formats and tooling: a workspace of crates for reading, writing and validating Odyssey Engine game data.

This manual documents the formats themselves, and how swkotor.exe reads them, separately from the Rust that implements them. The format knowledge is meant to stand on its own.

Requirements

• Rust Version: 1.88.0 or newer. The workspace resolves against that floor rather than around it, so a dependency needing more than it changes what cargo picks instead of quietly raising the real requirement.

Documentation Domains

Two: the Software API and the Format Specifications.

1. The Workspace (Code API)

If you are developing against Rakata and need the layout of types, functions and data structures, the Rustdocs are the reference. The crates are:

Libraries (crates/)

• rakata-core: Foundational primitives (ResRef, ResourceType, ResourceId) and core utilities (encoding, filesystem, detection).
• rakata-formats: Readers and writers for KotOR’s binary and text formats, including GFF, ERF, RIM, KEY/BIF, MDL/MDX, TPC and TGA.
• rakata-generics: Typed wrappers around the GFF-backed resources (UTC, UTI, UTW and the rest). from_gff / to_gff are honest projections that model only the enumerated fields; byte-exact preservation is the raw Gff tree’s job.
• rakata-extract: Tiered resource VFS (GameVfs) resolving mounted save, extra overrides, Override/, active module, then chitin/BIFs. The last three follow the engine’s traced order; the first two are the crate’s own. Plus composite module handling (.mod + _s.rim + _dlg.erf) and install-wide enumeration helpers.
• rakata-lint: Resource validation against engine-derived field schemas, catching crash-causing mod errors before they reach the game.
• rakata-save: Save game parsing and modification logic.
• rakata-install: Installation discovery. Reports candidates with what is needed to tell them apart, and never picks one. The only crate that touches OS-specific paths; nothing in core, formats or generics depends on it.
• rakata-patcher: Installing a loose-file mod and taking it back. Reads a payload as a folder or as the zip, 7z or rar it arrived in, works out what installing it would replace, and keeps a copy of each overwritten file beside a record naming them.
• rakata-ui: What the GUI tools share: colours named for what they mean, the controls somebody should recognise between tools, the two window shapes, and each tool’s log.
• rakata: Facade crate re-exporting the ecosystem.

Tools (tools/)

• rakata-modinstaller: Desktop GUI application for installing loose-file mods where the filesystem tells Override and override apart.
• rakata-saveeditor: Desktop GUI application for editing save games.
• vanilla-inspector: Corpus validation tool for testing format implementations against all vanilla game assets.

🔗 View Rakata Rustdocs

2. Format Specifications (This Wiki)

The formats/ manual is Rakata’s evidence log. It covers each format’s binary structure and what swkotor.exe does with it, with every engine claim carrying its own provenance.

• Archive Formats: the containers, BIF, KEY, ERF and RIM.
• GFF Structure: the labelled tree under most of KotOR’s data, and the blueprint types built on it (creatures, dialogues, triggers and the rest).
• 3D Models & Mesh: MDL/MDX structures and binary walkmeshes.
• Textures and Audio: TPC and DDS compression, MP3 and Miles Sound System wrappers.
• Text & Data Formats: talk tables (TLK), rule tables (2DA), and layout geometry (LYT, VIS).

The Goals & Roadmap covers where the project is heading, and Architecture covers how the workspace fits together.

Project Roadmap

This document outlines what we’re tinkering with in rakata and where the project is heading.

Note

For day-to-day progress, bug fixes, and specific technical tasks, check out the Codeberg Issues tracker instead.

The End Goal

There are two of these, and they sit at very different distances.

The near one: be the reference implementation. Plenty of tools can read KOTOR’s formats. What almost none of them tell you is what the engine actually does with a field your file leaves out, and that is the difference between a document you can read and one you can build from. Every format page here is written against swkotor.exe itself rather than against folklore, and we are working toward the point where somebody can implement a conforming reader and writer from the page alone, without ever opening our Rust. That one is close enough to be a plan rather than a wish.

The far one: an actual engine integration. It would be very cool to tie all these isolated pieces together into a real rendering pipeline - dropping a vanilla model into an active window and having it stream textures and background audio straight out of the game data. That is a pipedream and we are honest about it, but the closer the foundation gets to exact, the less mad it sounds.

How We Get There

Since this is a passion project, we try to match the original game behavior down to the exact byte before building higher-level abstractions on top of it. It takes a bit longer, but it keeps us from having to constantly rewrite core parsers when we stumble into weird edge cases.

1. Laying the Foundation (Mostly Done)

Our core libraries (rakata-formats, rakata-save, etc.) can currently read, write, and safely roundtrip 19 different KOTOR file formats. We’ve tackled a lot of the weird legacy archives (BIF), models (MDL/MDX), raw textures (TPC), and the binary walkmeshes behind WOK, DWK and PWK, ensuring they line up with vanilla behavior.

However, the foundation is still growing! We still have a handful of outstanding data formats to map out and implement, including Pathfinding (PTH), UI Layouts (GUI), and Journals (JRL).

Additionally, formatting and bytecode support for NCS (Compiled Scripts) is actively being prioritized (see Issue #19) to allow rakata to interface natively with upcoming Rust-based community compilers and decompilers.

2. Writing It All Down (Also Active)

The formats/ manual isn’t a side effect of the code, it’s a deliverable in its own right. Every page is written from Ghidra work against the real executable, and every claim is meant to trace back to either a decompilation finding or a measurement across the vanilla corpus.

The part nothing else has is absent-field behaviour: for each field, what value the engine is actually holding when a file doesn’t carry it. That matters more than it sounds. An absent TrapType resolves to 0xFF, meaning no trap at all - read it as 0 and you have just named a real row in traps.2da. An encounter missing its Geometry field loads perfectly well, while one carrying an empty Geometry field gets refused outright. That isn’t trivia, it’s the difference between a mod that works and one that dies on load.

What’s missing, because a roadmap that only lists wins isn’t much use: compiled scripts (.ncs) have no page at all, and they are the most cross-referenced format in the whole manual, since nearly every blueprint points at one. Until Issue #19 lands, every other page carries a reference into a hole. PTH, GUI and JRL are smaller gaps. And a fair chunk of binary layout detail still lives in Rust source comments rather than on the pages where a reader would go looking for it, which we are partway through moving out.

3. Building Real Tools (Our Active Focus)

Now that we can parse the data reliably, we are building stuff the community can actually use:

• Mod Linter: A tool to scan modded files and point out if they break the game’s actual data constraints, catching crashes before you load them in-game.
• Save Editor: A basic offline save editor (rakata-saveeditor) built directly on top of our stable format parsers.
• Audio Streaming: Updating the generic audio logic (rakata-audio) so we can natively stream game music and voice lines instead of loading giant buffers into memory.
• Drop-in Replacements: Providing modern, reliable drop-in replacements for legendary (but aging) community tools. By backing these with rakata’s strict parsing rules, we can offer faster, safer, cross-platform native tools for unpacking archives, compiling models, and building mods. (Note: While we aim to replace these tools, we will not inherit their legacy bugs or non-vanilla API quirks. When in doubt, the original game engine is our only source of truth).

4. KOTOR 2 (TSL) Support

We are strictly focusing on KOTOR 1 right now, but extending parsing support for TSL via compatibility flags is a planned enhancement for further down the line once K1 is completely stabilized.

5. The Runtime Engine (The dream but probably a few years away)

Once our standalone tools prove that our format parsers are perfectly stable, we have a pipedream to one day start weaving them together into a natively synchronized rendering loop.

Architecture Guide

This document outlines how the rakata workspace is structured and the design principles we try to stick to.

Core Principles

1. Vanilla K1 First

   • By default, we target the original vanilla behavior of KotOR 1.
   • Compatibility for TSL or community tools is strictly opt-in behind feature flags, not the default assumption.
   • When deciding how to parse something, the original game engine is our ultimate source of truth. We use local fixtures and original game data to prove our parsers work, rather than just copying how older community tools did things.

2. Aim for Lossless

   • We want to be able to read a file and write it back out to the exact same bytes. We’ve largely achieved this for standard archives and data formats (GFF, ERF, RIM, KEY, TLK, etc.).
   • For highly complex formats (like MDL/MDX models), there are some known divergences where achieving a byte-exact roundtrip is essentially impossible due to how the original compilers ordered geometry blocks. We track these exceptions, but the output still safely runs in-game.
   • No Lazy Pass-throughs: undocumented fields don’t get read as an opaque Vec<u8> and passed through. The goal is to map every struct boundary properly.
   • Reserved fields are the exception: where the binary layout defines a reserved field whose meaning we haven’t cracked, we map it as a correctly-sized reserved value rather than dropping data the engine might rely on. Explicit blank padding isn’t stored at all; it’s recalculated on write.
   • Layer scope: this lossless guarantee applies to the byte-level format layer (rakata-formats). Typed views in rakata-generics (Utc, Uti, Are, …) are explicitly honest projections that model only the fields they enumerate; byte-exact preservation stays with the raw Gff tree. See Typed Views and Raw GFF below for the full rule.

3. Strict Text Handling

   • All text decoding goes through rakata-core::text.
   • Localized text (TLK entries, strings) uses language-aware encodings (Windows-1252, Shift-JIS, etc.) to match what the engine expects.
   • Binary strings (like node names or texture paths) use TextEncoding::Windows1252 since that’s what the engine actually uses under the hood. No silently stripping weird characters with lossless backups.

(For day-to-day coding rules around iterators, zero-cost abstractions, and memory safety, see the Idiomatic Rust section in the contributing.md guide!)

Workspace Boundaries

Note: this layout is a moving target. rakata-audio is planned and does not exist yet, and the tools are at very different stages, so expect these crates to fill out and new siblings to appear as the roadmap goals land.

The workspace is organized in a clean dependency chain. Crates can only depend on crates listed “above” them:

rakata-core          (no workspace deps)
  rakata-formats     (depends on: core)
    rakata-extract   (depends on: core, formats)
    rakata-generics  (depends on: core, formats)
    rakata-lint      (depends on: core, formats, extract, generics)
    rakata-patcher   (depends on: core, formats, extract)
    rakata-save      (depends on: core, formats)
  rakata-install     (depends on: core)
rakata               (facade: re-exports all library crates)

rakata-ui            (no workspace deps; the GUI tools only)

  rakata-audio       (planned, not yet created)

Library Crates (crates/)

• rakata-core: The absolute basics (ResRef, IDs) and core utilities like file streams and text encoding.
• rakata-formats: Our massive library of parsers and writers (GFF, ERF, BIF, MDL, TPC, etc.). This parses bytes into objects, but doesn’t know anything about how the game actually uses them.
• rakata-audio (planned): Audio streaming and decoding for the engine’s various sound formats (WAV, ADPCM, MP3). Not yet created; WAV reading currently lives in rakata-formats.
• rakata-formats-derive: The proc macro behind #[derive(GffModel)]. Only rakata-formats depends on it, but it is where a field’s declaration is turned into a reader, a writer and a schema entry at once, and where several contracts are enforced as build errors rather than as tests.
• rakata-generics: Strongly-typed Rust models for all the different GFF files (like Doors, Items, Characters).
• rakata-extract: The logic for hunting down actual game files in the wild. It knows how to look inside ERFs, check the Override folder, and resolve files just like the engine does.
• rakata-lint: Our rule engine for scanning modded files and checking them against vanilla schema constraints.
• rakata-save: High-level logic for safely reading, editing, and backing up save files.
• rakata-install: Finds the game on this machine. It reports every copy it can see rather than picking one, because anybody who mods has several. The only crate that knows what operating system it is on.
• rakata-patcher: Installing a loose-file mod and taking it back. It reads a payload as a folder or as the archive it downloaded as, works out what installing it would replace, and keeps a copy of every file it overwrites beside a record naming them.
• rakata-ui: What the GUI tools share. Colours named for what they mean, the controls somebody should recognise between tools, the two window shapes, and the log each tool writes.
• rakata: A handy facade crate that re-exports everything so you only need to add one dependency.

Tool Crates (tools/)

• rakata-modinstaller: The desktop application for installing loose-file mods where the filesystem tells Override and override apart.
• rakata-saveeditor: The actual desktop application for editing save files.
• vanilla-inspector: A testing utility for validating our parsers against the actual mass of game files.

Format API Guidelines

Public API Shape

Every format parser in rakata-formats generally provides the same clean interface:

• read_<fmt><R: Read>(reader: &mut R) -> Result<T, E>
• read_<fmt>_from_bytes(bytes: &[u8]) -> Result<T, E>
• write_<fmt><W: Write>(writer: &mut W, data: &T) -> Result<(), E>
• write_<fmt>_to_vec(data: &T) -> Result<Vec<u8>, E>

Formats with multiple output modes (like exporting models to ASCII text or JSON) just use variations of these names (read_mdl_ascii()).

• Generic Traits: We strongly prefer accepting generic I/O trait bounds (Read, BufRead, Write, Seek) over concrete types. Accept the narrowest trait that covers your API’s needs so callers aren’t forced to jump through hoops.

Error Handling

Robust parsing means strict error boundaries:

• Each format module must define its own domain-specific error enum (e.g., GffError, ErfError) using the thiserror crate. Do not use generic stringly-typed errors or Box<dyn Error>.
• Low-level read failures (like sudden bounds exhaustion or bad magic numbers) should wrap our shared BinaryLayoutError.
• Never unwrap() at an API boundary! Only fail explicitly via Result or use .expect() with a hardcoded rationale if it is impossible to fail.

Memory & Ownership

While we try to avoid deep cloning and heavy allocations behind the scenes, we default to owned data types when crossing public API boundaries. Unless a module is explicitly built and documented as a zero-copy “View” type, you should avoid passing nasty lifetimes into the caller’s lap.

Keeping Concerns Separated

• Dumb Parsers: Format modules in rakata-formats are intentionally “dumb”. They solely translate between raw byte streams and Rust structs without any awareness of game architecture, filesystems, or what a “module” is.
• Smart Extractors: The environment logic lives in rakata-extract: finding loose files, enforcing precedence (checking Override/ before extracting from a BIF), and assembling composite files. That separation is why the parsers work on an isolated test fixture and on a live install alike.

How 2DA Tables Reach a Decoded View

Decoded views resolve file-native values against 2DA tables, so something has to hand them a table. resolve() takes &mut impl TwoDaSource, and the three concerns that twoda_cache.rs once fused into one file live in three crates:

Generics needs identity and capability, not implementation, so rakata-extract appears nowhere in the generics manifest, neither in [dependencies] nor [dev-dependencies]. Tests spanning both crates live in the rakata facade.

TwoDaSource::twoda returns Option<&TwoDa> rather than a Result, because every consumer discarded the error. A caller that needs to tell “no such table” from “the bytes would not parse” asks the cache directly through its inherent method, which still carries the full TwoDaCacheError.

rakata-lint also depends on rakata-extract, and that is not the same call. Lint is a leaf, so a concrete dependency propagates to nobody. Generics is foundational, so its dependencies reach everything above it. Weigh this by where a crate sits in the graph rather than by whether the edge looks tidy on its own.

Tracing & Telemetry

We strongly encourage instrumenting format parsers with tracing::instrument spans to help pinpoint exactly where a badly formed file breaks during a parse. However, this telemetry must remain entirely zero-cost for consumers who don’t need it! We achieve this by wrapping public parser entry points in conditional attributes: #[cfg_attr(feature = "tracing", tracing::instrument(...))]. If a user doesn’t explicitly opt-in via their Cargo.toml, the Rust compiler strips the instrumentation entirely.

Serialization (Serde)

Just like tracing, serde support for exporting our parsed files to JSON or YAML must be treated as a zero-cost, opt-in feature. Format structs and types should generously derive Serialize and Deserialize when the serde feature flag is enabled. This allows downstream utilities (like the Save Editor) to effortlessly convert memory layouts into text formats, while ensuring the core parsers stay extremely light for purely binary-focused applications.

Beyond Basic Parsing

While rakata-formats gives us the ability to parse isolated bytes, the game engine is much more complicated. Our higher-level crates exist to bridge that gap between “dumb bytes” and “actual game logic”.

Finding Files (rakata-extract)

rakata-extract handles the messy reality of finding files scattered across a massive KOTOR installation. It mirrors the vanilla engine’s lookup hierarchy in three distinct layers:

1. Primitives: Grabbing a file out of a single archive (like unpacking a standalone ERF or BIF file).
2. Composition: Treating related archive sets as a single “Module” (like grouping a .mod file with its matching _s.rim and _dlg.erf files so they load transparently together).
3. Game-wide: A GameVfs rooted at one install that owns each tier (chitin / BIFs, the Override/ directory, caller-pushed extra overrides, the single active CompositeModule, and a mounted save above all of them) and resolves resrefs through them in engine precedence order. See Resource System & Resolution for the full tier order and what the save tier does and does not shadow.

Because we want our extraction to perfectly mirror vanilla behavior, lookups are strictly case-insensitive, and loading precedence is explicitly designed to mirror how the original game works (so a file in the Override folder automatically beats a file buried in a BIF archive).

Strongly-Typed Data (rakata-generics)

When we parse a .utc Character file, rakata-formats just hands us a raw GFF tree of untyped labels and values. rakata-generics wraps those raw data blobs in strongly-typed Rust structs (Utc, Uti, Are, Git, Dlg, Ifo, and friends). This guarantees that if a developer needs to access a character’s “Strength” stat, they get a guaranteed u8 property rather than blindly guessing string handles inside a raw binary tree.

Typed Views and Raw GFF

These typed structs sit beside the raw Gff tree, not on top of it. They are projections, not replacements. You construct one with Uti::from_gff(&gff) and round-trip back with uti.to_gff(); the original Gff stays accessible the whole time.

The projection layer follows one load-bearing rule: model what’s enumerated; drop what isn’t. from_gff extracts the fields each typed view documents and silently ignores anything else; to_gff writes only those documented fields. There is intentionally no extra_fields: Vec<GffField> accumulator on Utc / Uti / Are / etc. that would round-trip unmodelled fields through the typed layer.

The reason is correctness. Unmodelled fields often depend semantically on neighbouring fields (a savegame’s animation state only makes sense at the exact moment of save; a toolset’s custom annotations describe a specific revision). If the typed view silently preserved them while a caller edited a modelled field, the output would be internally inconsistent. The staleness contract is real, but it belongs explicitly with whoever needs byte-exact preservation, not buried inside a layer whose only job is type-safe access to known fields.

This splits by what a caller is doing to the file, which is not the same question as what kind of tool it is:

• Reading it, to inspect or report. A linter or an inspector wants the typed view: type-safe access to known fields, and unmodelled bytes are nobody’s concern because nothing goes back to disk.
• Authoring a new file. The typed view again, and reconstruction is correct here because there is no original to lose.
• Editing a file that already exists. The raw Gff and its path API, never the typed view. A projection written back drops every field it does not model, and in a savegame that is most of them: another area’s object state, a mod’s own labels, anything unaudited. Nothing warns you, because a dropped field and a field the file never had look identical on the way out.

The verb decides it, not the program. A save editor reads through a typed view and edits through the tree, and it is the same save editor doing both. Any tool preserving toolset annotations or auditing round trips is in the third case for the same reason.

What gets enumerated: the engine has to read it

“Model what’s enumerated” only helps once you know what earns a place in the enumeration. The criterion is narrow on purpose:

A typed view models a field if and only if the engine reads it at that GFF path.

A field the engine never reads is a dead field. It gets recorded as dead where a reader will meet it, with the evidence, and it gets diagnosed by a Phase 1 lint rule walking the raw Gff. It does not go in the typed view. That is not a hole in the projection. crates/rakata-lint/ARCHITECTURE.md’s first design principle already puts schema and intra-resource checks on the raw tree for exactly this reason: they exist to validate the fields typed views drop.

Four clarifications carry most of the weight.

“At that path” is the whole test. A door blueprint’s Tag is read; the Tag on a door placement in a GIT is not, because the engine takes a templated door’s tag from the blueprint. Same label, same concept, one live copy and one dead one. A concept being live somewhere else says nothing about this copy.

Prevalence is not a criterion, and neither is carrying a real value. WaypointList[].TemplateResRef appears in every waypoint in a retail install and no load path reads it. The counts mislead in every direction, and all three have happened:

The corpus tells you where to look, never what to model.

“The blueprint wins” is not the rule, and assuming it gets half the cases backwards. The canonical dead field is a placement’s copy losing to the blueprint’s, and there is a family running the other way. A door’s Tag is read only on the blueprint, so the placement’s copy is dead. A door’s TransitionDestin and its LinkedTo siblings are read on the blueprint and then overlaid from the placement immediately afterward, so it is the blueprint’s copy that is dead. Triggers repeat both halves.

Same engine, same load, adjacent fields, opposite winner. What decides it is whether an overlay step exists for that field, not which struct the read was handed. So the question to ask of a new field is “does anything write over this after the read”, and a finding reporting only which struct a value came from has not answered it.

“Path” means the GFF path, not a decode-time variant. The rule stops at the structural position and does not reach inside a decoded enum. PropertyList[].Subtype is read at its path, so it is modelled, even though which property kinds actually consume it varies.

Ask whether there is any configuration in which the engine reads this label at this structural position. For Subtype, yes. For WaypointList[].TemplateResRef, never.

The point of the lint rule is that a dead field is a modder trap: someone sets it, expects an effect, and gets nothing. Silence is the worst answer, and the typed view is the wrong place to break that silence.

Ifo.Mod_Hak, Utc.SaveWill and Utc.SaveFortitude are modelled and documented dead. They predate this rule and round-trip harmlessly, so they stay. Treat them as legacy exceptions rather than precedent; the next field’s case has to stand on the criterion above rather than on their existence.

When in doubt: if you need byte-exact preservation across a parse-then-write cycle, work with the raw Gff. If you need ergonomic, type-safe access to the fields Rakata has audited, work with the typed view.

Decoded Views: Removed, Pending a Consumer

A second layer used to sit on top of the typed structs. A decoded view resolved file-native ids against the 2DA tables the engine consults, so a caller could ask a creature for its race label rather than its race id. It covered UTI and UTC, and it has been removed.

Nothing irreplaceable went with it. A decoded view resolved through ContentSource at run time, so the interpretation lived in the game’s own tables rather than in our source; rebuilding it re-derives from data we still read. What made it worth removing is that it was built against an architecture we have since replaced, it reached two of the fourteen typed views, and no consumer ever stated what it needed. It returns once one can, which is after MountedSave and the write path.

Two things the rebuild inherits rather than re-deciding:

• Projection and resolution are separate stages. File-native variant dispatch is scope-free and runs once; resolving against a context runs per scope. Mod-conflict analysis, vanilla-versus-modded diffs, and “read this the way a mounted save sees it” all reduce to one projection resolved several ways.
• A mod-extensible table needs an Unknown variant. Mods add rows to itempropdef.2da, so a decode that cannot name a kind has to surface the raw entry instead of dropping it. Per entry, rather than a struct-level accumulator.

ContentSource, NoSource and InstallContent stay put for it.

High-Level Interaction (rakata-save & rakata-lint)

Finally, crates at the top of the stack use our extraction logic and strongly typed generic structs to actually do things. rakata-lint compares typed structs against vanilla constraints to catch modding errors, while rakata-save gracefully handles unpacking, editing, and re-compressing massive save-game directories without corrupting the player’s campaign!

Contributing

Welcome to the Rakata workspace! This guide outlines how we build, how we test, and the core rules for keeping our code clean, compliant, and maintainable.

License policy

• License: All workspace crates use GPL-3.0-or-later.
• Third-Party Components: New dependencies must be compatible (MIT, Apache-2.0, BSD). Add them to THIRD_PARTY_NOTICES.md before merge.

Clean room implementation

To ensure everything we build is 100% our own original work and we aren’t accidentally borrowing from other community tools (if you’re curious about why we’re so strict about this, check out docs/src/legal.md):

1. Reference Policy: Treat existing tools (like PyKotor) as behavioral references, not copy sources.
2. No Copy-Paste: Do not copy source code blocks, large comments, or docstrings from third-party sources into Rust files.
3. Re-Derivation: Derive implementation logic from format documentation, observed behavior (hex dumps), and black-box fixture analysis.
4. Reverse Engineering:
   • Behavior verification via disassembly tools (e.g., Ghidra) is allowed for interoperability analysis.
   • Do not copy decompiled code into source files.
   • Record findings as paraphrased behavior notes natively within the relevant format specification under docs/src/formats/.

What belongs in the engine audits

The entire Rakata format specifications manual (docs/src/formats/) serves as the engine audit layer between reverse engineering and implementation. All Rust code is written strictly from these engine audits (specifically the Engine Audits & Decompilation sections embedded in each format’s blueprint), not from raw decompilation output.

• Record: Field names, data types, default values, error conditions, and observable behavioural rules (e.g., “field X is clamped to 0-100”, “list is sorted ascending by field Y”).
• Do not record: Step-by-step algorithmic sequences, control flow structure, or implementation details that go beyond what is needed for interoperability. The test is: could someone implement correct behavior from this note without it dictating a specific code structure?

Format work versus engine reimplementation

Right now this workspace is only about format parsing, linting and modding tools: reading, writing and validating the game’s data files.

An engine replacement, with gameplay logic, AI and rendering, is a job for another day. That is part of why the format blueprints matter: somebody building an engine later can work from the engine audits rather than digging through decompiled binaries themselves.

Code style and linting

Pre-commit hooks

We use pre-commit to keep the codebase consistently formatted without anyone having to manually police it. After cloning the repository, it’s highly recommended to set up the hooks:

pre-commit install
pre-commit install --hook-type pre-push

This registers two quick automated stages:

• pre-commit: Formats your code via cargo fmt --all (auto-fixing it for you) and runs cargo clippy across all targets.
• pre-push: Runs cargo test --workspace --all-features to ensure tests are green before you push.

Try to avoid skipping hooks using --no-verify. If a hook catches something, it’s usually just a helpful clippy suggestion or a quick formatting tweak!

Manual checks

If you prefer running things manually from the workspace root before committing:

cargo fmt --all
cargo clippy --workspace --all-targets --all-features
cargo test --workspace --all-features

Note: Passing --all-features to clippy and test is important so it catches optional code paths like serde and tracing! We just ask that fmt and clippy run cleanly before you open a Pull Request.

Idiomatic Rust

A few principles the codebase leans on:

• Safe Numeric Casts: To prevent silent truncation bugs, we enforce #![warn(clippy::as_conversions)]. Avoid the raw as keyword; lean on From, TryFrom, or .into(). If an unsafe cast is truly unavoidable (like an f32 down to an i32), use a scoped #[allow(clippy::as_conversions)] and drop an inline comment explaining why it’s safe.
• No Primitive Obsession: We heavily utilize strongly-typed wrappers (like ResRef) rather than passing raw [u8; 16] or String primitives around.
• Strict Error Handling: We explicitly forbid .unwrap() and .unwrap_unchecked() in library code. Everything must propagate cleanly via Result using typed error enums (managed via thiserror).
• Composition over Hierarchy: We prefer flat structs and trait combinators over deep class hierarchies.
• Honest Projections in Typed Views: Typed views over GFF in rakata-generics (Utc, Uti, Are, Git, Dlg, Ifo, Utd, Ute, Utm, Utp, Uts, Utt, Utw) model only the fields they enumerate. from_gff silently drops unmodelled fields and to_gff writes only the modelled ones. Do not add an extra_fields accumulator on the struct; callers that need byte-exact preservation work with the raw Gff tree directly. See Typed Views and Raw GFF for the rationale.
• Iterators over Loops: We prefer functional iterator chains (map, filter, fold) over maintaining manual mutable state in for loops.
• Zero-cost Features: Optional functionality (like serde serialization or tracing telemetry) must introduce no overhead when disabled.
• Safe by Default: We use #![forbid(unsafe_code)] across all core parser crates to enforce strict memory safety boundaries.

Testing

Tests here are gray box: white-box knowledge of the engine, taken from the audits under formats/, drives strictly-validated black-box cases. See Testing for what to include with a new format, and for the ways a passing test can fail to check anything.

The reserved field rule

Game engines are weird, and sometimes they leave mysterious “padding” or “reserved” sections in their binary formats. Every struct field that corresponds to a reserved region must be:

• Stored strictly as a named array (e.g., reserved: [u8; N]) in the format struct.
• Read directly from the source bytes verbatim.
• Written back verbatim during a roundtrip.

If a writer zeroes out or silently drops a reserved field you parsed, we consider that a “lossless bug”, even where the engine appears not to use those bytes. If you’re constructing a brand new file from scratch, you can safely write zeroes for reserved regions, but the struct must be capable of storing exactly what it read off disk.

Release process

(TODO: We haven’t cut an official production release yet. Right now we are building out the rakata-lint engine rules and expanding format coverage. Once we officially stabilize v0.3.0 to crates.io, we’ll formalize our exact release checklist, dependency license refreshes, and CI pipelines here.)

Testing

How this workspace tests its parsers, and the habits that make a passing test worth something.

A test here has one job: prove that what we wrote matches what the engine does. Most of the ways a test fails at that job still look like success, so the practices below are mostly about arranging for a check to be capable of failing before you rely on it passing.

Strategy

We use a gray-box approach. White-box knowledge of the engine, gathered from the audits under formats/, is used to build strictly-validated black-box tests. Tests target how the engine actually behaves, not a mock of it.

When you add a new format, include:

• Fixture-backed tests. Full round-trip coverage over synthetic files in fixtures/. Never commit real game assets; run cargo test --test gen_fixtures -- --ignored to generate them. Byte-exact round-trip assertions are the bar for any format the engine reads byte for byte.
• Mutation tests. A pass confirming the parser rejects malformed and truncated input without panicking, usually through corruption_matrix.rs.
• Module documentation. A rustdoc block showing the format layout.

Reference a fixture with concat!(env!("CARGO_MANIFEST_DIR"), "/../../fixtures/name.ext") rather than a path relative to the source file, so moving the file does not break it.

Writing a check

Make it prove it arrived

Assert on what the check examined, not only on what it found. Count the subjects it compared and assert the count is not zero.

This is the single highest-value habit on the page, because the default failure of a check is silence rather than noise. cargo test <filter> prints test result: ok when the filter matches no tests at all, which is why scripts/test-filter.sh exists and fails when a filter matches nothing.

The same shape recurs at every level. A value comparison walked one side’s fields and skipped any label the other side lacked, so renaming a field on both sides passed. A test for diagnostic grouping hit a type-mismatch rule first and returned before reaching the grouping. Schema checks recurse only where an entry declares child fields, so anything below a childless entry was never visited; three separate checks did this independently, and descending by default is what stops the fourth.

Count what the check compared, not what it visited. Those are different numbers, and the gap between them is where this hides.

Take the input from somewhere the subject does not control

If the thing under test also supplies the test’s input, whatever is missing from the subject is missing from the input that would reveal it. Adding more cases cannot break that loop.

A check that a view writes no label its schema fails to declare built its input from that same schema. A saved object writes either a Portrait resref or a PortraitId row index, and Portrait was declared nowhere. No Portrait was generated, so the read always took the id branch, so the missing declaration was never written, so the check never saw it.

The weaker version of this is a generated fixture. A generated fixture exercises only what its generator produced. Child fields it does not build, lists it leaves empty, and branches it does not select are all outside reach, and none of them look like gaps from inside the test:

• A check written to catch skipped levels built its input with Default::default(), whose lists are empty, so it stopped above every level it existed to cover.
• A coverage check on Git built its input from the schema, which filled UseTemplates with an arbitrary non-zero value. That flag selects between two forms of the file, so every run took the same branch and the Saved* types were never called.

That last one deserves care, because it leaves no trace. Nothing is missing, nothing is empty, and the walk completes normally. It goes one way at a fork and the other way is invisible.

Compare in a vocabulary the code under test did not choose

Two things have to be made comparable before a check can compare them. When the code under test is what makes them comparable, the check inherits its blind spot exactly.

A typed view models a field only where the engine reads it at that path, which is right for reading and wrong for writing anything back. A round-trip guard read a file into a view, wrote it out, and compared the two views. Every field it compared agreed, because every field the view does not model was missing from both sides. A writer that lost a save’s entire session state would have passed.

The tell is that the check never leaves the model. “Read a Uti, write a Uti, compare the Utis” is a closed loop, and no fact from outside can get in to fail it. That is visible while you are writing it, which is what separates this from a check that turns out afterwards to have been looking at the wrong thing.

Here the outside vocabulary is the file’s own bytes: read a real file, write the parsed tree back, compare against what was read. One such check runs over a single saved area carrying labels no view models, another over every GFF the install ships.

Break it on purpose before you trust it

Reintroduce the defect, run the check, and confirm the assertion you expected is the one that fails. Most of the problems on this page were caught this way and by nothing else. A test you have never seen fail has not yet earned anything.

Break each half of a compound check separately. A grouping keyed on both a field’s path and its reason had to fail differently for each half, which is what made the key defensible rather than merely plausible.

Two specific shapes need more than one break:

• A fallback with several preconditions needs a case that removes all of them. A portrait falls back only when Portrait and PortraitId are both missing, so dropping either one left the other in the file and the read took a branch rather than its fallback. List the reachable states before trusting a probe that varies one input.
• If a check runs over several subjects, breaking one subject must fail it. A fix that declared a label on four types and asserted both branches were produced was satisfied by any one of them, so reverting a single declaration left three siblings covering for it.

Choosing your evidence

Prefer real files, and know what yours cannot show

Real game files are the only source nobody on this project wrote, which makes them the only source that can disagree with us.

The minigame types read their enemy and obstacle lists off the wrong parent. The reader had it wrong, the module diagram in are.rs had it wrong, and the round-trip test had it wrong, because one person wrote all three from one reading of the format. Three sources agreeing was one mistake stored three times, and every enemy and obstacle in the game parsed as absent for as long as the type existed: 95 enemies and 67 obstacles across the four minigame areas.

A corpus still has to be large enough to tell two explanations apart. A waypoint reader keyed its map note off the note text and derived the HasMapNote flag back from it, defended by a comment observing that the two never disagree across the fixture saves. They do not disagree, and that is not what the fixtures showed: across a larger local corpus the flag is present on every waypoint while the text is present on a minority. What looked like two fields tracking each other was one field always being written.

A corpus too small to hold a counter-example cannot tell a relationship from a constant, and the reading that assumes a relationship is the one that then justifies ignoring a field.

Know which populations no corpus can reach

Ranking work by how often a fallback fires in the corpus puts saved forms last, because their fallbacks never fire: the engine’s saver writes saved objects exhaustively, so every field is present on every saved entry.

So the population with no corpus evidence is exactly the one where documentation is the only oracle that will ever exist, and a firing-rate ranking sends it to the back of the queue. A fallback no corpus can reach is not low priority, it is unfalsifiable by measurement, and it needs the reading rather than less of it.

When a check built on documentation disagrees with the code, the documentation decides

Unless you can say from the documentation why it is wrong. Settling it the other way turns the check into a comparison between the code and itself.

A schema entry’s absent-value records what the engine holds for a field a file omits, populated from the audit pages under docs/src/formats/. A check compared each reader’s fallback against it, and that check is worth more than a round-trip precisely because its two sides come from different places and can disagree.

Utd’s Invulnerable fell back to the file’s Plot value, and the schema entry was changed to match on the reasoning that the reader looked right. It was not: the engine reads Invulnerable before Plot, so its fallback sees the constructor’s zero and never the file’s value, which is what the page says. Every disagreement settled that way turns one more entry into a copy of the reader.

Counting and measuring

Ask what the population can exhibit

A count can be wrong while its arithmetic is right, because the error is in the population. Three counts in one audit each needed a whole category subtracted after the fact:

The shared cause: the inflating members were structurally unable to exhibit the property being counted. You cannot agree without an opinion, cannot be unconditional if you are conditional, cannot constrain a merge if you never write. In each case the measure looked at the label while the property lived at the label and its context.

The third was predicted from the first two before it was found, which is what makes this a pattern to apply rather than three anecdotes. It is three-for-three rather than a law, so check the fourth.

Recompute derived properties after you subset

The same error runs the other way. Having crossed those divergences against the write set, the survivors were reported with the axis each had been classified under before the crossing. Two changed: OnHeartbeat and OnUserDefined diverged on liveness only because of a mount that declares them and never writes them, so removing non-writers left them diverging on default alone.

Membership changed, so every property derived from membership changed with it. One version of this error is a property held by members that cannot exhibit it; this is a property computed on a population that no longer exists.

Spot-check a probe, and say which way it errs

Two probes written for those counts had a predicate that did not match the property. One used “is this path present when the view is default-constructed” as a proxy for “is this field written unconditionally”. It returned 31 against a true 83, because a list child is absent at default when the list is empty, not when the write is conditional. The other missed the multi-line form of a helper whose label is its second string argument, so it under-counted writers.

Both were caught by checking a handful of cases the author already knew the answer to. Neither would have been caught by reading the code again.

Note the direction as well as the size. Under-counting writers removes real constraints, so that probe failed toward “safe to share”, the direction that produces a bad merge rather than a noisy report. A probe’s error direction belongs alongside its result, because a conservative probe and an optimistic one with the same error rate are not equally usable.

Check the catalogues before calling a finding new

Several findings in one session were reported as fresh and turned out to be on record already. A liveness condition sat in an issue comment while the issue body listed the others. An exclusion’s reasoning sat in a comment on the issue it constrained. A modelling gap was already carried by the schema, at the declaration for the path it was about.

The records were good. None were reachable from where the question got asked, which is the part worth fixing. Before flagging an oddity, check the schema tables, the declaration for the path itself, and the issue comments rather than only the issue bodies.

Reading a result

A pass can mean the check compared nothing

Two shapes produce this, and neither looks like a skip.

The data is not there. A check comparing a type’s Default against the engine’s constructor values reached a nested block through its parent, whose field for that block is an Option defaulting to None. Nothing is written under it, so every path resolves to nothing, so there is nothing to compare, and having nothing to compare reads exactly like agreement. An optional container that defaults to absent hides its children from anything reaching them through the parent. Check the child type directly rather than making the parent write something it otherwise would not.

The entry opted out. Schema entries carrying Unexamined were skipped deliberately, since nobody has read the page and failing them would report unread pages as reader defects. The effect is not “unknown” but exempt from every guard: an unpopulated declaration and a verified-correct one become indistinguishable, while the entry is still walked, still counted as reached, and still passes the coverage assertion meant to catch checks that stop short. Thirteen saved-form script hooks and two trap fields read empty where the engine holds "default" and an armed flag, under a guard with a test named after that exact type and green results throughout.

A skip condition on the data is a coverage hole that reports as coverage. Treat a per-entry opt-out as a bucket to be reported, never as a state to be skipped past.

A failure can be the guard’s fault

A list of labels the typed views deliberately stop writing needs a guard, because a wrong entry silently drops a field from files that carry it. The obvious guard asks whether each listed label is still in the corpus validator’s “written but in no file” set, and it passes today. Then the omission lands, the views stop writing those labels, and a label nobody writes is no longer in that set. Every successfully omitted label reports as a violation.

A check derived from a set the change mutates cannot stay true after the change it guards. The tell is a guard asking whether X is still in S when the change is precisely what removes X from S. It reads as solid right up to the moment it matters.

Derive the guard from the invariant that survives the change, not the state that holds now. Here that invariant is “no real file carries this label”, a fact about the corpus alone, so the guard asks the corpus and means the same thing on both sides of the change.

This one was caught immediately because it was total: every label in the first batch failed at once, which is obviously a broken check rather than that many broken fields. The dangerous version is partial. A mix of already-omitted and not-yet-omitted labels would have produced a handful of reds that looked like findings, and findings get explained.

A comment that explains a finding away is a claim

validate gff compares the typed views against the vanilla corpus in both directions: labels real files carry that no view models, and labels a view writes that appear in no file. Repos_Posy sat in the first list and Repos_PosY in the second, which is one field read under one spelling and written under another, reported twice from two angles. The tool’s own module documentation named the pair and explained it as the label-normalization policy working as intended. Every container item this library wrote lost its grid position for as long as that note stood.

The note was not lazy. It was written from the same reading of the format that produced the writer, which is a check repeating the code’s mistake wearing different clothes. What makes it worth separating is where it lands: not in a test that agrees with the code, but in prose that removes a disagreeing result from consideration. Running the tests cannot falsify a sentence.

Two habits follow. Write down what you checked rather than what you concluded, because “known false positive” is unfalsifiable while “these 4215 files carry the label and none carry the other spelling” is something a later reader can re-run and disagree with. And treat a matched pair as a question: a label the corpus has and the view lacks, alongside a label the view has and the corpus lacks, is the shape a rename leaves behind.

None of this argues for writing more tests. It argues for knowing what the ones you have have actually looked at.

Linting

rakata-lint reads a GFF resource and tells you what the engine will do with it that you probably did not intend. Not “is this valid GFF” (that is the parser’s job) but “will this crash, get silently truncated, or sit there doing nothing”.

Every rule traces back to a Ghidra audit of swkotor.exe, written up per format under formats/gff/. If a rule cannot point at a page, it does not exist yet.

The two entry points

lint(&gff) takes a parsed GFF and nothing else. It picks a schema off the file type, walks the tree against it, and runs the intra-resource rules. No filesystem, no game install, no 2DAs. Everything it knows is in the bytes you handed it.

lint_with_context(&gff, &mut LintContext) does all of that and then some. The context is what lets a rule ask a question about the world outside the file.

Both collect everything rather than stopping at the first problem. You get a Vec<LintDiagnostic>, because a mod with eleven issues should take one run to find out, not eleven.

LintContext

A LintContext holds a borrow of a GameVfs and a 2DA cache. That is the whole type, and both halves earn their place.

The VFS is how a rule answers “does this resref resolve?” against the install the user actually has, overrides and all, the same way the engine would. The cache is how twelve rules across four hundred files avoid loading baseitems.2da twelve hundred times.

The important part is whose install it reads. The linter never checks against a vanilla baseline. A range check bounds against however many rows the loaded 2DA has, not against the row count that shipped in 2003, because the engine does not know the difference either and a mod that adds appearances is not thereby broken. When a table is missing or fails to parse, the rule emits a LINT-CTX-* diagnostic and skips, so you find out a rule did not run instead of reading its silence as a pass.

The three phases

The phases are not a schedule. They are a statement about what a rule needs in order to answer.

Phase 1, intra-resource. Everything answerable from the file alone. Forced defaults, sentinel handling, truncation behaviour, dead data, and the schema walk itself. GroundPile is always forced to 1 no matter what you wrote, so writing it is decorative and worth saying so. These rules work on the raw Gff tree rather than a typed view, deliberately: a typed view drops toolset-only and dead fields, and those are exactly what several of these rules exist to find.

Phase 2, range and reference. Everything that needs a table or the resource system. Is this BaseItem a real row? Does this script exist? Is Gender inside the range the engine tolerates? These take a typed view, because by the time you are checking a value against baseitems.2da the typed view has already done the dispatch and resolution work you would otherwise write twice.

Phase 3, cross-resource. Everything that needs other files to be in the room. Does this transition trigger name an area tag that exists? Does the creature’s equipment resolve to real items? Does the conversation tree hang together? Planned rather than built.

Phases 1 and 2 are complete for all fourteen generic types. Phase 3 is the interesting one and is where the mod validation tool starts.

Reading a diagnostic

Rule ids carry their origin in the prefix.

SCHEMA-* comes from the generic walk and means something structural: wrong type, missing required field, a label the schema does not declare, a value outside a declared range, or a field the engine never reads.

A format prefix like UTI-006 or UTW-001 is a hand-written behavioural rule, numbered within that format’s set. These are functions rather than data because the logic varies too much to declare.

LINT-CTX-* means the linter could not answer, not that the answer was fine.

Severity splits three ways and the split is about the engine, not about how annoyed you should be. Error is a crash or corrupted state. Warning is the engine silently truncating, clamping, or ignoring you. Info is dead data and forced defaults, which is to say the field does nothing and you may as well know.

For the crate’s internal layout and the full rule inventory, see crates/rakata-lint/ARCHITECTURE.md in the repository.

Legal & Compliance

Disclaimer: We aren’t lawyers! The following information references specific legal statutes regarding software interoperability and reverse engineering simply to clearly demonstrate our commitment to strictly lawful development.

Project Intent

Rakata is an open-source research project and software library strictly designed to build interoperability with the data formats used by Star Wars: Knights of the Old Republic (KOTOR).

• Our Goal: We want to empower users to access, read, edit, and safely modify their own legally purchased game files on modern operating systems using open-source tools.
• No DRM Circumvention: This project completely avoids the game executable. We do not bypass, strip, or defeat any Digital Rights Management (DRM) or software encryption. We solely parse static data files (like .rim, .bif, and .mdl files) for the pure purpose of compatibility.
• No Pirated Assets: This repository does not contain, distribute, or host any copyrighted game assets (art, sound, proprietary code, or binaries) owned by the original rights holders. You must supply your own legally obtained copy of the game to do anything useful with this software.

Legal Basis for Reverse Engineering

This project operates under the specific “Interoperability” exceptions provided by copyright law in major jurisdictions:

🇨🇦 Canada (Jurisdiction of Maintainer)

Under the Copyright Act (R.S.C., 1985, c. C-42), this project relies on Section 30.61, which permits the reproduction of a computer program for the purpose of:

• (a) obtaining information that is necessary to allow the computer program to be compatible with another computer program; or
• (b) correcting errors in the computer program.

🇺🇸 United States

Under the Digital Millennium Copyright Act (DMCA), this project operates under the 17 U.S.C. § 1201(f) exception for Reverse Engineering, which states:

• (1) … a person who has lawfully obtained the right to use a copy of a computer program may circumvent a technological measure… for the sole purpose of identifying and analyzing those elements of the program that are necessary to achieve interoperability of an independently created computer program with other programs…

🇪🇺 European Union (Host Jurisdiction - Codeberg)

Under Directive 2009/24/EC (Legal Protection of Computer Programs), this project adheres to Article 6 (Decompilation), which allows for the reproduction of code and translation of its form when:

• (a) these acts are performed by the licensee or by another person having a right to use a copy of a program…
• (b) the information necessary to achieve interoperability has not previously been readily available…
• (c) these acts are confined to the parts of the original program which are necessary to achieve interoperability.

Acknowledgements

Portions of the initial file format logic were originally derived from research by the awesome PyKotor project (licensed under LGPL-3.0-or-later) and verified against original game binaries using clean-room reverse engineering techniques (via Ghidra and ret-sync).

Transcribed material in the MDL surface

Behavioural referencing

We observe what they emit so our output round-trips through them, which is the ordinary practice described in Contributing and needs no special mention. One item is different in kind, being content taken across rather than behaviour observed, and it is named here because that distinction is the one worth being honest about.

The eight MDL classification name strings in mdl/ascii_names.rs come from mdledit’s ReturnClassificationName (by bead-v, source). The numeric codes are independently ours, attested against retail models; only the human-readable names are borrowed.

mdledit states no licence: no licence file, and no licence text in any source header. We are not treating that silence as a grant, and it cannot be settled upstream either, since the author has been out of contact for years. We would rather remove a dependency than reason our way to a comfortable conclusion about someone else’s work.

This one cannot be removed by re-deriving it. swkotor.exe carries no ASCII name for any classification bit: no such string anywhere, no adjacent table of eight, and the words that do occur belong to unrelated subsystems. There is nothing on the engine side to compare these strings against in either direction, so they are unattestable rather than pending.

The MDL controller tables are no longer on this list. All 58 codes and their name strings are traced directly from swkotor.exe, from four named functions covering the base node, emitters, lights and meshes, and the set is closed rather than sampled: every call site of the three controller-registration routines in the binary falls inside those four. mdl/ascii_names.rs records the trace address against each table. The per-mesh sequence value and the mesh block write order are likewise ours, derived from the retail model corpus.

Behavioural referencing, which is not borrowing

Called out so its absence from the list above is not read as an oversight. Our ASCII writer matches mdledit’s field ordering and formatting conventions so files round-trip through it. Our reader tolerates node orderings that mdlops and PyKotor produce. Cross-checks against kotorblender’s reader confirmed several offsets that were independently traced, and reone’s saber-segment constants agree with a vertex count read from vanilla models. models/mesh_derived_fields.md compares how six tools each handle the same ambiguous fields, which is documentation about those tools rather than anything taken from them.

Where xoreos, kotorblender or reone has its own name for a field we also model, the source records theirs beside ours for cross-reference. Our identifiers are our own.

reone publishes GPL-3.0. KotorBlender exists as two maintained forks, ndixUR’s at GPL-2.0-or-later inherited from NeverBlender and seedhartha’s at GPL-3.0-or-later. All are compatible with this project’s own GPL-3.0-or-later. We are not lawyers and this is not legal advice; if any author would prefer different handling, we would rather hear it and act on it than defend a position.

• This project is open-source and licensed under GPL-3.0-or-later.
• Star Wars: Knights of the Old Republic is a trademark of its respective owners. This passion project is not affiliated with, endorsed by, or connected to Bioware, LucasArts, or Disney in any way.

Format Implementation Reference

Every file format KotOR uses, what the engine does with it, and how much of that Rakata implements.

Start here if you are looking for a format. The tables below link every page and say how far each is implemented. If you are reading a page and want to know how far to trust it, or what a convention means, that is further down.

A format page runs in a fixed order: At a Glance for the extension and magic, File Layout for the on-disk structure, Field Schema where the format is GFF-backed, Engine Audits & Decompilation for what the loader does, and Implemented Linter Rules. Knowing the order is the fastest way to find one fact on an unfamiliar page.

On the GFF-backed pages the full generated field table sits at the very end rather than inline, because it runs to hundreds of rows on the larger formats and everything worth reading would otherwise sit behind it.

Status Legend:

• Full: Binary reader/writer implemented with roundtrip tests.
• Generics: Strongly-typed wrappers and linting schemas implemented.
• Documented: Engine-audited spec page exists; not yet wrapped in rakata-generics or given a standalone reader/writer.
• Read-only: Reader implemented; the writer cannot yet emit a form the engine reads.
• Reference: Structurally covered by another format’s page; not separately modelled.
• Deferred: Currently unimplemented, with no strongly-typed wrapper yet.

Archive Formats

GFF & Blueprints

The save-only GFFs (NFO savenfo, PT partytable, GVT globalvars) each have a page under Save Games rather than here; they exist only inside a save folder and are handled by rakata-save. FAC keeps its own page because repute.fac is a real module and save resource. BIC gets only the reference row above: it is structurally an IFO/UTC record with no routine on-disk presence to model, and its gated Player.bic save behaviour is covered in the Save Game Deep Dive.

3D Models & Walkmeshes

Texture Formats

Text & Data Formats

Audio Formats

Missing / Deferred Formats

No page and no dedicated reader. The two GFF-backed ones parse as a generic GFF tree today; what is missing is the type schema saying what the labels mean.

Resource Type Codes

Every archive in the game identifies its contents by a numeric type code rather than by a filename extension. KEY and ERF store it as a u16; RIM and BIF give the field four bytes and use the low two. The table is the same everywhere, and nothing but this table connects a code to a format.

Each code is marked against the four archive families that have been read end to end. ● means the type was found there, — that it was not.

TexturePacks/ is not indexed by chitin.key. An enumeration that starts from the KEY file walks past the game’s entire texture library with no hint that it exists, so the two codes that live there, 3007 and 2022, read as attested nowhere until those archives are opened directly.

A dash means these four families were opened and the type was not in them, not that it never occurs. For mod, erf, bif, key, rim and bzf that is expected: those name containers rather than things stored inside one.

Six codes were confirmed by opening a sample rather than by convention. 2026, 2030 and 2047 carry the GFF fourccs BTC , ITP and GUI in their own first four bytes, all at version V3.2; 2009 is NWScript source text; 2052 and 2053 carry walkmesh magic.

are, ifo and git occur exactly once per module in the RIM archives. ncs outnumbers everything else there by a wide margin.

Note

A nine-byte ASCII read of any GFF yields <fourcc>V3.28, and the 8 is not part of the version The header is 56 bytes, so struct_offset holds 0x38, which is ASCII 8. Read eight bytes and you get the fourcc and V3.2; read nine and the low byte of the next field joins the string. There is no V3.28.

Note

Rakata names 34 of these and carries the rest as raw numbers. ResourceTypeCode is a transparent wrapper over the u16, so a code the crate has no name for is read, stored and written back unchanged — an unknown type is never a parse failure. What it loses is the extension: extracting a 2052 resource yields the right bytes with no .dwk on the end. Worth knowing if you are enumerating an archive rather than fetching a known resource.

Conventions that apply everywhere

These hold for every page in this section, so no page repeats them. The first three are facts about the formats themselves. The last two are about how far to trust a claim on any page.

Important

Every multi-byte integer and float in every format here is little-endian, and no page repeats it. KotOR shipped on x86 and the engine reads its structures without byte-swapping anywhere, so the on-disk representation is the platform’s. Take this as read for every offset table in this manual: a u32 at 0x08 is four bytes low-order first. The only exceptions are called out where they occur, and there are currently none in the KotOR-native formats. The notes elsewhere about endianness concern an embedded LZMA sub-header in BZF and the MDL float ABI, neither of which is a departure from this rule.

“The engine ignores this” is not “you may leave it out”

These are different questions, and knowing the answer to one tells you nothing about the other. A field the engine never reads still has a right answer for a writer, and it is not always “anything”.

Four cases occur, and which one applies is a per-field fact:

A fifth case is the genuinely free one: a field present in vanilla, read by nothing, and carrying no positional obligation, so a writer may drop it and produce a file the engine treats identically. Fields the engine never reads is where those live, and it says what dropping them costs.

The row that catches people is the first. “The engine does not read this byte” and “any value passes” are the same statement, and “you may write anything” and “vanilla writes one specific value” are both true at once. Which one matters depends on whether you are aiming for a file the engine loads or a file that matches what shipped.

Counted, terminated, or neither

Every repeated run in these formats is delimited one of three ways. Which one a format uses is on its own page, because guessing wrong is not a graceful failure.

• Counted. A field earlier in the file says how many follow. Most of the binary formats, and LYT among the text ones.
• Terminated. A marker ends the run. TXI’s coordinate lists use endlist.
• Both, per instance. TXI again: a list takes either form, and a reader implementing only the counted one will consume the rest of the file as coordinates the first time it meets a terminated list.
• Length-delimited. A byte count rather than an element count, which is not the same thing. TLK’s text blob, and every variable-length GFF value.
• Neither. Extent comes from the file or section boundary. VIS.

The failure mode is asymmetric. Assuming counted where the file is terminated over-reads, usually to end of file. Assuming terminated where the file is counted stops early and silently drops data.

Naming a population

When a page says a field is always something, or never anything, it names the archives that were opened: “every GFF in chitin.key”, “the module RIM archives”, “the ERFs inside a save”.

Category words like vanilla, static, shipped and the corpus look like scope and are not. A category includes archives nobody opened, so a claim worded that way is wider than its evidence.

An absence therefore carries its scope: “not present in the archives we read” and “does not occur” are different claims, and only the first is established by reading files. Populations are given in words rather than as a count, because how many files matched depends on how they were sieved.

A number that is itself the finding stays. The rule is about denominators, not digits. That .pth files outnumber the modules holding them is how a reader learns the format is per-area rather than per-module, and a per-label prevalence column is most of what tells a reader which GUI fields are optional. Neither survives being reworded into “many”.

Provenance

Evidence here is not all of one strength, so every Engine Audits section names its source and its provenance level:

“Derived, not attested” describes most audit tables here, and those rows are the reverse-engineering queue. The level is not a formality: both tables that have since been checked against something other than the decompilation behind them lost rows. The walkmesh table put vertex_count at +0x08 and gave +0x48 to +0x6C to AABB trees; files refute both. Re-auditing DDS found a citation naming the wrong function, an encoding claim spanning two different domains, and a formula that appears nowhere in the binary.

Provenance Policy

Because this project seeks to achieve strict interoperability with a two-decade-old engine, mere “correctness” is insufficient. We guarantee canonical behavior.

• Target: Canonical vanilla Star Wars: Knights of the Old Republic 1 (2003).
• Engine Audits: We do not guess how the engine behaves. Code is written exclusively from observed engine evidence notes derived from clean-room reverse engineering (via Ghidra/ret-sync). Every implementation choice is documented directly inside that format’s specific page on this site.
• Verification: Behaviors are locked via deep integration tests against synthetic fixtures. If a parser perfectly round-trips an invalid file but the game engine rejects it, it is treated as a critical bug.

Archive Formats

At the heart of the Odyssey Engine is its virtual file system. Instead of loading tens of thousands of tiny loose files straight from the local disk, the engine efficiently streams them from large, concatenated archive blobs. You can think of these formats as extremely specialized zip files used to store binary models, compiled scripts, textures, and UI data.

Note

KOTOR utilizes a highly strict two-tier architecture. BIF & KEY act as the core foundational registry for all base-game assets (e.g. data/models.bif is mapped using chitin.key as the absolute global lookup index). Meanwhile, ERF & RIM files act as completely independent, self-contained archives used aggressively for loading localized module levels, stateful save games, and community mods.

Implementation Blueprints

BIF (Binary Information File)

A BIF is bulk uncompressed storage: tightly packed resource bytes with no metadata and no filenames. It is built to be read at a known offset, which is what the companion KEY index supplies.

At a Glance

File Layout

A fixed 20-byte header, one or two resource tables, and the payload. The variable table is found by variable_table_offset; the fixed table, when a file has one, follows it directly. Payload bytes are addressed per entry.

There are no names anywhere in here. A BIF entry knows its own id, type, offset and size, and nothing else. The resref lives in the KEY, which reaches in by position. That is what makes a BIF unreadable on its own and why the two formats are always discussed together.

Header (20 bytes)

Variable Resource Entry (16 bytes each)

Fixed Resource Entry (20 bytes each)

Note

resource_id is positional, and it is the KEY’s word repeated A variable entry’s resource_id is the same packed value the KEY carries for that resource: the entry’s own index within this archive in the low twenty bits, this archive’s index in the KEY file table in the high twelve. Both halves hold in every variable entry of every archive a retail install’s chitin.key names.

The two files agree exactly. Every BIF entry is named by one key, no key points at an entry that is not there, and no two keys carry the same value, so the correspondence is one-to-one in both directions rather than merely consistent where it was checked.

That makes the field carry nothing a reader does not already have from position. A writer, though, has to compute it rather than copy it, because the high half is not a property of the BIF at all: it depends on where the archive lands in the KEY’s file table, which the BIF cannot see.

The fixed table’s resource_id is untested, since nothing shipped populates that table at all.

Note

The fixed table is a format feature nothing uses fixed_count is 0 in all 26 archives of a full vanilla install, without exception. The engine reads the scalar and then ignores it entirely, as the audit below records: files declaring fixed entries are accepted and those entries are never mapped. Rakata parses the table when one is present, so a file carrying it round-trips, but nothing in the game will ever look at what it holds.

The Compressed Variant (.bzf)

Compression did not exist in the original 2003 PC release. Aspyr added it for the modern mobile ports to save storage, and it is the one place the BIF format gets genuinely confusing, because nothing inside the file says it is compressed.

The extension is the only discriminator that exists in shipping data. Everything else matches. That has a direct consequence for tooling: compression has to be stated, not sniffed. Rakata reads it from the path when opening a file, and requires it as an argument when reading from a window that has no filename attached.

Payload Layout

Each resource is stored as its own LZMA-alone stream:

0x00        properties byte     packs (pb * 5 + lp) * 9 + lc
0x01..0x05  dictionary size     u32, little endian
0x05..      compressed data     terminated by an end-of-stream marker

There is no length field in the stream, because the uncompressed length already lives in the entry table. And there is no packed length recorded anywhere: an entry’s compressed extent runs from its offset to wherever the next entry begins, with the last one running to the end of the file. Trailing alignment inside that span is harmless, since the decoder stops at the end-of-stream marker.

Note

Ground truth and its limits. The facts above are read from a shipping Android bundle (com.aspyr.swkotor), whose 26 compressed archives every one carry the BIFF signature. Rakata decodes all 26, each entry to its exact declared length. iOS and Switch are unverified and simply assumed to match.

Two things worth flagging as inference rather than fact. Community references describe a BZF signature; no file in the bundle uses it, so Rakata does not look for one. And the engine presumably swaps the extension when resolving a KEY entry on mobile, since the KEY says .bif and the disk says .bzf, but that path has not been traced in a mobile binary. The Ghidra project carries the Android builds, so it is auditable whenever someone wants to.

Engine Audits & Decompilation

Read from CExoResFile::LoadHeader (0x0040d910) and CExoResFile::ReadResource (0x0040da20) in swkotor.exe. Provenance: derived, not attested. The rows below have not been separately re-derived, so they sit on the reverse-engineering queue.

Archive Initialization (CExoResFile::LoadHeader)

Mapped from 0x0040d910.

Caution

Because the engine passes the internal data_offset integer directly into a raw C fseek(SEEK_SET), any custom BIF files must meticulously guarantee byte-perfect offset tables. If the offset is even slightly misaligned, the engine will read garbage data into the stream, inevitably crashing the game.

KEY (Global Index)

Think of the KEY file as the absolute master table of contents governing the entire game directory. Because uncompressed BIF archives are completely blind payloads that contain no internal filenames, the KEY file acts as the singular, authoritative index that tells the engine exactly which BIF holds which file, and precisely where to seek inside that BIF to find it.

At a Glance

File Layout

Four blocks, and only three of them are found the usual way. The header sits at 0x00, the BIF file table and the key table are each located by their own header offset, and the BIF filenames are not a located block at all: every file entry carries its own offset and length pointing into the filename region, so the strings are addressed individually rather than as a table.

Header (64 bytes)

BIF File Entry (12 bytes each)

Key Entry (22 bytes each)

The resource_id bitmask

This is the whole point of the format, and it is what the engine’s payload mapping below is tearing apart. A resource_id is not an index into anything on its own. It is two numbers packed into one word:

So resolving a resource is: find the key entry by resref and type, split its resource_id, use the high twelve bits to pick a BIF from the file table, and the low twenty bits to pick an entry inside it.

Warning

The format allocates twenty bits to the index and the loader reads fourteen, so a BIF holds 16,384 resources at most Both halves are confirmed and they do not conflict. The twenty-bit split above is what the field carries: across every key entry in a full install, the low twenty bits equal the resource’s index within its BIF and the high twelve equal that BIF’s position in the file table, without a single exception. The loader is narrower. The BIF audit records CExoResFile::ReadResource masking with 0x3fff before scaling by the 16-byte entry stride, which is fourteen bits, and nothing on that path reads or tests bits 14 through 31 at all.

Bits 14 to 19 are therefore allocated by the format and thrown away by the reader, and the consequence lands on a writer rather than a reader. A BIF carrying more than 16,384 resources yields a KEY the engine resolves to the wrong entry, quietly, because index 16,384 masks down to zero. The bounds check on that path does not help: it compares the masked index against variable_count, so an aliased index is in range and reads as a legitimate hit. Rakata implements the full twenty bits and is thus more permissive than the engine. Treat 16,384 as the ceiling.

Nothing shipped comes near it. The largest vanilla archive, models.bif, holds well under half that many resources, so no vanilla lookup can reach the divergence and a tool that only ever reads retail data will never see it.

Note

The version field has two trailing spaces It is V1 , not V1.0. A V1.1 constant exists in our reader and is accepted only in compatibility mode; the canonical K1 mode takes V1 alone, matching the engine. As the audit below records, there is no V1.1 branch anywhere in vanilla K1 and it is not established that such a file exists at all.

Engine Audits & Decompilation

Read from CExoKeyTable::AddKeyTableContents at 0x0040fb80 in swkotor.exe, with each subsection naming its own function below. Provenance: derived, not attested. The rows below have not been separately re-derived, so they sit on the reverse-engineering queue.

Key Table Registration (CExoKeyTable::AddKeyTableContents)

Mapped from 0x0040fb80.

Note

The engine handles KEY table loading extremely early in the application lifecycle during CExoBase::InitObject. If a global KEY fails to mount due to malformed headers, the engine immediately aborts execution.

ERF (Encapsulated Resource File)

An ERF is a self-contained archive: it carries its own table of what is inside it, so unlike a BIF it needs no external KEY index to resolve a resource. Modules (.mod) and save games (.sav) are both ERFs.

At a Glance

File Layout

An ERF is five blocks, and only the header sits at a fixed address. Everything else is found by reading a pointer back out of the header, so while the blocks are laid out contiguously in every file you’ll ever meet, that ordering is a convention rather than a rule the format enforces.

Note that entry_count governs both tables at once. The key table and the resource table are parallel arrays: key n describes what resource n is, and resource n says where its bytes live.

Header (160 bytes)

Key Entry (24 bytes each)

Resource Entry (8 bytes each)

What the two ERF populations agree on

Two sets of ERF archives have been read byte by byte. Naming them separately matters because one is much narrower than “vanilla ERFs” suggests.

• Shipped archives: every .mod under lips/, plus patch.erf. Almost all lip-sync data, so an invariant measured only here describes one content type.
• Save archives: every SAVEGAME.sav in a save corpus, plus the per-module ERFs nested inside them.

Five invariants hold in both:

resource_id shares a name with KEY’s packed word without sharing its meaning. A KEY entry has to say which archive as well as which entry, so it packs two numbers. An ERF resolves inside itself, leaving nothing to pack.

But it is the pairing key, not a restatement of the row it sits beside. The engine mounts an archive by walking the key table in file order and, for each entry, taking the resource row named by that entry’s resource_id. The loop’s own counter bounds the walk and selects nothing. So an entry’s position in the key table decides only when it is read, and its resource_id decides what it is paired with.

That distinction is invisible in every archive anyone has: the invariant above holds in both populations, so the two readings agree everywhere and only diverge on a file no writer produces. It matters to a writer regardless, because emitting the field by counting is correct by accident rather than by rule.

And the engine does not pair them the same way everywhere. Mounting an archive into the resource system uses resource_id, as above. Unpacking one walks both tables under a shared index and pairs by position instead. Two paths, two rules, and nothing reconciles them.

So an archive whose resource_id values are not its indices would mount as one set of resources and unpack as a different one, from the same bytes, with neither path complaining. Which is the practical reason to keep emitting the field by counting even though the mount path would accept anything: it is the only value both readings agree on.

A duplicate resref and type is dropped, and the first one wins

The key table is mounted into a hash table keyed on resref and type together. A second entry whose resref and type already occupy a matching slot is detected as a duplicate and discarded without touching the table, so the entry that appears first in file order is the one that resolves and the later one is unreachable rather than merged or overriding.

Uniform across every archive kind. .mod, .erf, .hak, .sav and .nwm all mount through the same path and there is no per-kind branch for this to differ across.

The engine identifies the offending resource by name internally when it happens, building a diagnostic that names it. Whether that message reaches anywhere a person would see is unconfirmed, so do not expect a duplicate to announce itself. The drop is silent as far as anyone has established.

Quirks

Each of these changes what a reader or a writer has to do.

A .sav file does not contain SAV magic

The extension and the signature come apart, and conflating them produces a file the engine refuses. A save archive is an ERF-family container carrying MOD in file_type, as the save page records independently. No validation branch for a SAV signature exists anywhere in the loader, so such a file is not read leniently, it fails.

Measured, not reasoned from the loader: every SAVEGAME.sav in a save corpus and every per-module ERF inside them carries MOD with version V1.0, at both levels.

Rakata accepts SAV magic in compatibility mode only, for inspecting whatever produced such a file, and never emits it.

build_year and build_day are written on save and unread on load

The audit below folds both into the engine’s unread set. That is true of the loader and misleading about the format: every save archive carries a real date, build_year as years since 1900 and build_day as a day-of-year, both taking many distinct values across a save corpus.

So “the engine never reads it” and “a writer may leave it zero” are different claims here, and only the first is established. These are the case in the engine ignores this is not you may leave it out where something outside the traced loader consumes the value. description_strref is the one field in the group that really is zero everywhere.

The localized string block has no documented entry layout

Nothing in either population carries one. localized_string_count and localized_string_size are zero in every shipped archive and every save archive, at both nesting levels, so the gap spans both producers and a writer emitting a description has nothing to work from.

One trap follows. localized_strings_offset and keys_offset are both 160 across the save archives, and with the block empty they name the same byte. A reader deriving the key table by adding localized_string_size to the string offset gets the right answer for the wrong reason, and breaks on the first archive that populates one.

Some .mod files carry a blank block

An extra unused block sits between the key table and the resource table in some archives, left behind by older tooling. Both tables are located by their own header offsets rather than by following on from each other, so a reader that trusts those offsets handles the padded and unpadded variants alike. One that assumes the tables are adjacent reads garbage.

V1.1 exists and KotOR will not touch it

The version field has a second value in the wild, V1.1, from later Aurora-family games. The KotOR engine validates for V1.0 exactly, so a V1.1 archive is not a KotOR archive whatever its extension says. Rakata’s strict reader matches the engine; its compatibility mode accepts V1.1 for inspecting foreign archives, not for producing anything the game loads.

Engine Audits & Decompilation

Read from CExoEncapsulatedFile::LoadHeader at 0x0040e1f0 in swkotor.exe, with each subsection naming its own function below. Provenance: derived, not attested. The rows below have not been separately re-derived, so they sit on the reverse-engineering queue.

Capsule Header Initialization (CExoEncapsulatedFile::LoadHeader)

Mapped from 0x0040e1f0.

Tip

The dead zone is larger than the reserved block, and it is not discarded The obvious dead region is 0x2C to 0xA0, 116 bytes of old BioWare build metadata. The engine’s actual unread set is bigger: 0x18 is skipped, and so is everything from 0x20 on, which folds build_year, build_day and description_strref into it. Unread is not the same as unwritten: see the note above on the dates the save writer puts there. Nor is any of it discarded, since the whole 160-byte buffer lives as long as the object does and is simply never read past 0x1C.

How keys_offset being unread squares with the archive working. Resource lookups in this class index the resource-list array built from 0x1C by raw numeric position, never by name, so nothing in it needs the key table. keys_offset is correct in every vanilla file and should be written correctly regardless, because the engine’s own writer uses it to place entries even though no reader consults it.

The header and the three tables are read sequentially, not by their offsets

A save archive is read by CERFFile, not the class above, and it never seeks by any of the three block offsets in the header. CERFFile::ReadHeaderVariance starts at 0xa0, the fixed end of the header, and takes the localized string block, then the key table, then the resource table in that order, sizing each from localized_string_count and entry_count alone. CERFFile::Read does parse keys_offset and resources_offset into memory beforehand; nothing then reads them back.

So those four regions have to be contiguous and in that order. A file that puts them somewhere else and says so in the header is one this reader mis-parses, with every offset field in it correct.

The payload is the exception, and the only part of the layout that is genuinely free: each entry’s bytes are found through its own data_offset, which is read. So a writer may place the payload where it likes and must not move the four regions above it.

Warning

Key entry n and resource entry n must describe the same resource, and nothing checks that they do This is the unpack path specifically, and it is not how the same archive pairs when it is mounted. Unpacking walks both tables under one index: the output filename comes from the key entry, the bytes come from the resource entry at the same position, the two are never compared, and the resource is never found by name. Mounting pairs by the key entry’s resource_id instead, so the two paths only agree because every real archive has those two numbers equal.

So a resource’s identity is its name and the bytes carrying that name are positional. Sort one table without the other and the result is a correctly named file holding a different resource’s contents, with nothing reporting a problem.

The engine’s own writer cannot produce that: CERFFile::WriteResource emits both entries for one file in a single call under a shared index. The correspondence is a property of the writer, and the reader assumes it.

Order within the two tables is free, since nothing matches a key against anything by name. A writer may order entries however it likes as long as both tables are ordered together.

These rules apply to a nested archive as much as a top-level one, because nothing opens a nested archive in place. CExoEncapsulatedFile::OpenFile branches on a stored type tag and every branch opens a named file from disk; no path in either class opens a container at an offset inside an already-open parent. An archive carried inside another is extracted to its own file first and reopened from the top, which is how a save’s per-module archives are read. Reading one in place instead yields the same bytes, and is a thing the engine never does.

Read from CERFFile::Read (0x005dce50), ReadHeaderVariance (0x005dd3c0), ExportFilesFromERF (0x005dd710) and WriteResource (0x005ddbc0), plus CExoEncapsulatedFile::OpenFile (0x0040dc30). Provenance: traced. Scoped to those two classes; a third consumer of this format, if one exists, was not looked for.

RIM (Resource Image)

RIM files operate as a radically leaner alternative to ERFs. They are used exclusively by the game engine for distributing absolutely essential or lightweight modules without the hefty structural metadata overhead of an ERF file. They provide rapid, self-contained loading for core engine environments.

At a Glance

File Layout

Three blocks: a fixed 120-byte header, a single key table, and the payload. The key table is found by keys_offset out of the header, and each entry carries its own payload offset, so nothing here depends on the blocks sitting next to each other.

Warning

Vanilla RIMs are padded, not tightly packed, and none of it is optional-looking Measured across every static RIM in a retail install, a shipped archive has structure between its payloads that a naive writer will not reproduce:

• Every data_offset is 4-byte aligned, without exception.
• Consecutive resources follow next_offset == round_up_4(prev_end) + 16 in all but a handful of non-empty archives, a mandatory 16-byte gap on top of the alignment padding.
• Interior gaps are zero-filled, never left as stale bytes.
• An 8-byte zero gap separates the key table from the first payload, widening to 72 bytes in two outliers.
• Every archive ends with exactly 10 zero bytes past the last payload.

A writer that packs tightly produces a structurally valid file the engine will read, and one that resembles no archive BioWare shipped. Since offsets are read from the table rather than inferred, the padding is not load-bearing for a reader. It is what a byte-comparison against vanilla trips on, and what tells you a file was generated rather than shipped.

The leanness compared to ERF is structural rather than cosmetic. An ERF splits its bookkeeping across two parallel tables, one saying what each resource is and another saying where its bytes are. A RIM has one table that does both jobs, which is why its entries are 32 bytes where an ERF’s are 24 plus 8. There is also no localized string block and no description, which is the metadata a RIM gives up in exchange.

Header (120 bytes)

Key Entry (32 bytes each)

Note

resource_id is the entry’s index, not the KEY’s packed word The field shares a name with KEY’s and does not share its meaning. A KEY packs an archive number and an entry number into one word, because a KEY entry has to name which BIF it is talking about. A RIM answers only for itself, so there is nothing to pack: the value is the entry’s own position in the key table, matching in every entry of every RIM under a retail install’s modules/ and rims/.

It is therefore redundant with the array index a reader already has, and a writer produces it by counting. The high twelve bits, which are the archive half in a KEY, are zero throughout.

Note

type_id is four bytes wide holding a two-byte value Resource type codes are 16-bit everywhere else in the engine, including in KEY and ERF, but a RIM key entry gives the field a full four bytes.

The engine truncates. CExoKeyTable::AddResourceImageContents (0x0040f990) copies all four bytes out of the entry unmasked, then passes the value to AddKey (0x0040e990) through an explicit two-byte cast. Everything after that point sees the truncated value: it is what gets hashed, what gets compared against existing entries, and what is stored into the live table’s two-byte type field. There is no bounds check anywhere on either side of the cast and no rejection path at all, so an out-of-range value does not fail. It silently aliases to whatever survives the truncation.

No vanilla file exercises it. Across every key entry in every static RIM archive the upper half is zero, and every type value present is a real resource type code. That means the corpus is silent on the question rather than agreeing with the engine: it never produces a value the truncation would change. The population is a retail install’s modules/ and rims/; saves contain no RIMs and were not searched.

Rakata’s reader rejects any value that does not fit a u16. That remains our own strictness rather than a match for engine behaviour, and now in a specific direction: the engine would have accepted such a file and quietly mangled the type, where we refuse it. Keeping the rejection is the right call, but it is a choice to be stricter, not conformance.

Engine Audits & Decompilation

Read from CExoKeyTable::AddResourceImageContents at 0x0040f990 in swkotor.exe, with each subsection naming its own function below. Provenance: derived, not attested. The rows below have not been separately re-derived, so they sit on the reverse-engineering queue.

Resource Image Overrides (CExoKeyTable::AddResourceImageContents)

Mapped from 0x0040f990.

Tip

The 96-Byte “Dead Zone” Exactly like the ERF dead zone, RIM files feature a massive 96 bytes of completely inert padding sitting physically between offsets 0x18 and 0x77 inside the 120-byte header. The engine blindly sweeps right past it during initialization. It is perfectly safe to zero out this region when generating new synthetic fixtures.

GFF (Generic File Format)

The Generic File Format (GFF) is BioWare’s core binary serialization format, functioning like a binary JSON object or XML tree. It holds arbitrarily nested structures, typed fields, and lists, powering UI layouts, character sheets, dialogues, and area descriptions.

At a Glance

File Layout

A 56-byte header holding an offset-and-count pair for each of six sections, and the sections themselves. The write order below is fixed and every section is located by its own header entry, so a reader never has to assume adjacency. (The audit further down counts seven contiguous sections, which is the same file: it counts the header as the first.)

Header (56 bytes)

The last three counts are byte lengths, not element counts, unlike the first three. Field data is a heterogeneous blob and both index arrays are u32 runs whose element boundaries only make sense once you know which struct or field is pointing into them.

Struct record (12 bytes)

Warning

struct_id carries real meaning in several formats, and a writer that invents one breaks the file silently The container itself does nothing with the value. Per-format readers do, and they read it instead of a field, so there is no label to search for and nothing reports a wrong value.

Two attested cases. A UTC’s Equip_ItemList element carries the equipment slot as its struct id, as a single bit: across every creature in chitin.key and the module RIM archives the ids that occur are 1, 2, 8, 16, 32, 128, 256, 512, 1024, 16384, 32768, 65536 and 131072, and nothing else. A GIT object list uses one fixed id per list, which is how an element knows what kind of object it is.

So a writer copying a struct from one place to another must carry its id, and a writer creating one must know which value the format expects. Emitting -1 everywhere produces a file that parses and loses every equipped item.

A GIT’s Creature List is the case traced end to end. The loader compares each element’s id against the one value it expects and skips the element entirely when it differs, silently, moving straight to the next index. The creature does not load, nothing is defaulted, and nothing fails.

One accessor is the only way to reach an element’s id, CResGFF::GetElementType, and the reader class hands no raw struct pointer outside itself: every method takes and returns a wrapper carrying an index. So a list whose loader never calls that accessor has ids nothing can be reading, and the lists below are settled rather than merely unobserved.

A UTC’s ItemList never reads its element ids, in the same function that reads Equip_ItemList’s. Neither does ClassList, nor FeatList, nor any list in a DLG, nor a GIT’s CameraList. The sequential ids an ItemList carries and the constant every FeatList element carries are whatever a writer happened to put there.

-1 genuinely means nothing where a format does not use the field, which is most structs and every one this page describes generically.

Which record is the root

Struct record 0. Nothing in the header says so, which is the gap: a reader holding the struct array and the field array has no stated place to begin.

Measured rather than assumed, and by the property that defines a root rather than by position: across every UTC and GIT in chitin.key and the module RIM archives, no struct field and no list element ever points at index 0. Every other record is reachable from it and it is reachable from nothing.

Field record (12 bytes)

label_index indexes the label section, which is a flat array of 16-byte NUL-padded names. Labels are shared, so two fields with the same name in different structs point at one entry.

Important

Two fields with the same label in one struct: the first wins and the second is unreachable Lookup is a linear scan across the struct’s fields in stored order, comparing the label bytes and returning the first match (CResGFF::GetFieldByLabel). A duplicate is neither an error nor a replacement. The later field is dead weight nothing ever reads.

Which makes on-disk order load-bearing, because “first” means first in the file and nothing else. A tool that changes a field by appending a fresh copy of the label has written a file where its own edit does not take effect, and no part of the format reports it.

Important

A one-field struct stores its field differently, so growing one to two fields is a rewrite field_count selects between two physical shapes. A struct with exactly one field puts that field’s index straight into its own data_or_offset, with no indirection at all. A struct with two or more puts a byte offset there instead, pointing into the shared field indices array.

Reading this is easy enough, since the count tells you which shape you are looking at. Writing into an existing file is where it bites: adding a field to a struct that already has two or more appends to that shared array and nothing else moves, but adding a second field to a struct that has one has to lift the existing index out of data_or_offset, put both indices into a fresh span of the array, and grow the header’s count to match. Same operation from the caller’s side, two different things underneath.

Field type codes

Eighteen codes, and the first ten are the ordinary scalars. The Storage column is the part a reader has to get right: it says whether data_or_offset holds the value itself or points somewhere, and where.

The four-byte scalars sit in data_or_offset directly rather than being pointed at. Anything wider than four bytes is in the field-data blob, including DWORD64, INT64 and DOUBLE, which is easy to miss because their siblings are immediate.

Warning

Code 18 has no storage rule here Whether StrRef holds its value immediately like the other four-byte scalars, or points into the field-data blob, is not established: it occurs in none of the four archive families, so no file demonstrates either reading. INT64 and DOUBLE are also absent from the static archives but do have rules, taken from the codes around them and from saves; 18 has neither.

A reader that meets one should surface it rather than guess. Picking the wrong branch reads a plausible number out of the wrong region, failing as quietly as the Struct case below.

The complex encodings

Each is written at the offset data_or_offset gives, counted from field_data_offset.

Note

Only one language-and-gender id is attested The conventional encoding is language * 2 + gender, 0 being masculine, so an English feminine substring is 1. (Provenance: paraphrase. General knowledge about the format, not something this binary was seen doing.)

Every substring in chitin.key and the module RIM archives carries id 0, across the handful of localised strings holding inline text at all. The multiplier and the gender bit are unattested here, so the formula is worth treating as a convention rather than a measurement.

Language codes themselves, and the one the engine special-cases, are on the TLK page with their codepage mapping.

Important

A Struct field holds an index, not an offset Code 14 puts a direct index into the struct array in data_or_offset. Every other pointer-like field in the format holds a byte offset, so this one reads as an inconsistency and is easy to implement as an offset by analogy with its neighbours.

The two readings do not fail loudly against each other. Struct records are 12 bytes, so index n and byte offset 12n are both plausible numbers landing inside the same section, and a reader using the wrong one produces a file that parses into the wrong tree rather than one that errors.

List is the other indirection. data_or_offset is a byte offset into the list indices array, where a u32 count is followed by that many struct-array indices, one per element.

Important

An empty list is not the same thing as an absent field Three states are distinguishable in the file: the label is absent, present with a count of zero, or present with elements. An empty list is an ordinary field record of type 15 whose data_or_offset points at a u32 zero, with no struct indices after it.

Offset 0 is legal and used, so a reader must not read a zero offset as a missing field. Empty lists are ordinary rather than exceptional across every GFF in chitin.key and the module RIM archives.

A writer that drops a list rather than emitting a zero count has changed the file’s meaning. Four format pages turn on this, and UTC records a case where absent and present-but-empty behave identically on a fresh template and diverge on an object that already holds values.

A CExoLocString in chitin.key is almost always a bare StrRef pointing into the TLK, with no inline text at all: only a handful carry any, and each of those carries exactly one substring, with language-and-gender id 0.

That is a fact about chitin.key and nothing else. Module RIMs and saves were not in it, and a save is where player-entered text would have to live, so whether either exercises the substring loop is unchecked rather than settled. Implement the loop and test it against something other than the base archives.

Important

The substring wins and the StrRef is the fallback, not the other way round Reading one of these, the engine looks for the inline substring matching the running language and gender first, unconditionally, and only consults the StrRef when that lookup comes back empty (CExoLocString::GetString). A field carrying a valid StrRef and a matching substring displays the substring.

The obvious reading is the reverse, because 0xFFFFFFFF in the StrRef looks like a “use the inline text instead” marker. It is not one. The engine never inspects the StrRef’s validity to make this choice, so the invalid value is simply the case where the fallback has nothing to offer either.

The rule lives on the type rather than on any field. Dialogue lines, item property descriptions, map notes and the save’s stat block all read through the same accessor.

Language 0 ignores the gender bit. The packed substring id is language * 2 + gender, but the gender term is only honoured when the language is non-zero. For language 0 the lookup always probes the ungendered slot, whatever gender was asked for. So a gendered language-0 substring is text the engine will never display.

The write side collapses it identically: asked to add a gendered substring under language 0, the engine lands it in the ungendered slot. So the engine’s own code cannot produce two language-0 substrings split by gender, and their absence from any corpus is structural rather than a gap in what has been looked at. A tool writing one is writing something the engine never would. Why the default language is special is not established, and it is not visible from the code either way.

How these were established

(Provenance: measured.) The encodings are derived from the bytes rather than inherited from another project’s header, and checked by tiling: decoding every field with the rules above, the field-data blob closes exactly in every GFF in a retail chitin.key and in a save corpus, with no gap, no overlap, and the last span ending on field_data_count. The six sections likewise tile from byte 56 to end of file in every GFF of both.

A wrong length rule for any variable-length type leaves a hole or an overrun, and a wrong reading of Struct or List puts an index outside its array, so a corpus that tiles with no slack constrains every rule at once. Saves are included because they carry type codes chitin.key does not.

Which codes actually appear, and where

Reported per archive, because each family exercises a different part of the code space. Four have been opened: the GFFs in chitin.key, the module RIM archives under modules/ and rims/, the static ERF archives (lips/ plus patch.erf), and a save corpus.

VOID and Vector4 are not save-only. Both are absent from chitin.key and present in module RIMs, so a reader working from the base BIFs alone will not meet them and a reader working from any module will.

Every Vector4 in either population is a GIT Orientation, which corroborates rather than complicates the audit below: GIT’s camera list really is the format’s only Vector4 call site, and the field is written by the toolset into static GITs as well as by the engine into saved ones. VOID in a module RIM is likewise narrow; in saves it carries the packed value arrays in GLOBALVARS.res and a flag block in PARTYTABLE.res.

CHAR and DWORD64 are the codes that really are save-only: absent from chitin.key, from every module RIM and from the static ERFs, and abundant in saves. INT64 and DOUBLE appear in none of the four, which is an absence with a named scope rather than a reason to think the codes are unreal. A reader must still handle them.

Note

Why Vector4’s component order can be read off the files The w, x, y, z order is documented from the engine below, and saved GITs confirm it independently. Across every Vector4 in the save fixtures the second and third slots are zero and the first and fourth vary, and all of them are unit-length. A camera that only turns on the spot has a non-zero scalar and one non-zero axis term, which under w, x, y, z is exactly the first and fourth slots. Under an x, y, z, w reading the non-zero pair would have to be the third and fourth instead.

The identity value settles it from the other side. One camera carries (1, 0, 0, 0), the identity under w, x, y, z; under the alternative that same value is a half-turn about x, which is not an orientation a resting camera holds.

Text encoding

GFF stores text as bytes and declares no encoding anywhere in the file, so a reader cannot learn it from the container. There is no lookup in the engine either: it hands the bytes to the process’s ANSI codepage, which is Windows-1252 on a western install. The TLK page documents the one place the engine special-cases a language and what follows from that.

In practice the text in chitin.key is almost entirely ASCII. The only byte outside that range anywhere in its strings and resrefs is the plus-or-minus sign, in the Pazaak card names. Treating GFF text as single-byte and decoding it as Windows-1252 reproduces that archive exactly, and nothing in it requires a multi-byte sequence. Module RIMs and saves were not scanned for this, and player-entered text lives in the latter.

The overloaded word

data_or_offset is the mechanic the whole format turns on, and it means different things depending on context rather than carrying a discriminator of its own:

• On a field whose type fits in four bytes, it is the value. For anything larger, so strings, resrefs, doubles, structs and lists, it is an offset into the field data blob or into the index arrays.
• On a struct with exactly one field, it is that field’s index directly. With any other count it is a byte offset into the field indices array, where field_count consecutive indices live.

A struct with field_count == 0 has no defined meaning for the word, and no vanilla file provides one: not a single zero-field struct occurs in any GFF in chitin.key or the module RIM archives. The rule above still applies literally, so the word is an offset into the field indices array naming zero consecutive indices, and nothing dereferences it. A reader must not follow it, and a writer creating one has no vanilla precedent to match. UTI describes what the engine does with an empty entry in a PropertiesList, which is a code path a hand-authored file can reach even though no shipped file does.

So the same u32 is variously an immediate value, an offset into one of three different regions, or an index. What it is at any point follows from the field’s type and the struct’s field count, never from anything stored beside it. A reader that guesses wrong here does not fail loudly; it reads a plausible number out of the wrong region.

Engine Audits & Decompilation

Binary: swkotor.exe

Serialization Architecture (WriteGFFFile)

Derived from 0x00413030 / 0x004113d0.

The writer builds the whole file in memory and emits seven sections back to back in a fixed order, with no padding or alignment bytes between them. It records each section’s byte offset into the 56-byte header as it goes. This is the path save games and area extraction both write through.

Warning

The label array holds fixed 16-byte elements, so a label longer than 16 characters is truncated on write.

Note

The GFF version is always V3.2. The header’s version field is written by CResGFF::CreateGFFFile (0x00411260) from a single global value, and the version string a caller passes in is ignored. So the on-disk version never varies, even where the calling code asks for something else (several save-game writers request V2.0, but it never reaches disk). Read the V3.2 you observe; the version is not a per-resource signal.

Note

Field-label lookup is case-sensitive. Every CResGFF::ReadField* wrapper resolves its label through CResGFF::GetFieldByLabel (0x00411630), which copies the requested label into a fixed 16-byte buffer with no case-folding and compares it against each field’s stored label with an inlined byte-for-byte comparison, not a case-insensitive string function. A label that differs from the one the engine’s own code constructs only in capitalization never matches: FortBonus against the engine’s fortbonus is a different string, not a fallback path. This holds for the whole ReadField* family, every scalar and string type, so exact-string field matching in a reader is the behaviourally correct model of this engine, not a shortcut that happens to work on vanilla data.

Important

A Vector4 field’s on-disk component order is w, x, y, z. Slot 0 is w, slot 1 x, slot 2 y, slot 3 z, so the identity quaternion is [1.0, 0.0, 0.0, 0.0] and not [0.0, 0.0, 0.0, 1.0].

CResGFF::ReadFieldQuaternion (0x004121b0) and CResGFF::WriteFieldQuaternion (0x00412ca0) both assign field by field rather than blitting memory, so the order is legible rather than inferred.

Confirmed at the format’s only Vector4-typed call site, GIT’s CameraList[].Orientation, and cross-checked against the engine’s Quaternion struct layout, which is the same struct the MDL format already documents.

Note

Carry-over versus fresh-literal is a property of the read call, not of the field, and it recurs on every format page in this section. Every GFF scalar read takes a “default if absent” argument, and what sits in that argument is the whole distinction:

Mechanism	The default argument holds
Carry-over	The field’s already-constructed value on the object, so an absent field leaves it where it was.
Fresh literal	An unrelated literal baked into the call site, stamped over whatever the object held.

Either way the assignment always executes, with no visible branch on presence, which is why the two are indistinguishable from the resulting value alone.

They can diverge sharply. UTC’s LoadCreature fields include five where the read literal disagrees with the constructor outright. Naming which mechanism a field uses is the most repeated question these pages answer, so it is defined once here.

Engine Blueprints: Specialized GFF Containers

The sections above describe raw GFF nodes. The engine also uses GFF as a wrapper for a family of fixed layouts called blueprints: creatures, dialogue trees, placeables, area parameters, and the rest.

Each blueprint page documents how the K1 GOG executable (swkotor.exe) maps that layout into memory through its Load*FromGFF functions, which is what rakata-lint validates against.

How far to trust any given claim is a per-page question, and each page answers it. Every Engine Audits section names the function it was read from and its provenance level, and those levels differ: some rows are traced instruction by instruction, some are measured against real files, and most are derived from one decompilation pass that nothing has separately re-checked.

Reading the field tables

Every blueprint page ends with a field table generated from the schema itself, so no label can be quietly left out. It sits at the end because it runs long, and the page’s prose comes first. Each table splits in two.

What the engine does with each field holds the labels where the engine’s behaviour is established, with what it does and what it holds when a file omits the label.

Fields nobody has examined holds the rest. That is a gap, not a finding: nobody has established whether the engine reads them, which is not the same as establishing that it does not. Many still have an answer under When absent, because the two questions were settled separately.

A bracketed number sends you to the finding under the table. The same number on many rows means one passage settles all of them, which is worth seeing before you rely on any single row.

Note

The typed blueprint structs documented below (Utc, Uti, Are, Git, Dlg, Ifo, Utd, Ute, Utm, Utp, Uts, Utt, Utw) are projections over raw GFF, not replacements. Each from_gff extracts only the documented fields and silently drops anything else; to_gff writes only those documented fields. The raw Gff tree stays alongside the typed view for callers that need byte-exact fidelity. See Typed Views and Raw GFF in the architecture guide for the full rationale and the choose-which-layer guidance.

The Blueprint Engine Audits

Each audit in this section’s navigation bar records the fields a format declares, how the engine loads them, and the rules it enforces beyond what the container’s own structure guarantees.

A field can be structurally valid GFF and still break the engine. rakata-lint flags those cases, and these audits are what it validates against.

ARE Format (Area Static Blueprint)

An .are file is an area’s static setup: its name, whether it counts as interior or exterior, its weather and grass, its sun and moon lighting and fog, and the scripts that fire at area level. Everything that moves around in the area, creatures and doors included, lives in the module’s GIT rather than here.

This page documents ARE’s field defaults, the confirmed-dead legacy fields still written by older tools, and the 52-field swoop-racing minigame subsystem. Evidence is drawn from Ghidra decompilation of swkotor.exe (K1 GOG build), cross-checked against a full K1 install’s vanilla .are corpus. The tables below are lookup surfaces, meant to be searched rather than read start to end.

At a Glance

Field Schema

The format’s field families, as an orientation before the full list.

Note

The ARE never gets re-saved. It gets re-copied. When a module is saved, the engine doesn’t parse or rewrite a single ARE field. CSWSModule::SaveModuleFinish hands the area’s static ARE resource to a generic “copy this resource type verbatim” helper, which looks up whatever ARE the resource manager currently has bound for that area and copies it byte-for-byte into the save archive. Every engine rule and clamping behaviour documented on this page (weather truncation, fog clamping, tag lowercasing, and so on) applies only to the initial parse when a module is freshly loaded, never to the save/resume cycle.

The area’s dynamic, session-changeable state, meaning weather, stealth XP, map exploration, cameras and transition flags, lives entirely in the module’s GIT resource instead, not in a re-saved ARE. If you’re building a save-editing tool, patch the GIT; don’t expect to patch an ARE inside a save archive.

Engine Audits & Decompilation

Read from CSWSArea::LoadArea at 0x0050e190 in swkotor.exe. Provenance: derived, not attested. The rows below have not been separately re-derived, so they sit on the reverse-engineering queue.

The initial LoadArea dispatch branches out to parse the .are GFF, .lyt layout, .git instance tracking, and .pth bounds. The engine processes roughly 61 scalar fields, 4 scripts, 3 lists, and a nested minigame struct within the LoadAreaHeader subroutine.

Core Environmental Identity

Interior areas lose their weather If Flags (Bit 0) marks the area as interior, the engine zeroes every weather property on load, discarding whatever the file set.

Weather & Terrain Generation

Area Lighting & Sun/Moon Tracking

KOTOR handles dynamic sunlight constraints separately between Sun and Moon.

DayNightCycle doesn’t inherit its own constructed default. The area constructor sets day_night_cycle = 1 (cycle on) before any GFF read happens, but the read itself uses a hardcoded literal 0 as its fallback, not the constructed value, so an area missing DayNightCycle loads with the cycle forced off, silently overriding what the object was built with. This looks like it could be an engine oversight (the constructor’s own default is never actually reachable through this load path), but intent aside, the mechanism is unambiguous: absent means 0, not 1. IsNight and LightingScheme share the ordinary unconditional-0 pattern with no such mismatch. NoRest, TransPending, TransPendNextID, and TransPendCurrID also carry over a constructed value (all 0/false), same practical outcome as an unconditional default given the single-call-path caveat above.

Grass_Emissive and the entire Dirty* overlay set are confirmed dead in this K1 build, not merely unread. None of their field-name strings, Grass_Emissive, DirtyARGBOne/Two/Three, DirtySizeOne/Two/Three, DirtyFormulaOne/Two/DirtyFormulaThre and DirtyFuncOne/Two/Three, exist anywhere in swkotor.exe’s string table, verified against a binary-wide search that does find every neighbouring Grass_* field. This is stronger than “the loader doesn’t consume it”: no code path in this build can even look these fields up. Treat them the same as DisableTransit/NoHangBack/PlayerOnly/PlayerVsPlayer below, toolset-only and invisible to K1’s engine.

Map Transitions & Saving states

The map block sits behind three gates

The geographic vectors, MapResX and the coordinate structs like WorldPt1X, are read only when all three hold:

1. A minimap TGA or TPC asset matching the level name exists on disk.
2. The Map sub-struct is present in the GFF.
3. MapResX’s resolved value is nonzero.

MapResX reads with an unconditional literal default of 0, so an absent MapResX is a gating sentinel rather than merely a zero. That 0 is tested directly, and where it holds the engine skips NorthAxis, MapPt* and WorldPt* entirely and falls through to a disabled map with MapZoom fixed at 1.

Where the block is read, MapPt goes through a dual path checking whether the field is formally FLOAT or INT. An absent MapPt1X, MapPt1Y, MapPt2X or MapPt2Y resolves to 0 either way: the INT branch reads a literal 0, and the FLOAT branch’s 0.0 survives its floor conversion. NorthAxis defaults to 0. WorldPt1X, WorldPt1Y, WorldPt2X and WorldPt2Y are independent FLOAT reads defaulting to 0.0, with no gating between them.

StealthXPCurrent chains its default off StealthXPMax

Both are snapshotted as DWORDs, and they default by different mechanisms. StealthXPMax uses the ordinary carry-over, its own prior value, zero-initialised by the constructor. StealthXPCurrent defaults to whatever StealthXPMax just resolved to, not to its own prior value.

On a fresh load both land on 0 either way, so only the mechanism differs. After the read the engine clamps StealthXPCurrent down to StealthXPMax where it exceeds it.

Per-Room EnvAudio

Each entry in the Rooms list carries its own EnvAudio INT, read by LoadAreaHeader alongside that room’s AmbientScale, defaulting to 0 when absent. It’s a genuine per-room reverb/environment-audio zone selector, not inert data: CSWRoom::SetRoomEnvAudioProps matches each room by name and copies its EnvAudio/AmbientScale pair into the client-side audio setup that runs when an area loads. (The exact downstream reverb table or effect it selects wasn’t traced past that per-room handoff.)

Don’t confuse this with a same-named field on the GIT’s own area-level AreaProperties struct (see GIT’s AreaProperties.EnvAudio). That one is a different struct entirely, and unlike this per-room field, it’s never read by anything.

Rooms and PartSounds: Remaining Field Defaults, and Two Confirmed-Dead Fields

No entry-level presence-chain abort exists in either list: the room loop and the nested PartSounds loop both process every index regardless of whether an individual GetListElement call succeeds, so a partially-specified entry is always kept, with each field defaulting independently.

RoomName defaults to an empty string if missing, unconditional. It is the same name SetRoomEnvAudioProps matches against a live room, so an empty RoomName simply never matches anything. AmbientScale defaults to 0.0, unconditional and independently gated from EnvAudio’s own default (the two are read back-to-back but neither gates the other). ForceRating and DisableWeather are confirmed dead the same decisive way as Grass_Emissive/Dirty* above: neither field-name string exists anywhere in swkotor.exe, confirmed by a binary-wide search. Toolset-only in this build.

PartSounds entries: Looping defaults to 0/false, unconditional. ModelPart defaults to an empty string, unconditional. OmenEvent is read as a CExoString, not the INT its name might suggest, confirmed by its sole cross-reference in the binary landing on a ReadFieldCExoString call inside this exact loop, and defaults to an empty string, unconditional. Sound defaults to an empty resref, unconditional; the (possibly-default) result is appended to the room’s sound list regardless of whether the file actually supplied one.

Expansion_List Defaults

Expansion_Name defaults to an empty localized string if missing, unconditional. Expansion_ID defaults to 0, unconditional. The list itself is only processed at all if the Expansion_List field is present in the GFF, a list-level gate rather than a per-entry one. Once inside, no entry is ever dropped for a missing field, same as Rooms/PartSounds above.

The Minigame Struct

Read via CSWMiniGame::Load (0x006723d0). If a minigame context triggers, the .are reads the nested Type (DWORD mapping 1=Swoop, 2=Turret), then the float properties governing movement:

The Player struct, each Enemies list entry, and each Obstacles list entry are three genuinely different shapes rather than siblings sharing one flat layout. Player and Enemies share a common vehicle base (hitpoints, a nested weapon Gun_Banks list, Scripts, Sounds) with Player adding its own movement/track-boundary fields on top, while Obstacles are a much lighter leaf with only a Scripts struct. See the Swoop & Turret Minigame Deep Dive for the full field-by-field breakdown and absent-field defaults.

Implemented Linter Rules (Rakata-Lint)

Phase 1 (intra-resource, no context)

Implemented under rakata_lint::rules::are.

1. ARE-001 (Context Discards): Warns when interior areas (Flags & 1) carry non-zero ChanceRain, ChanceSnow, ChanceLightning, or WindPower; the engine discards weather for interiors.
2. ARE-002 (Weather Truncation): Warns when ChanceRain, ChanceSnow, ChanceLightning, or WindPower exceed 255; the engine truncates these to bytes at runtime.
3. ARE-003 (Fog Clamping): Warns when MoonFogNear/Far or SunFogNear/Far are negative; the engine clamps fog distances to >= 0.0.
4. ARE-004 (Tag Lowercasing): Warns when Tag contains uppercase characters; the engine lowercases area tags on load.
5. ARE-005 (Toolset Fields): Informs when DisableTransit, NoHangBack, PlayerOnly, or PlayerVsPlayer are set; never read by the K1 engine.

Phase 2 (resource existence, requires LintContext)

Implemented under rakata_lint::rules::are_range.

6. ARE-006 (Resref Existence): Warns when any of OnEnter, OnExit, OnHeartbeat, or OnUserDefined (.ncs) does not resolve, or when any Rooms[i].PartSounds[j].Sound (.wav) does not resolve in the configured resource sources.

Pending

• Grass Texture Fallback: Informs when Grass_TexName is empty; the engine treats this as the literal string "grass".
• Texture / MiniGame Resref Existence: DefaultEnvMap, Grass_TexName, and the nested MiniGame model / track / music graph. ResourceTypeCode mapping for engine-specific texture and model packs is still being audited.

Every label the schema declares

Generated from the schema, so no label can be quietly left out. How to read these tables.

What the engine does with each field

Fields nobody has examined

Whether the engine reads these has not been established, which is not the same as establishing that it does not. Where When absent carries an answer, that half is settled.

DLG Format (Dialogue Blueprint)

A .dlg file is one conversation: a graph of NPC lines and player replies, plus everything the engine needs to stage it. Each node carries its text and voice-over, the camera framing and fades, the animations to play, and any script to run when it fires.

At a Glance

Field Schema

The format’s field families, as an orientation before the full list.

Engine Audits & Decompilation

Read from CSWSDialog::LoadDialog (0x005a2ae0), cascading through LoadDialogBase (0x0059f5f0) and LoadDialogCamera (0x0059eaa0) in swkotor.exe. Provenance: derived, not attested. The rows below have not been separately re-derived, so they sit on the reverse-engineering queue.

The LoadDialog subroutine processes the root-level conversation configuration before iterating over the nested EntryList and ReplyList. For each of those nodes, it delegates parsing to LoadDialogBase (for text and scripts) and LoadDialogCamera (for viewport directions).

StartingList provides the dialogue entry points, while the StuntList associates cutscene actor models.

Root Conversation Configuration

Shared Dialogue Node Properties (LoadDialogBase)

These fields apply to both entries (NPC spoken) and replies (Player spoken), and are parsed via LoadDialogBase.

Important

PlotIndex and PlotXPPercentage each fall back to a plain, unconditional literal. PlotIndex reads with a fallback of 0, not -1, a value that would look like a deliberate “no plot” sentinel but isn’t what the read call itself falls back to. PlotXPPercentage reads with a fallback of 0.0, not 1.0. Delay’s own fallback is documented above: a literal 0, not 0xFFFFFFFF. The confusion there is understandable, since 0xFFFFFFFF is a real, meaningful sentinel for that field, just not the one the read call falls back to on absence.

Note

SoundExists’s own absent default is a genuine oddity: 0x80 (128), not 0 or 1. That’s what the field resolves to when absent and neither the runtime-downgrade condition (Sound and VO_ResRef both invalid, which forces it to 0) nor an explicit file value overrides it. FadeColor, FadeDelay, and FadeLength each default to zero (black, 0.0, 0.0 respectively) at their own read site, distinct from the later FadeType == 0 pass that zeroes them again regardless of what was just read.

Warning

A node that carries SoundExists carries it six times. Where it appears in an EntryList or ReplyList element it is always present exactly six times, never fewer, and the six always agree on their value. It is the only duplicated label anywhere in the corpus: every other repeated label in every other resource type is a list element rather than a repeat within one struct.

It is six field records sharing a single label-table entry, not six labels. The label table itself carries no duplicate, so a tool walking labels sees one and a tool walking a struct’s fields sees six.

Reading is unaffected and writing is not. Since the six agree, taking the first is correct for a reader. A writer that updates one copy leaves five holding the old value, and a file in that state has never been observed, so a tool producing one is producing something the game has never written.

Viewport Framing (LoadDialogCamera)

Link Fields: Active and Index

Active and Index (on RepliesList/EntriesList/StartingList entries alike) both default unconditionally when absent: Active to an empty resref, Index to 0. Neither default is a placeholder that gets special-cased later; both feed directly into real behaviour:

• An absent (empty) Active genuinely means “always active,” not just “no condition configured that happens to evaluate true.” CSWSDialog::CheckScript, the function that evaluates a link’s condition at runtime, opens with an explicit check for an empty resref and returns true immediately without ever touching the script virtual machine. Only a non-empty resref gets compiled and run for real. Absence and “always true” are the same code path by construction.
• An absent Index resolves to 0 and is bounds-checked exactly like an explicit 0, since the already-documented fatal-bounds-check behaviour runs against whatever value ends up stored, absent or not. Since 0 is a valid index into every target list, an absent Index doesn’t trigger the fatal path; it silently links to the first element of the target list instead.

Relational Data Trees

Dialogues are built out of link-lists pointing at each other.

• Entry -> Reply Links (RepliesList within an Entry Node): Maps the Index (DWORD) against the .ReplyList bounds. The only variant that parses the DisplayInactive Byte.
• Reply -> Entry Links (EntriesList within a Reply Node): Maps the Index against the .EntryList bounds.
• Start Indices (StartingList): Uses the exact same linkage schema as a Reply->Entry link. Validates Index against entry_count.

All three link-list variants read only Active (a CResRef condition script) and Index; RepliesList additionally reads DisplayInactive, and no link-list variant reads anything else.

Warning

Corrupted Link Constraints, and the one value that gets through Index paths are checked at load, before anything traverses them, and the same idiom covers all three link relationships: a RepliesList link against the reply count, StartingList and a ReplyList entry’s EntriesList against the entry count. A link that fails aborts the whole file, not just itself. The loader short-circuits its remaining work, cleans up, and returns failure, so one bad index costs the entire conversation.

The bound is off by one, in the permissive direction. The test is count < index, so an index exactly equal to the count passes: one element past the end of the array, admitted by the check that exists to keep it out.

That value is not caught anywhere later either. SendDialogReplies reaches a reply by pointer arithmetic straight off the base of the reply block, with no bounds test of its own, and the block is allocated to hold exactly count elements. So index == count reads one whole reply structure past the end of the allocation, and what comes back is whatever the heap has put there.

For a tool this is the sharpest case on the page: a file carrying that one value loads cleanly, passes every check the engine makes, and misbehaves later during the conversation itself.

DisplayInactive Gates Whether a Failing Link Is Hidden or Shown Disabled

DisplayInactive defaults to 0 when absent from a RepliesList entry. At runtime, SendDialogReplies (0x005a3820) evaluates each reply link’s Active condition script; when that condition is false, DisplayInactive decides what happens next: a nonzero value still builds and sends the reply to the client (shown as a disabled option), while a zero value drops the reply from the outgoing list entirely, so the client never sees it at all. EntriesList and StartingList links have no equivalent field and are always dropped outright when their condition fails.

No vanilla .dlg file contains DisplayInactive at all, which means every vanilla dialogue takes the drop-entirely branch for every conditionally-failing reply. The shipped game never exercises the “show as disabled” behaviour. Writing an explicit DisplayInactive = 0 is behaviourally identical to omitting the field outright, since both resolve to the same default, though it diverges from vanilla’s own convention of never writing the field at all.

Fields the Loader Never Reads: NumWords, VO_ID, IsChild, Comment, LinkComment

These fields appear in vanilla .dlg files carrying real values that no loader ever reads, and the evidence is stronger than “untraced”: none of their label strings exists anywhere in the executable, so no reader can reach them on any code path. They are unmodelled, so a Rakata round trip drops them.

The full write-up lives in Fields Vanilla Writes That the Engine Never Reads, alongside the same finding on other formats.

Ancillary Configuration Lists

• AnimList: Defines custom Participant models and their accompanying Animation (WORD) action index to loop.
• StuntList: Names which StuntModel stands in for a given Participant during the cutscene.

Implemented Linter Rules (Rakata-Lint)

Phase 1 (intra-resource, no context)

Implemented under rakata_lint::rules::dlg.

1. DLG-001 (Camera Angle Compliance): Warns when CameraID is populated while CameraAngle != 6; the engine forces the ID to -1.
2. DLG-002 (Conversation Type Mismatch): Warns when ComputerType is set but ConversationType != 1 (Computer Dialog); ComputerType is dead data otherwise.
3. DLG-003 (Ghost Delay Flags): Warns when an entry delay is maxed (0xFFFFFFFF) but no sound/VO is configured and the parent fallback delay is 0; the node terminates instantly.
4. DLG-004 (Fatal Bounds Checking): Errors when any Index in a node’s link list, the starting list, or a reply list points past the end of the array it targets; this triggers a fatal engine load failure.
5. DLG-005 (Context Zeroing): Warns when FadeDelay, FadeLength, or FadeColor are configured but FadeType=0; the engine discards the timings.
6. DLG-007 (Admitted Link Index): Errors when an Index equals the length of the array it targets. Separate from DLG-004 because the two fail in opposite ways: past the end the file will not open, while exactly at the end it opens, passes every check the loader makes, and reads one element past the allocation during the conversation. The engine’s own test is count < index and cannot reject this value.

Phase 2 (resource existence, requires LintContext)

Implemented under rakata_lint::rules::dlg_range.

7. DLG-006 (Resref Existence): Warns when any of EndConversation / EndConverAbort (.ncs), CameraModel (.mdl), AmbientTrack (.wav), per-stunt StuntList[i].StuntModel (.mdl), or per-node Script (.ncs), Sound / VO_ResRef (.wav), and Links[j].Active condition scripts (.ncs) do not resolve in the configured resource sources.

Every label the schema declares

Generated from the schema, so no label can be quietly left out. How to read these tables.

What the engine does with each field

Fields nobody has examined

Whether the engine reads these has not been established, which is not the same as establishing that it does not. Where When absent carries an answer, that half is settled.

FAC Format (Faction & Reputation Table)

A .fac file is a single global table describing every faction in the game and how each faction feels about every other. The engine keys it on the resref REPUTE (type FAC ), and a save game stores the live, mutated copy under that resref. It is a flat GFF, not a per-object blueprint: there is one faction table for the whole session, not one per creature. Do not confuse it with repute.2da, a separate 2DA holding the static faction definitions a fresh game is seeded from (see Save-game context below).

At a Glance

File Layout

A FAC file is two top-level lists:

• FactionList: the roster of factions, in faction-id order (a faction’s id is its index in this list).
• RepList: a sparse set of pairwise reputation overrides between factions.

Individual objects (.utc/.utd/.utp/.ute) do not embed faction data; they carry a single Faction id that indexes into this shared table.

Field Schema

Every label the schema declares is tabulated at the end of this page, generated from the schema rather than written by hand.

Engine Audits & Decompilation

Read from the functions named below in swkotor.exe (K1 GOG build). Provenance: derived, not attested. The rows have not been separately re-derived, so they sit on the reverse-engineering queue. The field tables, the sparse-matrix rule, the reaction bands, and the global/personal model are read from: