Rakata

Rakata is a clean-room Rust implementation of Knights of the Old Republic (KotOR) data formats and tooling. It provides a modular workspace designed for robust, type-safe, and canonical handling of Odyssey Engine game data.

This Wiki serves as the definitive reference manual for KOTOR Formats and Engine Behaviors, designed to decouple format knowledge from the underlying Rust source code.

Requirements

• Rust Version: 1.85.0 or newer.

Documentation Domains

Rakata’s documentation operates on two tiers: the Software API and the Format Specifications.

1. The Workspace (Code API)

The workspace is organized into focused crates and tools. If you are developing against Rakata and need to know the semantic layout of types, functions, and data structures, refer to the respective Rustdocs:

Libraries (crates/)

• rakata-core: Foundational primitives (ResRef, ResourceType, ResourceId) and core utilities (encoding, filesystem, detection).
• rakata-formats: Binary and text format readers/writers for 19 KotOR formats including GFF, ERF, RIM, KEY/BIF, MDL/MDX, TPC, TGA, and more.
• rakata-generics: Typed wrappers around GFF-backed resources (all 13 types: UTW, UTC, UTI, etc.). 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) mirroring engine precedence (mounted save, extra overrides, active module, Override/, chitin/BIFs), plus composite module handling (.mod + _s.rim + _dlg.erf) and install-wide enumeration helpers.
• rakata-lint: Comprehensive resource validation against engine-derived field schemas. Catches crash-causing mod errors across all formats before they hit the engine.
• rakata-save: Save game parsing and modification logic.
• rakata: Facade crate re-exporting the ecosystem.

Tools (tools/)

• 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 entire formats/ specification manual effectively serves as Rakata’s formal Evidence Log. If you need to understand binary structure, historical context, or how the original swkotor.exe engine interprets byte bounds under the hood (via Ghidra-backed engine constraints), you are in the right place!

Navigate through the sidebar to explore our exhaustive, decoupled format libraries:

• Archive Formats – Detailed overviews of encapsulated containers (BIF, KEY, ERF, RIM).
• GFF Structure – The bedrock of KOTOR’s data, exposing the 13 distinct blueprint constraints (Creatures, Dialogues, Triggers, etc.).
• 3D Models & Mesh – MDL/MDX structures and binary walkmesh topologies.
• Textures & Audio – Overviews detailing graphic compression (TPC, DDS) and MP3/Miles Sound System wrappers.
• Text & Data Formats – Localized Talk Tables (TLK), rule mappings (2DA), and hierarchical layout geometries (LYT, VIS).

Ready to dive in? Head over to the Goals & Roadmap to see where the project is heading, or look into the Architecture logic that powers the Rakata suite.

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

Right now, our libraries are mostly just good at reading and writing individual game files - like extracting a 3D model, opening a save file, or decoding audio. But the real dream for rakata is to build a full, modern KOTOR engine integration.

Eventually, it would be cool to tie all these isolated pieces together into an actual rendering pipeline. For example: dropping a vanilla model into an active window and have the engine stream the textures and background audio straight from the game data.

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 over 17 different KOTOR file formats. We’ve tackled a lot of the weird legacy archives (BIF), models (MDL/MDX), and raw textures (TPC), 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 Walkmeshes (WOK/DWK/PWK).

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. 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).

3. 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.

4. 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: If a file has undocumented fields, we don’t just read them as an opaque Vec<u8> blob and blindly pass them through. Our goal is to properly reverse-engineer and map every single struct boundary. However, if we identify defined “reserved” fields in the binary layout that we haven’t cracked the meaning of yet, we will map them as properly sized reserved values so we don’t accidentally drop data the engine might rely on. (Note: explicit blank padding bytes aren’t stored in memory at all - we just recalculate those dynamically 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 living target! rakata-saveeditor is under active development, and rakata-audio is planned but does not exist yet. As we tackle our near-term roadmap goals – like building out the rakata-lint validation engine – expect these crates to flesh out, alongside brand new sibling crates being added to the ecosystem.

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-save      (depends on: core, formats)
rakata               (facade: re-exports all library crates)

  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-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: A handy facade crate that re-exports everything so you only need to add one dependency.

Tool Crates (tools/)

• 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: All the messy environment logic – hunting down loose files, enforcing vanilla precedence rules (e.g., checking the Override folder before extracting from a BIF archive), and assembling composite files – lives safely isolated inside rakata-extract. This separation guarantees our parsers can cleanly process isolated test files just as well as they operate in a massive live-game workflow.

How 2DA Tables Reach a Decoded View

Decoded views resolve file-native values against 2DA tables, which means something has to hand them a table. For a long time that something was TwoDaCache itself, and since the cache is GameVfs-backed, rakata-generics depended on rakata-extract to get it. That edge pointed backwards: generics is foundational and extract sits above it, so every consumer that only wanted to parse and resolve bytes got the whole VFS along for the ride.

The fix was to notice that twoda_cache.rs had three separable things fused into one file:

• Identity – what tables exist and what they are called: TwoDaName, tables::*. This is game-content knowledge of the same kind ResourceType carries, so it lives in rakata-core. A 2DA parser has no business knowing appearance.2da exists.
• Capability – something can hand me a table by name: the TwoDaSource trait. It returns &TwoDa, so rakata-formats is the lowest crate that can name the return type. A home in core would need core -> formats, which would be a worse inversion than the one being fixed.
• Implementation – the VFS hands me tables and I remember them: TwoDaCache, TwoDaCacheError. The cache holds a &GameVfs, and nothing below extract knows what a VFS is, so this stays in rakata-extract.

Generics needs identity and capability. It never needed implementation; it was taking implementation in order to get the other two. resolve() now takes &mut impl TwoDaSource, and rakata-extract appears nowhere in the generics manifest – not in [dependencies], and not in [dev-dependencies] either. Tests that span both crates live in the rakata facade, which is the umbrella over all four members and the natural home for tests that cross them.

TwoDaSource::twoda returns Option<&TwoDa> rather than a Result. Every consumer discarded the error, so an error type would have carried a variant nothing reads. A caller that genuinely 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, but not under the same rule, and the two should not be cited together. Lint is a leaf: nothing depends on it, so a concrete dependency propagates to nobody and there is nothing to revisit. Generics is foundational, and that is the whole reason its case stayed open long after it was first flagged. Weigh this kind of call by where the crate sits in the graph, not by whether the edge looks tidy in isolation.

One process note worth keeping. This was flagged as an architectural error once and correctly deferred, on the grounds that every real consumer already depended on rakata-extract anyway, so building the trait then would have been the speculative abstraction the rest of this guide warns against. The deferral named a condition to revisit on. That condition quietly came and went and nothing prompted anyone to look, because a trigger only works if something is watching it. The second time it came up it became a ticket instead.

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 naturally splits into two audiences served by one storage layer:

• Tools (save editor, mod linter, format inspector) reach for the typed views. They want type-safe access to known fields and don’t care about unmodelled bytes.
• Engines or byte-fidelity workflows (a future engine shim, a roundtrip auditor, anyone preserving toolset annotations) work directly with the raw Gff from rakata-formats. They own the staleness contract explicitly.

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.

Three 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. WaypointList[].TemplateResRef appears in every waypoint in a retail install and no load path reads it. The corpus tells you where to look, never what to model.
• “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; decoded/uti.rs keeping subtype_id on the kinds that ignore it is shape parity across variants, and correct. The question to ask is 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.

The one place where projection meets enumeration-by-design is rakata_generics::decoded::DecodedProperty. UTI item properties carry a PropertyName that indexes into itempropdef.2da, a table mods can extend with new rows. The enum has an Unknown variant that preserves the raw fields for one entry within an enumerated list, so an unrecognized property kind still surfaces through the decode pass instead of being dropped. It is a per-entry catch-all, not a struct-level accumulator, and the staleness risk is low because property entries are independent records.

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: Projection and Resolution

The typed structs (Uti, Utc, etc.) bring file-native fields into Rust types. A second layer on top, the decoded view, resolves those file-native fields against external context. For UTI, that context is the 2DA tables the engine consults at item-property evaluation time: itempropdef.2da for property-kind dispatch, baseitems.2da for combat / equip metadata, the iprp_* cost tables for magnitude resolution.

A decoded view splits into two stages so cross-scope analysis is a first-class operation:

• Uti::project(itempropdef) -> UtiProjection<'_>. File-native typed-variant dispatch. Cheap, scope-free, takes only the minimal context (the property-kind dispatch table) needed to pick variants. The projection is the intermediate from which one or many resolutions are built.
• UtiProjection::resolve(&mut impl TwoDaSource) -> UtiResolved<'_>. Resolves the projection against a full per-scope context. Loads every table the resolved view’s query methods could need and caches the values. All query methods on the resolved view are &self borrow-free reads against that cache.
• Uti::resolve(&mut impl TwoDaSource) -> UtiResolved<'_>. Single-scope shortcut for project(...).resolve(...). Most callers want this.

The split exists because tools, the linter, and a future engine shim want to ask “what does this UTI look like under condition X” without re-running the file-native dispatch step for each context. Mod conflict analysis (does this item resolve differently with mod A loaded?), vanilla-vs-modded diffs, and reading a resource as a mounted save sees it all reduce to “build one projection, resolve under several contexts, compare.” The projection step is shared across resolutions; only the per-scope resolution repeats.

A resolved view does not retain the cache borrow once constructed. To query under a different scope, call projection.resolve(&mut other_cache) again on the same projection. The typed-variant dispatch is not redone.

The cost-table magnitude resolution recipe each resolved UTI view bakes in is documented in the Cost-Table Magnitude Resolution subsection of the UTI engine audit: which iprp_costtable.2da index every typed property kind dispatches through, which column carries the magnitude, and which handlers bypass the dispatch chain entirely.

UTC follows the same shape with format-specific differences: Utc::project() takes no minimal context (UTC has no single dispatch table; typed list dispatch happens at resolve time against per-list 2DAs), while UtcProjection::resolve(&mut impl TwoDaSource) loads racialtypes.2da / appearance.2da / portraits.2da / soundset.2da / classes.2da / spells.2da and caches scalar-id resolutions, typed DecodedClass variants, and typed DecodedSpecialAbility variants. UtcResolved exposes the same &self borrow-free query surface (race_label, classes, total_level, is_force_user, is_droid, has_class, special_abilities, equipment, inventory, etc.). Any future generic that grows a decoded view follows the same two-stage rule.

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 Guide

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 behavioral rules (e.g., “field X is clamped to range 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 vs Engine Reimplementation

Right now, this workspace is exclusively focused on format parsing, linting, and modding tools - reading, writing, and validating the game’s actual data files. We are fundamentally just mapping out how the original game structures its data so we can build cool tools around it.

Building an actual game engine replacement (with gameplay logic, AI, and rendering pipelines) is a completely different beast for another day. But that’s exactly why these format blueprints are so critical: if someone wants to build an engine later, they can just use our shared engine audits to understand the data, rather than having to dig through raw decompiled binaries themselves!

Code Style & 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 don’t like automated hooks and prefer running things manually from the workspace root before committing, you absolutely can:

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

To keep the codebase consistently safe, lean, and fast, we heavily rely on a few core Rust principles:

• 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 lean, flat structs and trait combinators over deep, messy object-oriented 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.
• Project-Then-Resolve Decoded Views: Decoded views (UtiResolved, UtcResolved, etc.) split into a scope-free projection (format.project(...)) and a per-scope resolution (projection.resolve(&mut cache)). Uti::resolve(&mut cache) is the single-scope shortcut. All queries on a resolved view are &self borrow-free reads against eager-resolved cached state; the view does not retain the cache borrow. To query under a different scope, resolve the same projection again against a different context. See Decoded Views: Projection and Resolution 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 absolutely zero overhead when disabled.
• Safe by Default: We use #![forbid(unsafe_code)] across all core parser crates to enforce strict memory safety boundaries.

Testing & Quality

Our testing approach is a Gray Box strategy: we use our hard-earned white-box knowledge of the game engine (via Ghidra audits) to build extremely strictly-validated black-box test cases for our parsers. We want to test against how the real game engine behaves, not against artificial mocks.

When adding a brand new format, please make sure your PR includes:

• Fixture-Backed Tests: Full roundtrip coverage using synthetic test files (stored in fixtures/). We never commit real game assets; run cargo test --test gen_fixtures -- --ignored to safely generate them! Byte-exact roundtrip assertions are the gold standard for any format where the engine consumes bytes exactly as written.
• Mutation Tests: A quick pass to verify the parser safely rejects malformed or corrupted inputs without panicking (usually wired up via corruption_matrix.rs).
• Module Documentation: A clean rustdoc block showing the basic format layout.

What Did This Green Actually Verify?

A passing test is not automatically evidence. Two failure modes turn up here often enough that they’re worth naming, and they answer the same question badly: what did this green actually verify?

It shares the code’s blind spot. A test written from the same understanding as the implementation verifies self-consistency, not correctness. When the minigame nesting was wrong, the reader, the are.rs module diagram and the round-trip test all encoded the same misreading — three sources agreeing was one error with three copies, and every enemy and obstacle in the game read as absent for as long as the type existed. The corpus was the only independent source, because it was the only one nobody wrote.

It never reached its subject. The check ran, reported success, and its target was never touched. Every one of these looked identical to a real pass:

• cargo test <filter> matching zero tests still prints test result: ok. Hence scripts/test-filter.sh, which fails when a filter matches nothing.
• A value comparison that walked one side’s fields skipped every label the other side lacked — so renaming a field on both sides passed.
• Schema guards descend only where a schema entry declares children, so levels reached through children: None passed by never being visited.
• A test for diagnostic aggregation tripped a type-mismatch rule first and returned before reaching the aggregation at all.
• A guard written to catch skipped levels walked a default() value whose lists were empty, so it stopped above every level it existed to cover.

That last one is the shape in miniature: a coverage guard should prove it arrived somewhere, not just that it didn’t complain. If a test’s job is to reach a place and look, assert that it got there.

So falsify before trusting. Reintroduce the defect, run the test, and watch the right assertion fail. Four of the five above were caught this way and not otherwise. Where a check keys on something with two halves, falsify both — when a fold keyed on (path, reason), breaking the path half and breaking the reason half had to fail differently, and that’s what made the key defensible rather than merely plausible.

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

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 if the engine doesn’t explicitly seem 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 aggressively building out the rakata-lint engine rules and expanding our 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.)

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).

• 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

This launchpad tracks the implementation status of KotOR file formats across our parsing libraries (rakata-formats) and our strongly-typed wrappers (rakata-generics).

Status Legend:

• Full: Binary reader/writer implemented with roundtrip tests.
• Generics: Strongly-typed wrappers and linting schemas implemented.
• Partial: Basic parsing support, advanced features deferred.
• Canonical: Validated against vanilla KotOR (K1) runtime behavior.

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

These formats are currently unimplemented or do not yet have strongly-typed wrappers in rakata-generics.

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)

BIFs are essentially giant, uncompressed data silos. Because they act as the raw storage tier of the KOTOR engine, they don’t waste bytes on complex metadata or internal filenames – they are simply pure, tightly packed continuous byte arrays for game resources. They are designed to be randomly accessed extremely quickly at runtime strictly via their companion KEY index file.

At a Glance

Data Model Structure

The rakata-formats crate handles raw Bif parsing for you by reading the internal offset tables. However, developers very rarely interact with a raw Bif file on its own.

• Unified Access: Typically, you’ll use the KeyFile API (rakata_extract::keyfile::KeyFile), which automatically ties .key index files to their .bif data payloads so you don’t have to map them yourself.
• Seek Performance: To prevent loading 100MB+ binary files completely into memory just to read a tiny script, Rakata parses the archive’s entry table once, caches it, then jumps straight to the coordinate of the single resource you asked for. models.bif alone is nearly a gigabyte, so this is the difference between a lookup costing a hash probe and it costing the whole file.

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

The following documents the engine’s exact load sequence and field requirements for .bif archive headers mapped from swkotor.exe.

(Decompilation logic for this section was entirely audited and verified via native Ghidra pipeline against swkotor.exe, explicitly pulling from CExoResFile::LoadHeader (0x0040d910) and CExoResFile::ReadResource (0x0040da20).)

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

Data Model Structure

The rakata-formats crate evaluates the .key file as the holy grail mapping for global engine initialization.

• Indices Hierarchy: Internally, the format houses an array of bif_entries bounding archive paths and sizes, alongside a massive array of KeyResourceEntry structures fusing a standard ResRef string and a format TypeCode to a bit-packed numeric ResourceId.
• Conflict Resolution: Because the game engine relies on a strict override hierarchy, multiple KEYs might accidentally declare the same resource! When constructing the active dictionary out of a KEY file (KeyFile::build_key_resource_index), Rakata explicitly utilizes or_insert() to strictly ensure only the first defined entry for a conflict is honored, perfectly mimicking the engine’s aggressive linear-scan precedence rules.

Engine Audits & Decompilation

The following information documents the KOTOR engine’s exact load sequence and field constraints for genuine .key files. All behavior was mapped natively from swkotor.exe during clean-room reverse engineering.

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)

ERFs are the heavy lifters for standard game modules (.mod) and save game architectures (.sav). Unlike BIFs, which rely entirely on an external KEY file to resolve their resource identities, ERFs are completely self-contained entities that carry their own internal file tables, localized descriptions, and asset payloads.

At a Glance

Data Model Structure

ERF files share the same structural responsibility as RIM files: both act as self-contained module wrappers. Rakata hides that difference at the module level rather than the archive level.

• Reading one archive: rakata_formats::erf::ErfIndex parses the header and entry tables once and reads entry bytes on demand, so opening a large archive costs table parsing rather than its full size. RimIndex is the RIM equivalent. They stay separate types because their tables genuinely differ.
• Reading a module: rakata_extract::CompositeModule is what makes the container invisible. It merges a module’s .rim, _s.rim, _dlg.erf and .mod parts behind one lookup, so callers ask for a resource by name and type and never name the archive it came from.

Engine Audits & Decompilation

The following information documents the KOTOR engine’s exact load sequence and field requirements for genuine .erf capsule variants. All behavior was mapped natively from swkotor.exe during clean-room reverse engineering.

Capsule Header Initialization (CExoEncapsulatedFile::LoadHeader)

Mapped from 0x0040e1f0.

Tip

The 116-Byte “Dead Zone” The giant block of bytes stretching from physical offsets 0x2C down to 0xA0 inside the 160-byte header is formally loaded into the engine’s active memory stack… and then completely discarded immediately. It is totally inert data containing old Bioware build metadata.

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

Data Model Structure

RIM files are a lightweight twin to the ERF format, and Rakata treats the pair the same way: separate readers per container, one merged surface per module.

• Reading one archive: rakata_formats::rim::RimIndex parses the header and entry table once and reads entry bytes on demand. ErfIndex is the ERF equivalent. They stay separate types because the tables genuinely differ, even though the job is the same.
• Reading a module: rakata_extract::CompositeModule merges a module’s .rim, _s.rim, _dlg.erf and .mod parts behind one lookup, so a caller asking for a resource never has to know which container answered.

Engine Audits & Decompilation

The following information documents the KOTOR engine’s exact load sequence and field requirements for genuine .rim capsule variants. All behavior was mapped natively from swkotor.exe during clean-room reverse engineering.

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

Data Model Structure

The rakata-formats crate maps the GFF struct/field/list indexing graph into an in-memory model (rakata_formats::Gff).

• Typed values: GFF fields carry discrete types (BYTE, SHORT, VOID, STRUCT, LIST, …). rakata_formats::GffValue mirrors them one-to-one, so callers never touch raw byte layouts or indirect index arrays.
• Label deduplication: GFF caps field labels at 16 characters and deduplicates them in a contiguous LabelTable. The writer reproduces this layout exactly, so serialized binaries are deterministic and byte-compatible with what the engine emits.

Engine Audits & Decompilation

Binary: swkotor.exe

Serialization Architecture (WriteGFFFile)

Derived from 0x00413030 / 0x004113d0.

The engine allocates the output buffer entirely in-memory and serializes exactly 7 contiguous sections in an absolutely strict order. No inter-section padding or reserved alignment bytes are inserted anywhere natively. Each section’s byte-offset is dynamically snapshotted into the 56-byte header, operating as the canonical write path utilized for save games and area extraction.

Warning

Because BioWare enforces fixed 16-byte elements inside the Label arrays, any label that exceeds 16 characters is strictly truncated by the engine array bounds.

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 – FortBonus versus the engine’s fortbonus, for instance – never matches, full stop; it isn’t a fallback path, it’s a different, unmatched string. This holds for the whole ReadField* family (every scalar and string type), so exact-string field matching in a reader is the behaviorally-correct model of this engine, not a shortcut that happens to work on vanilla data.

Engine Blueprints: Specialized GFF Containers

While the gff.md reference explains the layout of raw GFF nodes, the engine frequently uses GFF as a structural wrapper to serialize completely deterministic entities known as Blueprints. These blueprints operate as the strict layouts defining creatures, dialogue trees, placeables, and area parameters.

Because rakata-lint provides deep behavioral validation over these blueprints natively, we have comprehensively audited how the K1 GOG executable (swkotor.exe) maps these layouts into active memory via its Load*FromGFF functions.

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

The audits listed in this section’s navigation bar are formal, decompilation-backed blueprints cataloging KOTOR’s physical constraints. They document the exact fields, load phrasing, and engine rule evaluations that supersede any generic structural validity.

If a field exists in GFF but breaks the engine, our Linter rules will flag it using these documentation audits as the source of truth.

ARE Format (Area Static Blueprint)

The Area (.are) blueprint format operates as the static environmental foundation of any game module. It establishes the rigid, overarching properties of a level, orchestrating the terrain’s grass rendering definitions, dynamic sunlight and fog constraints, ambient audio scale, and the primary interior/exterior state configurations. It effectively constructs the structural ‘stage’ that dynamic entities (like creatures and doors) populate later on.

At a Glance

Data Model Structure

Rakata maps an Area into the rakata_generics::Are struct. The struct’s Rustdocs document every field’s binary schema and GFF mapping; the table below is the high-level anatomy.

rakata-lint validates these fields against the engine constraints documented below.

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 actual dynamic, session-changeable state – weather, stealth XP, map exploration, cameras, 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

The following documents the engine’s exact load sequence and field requirements for .are files mapped from swkotor.exe.

(Decompilation logic for this section was entirely audited and verified via native Ghidra pipeline against swkotor.exe, explicitly pulling from CSWSArea::LoadArea at 0x0050e190.)

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 natively within the LoadAreaHeader subroutine.

Core Environmental Identity

Note

Internal Weather Truncation If Flags (Bit 0) marks the area as an interior space, the engine zeros out all weather properties upon load, actively discarding any prior weather assignments.

Weather & Terrain Generation

Area Lighting & Sun/Moon Tracking

KOTOR handles dynamic sunlight constraints separately between Sun and Moon.

Note

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.

Note

Grass_Emissive and the entire Dirty* overlay set (12 fields) 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, DirtyFuncOne/Two/Three – exist anywhere in swkotor.exe’s string table, verified against a binary-wide search that does find every neighboring 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, invisible to K1’s engine.

Map Transitions & Saving states

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 – 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 – that’s a list-level gate, not a per-entry one – but 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). It injects highly specialized float properties modifying basic terrain speeds:

The Player struct, each Enemies list entry, and each Obstacles list entry are three genuinely different shapes, not 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.

DLG Format (Dialogue Blueprint)

Description: The Dialogue (.dlg) format is the beating heart of KOTOR’s storytelling. It acts as the master “script” for every conversation, cutscene, and cinematic sequence. Rather than just holding localized text, it acts as a branching storyboard that tells the engine exactly what the characters should say in audio, what animations they should perform, which camera angles to use, and when to fire off scripts that impact the plot.

At a Glance

Data Model Structure

Rakata maps a Dialogue into the rakata_generics::Dlg struct. The struct’s Rustdocs document every field’s binary schema and GFF mapping; the table below is the high-level anatomy.

rakata-lint validates these fields against the engine constraints documented below.

Engine Audits & Decompilation

The following documents the engine’s exact load sequence and field requirements for .dlg files mapped from swkotor.exe.

(Decompilation logic for this section was entirely audited and verified via native Ghidra pipeline against swkotor.exe, explicitly pulling from CSWSDialog::LoadDialog (0x005a2ae0), cascading through LoadDialogBase (0x0059f5f0) and LoadDialogCamera (0x0059eaa0).)

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

Additionally, 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.

Warning

Two field defaults in rakata’s code don’t match the binary. PlotIndex reads with a fallback of 0, not the -1 rakata’s typed view currently defaults to. PlotXPPercentage reads with a fallback of 0.0, not 1.0. Neither field is referenced again after its read, so there’s no downstream consumption masking the discrepancy – both are plain misses that should be corrected in code.

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.

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 – 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 operate as highly interconnected link-lists.

• Entry -> Reply Links (RepliesList within an Entry Node): Maps the Index (DWORD) to the overarching .ReplyList bounds. Unique in that it exclusively parses the DisplayInactive Byte.
• Reply -> Entry Links (EntriesList within a Reply Node): Maps the Index to 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 Index paths are strictly evaluated against the internal array bounds prior to traversing. If a node tries to link out of bounds, it immediately triggers a fatal Load Failure within the engine.

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” behavior. Writing an explicit DisplayInactive = 0 is behaviorally identical to omitting the field outright (both resolve to the same default), so rakata’s writer emitting it costs nothing functionally, but it does diverge from vanilla’s own convention of never writing the field at all.

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

A corpus scan of vanilla .dlg files turns up five fields present and carrying real values that no loader function ever reads. This isn’t inferred from tracing every call site – it’s confirmed directly: CResGFF::ReadField* always takes the field’s name as a literal string argument, and none of these five label strings, NumWords, VO_ID, IsChild, Comment, LinkComment, exist anywhere in the compiled binary at all (verified against a working string search that does find neighboring labels like VO_ResRef and DisplayInactive). A field whose name string doesn’t exist in the binary cannot be read by any code path, so this is a stronger result than “untraced” – these fields are structurally inert at runtime, full stop.

Because none of the five is ever handed to a reader, the usual “what happens when the field is absent” question doesn’t apply to them the way it does to fields the engine actually reads: there’s no default-substitution logic and no carried-over-value behavior to describe, because there’s no reader code path to hit in the first place. Presence or absence in the file makes no difference to engine state.

What each field appears to be, going by name and by the patterns already documented for other formats in this codebase:

• NumWords: reads like toolset-computed word-count metadata (translation/VO-scheduling bookkeeping), never read back by the engine. No word-counting logic over Text exists anywhere in the binary either, so it isn’t silently recomputed and re-verified on load – it’s pure dead round-trip data.
• VO_ID: reads like an authoring-side lookup key into an external voice-over production database, distinct from the engine’s own VO_ResRef playback resref. Never consumed by the runtime.
• Comment: the same dead-authoring-metadata pattern already documented for UTC and UTD’s Comment fields, just more absolute here – those formats at least read the field into an unused struct member; DLG’s loader doesn’t reference the string at all.
• IsChild and LinkComment: the corpus counts line up exactly (LinkComment present in exactly the 542 files where IsChild carries a value), suggesting the two are one editor-side subsystem rather than independent fields. This can’t be confirmed or refuted from the compiled engine, though, because the runtime loader never parses either field on any struct – not the node, not the link-entry struct, nowhere. Whatever relationship they have is entirely a property of the original toolset’s .dlg authoring format, invisible to and unenforced by the shipped game.

Ancillary Configuration Lists

• AnimList: Defines custom Participant models and their accompanying Animation (WORD) action index to loop.
• StuntList: Dictates which StuntModel should proxy standard rendering behavior for a given Participant.

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 exceeds the target array bounds; 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.

Phase 2 (resource existence, requires LintContext)

Implemented under rakata_lint::rules::dlg_range.

6. 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.

FAC Format (Faction & Reputation Table)

Description: The Faction (.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

Data Model Structure

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.

Engine Audits & Decompilation

Documented from Ghidra decompilation of swkotor.exe (K1 GOG build); see the Provenance Policy. The field tables, the sparse-matrix rule, the reaction bands, and the global/personal model are read from:

FactionList fields

A faction’s own id is its position in FactionList; it is not stored on the element.

Global versus personal factions. FactionGlobal flags whether a faction is one of the standard, shared factions (the set seeded from repute.2da) or a non-global one; when the field is absent on load it defaults to 1 (global). At the script layer, ChangeToStandardFaction moves a creature into a standard faction (the engine validates the target id with CFactionManager::GetIsNPCFaction and refuses otherwise), while ChangeFaction moves it into another creature’s faction; neither can change a player character’s faction. When no faction table loads at all, the engine falls back to a small hardcoded default set (CFactionManager::CreateDefaultFactions) rather than reading repute.2da.

FactionName defaults to a literal empty string when absent, unconditionally. An empty name still leaves the faction in the general roster – it’s just never wired up as one of the manager’s special named roles (player, hostile_1, friendly_1, hostile_2, friendly_2, neutral, insane), since an empty string can’t match any of those six comparisons.

FactionParentID is a dead sentinel

Every faction in a real save carries 0xFFFFFFFF in this field, which looks like a “no parent” sentinel – and it is one, but not a live one. LoadFactionsFromSaveGame reads FactionParentID unconditionally and copies it straight onto the in-memory faction record with no comparison, no branch, and no special case for 0xFFFFFFFF. SaveFactions writes that same stored value straight back out: a pure round-trip, not a use. Nothing in the faction subsystem – reputation lookups, faction-membership changes, the script-layer faction commands, anything with a CFactionManager* or CSWSFaction* in its signature – ever reads the stored value back out for a lookup or a decision. There is no parent-child traversal anywhere in this engine build.

The sentinel’s origin is mundane: LoadFactions, the fresh-game path that seeds factions from repute.2da (as opposed to restoring them from a save), hardcodes 0xFFFFFFFF for every faction it creates. Nothing downstream ever sets it to anything else, so it survives unchanged through every subsequent save and load. FactionParentID is best understood as vestigial infrastructure for a faction hierarchy the engine never implements, in the same family as this codebase’s other confirmed-dead fields.

RepList fields and the sparse-matrix rule

Reputation is conceptually an N x N matrix (every faction’s standing toward every other faction), but it is stored sparsely. The default standing is 100 (the top of the friendly band, see below), and the writer emits a RepList entry only for pairs whose reputation is not 100.

Important

A missing pair means 100, not zero. On load the engine first rebuilds the full reputation matrix at its default baseline (every pair starts at 100), then applies the RepList entries as overrides. FactionRep is clamped to 0-100 on load (values at or above 101 snap to 100, negatives snap to 0). A reader that treats absent pairs as 0 will make the whole galaxy hostile.

FactionID1 and FactionID2 Share a Default, Not a Consequence

Both fields default to a literal 0 when absent from a present RepList entry – but that shared 0 behaves completely differently on each side, because of an asymmetric bounds check the write is gated on (FactionID2 must be strictly greater than 0; FactionID1 only needs to be a valid index, and 0 qualifies). An absent FactionID2 defaults to 0, fails that strict check, and the whole entry’s write is silently skipped – functionally the same as if the entry weren’t there at all. An absent FactionID1, on the other hand, also defaults to 0, but 0 passes as a legitimate faction index – so a RepList entry with a present, valid FactionID2 but a missing FactionID1 doesn’t get dropped. It gets written using faction index 0 as the row, silently overwriting whatever reputation pair happens to sit at (faction 0, FactionID2) instead of doing nothing. Same field type, same literal default, opposite outcomes.

FactionRep itself also defaults to a literal 0 when absent from a present, otherwise-valid entry – not the 100 sparse-matrix baseline documented above, which only applies when the whole pair is missing from RepList. A present entry with valid ids but no FactionRep writes a standing of 0 (hostile) into the matrix, clamped as a no-op since 0 is already in range, overwriting whatever baseline was sitting there.

There’s a second-order hazard worth knowing if you’re hand-editing a RepList: the loader reuses one found-flag variable across all three fields in an entry, and only checks it after FactionRep – the last of the three reads. A present FactionID1/FactionID2 with an absent FactionRep clears that shared flag, and the loader reads it as “this entry failed,” silently truncating every RepList entry that follows, not just the one with the missing field.

What the numbers mean

FactionRep is a 0-100 standing, and the engine reads it in three bands:

The same 10 and 90 boundaries turn up all over the engine: whether an NPC counts you as an enemy, whether a placed mine arms against you, and whether you may use a placeable, door, or trigger that a faction owns. So the default of 100 lands an unmodified pair squarely in the friendly band, not a literal midpoint.

Save-game context

There is no per-module faction file. When the engine stores a module it writes the entire global faction manager to a single REPUTE resource (type FAC ) in the GAMEINPROGRESS: working directory, which is then bundled into SAVEGAME.sav. So a save’s faction state lives at the resref REPUTE inside the main save archive, carrying the FactionList / RepList structure described above.

On load, LoadModuleStart probes for a REPUTE resource of type FAC . If one resolves (the save’s bundled copy, or a repute.fac that ships inside a module archive) it restores the table with LoadFactionsFromSaveGame / LoadReputationsFromSaveGame. If none is found, it builds the table from repute.2da instead and seeds the default reputations.

Note

repute.fac and repute.2da are two different resources, and only one of them is this format. repute.fac is the FAC GFF: the runtime/saved faction table (resref REPUTE, type FAC ). It is never a loose file. It lives bundled inside SAVEGAME.sav and inside some module archives. repute.2da is the static definition table the engine reads to build factions for a fresh game, and it is the repute entry you will find in chitin.key / 2da.bif. Go looking for repute.fac on disk and you will not find it. Only repute.2da turns up.

See the Save Game Deep Dive for how the save archive bundles its resources.

Implemented Linter Rules (Rakata-Lint)

None yet. The format is documented here ahead of any dedicated rakata-lint rules.

GIT Format (Game Instance Template)

Description: The Game Instance Template (.git) orchestrates the exact placement of every single entity within an environment. If the .are file is the underlying “stage”, the .git file acts as the blueprint for its “actors”–defining exactly where creatures initially spawn, where placeables sit, the physical rotation of doors, and the bounds of any active sound emitters.

At a Glance

Data Model Structure

Rakata maps a Game Instance Template into the rakata_generics::Git struct. The struct’s Rustdocs document every field’s binary schema and GFF mapping; the table below is the high-level anatomy.

rakata-lint validates these fields against the engine constraints documented below.

Engine Audits & Decompilation

The following documents the engine’s exact load sequence and field requirements for .git files mapped from swkotor.exe.

(Decompilation logic for this section was entirely audited and verified via native Ghidra pipeline against swkotor.exe, explicitly pulling from CSWSArea::LoadGIT at 0x0050dd80.)

The LoadGIT subroutine is a massive dispatcher. It evaluates 3 immediate root scalars before handing off evaluation to 13 distinct object-list loaders mapping entities. Crucially, the flag UseTemplates dominates this process by dictating whether these lists refer to external files or contain fully inline entity data.

Root Behavior Properties

(The engine validates weather fields against the .are properties immediately during load).

Notably, UseTemplates itself has no save-writer path at all: SaveGIT never emits this field, confirmed by inspecting a real save file’s GIT struct directly (no UseTemplates field present). Every save relies entirely on the loader’s own hardcoded default of 0.

Note

The same schema serves two roles, and UseTemplates is the discriminator. A module’s static .git sets UseTemplates = 1: each object element is a sparse placement that carries a TemplateResRef, and the engine loads the matching blueprint (.utc/.utd/.utp/.utt/…) and overlays the few instance fields the element holds. A savegame GIT (bundled inside SAVEGAME.sav) instead sets UseTemplates = 0: each element is a full self-contained snapshot read field by field, with no TemplateResRef and no blueprint load. A field missing from a UseTemplates = 0 element resolves to the engine’s hardcoded default, not to a blueprint. See the Save Game Deep Dive for how savegames bundle and read these GITs.

One object type is effectively savegame-only: area-of-effect objects (AreaEffectList) are runtime spell/ability effects with no template (note their absence from the GIT-006 TemplateResRef set below), so they appear in savegame GITs rather than static module layouts.

How Rakata Models the Two Forms

Each dispatching list is a GitObjects<Static, Saved>: Static for UseTemplates = 1 placements, Saved for UseTemplates = 0 snapshots. The flag is not kept as a separate field on Git, because the enum already records the choice and storing both would let them disagree.

Three lists sit outside that shape:

• WaypointList is a plain Vec<GitWaypoint>, because LoadWaypoints ignores the flag entirely and there is only ever one form to read.
• AreaEffectList is a plain Vec<GitAreaEffect>, because these objects have no blueprint at all, so the saved form is the only form.
• Encounter List is still read as static placements whatever the flag says, which is wrong for a savegame GIT. It is the one list whose saved field set is not modelled: no save in the fixture corpus carries an encounter, and unlike area effects its saved layout is not written down here either, so there would be nothing to check a model against.

Saved snapshots are checked against the fixture save corpus rather than synthetic fixtures: every object of every modelled type is parsed, written back, and compared field by field against what the engine originally wrote. AreaEffectList is the exception, since no fixture save has one; its field set comes from the load and save behaviour documented below, and a test asserts the list is still empty so a corpus that grows one does not go unchecked.

Field Naming Inconsistencies

Due to legacy asset sprawl, the engine evaluates vectors explicitly according to vastly different naming conventions depending entirely on the entity class. This is hardcoded into swkotor.exe.

Bearing does not mean the same thing for the two classes that use it: a door stores its scalar bearing verbatim, while a placeable derives Bearing from the yaw of its orientation at save time (lossy). Encounter spawn points (inside SpawnPointList) carry a single-float Orientation per point, distinct from both the Bearing scalar and the orientation vector. Sounds have no orientation at all; they use Positional / RandomPosition flags plus RandomRangeX / RandomRangeY instead.

Warning

Orientation Normalization The engine strictly evaluates 3D orientation logic. If a normalized orientation vector (like in StoreList or AreaEffectList) inadvertently resolves to 0.0 unconditionally, the engine catches the math fault and applies a hard fallback vector to (0, 1, 0).

Standard Instance Arrays

Standard loaders evaluate the generic ObjectId, process the localized position/orientation floats, and dispatch behavior mapping logic.

ObjectId Has One Default Across Every List, Static or Saved

ObjectId isn’t read by any of the per-type field loaders (LoadDoor, LoadPlaceable, LoadTrigger, the sound/store/encounter/item loaders, LoadWaypoint). It’s read exactly once per element, by the area-level list dispatcher (CSWSArea::LoadDoors, LoadPlaceables, LoadTriggers, LoadSounds, LoadStores, LoadEncounters, LoadItems, LoadWaypoints, LoadAreaEffects), before that dispatcher branches into the static-template path or the full-instance path. Every one of these nine dispatchers uses the identical default: 0x7F000000 (OBJECT_INVALID). Since the read happens once, ahead of the branch, and both branches receive the same already-assigned id, there is no static-versus-saved distinction for this field anywhere in the engine – one default covers every list, in both forms.

Creature is a structural exception, and on the static path the field is dead, not defaulted. CSWSArea::LoadCreatures branches on UseTemplates before touching ObjectId, not after. The full/save branch reads ObjectId the same way as every other type – CResGFF::ReadFieldDWORD(..., "ObjectId", ..., 0x7F000000) – so that branch genuinely defaults an absent field, same as everywhere else. The static/template branch is different in kind, not just mechanism: confirmed by decompilation, it never issues a ReadField* call against "ObjectId" at all, anywhere in the branch. 0x7F000000 reaches the CSWSCreature constructor as a bare literal, not a value derived from any read. Both branches land on the same number, but only one of them is “defaulting an absent field” – the static branch never looks at the field to begin with. Per this codebase’s modeling rule (model a field only where the engine reads it at that path), ObjectId is genuinely dead on a static creature placement, not merely defaulted: whatever a static .git creature entry carries there has zero effect, the same “never looked up” status already established for other confirmed-dead fields like .utc’s Tail/Wings. This is specific to Creature – the other nine dispatchers read ObjectId once, ahead of their own static/save branch, so the field is genuinely read-with-default on both of their paths.

One corollary worth flagging for rakata’s own code: the field-level default documented for AreaEffectList below isn’t a special case, it’s the general rule – and rakata’s typed views currently only apply OBJECT_INVALID to the ten static (UseTemplates = 1) types. The seven Saved* types (the UseTemplates = 0 full-snapshot forms) currently default ObjectId to plain 0 in code, which this trace shows is wrong: the full/save branch uses the identical 0x7F000000-default read as the static branch, for every type. module.ifo’s Mod_Area_list has the same gap – its ObjectId read (gated behind the save-game flag, confirming the existing “only read inside a save state flow” note) also defaults to 0x7F000000, not the 0 currently documented and coded there.

Appearance Is a Real Instance Override on Doors and Placeables

Both CSWSDoor::LoadDoor and CSWSPlaceable::LoadPlaceable read a field literally named Appearance as a DWORD and truncate it to a single byte – the same truncation pattern already documented for the .utd/.utp blueprint reads. For doors, the resolved byte immediately keys doortypes.2da’s Model/VisibleModel columns to pick the door’s mesh, so this is a genuine “which visual model represents this object” field, not inert data, and it shares that meaning with the blueprint-level Appearance documented on UTD/UTP. It defaults to 0 when absent (a hardcoded literal on the placeable path; the door struct’s own zero-initialized member on the door path).

Appearance is already modeled on rakata’s SavedDoor/SavedPlaceable types (the UseTemplates = 0 save-snapshot form). It is not currently modeled on the sparse GitDoor/GitPlaceable types (UseTemplates = 1, template placements), which only carry Bearing/position/ObjectId. LoadDoor/LoadPlaceable are the same shared field readers regardless of which path calls them, so a sparse, template-referencing door or placeable placement that also carries its own Appearance value would have that value read as an override on top of whatever the referenced blueprint supplies – worth verifying against real static (UseTemplates = 1) .git entries before deciding whether GitDoor/GitPlaceable need the field added.

Compare UTE’s Appearance, which shares the label but is never read by the engine at all – confirming the two are unrelated despite the shared name. A placed WaypointList[].Appearance follows the same dead pattern as UTE’s, not Door/Placeable’s: LoadWaypoint’s fully-decompiled field list has no room for it, confirmed directly (see UTW’s Core Structural Findings). A waypoint has no rendered model to select in the first place, so this is the expected outcome, not a surprising one.

Description in a GIT Struct Is Toolset Residue, Not an Override

Description is the opposite case from Appearance: it’s a real, blueprint-level field on both UTD and UTP, but the area loader never reads it back out of a placed instance’s own GIT entry. Traced through both CSWSDoor::LoadDoorExternal and CSWSArea::LoadPlaceables: the ordinary GIT-instance path resolves Description (and every other non-instance field) entirely from the referenced .utd/.utp blueprint via LoadFromTemplate, and the four-field door overlay (TransitionDestin/LinkedTo/LinkedToFlags/LinkedToModule, see UTD) doesn’t include Description. A Description value sitting in a GIT file’s own Door or Placeable entry is written by the toolset but never consulted at load time – consistent with the corpus finding that 99 files carry the field and only one holds a non-empty value. It also isn’t area-level metadata: CSWSArea::LoadProperties, the function that reads the GIT’s own AreaProperties struct, has no Description field at all.

This was confirmed for Door and Placeable entries specifically; Creature, Item/Store, Trigger, Encounter, Sound, and Camera entries weren’t individually checked, so treat the same conclusion as likely but unproven for those list types. Waypoints are a related but distinct case, not just an unchecked one – see UTW’s Core Structural Findings, where a placed waypoint’s Description isn’t toolset residue with a source that goes unread, it has no source at all, because waypoints never resolve a TemplateResRef in the first place.

AreaProperties.EnvAudio Is Toolset-Only Duplication

The GIT’s own AreaProperties struct carries an EnvAudio INT in most vanilla files (present with a real value in 99 of 117 GIT files in a full install), but it’s a different field entirely from ARE’s per-room EnvAudio – same name, different struct, and this one has no engine consumer at all. CSWSArea::LoadProperties (the function that reads GIT’s AreaProperties) and its ambient-sound delegate, CSWSAmbientSound::Load (which reads the already-modeled MusicDelay/MusicDay/MusicNight/MusicBattle/AmbientSndDay/AmbientSndNight/AmbientSndDayVol/AmbientSndNitVol off that same struct), read neither field named EnvAudio between them. A binary-wide check confirms this isn’t a missed function: the "EnvAudio" string exists exactly once in the whole executable, with exactly one cross-reference, and that one reference is the ARE per-room reader, not anything reachable from AreaProperties.

So a GIT-level EnvAudio value has zero engine consumers, full stop. It’s plausibly a toolset habit – the area’s default or primary room EnvAudio value duplicated onto AreaProperties by the editor UI, never kept in sync with the real per-room values and never read back by the engine – but that’s the strongest claim the evidence supports, not a confirmed mechanism. There is no absent-field default to report, since nothing ever looks for the field in the first place.

The Blueprint’s Tag Always Wins

UTD’s “Save versus Template Load Paths” documents that a templated door’s Tag comes from its .utd blueprint, with no per-instance overlay – so two doors sharing one blueprint would share one tag. That turns out to be general engine behavior, not a door-specific gap: every templated GIT object type follows the identical pattern. Confirmed directly for Placeable, Trigger, Sound, Store, and Encounter, and for Creature and Item as time allowed:

• Placeable, Sound, Encounter, Creature, Item: the shared field-reading routine (LoadPlaceable, CSWSSoundObject::Load, ReadEncounterFromGff, the LoadCreature/LoadFromTemplate pair via ReadStatsFromGff, LoadDataFromGff) reads Tag unconditionally from whichever struct it’s handed – the placed instance’s own struct on a direct load, the blueprint’s top-level struct on a template load. The area-level dispatcher’s post-template overlay, where one exists at all, only ever covers position/orientation/geometry – never Tag.
• Trigger: same pattern, and Tag sits in the identical family as the door overlay – CSWSArea::LoadTriggers overlays TransitionDestination/LinkedTo/LinkedToModule/LinkedToFlags plus position/geometry back from the GIT instance after a template load, but Tag is conspicuously not among them.
• Store: uses ResRef rather than TemplateResRef for templating (already documented elsewhere on this page), but does carry a genuine, separate Tag field, read unconditionally by LoadStore the same way. LoadStores’ post-template overlay covers only orientation and position.

So there’s no engine-side protection anywhere against two placements that share one blueprint ending up with the same Tag – for any templated object type, not just doors. Vanilla avoids the collision purely by authoring convention (effectively one blueprint per placed instance), the same workaround already documented for doors. A lint rule for this should be written generically across every templating GIT object type, not scoped to doors.

Specialized Struct Parsings

Area-of-Effect Objects (Save-Only)

AreaEffectList holds runtime spell/ability effect objects (CSWSAreaOfEffectObject). As noted above, these have no blueprint file of their own – no loader anywhere in the binary ever opens a template for one, so every field is read straight off the GIT struct itself. Elements must carry struct type id 13 or the loader skips them; ObjectId defaults to the engine-wide 0x7F000000 (OBJECT_INVALID) placeholder – see above for why this is the general rule across every list, not a special case for area effects.

Note

Write-only script fields, confirmed dead on restore. OnHeartbeat, OnUserDefined, OnObjEnter, and OnObjExit are written by the save writer but never read back by any loader in the binary. A restored area-of-effect object genuinely never fires these four events again: nothing re-derives them from AreaEffectId or SpellId on the load path. That 2DA-driven derivation does exist (vfx_persistent.2da, keyed by AreaEffectId, supplying OnHeartbeat/OnObjEnter/OnObjExit script resrefs plus shape/size defaults), but it’s wired exclusively into the fresh spell-cast creation path, not into loading a save. The GIT loader has no equivalent “look this back up” step. OnUserDefined goes further still: it’s never populated by any path, including fresh creation, so it’s effectively dead in this engine build regardless of load versus save.

This doesn’t mean a restored effect goes inert, though: duration countdown, position tracking, and collision-based area membership all keep working after a reload, since those run off the object’s own stored data (Duration, DurationType, position) rather than off scripts. It’s specifically the four scripted event hooks that go silent.

Singular Structs

• AreaProperties: Orchestrates stealth behavior state tracking and dynamic audio states. It physically reads AmbientSndDayVol / AmbientSndNitVol and explicitly truncates their INT declarations into a single native runtime byte value. The loader and the save writer disagree on where several of these fields actually live: the writer nests RestrictMode, StealthXPMax, StealthXPCurrent, StealthXPLoss, StealthXPEnabled, and SunFogColor inside the AreaProperties struct, but the reader actually pulls those specific fields from the GIT’s top level instead – only Unescapable is genuinely read from inside AreaProperties. The practical effect: those six fields are permanently dead in every save this engine’s own writer produces. They’re always written to a location the reader never checks, so they always resolve to whatever value the object already had in memory. TransPending / TransPendNextID / TransPendCurrID are written in both places (the GIT top level directly, and a redundant copy inside AreaProperties), but only the top-level copy is ever consulted, so the AreaProperties copy is a harmless duplicate. This finding is grounded directly in decompiled code with reasonably high confidence, though it’s inferred from variable-usage patterns rather than a byte-level disassembly proof. Its MusicDelay/MusicDay/MusicNight/MusicBattle/AmbientSndDay/AmbientSndNight/AmbientSndDayVol/AmbientSndNitVol fields (read by the ambient-sound delegate, CSWSAmbientSound::Load) each carry over their constructor’s pre-armed value when absent – confirmed as a genuine carry-over with no divergence between the constructed value and the read’s own fallback, unlike the constructor/literal-default mismatches found elsewhere in this codebase’s format audits. Absent defaults: MusicDelay 5000, MusicDay 2, MusicNight 3, MusicBattle 1, AmbientSndDay 1, AmbientSndNight 2, AmbientSndDayVol/AmbientSndNitVol 0 each.
• AreaMap: Strict binary blobs evaluating rendering properties (AreaMapData). It is absolutely bypassed during fresh loads, only executed conditionally during save-game states.
• CameraList (GitCamera entries): Read by LoadPlaceableCameras (already documented above for its 51-entry rejection limit). Position defaults to the literal zero vector (0, 0, 0) and Orientation to the literal identity quaternion (w=1, x=0, y=0, z=0), both unconditional – the read helpers always populate the field from either the GFF data or the supplied default, and the loader never branches on which one it got. Absence of either field doesn’t drop the camera entry; it’s always kept and registered, with each field defaulting independently. No presence-chain abort exists in this loop beyond the already-documented 51-entry count cap.

Implemented Linter Rules (Rakata-Lint)

Phase 1 (intra-resource, no context)

Implemented under rakata_lint::rules::git.

1. GIT-001 (Weather Zeroing): Informs when CurrentWeather != 0xFF or WeatherStarted=true is configured; if the area is an interior, the engine forcibly zeros these on load.
2. GIT-002 (Camera Array Bounds): Errors when CameraList contains 51 or more entries; triggers an immediate engine-level loader failure.
3. GIT-003 (Stealth Clamping): Warns when StealthXPCurrent > StealthXPMax; the engine clamps on evaluation.
4. GIT-004 (Ambient Volume Truncation): Warns when AmbientSndDayVol or AmbientSndNitVol are outside 0..=255; the engine truncates to an 8-bit byte.
5. GIT-005 (Sound GeneratedType Truncation): Warns when any sound’s GeneratedType exceeds 255; the engine truncates to an 8-bit byte on save. Both forms of SoundList carry the field, so this one applies to savegame content as well as static.

Phase 2 (resource existence, requires LintContext)

Implemented under rakata_lint::rules::git_range.

6. GIT-006 (Template Resref Existence): Warns when any per-instance TemplateResRef does not resolve to its expected typed template file: CreatureList[].TemplateResRef (.utc), List[].TemplateResRef (.uti, item instances), Door List[].TemplateResRef (.utd), Placeable List[].TemplateResRef (.utp), SoundList[].TemplateResRef (.uts), TriggerList[].TemplateResRef (.utt), StoreList[].ResRef (.utm), and Encounter List[].TemplateResRef (.ute). Waypoint instances are genuinely inlined and have no template – confirmed by decompilation, LoadWaypoint never reads a field named TemplateResRef under any circumstance. Doors are not, and this rule excluded them on that assumption until the gap was found: a static (UseTemplates = 1) door placement resolves TemplateResRef against a .utd blueprint exactly like a creature or placeable does (see UTD’s “Save versus Template Load Paths”). GitDoor now carries the field and the rule checks it, so a door pointing at a missing blueprint no longer passes clean. Trigger LinkedToModule is deferred to Phase 3 cross-resource checks. The rule only looks at the static form of each list, since a UseTemplates = 0 snapshot has no resref to resolve in the first place.

IFO Format (Module Info Blueprint)

Description: The Module Info (.ifo) is the absolute root metadata file for any environment. It dictates global module behavior, handling everything from the starting spawn location, to the local calendar and time-of-day progression, to script execution for global module events.

At a Glance

Data Model Structure

Rakata maps a Module Info into the rakata_generics::Ifo struct. The struct’s Rustdocs document every field’s binary schema and GFF mapping; the table below is the high-level anatomy.

rakata-lint validates these fields against the engine constraints documented below.

Engine Audits & Decompilation

The following documents the engine’s exact load sequence and field requirements for .ifo files mapped from swkotor.exe.

(Documented from Ghidra decompilation of swkotor.exe. Load path: CSWSModule::LoadModuleStart (0x004c9050). Save-side writers referenced below: SaveModuleFinish (0x004ca680) – which calls SaveModuleIFOStart (0x004c7050), the function that actually writes Mod_ID/Mod_Creator_ID/Mod_Version – SavePlayers (0x004c7870), SaveLimboCreatures (0x004c5bb0).)

Module Identity & Structural Rosters

These fields are written on every module save regardless of save-vs-fresh state – they aren’t part of the save-only state covered further down.

Mod_ID is inert, and the length split is incidental

A vanilla module’s own .ifo (as shipped inside a .mod archive) carries a 16-byte Mod_ID. Every save-game’s bundled module.ifo carries 32 bytes. This isn’t two encodings of one concept, or a save-only extension of the field with meaningful extra data – it’s an artifact of how the engine reads and re-writes an opaque blob it never interprets.

LoadModuleStart reads Mod_ID into a fixed 32-byte destination inside the module object, using a read call capped at 32 bytes regardless of how long the field actually is. A shorter field, like a vanilla module’s 16 bytes, only overwrites the first 16 bytes of that destination – the read does not zero-pad the rest. The destination buffer itself is allocated without any zero-initialization, so whatever the remaining 16 bytes held at allocation time (uninitialized heap memory) is what stays there. Mod_Creator_ID and Mod_Version live immediately adjacent to Mod_ID in this same allocation, purely as a memory-layout convenience; they are distinct GFF fields, not part of Mod_ID itself.

On save, the writer always emits exactly 32 bytes from that same in-memory buffer, unconditionally, regardless of how many of those bytes came from the original file versus leftover heap contents. That is the entire explanation for the observed split: a vanilla .ifo’s 16-byte Mod_ID, once loaded and saved even once, becomes a 32-byte field whose upper half is incidental garbage, not a second logical sub-field with any meaning.

Nothing else in the engine ever reads Mod_ID back out. There is no comparison against the target module’s own file, no hash check, no “does this save belong to this module” validation anywhere – confirmed by an exhaustive check of every reference to the field and the buffer it’s read into. It’s pure write-only round-trip data. Because it’s inert, a tool rewriting module info does not need to preserve its bytes for correctness. But matching the engine’s own behavior exactly means treating it as a genuinely variable-length blob on read, and not attempting to reconstruct a fixed 32-byte shape on write – the engine’s own 32-byte output for a resaved vanilla module is a side effect of an uninitialized buffer, not a format requirement.

Global State Configurations

Time & Cycle Management

Note

Day/Night Cycle Computations The engine continuously computes localized day/night phases explicitly against Mod_DawnHour, Mod_DuskHour, and the current_hour. This dynamically updates an internal state flag denoting: 1=Day, 2=Night, 3=Dawn, 4=Dusk.

Warning

Mod_MinPerHour/Mod_DawnHour/Mod_DuskHour doc comments in rakata’s own code are wrong. crates/rakata-generics/src/ifo.rs currently claims these three default to 2, 6, and 18 respectively. None of that is true against the binary – all three read with a literal default of 0, confirmed directly. The code’s actual behavior (.unwrap_or(0) and the Default impl) already matches the engine; only the doc-comment prose is stale and should be corrected to stop asserting values the implementation doesn’t use.

Global Event Scripts

Each event is a single ResRef field naming a compiled script (.ncs) the engine fires when that event occurs. K1 defines 15 module events:

• Asymmetric I/O (equipping). Mod_OnEquipItem is read during module startup (LoadModuleStart), but SaveModuleIFOStart never writes it back out, so a save-game round-trip silently drops it. In the binary its label sits apart from the other fourteen (which are stored contiguously), matching the one-off handling.
• Absent-field default, all 15. Every script hook, Mod_OnEquipItem included, follows one uniform pattern: read with a locally-constructed empty resref as the default and unconditionally stamped into the module’s script table, no presence check consulted afterward. Mod_OnEquipItem’s asymmetry above is entirely a write-side omission – on the read side it’s handled identically to its 14 siblings.

Note

NWM = NeverWinter Module. Mod_IsNWMFile marks a module as a .nwm-type module, a format the Odyssey engine inherited from BioWare’s Aurora engine (the one behind Neverwinter Nights). When the flag is set, the engine pairs it with Mod_NWMResName and skips re-saving the area ARE static into the module’s save ERF. The skip is narrow: SaveModuleFinish gates the ARE static write behind is_nwm_file == 0, while the GIT is written unconditionally in SaveModuleInProgress. So an NWM save still gets its dynamic GIT, just not a re-copied static ARE .

Safe-State Injection (Save Games Only)

Certain blocks of data inside the .ifo are deliberately evaluated only when the engine is mounting a module directly from a loaded .sav archive block.

Note

No list in this format drops a partially-specified entry. Across Mod_Area_list, Mod_Expan_List, Mod_CutSceneList, Mod_PlayerList, and Mod_Tokens, a struct entry missing one or more of its fields is always kept – each missing field is independently defaulted to a literal (never carried over from a prior entry or a constructed value), and the entry itself is still appended. The only thing that can abort mid-list is a heap-allocation failure, which is an out-of-memory condition that terminates the entire LoadModuleStart call, not a per-entry skip.

More Confirmed-Dead NWN Residue: Mod_VO_ID, Expansion_Pack, Mod_GVar_List

A corpus scan across 117 real module.ifo files (vanilla and save-bundled) turned up three more fields alongside the already-documented Mod_Hak/Mod_IsNWMFile legacy residue, none of which the engine reads or writes anywhere. Confirmed by the same decisive test used elsewhere in this codebase: none of the three field-name strings exist anywhere in swkotor.exe at all, which settles it outright – GFF field access here is string-literal lookup, so a label the binary never spells out can’t be read by LoadModuleStart or written by SaveModuleIFOStart, full stop. There’s no read call site to trace and no absent-field default to give, because there’s no read at all in any of the three cases.

• Mod_VO_ID (CExoString) is the most notable of the three: it carries a value in 98 of the 117 files scanned, the highest live-value density of any unmodeled field found in this codebase’s completeness audits, yet the engine never reads it under any code path. It shares the exact fate of .uti’s already-confirmed-dead VO_ID field: both look like an authoring-side voice-over production lookup key, and neither has a runtime consumer in K1. Model it as dead/toolset-only rather than a live field with a meaningful default.
• Expansion_Pack (WORD) is present in every file and always 0. This is NWN/Aurora expansion-selector residue, consistent with the Mod_IsNWMFile/Mod_Hak precedents on this same format – a real, unrelated Expansion_ID/Expansion_Name pair exists in the binary (used by Mod_Expan_List, already modeled), but Expansion_Pack itself is a different, unread label.
• Mod_GVar_List (List) is present in every file and always empty. K1’s actual campaign-global mechanism lives exclusively in the save-scoped GLOBALVARS.res (GVT ), a completely separate system with no code path connecting it back to this module-scoped field. Mod_GVar_List is NWN module-format residue that happens to share vocabulary with the real mechanism, nothing more.

Implemented Linter Rules (Rakata-Lint)

Phase 1 (intra-resource, no context)

Implemented under rakata_lint::rules::ifo.

1. IFO-001 (Direction Fallback): Warns when Mod_Entry_Dir_X and Mod_Entry_Dir_Y are both 0.0. The engine substitutes a hard fallback heading of (1.0, 0.0) only when Mod_Entry_Dir_Y is absent from the GFF; a value that is present but (0.0, 0.0) is left as a degenerate heading with no facing.
2. IFO-002 (XP Dead-Scaling): Warns when Mod_XPScale == 0. Caveat: a Ghidra trace of K1 shows the engine parses Mod_XPScale but never applies it to awarded XP (the field is inert in swkotor.exe), so a zero has no in-engine effect in K1. The rule only matters if the value is meaningful to another tool.
3. IFO-003 (Eternal Day/Night Bounds): Warns when Mod_DawnHour == Mod_DuskHour. When the two are equal the engine skips the entire dawn/dusk/night computation and locks the phase to 1 (Day), so the module is stuck in perpetual daylight.
4. IFO-004 (Void Area Initialization): Errors when Mod_Area_list is empty; directly faults the load cycle.
5. IFO-005 (Dangling NWM Structure): Warns when Mod_IsNWMFile=true without Mod_NWMResName; evaluates to an unstable execution state.

Phase 2 (resource existence, requires LintContext)

Implemented under rakata_lint::rules::ifo_range.

6. IFO-006 (Resref Existence): Warns when Mod_Entry_Area (.are), any Mod_Area_list[i].Area_Name (.are), or any of the 15 Mod_On* script hooks (.ncs) does not resolve in the configured resource sources.

Pending

• Mod_StartMovie (.bik): No ResourceTypeCode variant for the Bink movie format yet.
• Mod_CutSceneList[i].CutScene_Name: Engine resolution is .dlg or .bik depending on context (audit deferred).

UTC Format (Creature Blueprint)

Description: The Creature (.utc) blueprint format defines the attributes, stats, and behavior of all in-scene NPCs and monsters. It covers a creature’s identity, class/level, appearance, equipment, and event scripts. Because they hold so much state, Creatures are one of the most dynamic and memory-heavy templates processed by the Odyssey Engine.

At a Glance

Data Model Structure

Rakata maps a Creature into the rakata_generics::Utc struct. The struct’s Rustdocs document every field’s binary schema and GFF mapping; the table below is the high-level anatomy.

rakata-lint validates these fields against the engine constraints documented below.

Engine Audits & Decompilation

The following documents the engine’s exact load sequence and field requirements for .utc files mapped from swkotor.exe.

(Documented from Ghidra decompilation of swkotor.exe, pulling from CSWSCreatureStats::ReadStatsFromGff at 0x005afce0 and its save-side counterpart CSWSCreatureStats::SaveStats at 0x005b1b90.)

Structural Load Phasing

Note

Zeroed Data Elements Tail and Wings are stronger than “bypassed”: ReadStatsFromGff never looks them up in the GFF struct at all – there’s no ReadFieldBYTE call for either label anywhere in the function. Instead it performs a flat, unconditional assignment of 0 to both members, overwriting whatever the object already held, regardless of whether the file even contains the fields. This is identical on the .utc blueprint path (LoadFromTemplate) and the save-instance path (LoadCreature) – both call the same ReadStatsFromGff, with no branch anywhere in it that distinguishes the two callers. This isn’t merely inert legacy data, though: SaveStats still writes both fields out unconditionally on every save. Whatever values a creature’s tail or wings hold in a save file are silently discarded the moment it’s loaded back in, a genuine round-trip loss rather than a “never populated” field.

Core Structural Findings

The engine strictly validates parameters when loading a .utc file. Improper formatting will trigger some of KOTOR’s most notorious game crashes.

Warning

Understanding Fatal Crash Codes (0x5fX) When the game engine parses a file and hits an invalid stat, it completely aborts loading. Instead of recovering gracefully, the engine deliberately triggers a fatal crash to your desktop and returns a specific hexadecimal error code (e.g., 0x5f7 or 0x5f4). The rules below track the specific scenarios where the game will crash.

Save-Game Snapshot Fields

A creature serialized into a save game carries live runtime state that a static .utc blueprint does not usually populate – but “usually” is doing real work in that sentence. The save writer (CSWSCreatureStats::SaveStats, the counterpart to ReadStatsFromGff) emits these alongside the template fields. They appear on the creature structs inside a save’s module GIT (UseTemplates = 0); see the Save Game Deep Dive. Since ReadStatsFromGff has no branch anywhere that distinguishes a .utc blueprint struct from a save-instance struct, several of these “snapshot” fields are genuinely read on the blueprint path too, the same “runtime fields read on the blueprint path” pattern already documented for .ute encounters – it’s just that vanilla .utc files never happen to populate them. Others are confirmed write-only on every path, blueprint included. The table below distinguishes the two.

The remaining snapshot fields weren’t individually re-verified for blueprint-path readability in this pass, so treat their status as the original framing (save-side emphasis, not a blueprint/save distinction):

Combat state (the active combat round and equipped-weapon data) is written separately through CCombatInformation::SaveData (0x00550f30; read back by CCombatInformation::LoadData at 0x00552350). The class/skill/feat/power progression is written by SaveClassInfo (0x005aec90) and reflects the creature’s current leveled state, which for a played character diverges from the blueprint. SaveClassInfo is a genuine member of CSWSCreatureStats itself, confirmed against the binary’s own class layout; CCombatInformation is a separate class with no members in common with CSWSCreatureStats, reached through a nested object the creature owns rather than through inheritance.

Does CSWSCreatureStats name the whole shared block?

Short answer: no. ReadStatsFromGff reads the bulk of a creature’s identity, six abilities, HP/FP pools, appearance and portrait fields, faction, challenge rating, AI state, and perception range directly inline, plus ClassList/LvlStatList inline too – no separate “read class info” delegate exists on the load side, even though the save side modularizes the equivalent work into SaveClassInfo. The two structured exceptions on load are CombatRoundData, delegated to CSWSCombatRound::LoadCombatRound, and the nested CombatInfo struct, delegated to CCombatInformation::LoadData.

That accounts for a large, coherent chunk of the 86-field shared set, but not all of it. A comparable amount lives one level up, owned directly by CSWSCreature::SaveCreature / CSWSCreature::LoadCreature rather than by CSWSCreatureStats: DetectMode, StealthMode, CreatureSize, IsDestroyable, IsRaiseable, DeadSelectable, AmbientAnimState, Animation, CreatnScrptFird, PM_IsDisguised, PM_Appearance, Listening, the full set of Script* event-hook resrefs, position/orientation, AreaId, and JoiningXP are all read and written inline in those two functions, with no CSWSCreatureStats involvement at all. Scripts are handled by CSWSCreature::ReadScriptsFromGff, a genuine member of CSWSCreature rather than a free function (correcting an earlier pass’s claim otherwise); items are handled by ReadItemsFromGff, not re-checked in this later pass so its namespacing is unconfirmed. Both are called from LoadCreature, not from CSWSCreatureStats, regardless of which one turns out to be a member. FollowInfo goes further still, delegated from SaveCreature to a fourth class, CSWSCreaturePartyFollowInfo::Save.

PerceptionList is the one field confirmed to split across classes in different directions: ReadStatsFromGff reads it, but SaveCreature writes it, directly and without delegating back to CSWSCreatureStats.

So CSWSCreatureStats is a real class boundary, not an invented one, and it does own everything under “Save-Game Snapshot Fields” above plus the class/skill/feat/power progression – but the 86-field shared set as a whole spans at least four engine classes (CSWSCreatureStats, CSWSCreature, CCombatInformation, CSWSCombatRound, plus CSWSCreaturePartyFollowInfo for FollowInfo) and two unnamespaced free functions. No single engine name covers the whole set; a Rust type modelling the full shared block needs a rakata-invented name, not a borrowed one. One corner is left untraced: CSWSObject::SaveObjectState / LoadObjectState and SaveListenData / LoadListenData run at the tail of SaveCreature / LoadCreature and were not decompiled here, so there may be a further split at the base CSWSObject layer this pass didn’t reach.

Write-Only Fields

Seven of the fields above look like round-trip state but are strictly one-way: SaveStats writes them on every save, and ReadStatsFromGff never reads a single one back. (Tail and Wings are in the same club; see the note above.) They’re one-way for two very different reasons, though, and the difference matters if you’re editing saves.

MaxHitPoints, ArmorClass, and the three saving-throw totals are recomputed, not restored. Each is written from a live getter (the same getters that combat rolls and UI displays call at runtime), and on load the engine simply rebuilds the number from inputs that already round-tripped:

So editing any of these five totals in a save changes nothing; the engine derives the real numbers from the inputs in the right-hand column. The totals exist as convenience snapshots for external tooling, and no state is actually lost.

A corpus scan turns up capitalized variants of these labels – FortBonus, RefBonus, WillBonus – in a handful of .utc files, always holding 0. These are dead by construction, not merely dead in practice: GFF field-label lookup is case-sensitive, and the only literal strings ReadStatsFromGff ever constructs to search for are the lowercase fortbonus/refbonus/willbonus already documented above. A capitalized variant simply never matches during the field-lookup pass; it isn’t found, read, discarded, or compared against anything. The same applies to SubRace versus the modeled Subrace – the engine only ever looks up Subrace, so a SubRace-spelled field is unreachable regardless of what value it holds.

MClassLevUpIn and PregameCurrent are the genuine dead writes: no reader exists anywhere in the binary, not even in the character-generation export path (SaveCharGenCreature) that also writes them. The class count MClassLevUpIn supposedly bookkeeps is derived from the restored ClassList’s length instead, and PregameCurrent – despite the name – behaves as a continuously-refreshed current-HP mirror that nothing ever reads back.

TemplateResRef Isn’t Read by ReadStatsFromGff at All

TemplateResRef never appears anywhere in ReadStatsFromGff – it’s read one level up, by CSWSArea::LoadCreatures, and only on the branch that resolves a GIT Creature List entry’s blueprint reference (never on the direct save-instance path, which has no use for it). The read itself defaults to an empty resref, but the loader explicitly checks the presence flag: if TemplateResRef is absent, it destroys the just-allocated creature object and drops the entry entirely – LoadFromTemplate, and therefore ReadStatsFromGff, never runs for that entry at all. This is a genuine presence-chain abort, and the identical pattern (same field, same behavior) governs blueprint resolution for triggers, placeables, items, doors, encounters, and sounds – a templated GIT entry missing its own TemplateResRef is dropped outright, not defaulted.

Six Core Abilities Default to 0, Not a D&D-Style 10

Str, Dex, Con, Int, Wis, and Cha all follow one identical mechanism: each is read with the object’s own current value as the fallback and stamped back unconditionally, a carry-over in effect even though the store itself always executes. The constructor initializes all six to a literal 0 before any read happens, so a .utc file missing an ability score doesn’t fall back to a sensible tabletop default – it resolves to 0, not 10.

Identity, Appearance, and State Fields

Most of the remaining identity and appearance fields follow that same carry-over mechanism – the read’s own fallback is the object’s current value, stamped back unconditionally, so an absent field is a practical no-op on a freshly constructed blueprint load: Tag, Conversation, Deity, Description, Age, StartingPackage, Subrace (the free-text name – see the naming note below), SubraceIndex (the numeric id), Color_Skin/Color_Hair/Color_Tattoo1/Color_Tattoo2, Phenotype, Appearance_Type, Gender’s own default (distinct from the already-documented clamp-to-4), DuplicatingHead, UseBackupHead, FactionID, AIState (read via the INT reader despite being a WORD field, truncated on store), GoodEvil’s own default (distinct from the already-documented clamp-to-100), ChallengeRating, NaturalAC, Min1HP, PartyInteract, Disarmable, Portrait (only reached conditionally, see PortraitId below), and WalkRate’s own default (the object’s current movement_rate, distinct from the already-documented MovementRate-falls-back-to-WalkRate rule). SoundSetFile is stored on the owning CSWSCreature, not CSWSCreatureStats – consistent with the class-boundary split already documented above. SkillPoints is genuinely read twice, at two different struct scopes: once flat on the top-level struct, and separately once per entry inside LvlStatList (same label, a nested struct) – a typed view needs both reads, not one.

Naming corrections worth recording precisely. The color fields are underscored (Color_Skin, not ColorSkin), and the type field is Phenotype, not PhenoType. SubraceName does not exist as a GFF label at all – the two real, distinct labels are Subrace (the free-text name) and SubraceIndex (the numeric id); rakata’s own struct already maps these correctly.

FirstName/LastName do NOT carry over – they’re an unconditional blank stamp, unlike the structurally identical Description field a few lines away. Description’s fallback is the object’s own current value (&this->description); FirstName and LastName are each read against a freshly default-constructed, empty localized string instead, with no reference to the object’s prior name at all. An absent FirstName/LastName unconditionally overwrites whatever name the object held with an empty one – it does not leave a prior name in place, the way Description (and nearly everything else on this page) does.

Plot has an undocumented legacy-label fallback, the same shape as MovementRate->WalkRate. The loader first tries a field literally named Invulnerable; only if that’s absent does it fall back to trying Plot by name. Either way the result lands in the same plot member, written unconditionally, with a final fallback (if neither label is present) of the object’s own prior plot value. Invulnerable is a real, distinct GFF label – the same one already documented as read by LoadDoor/LoadPlaceable for their own objects – and it takes priority over Plot for creatures specifically.

NotReorienting round-trips through a polarity inversion, not a bug. The GFF-visible field is the logical negation of the internal reorienting member on both read and write; the double negation cancels out algebraically, so this isn’t a defect, just worth knowing if you’re ever comparing the label’s sense to the internal state directly.

PortraitId uses a literal sentinel default of 0xFFFF, not a carry-over. Unlike most fields on this page, PortraitId’s fallback is a fresh literal, not the object’s current value. 0xFFFF fails the same < 0xFFFE check documented for the explicit 0xFFFE sentinel, so an absent PortraitId behaves identically to writing 0xFFFE explicitly – both route to the Portrait-resref path, which itself carries over the object’s current value when absent.

Comment and the Legacy-Field Batch: Fully Confirmed Dead, With Two Corrections

A binary-wide string-existence check – the same decisive test already used for TemplateList/CRAdjust/SaveReflex/MemorizedList0 – confirms Comment, Morale, MoraleRecovery, MoraleBreakpoint, PaletteID, BlindSpot, MultiplierSet, NoPermDeath, IgnoreCrePath, Hologram, WillNotRender, and LawfulChaotic don’t exist as field-name strings anywhere in swkotor.exe. Comment specifically settles as “not read at all,” not merely “read and ignored.” TextureVar and BodyVariation are a related but distinct case: both strings genuinely exist in the binary, but their only cross-references are the item (.uti) loader and saver – a real field name on a different format, never read by any creature-related function, functionally just as dead for UTC purposes.

Two fields need pulling back out of the “confirmed dead” framing: BodyBag and Interruptable are genuinely read. Both are read live by ReadStatsFromGff via an ordinary carry-over ReadFieldBYTE call and stored into real members (creature->body_bag, this->interruptable). Neither is in this page’s own UTC-007 lint list, so there’s no existing contradiction to fix – but don’t assume UTC’s Interruptable shares the fate of the identically-named, confirmed-dead Interruptable field already documented on UTD/UTP; it’s a different field on a different format, and this one is live. Whether the values these two store are ever consumed downstream (combat/AI logic) wasn’t traced in this pass.

The 14 Script Hooks Default to "default", Matching UTD/UTT

All 14 (ScriptHeartbeat, ScriptOnNotice, ScriptSpellAt, ScriptAttacked, ScriptDamaged, ScriptDisturbed, ScriptEndRound, ScriptDialogue, ScriptSpawn, ScriptRested, ScriptDeath, ScriptUserDefine, ScriptOnBlocked – not ScriptBlocked – and ScriptEndDialogue, truncated on-disk to ScriptEndDialogu by the 16-byte GFF label limit) follow the identical mechanism already confirmed for doors and triggers: CSWSCreature’s constructor pre-arms all 14 script slots to the literal string "default" before any GFF read happens, and each read’s own fallback is the slot’s current value – so an absent hook resolves to "default", not empty. Confirmed for both entry points: LoadFromTemplate (fresh .utc blueprint load) and LoadCreature (save-reload), with no re-arming between construction and either load path.

Skills, Classes, and Powers: Presence Chains Down to the Individual Entry

UtcSkills. SkillList isn’t 8 individually-labelled fields – it’s a GFF list of 8 positional entries, each carrying one Rank byte, matching skills.2da row order. If SkillList is entirely absent, the whole block is skipped and the object’s skill ranks stay at whatever they already held (all-zero on a fresh blueprint load). If SkillList is present at all – even as an empty list – every one of the 8 positions is first force-zeroed, then each position missing its own list entry gets a default computed live from the engine’s own skill-check function: ability modifier plus any already-applied feat bonus, not a flat 0 (the raw component is 0 at this point, so that’s what the derived default reduces to in practice, but the mechanism is genuinely sibling-derived, not a literal). Absent and present-but-empty look identical on a fresh template, but diverge on an object with pre-existing nonzero ranks – absent leaves them untouched, present-but-empty wipes them.

ClassList entries. Class carries over the slot’s existing class id, applied only if the field was present and doesn’t resolve to the -1/NONE sentinel – otherwise the slot’s existing id stands untouched. A resolved-but-out-of-range class id crashes with the same 0x5f7 error code already documented for duplicate classes, not a separate failure mode – worth folding into the existing crash-code table. ClassLevel also carries over, and its own read is gated: it’s only attempted if the slot already resolved to a valid (non-NONE) class earlier in the same pass. Freshly-constructed baseline values: slot 0 defaults to Soldier at level 1, slot 1 to NONE at level 0.

Per-class powers (KnownList0) are read by a separate function, not inside the ClassList loop. CSWSCreatureStats::ReadSpellsFromGff runs after ReadStatsFromGff returns, from both LoadFromTemplate and LoadCreature, and re-walks ClassList independently. It confirms directly (not just as an observed file convention) that the per-class known-power list label is always literally built as "KnownList" + 0, regardless of which class index is being processed. An absent or empty KnownList0 simply leaves that class with zero known powers – no abort. Within a present list, each power’s Spell field defaults to the sentinel 0xFFFF; when a power resolves to that sentinel (explicit or absent), the whole power entry is skipped and never appended – a presence-chain abort at the individual-power level, not a defaulted 0 power. This is a real divergence from rakata’s current code: parse_known_list in crates/rakata-generics/src/utc.rs currently defaults a missing Spell to 0 and still pushes that as a power, where the engine would have silently dropped the entry instead.

A related but distinct read lives inside the same ClassList loop (not ReadSpellsFromGff): a Jedi-only SpellsPerDayList/NumSpellsLeft block for uses-per-day bookkeeping. An absent list is a soft no-op, and only the first entry of that list is ever actually applied – any further entries are read but discarded.

SpecAbilityList entries. Spell, SpellFlags, and SpellCasterLevel each independently default to a literal 0, unconditional, no presence gate on any of the three. An entry is appended as soon as the list-element fetch itself succeeds – there’s no scenario where a kept entry gets dropped for missing scalar fields, matching and sharpening the page’s existing “unconditionally appends… no deduplication” description with the actual defaults.

FeatList entries. Feat defaults to 0, but the add is gated on presence: AddFeat is only called if the field was actually present, so an absent Feat contributes nothing at all for that list position – a presence-chain abort scoped to the single entry, confirmed unambiguously via an identical read idiom used elsewhere in the same function (the per-level FeatList inside the PC LvlStatList loop), even though the top-level call site’s own presence-flag register couldn’t be resolved with full certainty from the decompiler output alone.

Item Lists: EquippedRes/InventoryRes Absence Drops the Whole Entry

Equip_ItemList is one flat GFF list, not per-slot numbered fields (Equip_ItemList0/1/… don’t exist) – the equip slot itself is the list element’s own struct-id, read structurally off the GFF element header rather than any field, so it has no “absent” state to document; rakata’s existing slot_id modeling is already correct.

Both EquippedRes (on Equip_ItemList) and InventoryRes (on ItemList) share the same fate on absence: presence-gated, and if the field is missing, or present but doesn’t resolve to a real .uti blueprint, the freshly-allocated item object is destroyed on the spot and the loop moves on – a genuine presence-chain abort. A resref-less entry is dropped entirely, not kept with an empty resref. Dropable is unconditional on both lists: a literal 0 (not droppable) stamped regardless of presence, no gating.

One thing that looks like an absent-field question but isn’t: if an equipped item fails the CanEquipItem slot check after loading successfully, it isn’t discarded – it’s rerouted into the creature’s backpack instead. That’s a post-load routing decision, not a defaults question.

Repos_PosX/Repos_PosY are never read anywhere in the creature item-loading call graph – confirmed by decompiling every function that touches Equip_ItemList/ItemList entries for a creature, and by a binary-wide string search. The only code that reads either label at all is a different function entirely (ReadContainerItemsFromGff, serving placeable/store containers, i.e. UTP/UTM), not anything reachable from a creature load. So on the creature path specifically, these two fields are structurally inert – stronger than “usually absent,” genuinely unread regardless of what a hand-authored file supplies. Worth knowing too: the only casing that exists as a string anywhere in the binary is Repos_PosX and lowercase Repos_Posy – there is no Repos_PosY (uppercase Y) string in swkotor.exe at all, on any object type.

What actually can drop an item entry entirely, on the save-reload path only (LoadCreature, unreachable from a standalone .utc blueprint load): each entry can carry an ObjectId pointing at an already-instantiated item object, and the loader silently skips the entry if that item’s live possessor doesn’t match the creature currently being loaded – no equip, no backpack add, nothing. This plausibly the origin of the “spawns dead” framing (items reassigned to a corpse/loot container after death would trigger exactly this mismatch), but the actual mechanism is narrower and different: a stale-possessor check specific to save-reloads, not a hit-points-driven rule, and it never fires on a fresh .utc blueprint spawn at all.

Gold: Party Members Don’t Round-Trip It

Gold is written for every creature, but on load the engine skips the read for anyone currently in the party: a party member’s wealth lives in the shared PT_GOLD pool in PARTYTABLE.res, and the per-member snapshots are frozen copies the loader deliberately ignores. Editing a party member’s Gold in a save does nothing – edit PT_GOLD instead. Ordinary NPCs, merchants, and corpses round-trip Gold normally. The full routing design, including how the writer freezes those per-member copies, is covered in Gold and the party pool.

DetectMode: A Genuine Round-Trip Bug

Unlike the write-only fields above, DetectMode looks like it should round-trip and doesn’t, and this one reads like an honest bug rather than a design choice. SaveCreature writes the live detect-mode value faithfully. On load, LoadCreature reads a DetectMode byte from the save struct just to advance past it; the value is never assigned to anything, and construction-time logic resets every restored creature to detect mode 1 regardless of what the save contained. This is an engine quirk to be aware of, not something rakata should “correct” on read; the on-disk value is real and byte-accurate, the engine’s own loader simply never consumes it.

JoiningXP: Only Restored on Fresh Spawns

JoiningXP shares the same shape as the DetectMode bug. SaveCreature writes it on every save, but only LoadFromTemplate (the fresh-spawn path used for template-based creatures) reads it back. LoadCreature, the loader used for ordinary save-game continuation, never reads JoiningXP at all, so it silently resets to 0 every time a save is reloaded.

Structural Fields Written Only When Live

FollowInfo (party-follow state) and ExpressionList (listen/expression data) are only written by SaveCreature when the corresponding live pointer or list is actually populated. Their absence from a save isn’t a defaults question so much as a statement that there was no runtime state to save in the first place; on load, an absent struct just means that piece of party-follow or listen-data state stays unallocated.

A few more fields depend on runtime conditions at save time rather than always being present:

As a minor aside: the per-level and per-class known-spell lists are always labelled KnownList0 / KnownRemoveList0 in the GFF, literally suffixed with the digit zero rather than substituting the level or class index. Reader and writer agree on this, so it’s internally consistent rather than a bug, just an oddity worth knowing if you’re ever diffing raw GFF structs by hand.

Legacy & Ignored Data

Vanilla Data Anomalies

Corpus surveys of the K1 GOG .utc set surface two anomalies in the SpecAbilityList field. Both are vanilla data quirks rather than decoder bugs; the structural reader represents them faithfully.

Stacked SpecAbilityList entries on the Bastila variants

Six Bastila .utc templates (bastila00c, p_bastilla, p_bastilla001, p_bastilla003, p_bastilla005, p_bastilla006) each carry 99 identical entries of Spell = 52 (SPECIAL_ABILITY_BODY_FUEL) in their SpecAbilityList. The engine’s loader (the SpecAbilityList block of CSWSCreatureStats::ReadStatsFromGff at 0x005afce0) walks each list element and unconditionally appends (Spell, SpellFlags, SpellCasterLevel) to the in-memory special_abilities_ array; there is no deduplication step. Each of the 99 entries occupies its own array slot with independent SpellFlags and SpellCasterLevel, so the stacking is faithfully preserved at runtime.

The loop iteration count itself is taken from CResGFF::GetListCount masked down to a single byte, so any UTC with more than 255 SpecAbilityList entries would have its tail silently truncated at load. Bastila’s 99 sits comfortably below that cap.

Out-of-range Spell id on the partymember template

The partymember.utc template references Spell = 299. Vanilla K1 spells.2da has 132 rows (0–131), so 299 does not resolve to any row. The SpecAbilityList loader does not validate Spell against spells.2da at load time; the value is stored verbatim in the in-memory entry. spells.2da is itself read into a per-row struct array sized exactly to row_count (CSWClass::LoadSpellsTable at 0x005be4c0), so a use-time lookup of Spell = 299 indexes past the end of that array. The realised behaviour depends on heap layout at runtime and is not deterministic from the load path alone.

Both anomalies are candidate targets for future Phase 2 / Phase 3 UTC lint rules (e.g., “SpecAbilityList[].Spell must resolve to a row in spells.2da”; optionally “warn on stacked-duplicate SpecAbilityList entries unless explicitly whitelisted as a known vanilla pattern”).

Implemented Linter Rules (Rakata-Lint)

Phase 1 (intra-resource, no context)

Implemented under rakata_lint::rules::utc.

1. UTC-001 (Appearance Correction): Warns when Appearance_Head == 0; the engine forces this to 1 at runtime.
2. UTC-002 (Class Limit): Warns when more than 2 entries appear in ClassList; the engine ignores classes beyond the second.
3. UTC-003 (Class Duplications): Errors when duplicate class IDs exist in ClassList; causes a fatal engine crash (0x5f7) on load.
4. UTC-004 (Dead Save Fields): Informs when SaveWill or SaveFortitude are populated; the engine reads willbonus/fortbonus instead.
5. UTC-005 (Gender Clamp): Warns when Gender > 4; the engine clamps to a maximum of 4.
6. UTC-006 (GoodEvil Clamp): Warns when GoodEvil > 100; the engine clamps to a maximum of 100.
7. UTC-007 (Toolset / Legacy Fields): Informs when any of Comment, Morale*, PaletteID, BodyVariation, TextureVar, BlindSpot, MultiplierSet, NoPermDeath, IgnoreCrePath, Hologram, WillNotRender, or LawfulChaotic are set; never read by the K1 engine.

Phase 2 (range / 2DA / resref existence, requires LintContext)

Implemented under rakata_lint::rules::utc_range.

8. UTC-008 (Race Bounds): Errors when Race does not resolve to a row in racialtypes.2da; engine crash 0x5f4 on load.
9. UTC-009 (Class Bounds): Errors when any ClassList[].Class does not resolve to a row in classes.2da (or is negative); engine load failure.
10. UTC-010 (Appearance Bounds): Errors when Appearance does not resolve to a row in appearance.2da; engine renders missing model.
11. UTC-011 (Portrait Bounds): Errors when PortraitId (when not the 0xFFFE “use string Portrait” sentinel) does not resolve to a row in portraits.2da.
12. UTC-012 (Resref Existence): Warns when Conversation (.dlg), Portrait (.tga), any of the 14 Script* hooks (.ncs), Equip_ItemList[i].EquippedRes (.uti), or ItemList[i].InventoryRes (.uti) does not resolve in the configured resource sources.

UTD Format (Door Blueprint)

Description: The Door (.utd) blueprint defines interactive pathways on a level map. Beyond acting as physical barriers or transitions between areas, doors house lock mechanics, trap configurations, script hooks, and basic visual states (open, destroyed, jammed).

At a Glance

Data Model Structure

Rakata maps a Door into the rakata_generics::Utd struct. The struct’s Rustdocs document every field’s binary schema and GFF mapping; the table below is the high-level anatomy.

rakata-lint validates these fields against the engine constraints documented below.

Engine Audits & Decompilation

The following information documents the engine’s exact load sequence and field requirements for .utd files mapped from swkotor.exe.

(Decompilation logic for this section was entirely audited and verified via native Ghidra pipeline against swkotor.exe, explicitly pulling from the shared field-reading routine CSWSDoor::LoadDoor at 0x0058a1f0; see “Save versus Template Load Paths” below for the actual top-level dispatcher.)

Structural Load Phasing

The engine processes a Door structurally by mapping its sub-fields into distinct operational constraints.

Save versus Template Load Paths

A single UseTemplates flag, forwarded down from the area loader, decides how a door’s fields get populated on load. The actual branch point is CSWSDoor::LoadDoorExternal (0x0058c7ca), the true top-level dispatcher; LoadDoor (0x0058a1f0) is the shared field-reading routine both branches ultimately call. When the flag is clear, LoadDoorExternal calls LoadDoor directly on the door’s full instance snapshot out of the savegame; every field is already sitting in that struct. When the flag is set, LoadDoorExternal calls CSWSDoor::LoadFromTemplate (0x0058b468), which reads TemplateResRef, opens the referenced .utd blueprint, and calls the same LoadDoor against the blueprint’s own struct. Because a blueprint has no idea which specific instance it belongs to, four instance-only fields – TransitionDestin (the on-disk, 16-byte-truncated label for what the engine’s own source calls TransitionDestination; both names refer to the same field, see the note below), LinkedTo, LinkedToFlags, and LinkedToModule – are overlaid back onto the freshly-loaded door from the original save instance immediately afterward, back in LoadDoorExternal. This overlay is unconditional whenever the template branch is taken and the blueprint load succeeds; the only way to skip it is for the blueprint load itself to fail (an empty or unresolvable TemplateResRef), which aborts the whole door load rather than merely skipping the overlay.

LoadDoor itself makes no distinction between the two callers: its read of TransitionDestin runs unconditionally regardless of whether the struct it was handed is the blueprint’s or the save instance’s. So on a template-backed door, the field genuinely is read off the blueprint – it just never gets a chance to matter, because LoadDoorExternal’s overlay overwrites it with the save instance’s value immediately after LoadDoor returns. A hand-authored .utd carrying TransitionDestin would have it read the same way, and then discarded the same way.

Tag is a fifth field with instance-only stakes, but it isn’t overlaid. LoadDoor contains the only Tag read in the entire door-load call graph, so on a templated door Tag comes from the blueprint, exactly like Appearance or HP – and unlike the four fields above, nothing in LoadDoorExternal re-reads Tag from the placed instance afterward. That’s a real gap in the instance-overlay mechanism, not a documentation omission: multiple doors sharing one .utd blueprint would share one Tag, which would break any script that targets a door by tag. In practice this doesn’t bite, because the vanilla toolset works around it at the content level rather than the engine level – real modules generally give each placed door its own dedicated .utd, one blueprint per instance, rather than truly sharing a single template across multiple doors. A corpus scan bears this out: every door instance in a full install carries a real, distinct TemplateResRef value. The mechanism is technically “templated,” but the authoring convention makes it behave like one blueprint per door in practice.

This isn’t a door-specific quirk: every templated GIT object type behaves identically. See GIT’s “The Blueprint’s Tag Always Wins” for the general pattern across Placeables, Triggers, Sounds, Stores, Encounters, Creatures, and Items.

Core Structural Findings

The CSWSDoor parser natively guarantees strict state adjustments upon parsing.

Absent-Field Defaults: Most Are Simple, A Few Are Not

The governing mechanism across LoadDoor is a CResGFF::ReadField* call that takes a fallback argument: sometimes that fallback is the object’s own current member value (a true carry-over from whatever the constructor set), sometimes it’s a fresh literal constructed at the read site that ignores the current member entirely. Both look identical in the decompiled store, so which one applies has to be checked per field, not assumed from the value alone.

All 15 script hooks default to the literal string "default", not an empty resref. This is the standout finding on this page: the CSWSDoor constructor explicitly loops over all 15 script-slot members (OnClosed, OnDamaged, OnDeath, OnDisarm, OnHeartbeat, OnLock, OnMeleeAttacked, OnOpen, OnSpellCastAt, OnTrapTriggered, OnUnlock, OnUserDefined, OnClick, OnFailToOpen, OnDialog) and assigns each the literal string "default", not an empty string. Every hook read is a carry-over of that constructed value: an absent hook resolves to whatever the member currently holds, which on a fresh load is "default". This is the actual mechanism behind the already-documented OnTrapTriggered fallback rule (“empty, null, or literally "default"” routes to traps.2da) – it exists specifically because an absent OnTrapTriggered naturally becomes "default" through this carry-over, not because the engine special-cases three different absent-value spellings. The other 14 hooks have no such secondary lookup: they simply keep the literal resref "default", which won’t resolve to a real .ncs unless a module happens to ship one named exactly that.

TrapType’s absent default is the sentinel 0xFF (255), not 0, and it can chain into an out-of-range lookup. Combined with the OnTrapTriggered-absent-becomes-"default" carry-over above: a door missing both TrapType and OnTrapTriggered ends up looking up row 255 of traps.2da, which almost certainly doesn’t exist in vanilla data. That’s an out-of-range 2DA lookup, not a clean “no trap configured” state – worth a lint rule of its own, distinct from the already-flagged OnTrapTriggered fallback.

Lockable defaults to 0 – a door is not lockable unless the file says so. Same carry-over mechanism as most fields here (constructor sets lockable = 0), but worth calling out explicitly since “lockable by default” is the more intuitive assumption for a door.

HP (maximum) carries over a constructed default of 1, not 0. A freshly constructed door object nominally has 1 hit point before any GFF read touches it; an absent HP field leaves it there.

Hardness, Static, and LoadScreenID use a fresh literal 0, not carry-over – distinct mechanism, same value. Where most numeric fields on this page pass the object’s current member as the read’s fallback, these three pass a hardcoded 0 regardless of what the constructor set (which also happens to be 0 for Hardness/Static, so the observable value is identical either way – only the mechanism differs, and it would matter if the constructed defaults ever diverged from 0).

Plot and Invulnerable are entangled, and the gating condition genuinely couldn’t be resolved. LoadDoor reads a field literally named "Invulnerable" first (carry-over fallback: this->object.plot, constructor default 0), then conditionally reads a field named "Plot" with the identical carry-over fallback, potentially overwriting the first result. The condition gating that second read traces to a stack value with no discoverable prior write inside LoadDoor or its two known callers – genuinely unresolved, not just unchecked. What’s certain regardless of which branch fires: both reads share the same fallback, so an absent Plot and an absent Invulnerable both resolve to 0 (not plot) – unless Static is present and true, which forces the final value to 1 regardless, per the already-documented Static-enforcement rule. Worth flagging on its own: Invulnerable is not part of the documented UTD schema and isn’t written by the vanilla toolset, but the engine genuinely reads it if a file supplies it – a live field with no prior mention on this page.

OpenState carries a dead-in-practice override. The field itself carries over normally (constructor default 0), but the read result then feeds a check that can force it to a hardcoded 3 – gated on an internal flag the constructor sets to 1 and that nothing observed inside LoadDoor ever resets to 0 before a load runs. Under the normal construct-then-load flow this override never fires, so OpenState absent resolves to the plain carried-over 0 in practice; flagged here in case some other, unexamined path resets that flag first.

The remaining fields all follow the ordinary carry-over pattern with unremarkable constructed defaults: Faction/GenericType/AutoRemoveKey to 0, Bearing to 0.0, KeyRequired/OpenLockDC/CloseLockDC/SecretDoorDC/Fort/Ref/Will/DisarmDC/TrapDetectDC/TrapFlag/Min1HP to 0, Locked to 0 (unlocked), TrapDetectable/TrapDisarmable/TrapOneShot to 1 (true) – and a handful default to a fresh literal rather than carrying over, with the same practical value: LocName/Description to an empty localized string (a throwaway default-constructed value at the read site, not this->name/this->description), Conversation to an empty resref, Tag to an empty string (the one string field routed through SetTag rather than a plain assignment, carry-over of the constructor’s own "").

Legacy & Ignored Data

Implemented Linter Rules (Rakata-Lint)

Phase 1 (intra-resource, no context)

Implemented under rakata_lint::rules::utd.

1. UTD-001 (Static Parity): Warns when Static=true but Plot=false; the engine forces Plot to true at runtime.
2. UTD-002 (HP Bounds): Errors when CurrentHP > HP; the engine clamps to HP on template load.
3. UTD-003 (Portrait Shadowing): Warns when PortraitId < 0xFFFE and Portrait resref is set; the resref is ignored at runtime.

Phase 2 (range / 2DA / resref existence, requires LintContext)

Implemented under rakata_lint::rules::utd_range.

4. UTD-004 (Generic Door Type Bounds): Errors when GenericType does not resolve to a row in genericdoors.2da; engine renders missing model.
5. UTD-005 (Portrait Bounds): Errors when PortraitId (when not the 0xFFFE “use string Portrait” sentinel) does not resolve to a row in portraits.2da.
6. UTD-006 (Resref Existence): Warns when Conversation (.dlg), Portrait (.tga), or any of the 15 On* script hooks (.ncs) does not resolve in the configured resource sources. LinkedToModule (area transition) is deferred to Phase 3.

Pending

• Appearance Truncation: Flags legacy Appearance (u32) values above 255 (engine truncates to a single byte).
• Trap Hook Fallback Detection: Scans for empty / null / literally-named "default" OnTrapTriggered references that silently invoke the traps.2da fallback.
• Portrait Zero Hardcode: Detects PortraitId == 0 mappings since the engine hardcodes lookup to 0x22E.

UTE Format (Encounter Blueprint)

Description: The Encounter (.ute) blueprint defines interactive spawn points and boundary triggers across a level map. Instead of acting merely as a spatial zone, encounters handle complex difficulty scaling, bubble-sort creature limits, and explicit coordinate vertices to dynamically deploy combatants when a player crosses their geometry bounds.

At a Glance

Data Model Structure

Rakata maps an Encounter into the rakata_generics::Ute struct. The struct’s Rustdocs document every field’s binary schema and GFF mapping; the table below is the high-level anatomy.

rakata-lint validates these fields against the engine constraints documented below.

Engine Audits & Decompilation

The following information documents the engine’s exact load sequence and field requirements for .ute files mapped from swkotor.exe.

(Decompilation logic for this section was audited and verified via native Ghidra pipeline against swkotor.exe, explicitly pulling from the primary dispatcher CSWSEncounter::LoadEncounter at 0x00593830.)

Structural Load Phasing

The engine processes an Encounter structurally across several chunked subroutines, each responsible for unique spatial and logic bindings.

ReadEncounterFromGff and ReadEncounterScriptsFromGff are shared verbatim between two callers: the save-game path reads them straight off the area’s GIT struct, while the blueprint/template path reads the same fields off the .ute file’s own top-level struct. There is no UseTemplates branch inside the field readers themselves; the fork only decides which file supplies the struct.

Runtime Fields Are Read on the Blueprint Path Too

NumberSpawned, HeartbeatDay, HeartbeatTime, LastSpawnDay, LastSpawnTime, LastEntered, LastLeft, Started, Exhausted, CurrentSpawns, CustomScriptId, AreaListMaxSize, SpawnPoolActive, AreaPoints, plus the SpawnPointList, AreaList, and SpawnList lists, all read as one contiguous, unconditional block inside ReadEncounterFromGff. None of them sit behind a source-type check; the function reads whatever the struct it was handed contains, blueprint or GIT instance alike.

The actual blueprint-versus-instance fork lives two calls up, in CSWSArea::LoadEncounters (0x00505060): with no template, it calls CSWSEncounter::LoadEncounter (0x00593830) directly on the GIT instance struct; with a template, it opens the .ute named by the instance’s TemplateResRef and calls CSWSEncounter::LoadFromTemplate (0x00593a90), which runs ReadEncounterFromGff against the blueprint’s own struct. Afterward, LoadEncounters re-reads position, Geometry, and SpawnPointList a second time from the GIT instance as overrides – but the runtime-tracking scalars, AreaList, and SpawnList are not among the re-read fields, so whatever a template supplies for those would stand as read, with no instance-level override mechanism at all.

Practically: the corpus-observed absence of these fields from every vanilla .ute is an authoring-tool habit, not an engine restriction. A hand-authored .ute carrying them would have every one read and applied on the ordinary template-load path. One authoring hazard worth flagging: AreaList’s read allocates its buffer using AreaListMaxSize, itself one of the fields read from the same struct just above it – a file that supplies AreaList entries without a large enough AreaListMaxSize would size the destination buffer too small, with nothing in the loader stopping the read.

Absent-Field Defaults

Every scalar field ReadEncounterFromGff/ReadEncounterScriptsFromGff reads shares one idiom: the read call’s own “default if absent” argument is the field’s already-constructed value on the object, and the result is stored back with no visible branch on presence. Functionally this is a carry-over, not a fresh literal stamp, even though the assignment itself always executes – an absent field always resolves to whatever a freshly constructed CSWSEncounter already held for that member:

XPosition/YPosition/ZPosition follow the same self-default read, but with an extra step: the constructor sets the encounter’s position to the origin via SetPosition, each coordinate is individually read against its own current value, and the assembled vector is then unconditionally passed through SetPosition again. So an absent position doesn’t just leave the origin untouched in isolation – it’s carried over and then re-stamped, landing on the same origin either way. (This is the read LoadEncounters’ own instance-level position override, mentioned above, layers on top of.)

Core Structural Findings

The engine rigorously evaluates geometric and spatial boundaries. Improper definitions break the spawn mapping algorithm.

Warning

Understanding Fatal Log Drops While minor coordinate math errors usually just cause creatures to spawn inside walls, failing strict geometry constraints causes KOTOR to abruptly abort parsing the Encounter. Specifically, if a .ute file declares it has geometry boundaries but fails to provide the actual coordinate vertices, the engine dumps a fatal error to its trace log and refuses to spawn the encounter at all.

Legacy & Ignored Data

Implemented Linter Rules (Rakata-Lint)

Phase 1 (intra-resource, no context)

Implemented under rakata_lint::rules::ute.

1. UTE-001 (Dead Difficulty Traces): Warns when Difficulty > 0 while DifficultyIndex >= 0; the engine ignores the static Difficulty in favor of the 2DA lookup.
2. UTE-002 (Deficient Spawn Loops): Warns when an encounter is marked Active=true but CreatureList is empty.
3. UTE-003 (Dead Field Evaluation): Informs when TemplateResRef, Comment, or PaletteID are populated; never read by the K1 engine.
4. UTE-004 (Geometry Integrity Risk): Warns when Geometry has 0 vertices; an explicitly defined empty geometry array crashes the engine on load.

Phase 2 (resource existence, requires LintContext)

Implemented under rakata_lint::rules::ute_range.

5. UTE-005 (Resref Existence): Warns when any of OnEntered, OnExit, OnHeartbeat, OnExhausted, or OnUserDefined (.ncs) does not resolve, or when any CreatureList[i].ResRef (.utc) does not resolve in the configured resource sources.

UTI Format (Item Blueprint)

The Item (.uti) blueprint serves as the central data model for all tangible loot, weapons, armor, and usable gear in the game. It defines how an item physically appears on characters, what custom properties or stat bonuses it applies through specific upgrade hierarchies, its intrinsic monetary cost, and exactly what its runtime state behaves like when dropped into the world map.

At a Glance

Data Model Structure

Rakata maps an Item into the rakata_generics::Uti struct. The struct’s Rustdocs document every field’s binary schema and GFF mapping; the table below is the high-level anatomy.

rakata-lint validates these fields against the engine constraints documented below.

Engine Audits & Decompilation

The following information documents the engine’s exact load sequence and field requirements for .uti files mapped from swkotor.exe.

(Decompilation logic for this section was entirely audited and verified via native Ghidra pipeline against swkotor.exe, explicitly pulling from the primary dispatcher CSWSItem::LoadDataFromGff at 0x0055fcd0, the active-property predicate CSWSItem::IsFriendlyUsableItem at 0x00553900, the property-string resolver CSWSItem::GetPropertyStrings at 0x00554e00, and the IPRP table loaders CTwoDimArrays::LoadIPRPCostTables at 0x005c4730 / LoadIPRPParamTables at 0x005c49c0.)

Structural Load Phasing

The engine processes an Item structurally across multi-pass capabilities mappings.

Core Structural Findings

The engine rigorously evaluates base-item mapping constraints from 2DA arrays and aggressively overrides improperly defined models.

Most of the remaining top-level fields default to a carried-over constructed value rather than a fresh literal, in the same “read’s own default argument is the object’s current member” mechanism documented elsewhere on this page: BaseItem carries over to 30, LocalizedName/Tag to empty, StackSize to 1, Plot/Stolen/NonEquippable/NewItem/DELETING to false, and AddCost/Upgrades to 0. TextureVar is the one exception among these – when it’s actually consulted at all (base item’s model_type == 1), it’s read with a hardcoded literal default of 1, unconditional, not a carry-over.

PropertiesList Scalars: Six of Seven Default to Uninitialized Memory, Not Zero

PropertyName, Subtype, CostTable, CostValue, Param1, Param1Value, and ChanceAppear each get read with a literal default of 0 passed to the read call – but that 0 is never actually committed if the field is absent. Each of the seven writes is individually gated on its own presence flag, checked field-by-field right before the property struct member is set. Because the property array itself comes from a raw, unzeroed allocator, an absent field on an otherwise-populated PropertiesList entry doesn’t resolve to 0 at all – it leaves that struct member holding whatever was already sitting in that heap memory. This is a real correctness hazard, not just a documentation nuance: a linter (or a decoder) that assumes “absent property field reads as 0” is wrong for all seven of these, and should instead flag partially-specified property entries as producing undefined values.

(Note also: rakata models PropertyName as an INT-typed field, but the engine actually reads it with a 16-bit WORD read, same as Subtype and CostValue.)

Useable, UsesPerDay, and UpgradeType (already documented above) are the exception: those three are stamped unconditionally with no presence gate on the write, so they’re the only fields in a PropertiesList entry that are genuinely deterministic when absent.

A related edge case at the entry level, distinct from the per-field gating above: if a PropertiesList entry’s own struct is completely empty (zero fields at all, not just one missing label), the engine’s counting pass folds it into the passive tally, but the populate pass then skips writing it entirely once it reaches that entry. The property array was sized assuming that entry would be populated, so the slot it would have occupied is left as the same kind of uninitialized heap memory described above – an entirely empty entry doesn’t drop cleanly, it leaves a hole.

Property Table Dispatch

A UtiProperty carries three indices that point through three separate registry-of-registries chains. The engine holds no hardcoded mapping for any of them; every dispatch is a 2DA cell read, so mods that extend the underlying tables surface without engine modification.

Per-property subtype dispatch (resolved at display time inside GetPropertyStrings at 0x00554e00):

Cost-table dispatch (resolved eagerly at startup inside LoadIPRPCostTables at 0x005c4730):

Param-table dispatch (resolved eagerly at startup inside LoadIPRPParamTables at 0x005c49c0):

Engine constraints:

• Both iprp_costtable.2da and iprp_paramtable.2da row counts are stored as byte (u8) in CTwoDimArrays. Rows past index 255 are silently truncated by the loader and the affected per-property tables never get loaded into memory.
• Column-name lookups in 2DAs are case-sensitive at the engine API (C2DA::GetINTEntry / GetCExoStringEntry compare verbatim). The exact spellings the engine uses are Name, SubTypeResRef, TableResRef, Label, and ClientLoad.
• The subtype 2DA listed in SubTypeResRef is loaded lazily on display via GetPropertyStrings, not eagerly at startup. A missing subtype 2DA fails only the call that needs it, not the whole game load.
• The Name column on every level of the dispatch is a TLK strref. The Label column on the same row holds a developer-readable identifier (e.g. Damage_Bonus) that does not require talktable resolution.

Cost-Table Magnitude Resolution

The cost-table dispatch chain documented above ends at “the row at CostValue carries the cost effect for this property; column layout varies per cost table.” This section pins down the column layout for vanilla K1’s iprp_costtable.2da entries and how each Apply<PropertyKind> handler reads from them, sourced from the CSWSItemPropertyHandler::Apply* family in swkotor.exe (handlers cluster around 0x004e5490-0x004e7e80 and 0x004e9230-0x004e9390).

iprp_costtable.2da (vanilla K1) — index to per-cost 2DA mapping:

Per-handler magnitude resolution. Each Apply<Kind> handler that needs a cost-table magnitude calls CTwoDimArrays::GetIPRPCostTable(<index>) then C2DA::GetINTEntry(table, row=CostValue, column, out). The integer that comes back is the engine-side magnitude (in the units appropriate to the property kind: bonus number, damage soak amount, save delta, etc.). The column name is read case-sensitively; the only two columns the vanilla handlers consult are Value and Amount.

Handlers that bypass the cost-table dispatch. A surprising number of vanilla handlers do not call GetIPRPCostTable at all and instead consume CostValue (or another property field) directly as the magnitude:

• ApplyDamageBonus (covers PropertyName 11 Damage, 12 DamageAlignmentGroup, and 13 DamageRacialGroup in one switch) reads CostValue straight as the damage amount. There is no per-cost 2DA lookup. The iprp_damagecost.2da table is used for cost calculation (GetCost), not for damage-magnitude resolution.
• ApplyEnhancementBonus and ApplyAttackBonus read (Rules->internal).all_2DAs->iprp_meleecost via direct struct-field access (not through GetIPRPCostTable), then read column Value. Equivalent to a cost-table-index 2 (iprp_meleecost) dispatch, just inlined.
• ApplySkillBonus and ApplyBonusFeat read the magnitude / feat id from the property struct directly.
• ApplyImmunity switches on the subtype id and assigns one of ten hardcoded engine constants; no 2DA is consulted.
• ApplyRegeneration uses CostValue as the regen amount and a hardcoded 6000 ms tick interval; no 2DA.

Implications for decoded magnitude resolution. A decoder that resolves property magnitudes should:

1. First check whether the property kind is on the cost-table list above; if yes, read the resolved magnitude from the listed cost 2DA at row CostValue, column Value or Amount, with the documented post-processing.
2. If the property kind is on the bypass list, the magnitude is CostValue directly (or, for ApplyImmunity, hardcoded per subtype).
3. For ApplyDamageImmunity, the cost-table index is read from the property’s own CostTable field rather than being hardcoded per handler; mod-extended cost tables resolve through the same path.

Vanilla itempropdef.2da Label Reference

The following table lists every label in the vanilla K1 itempropdef.2da. The decoder in rakata_generics::decoded matches on the Label column at the row indexed by UtiProperty::property_name. The Subtype 2DA column is the file’s SubTypeResRef cell verbatim (lowercased per the engine’s case-insensitive resref handling); an empty cell means the property has no subtype dimension.

The four rows the engine treats as active (loaded into the per-character usable-ability table per IsFriendlyUsableItem) are marked. Every other row is passive.