Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Rakata

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

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

Requirements

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

Documentation Domains

Two: the Software API and the Format Specifications.

1. The Workspace (Code API)

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

Libraries (crates/)

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

Tools (tools/)

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

🔗 View Rakata Rustdocs

2. Format Specifications (This Wiki)

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

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

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