Skip to content

Home

Jump to bottom Edit New page
Benjamin Auquite edited this page Mar 24, 2026 · 47 revisions

Welcome to the PyKotor Wiki

Documentation

Start here: New to modding? Installing Mods with HoloPatcher → Mod Creation Best Practices → File formats and specifications or TSLPatcher guides as needed. Core terms: Concepts; format index and type IDs: Resource formats and resolution. Binary and engine-level detail: Low-level structures and implementations. Community sources and archives. Contributing: Wiki Conventions.

For End Users

Guides and tutorials

Installation, tool use, and step-by-step guides:

Holocron Toolset (in-app help):

Tutorials:

Scripting (NWScript): Function and constant reference for writing scripts. Full index and all routine/constant pages: NSS File Format. Quick links to major categories:

File formats and specifications

Reference for binary layout, field definitions, and format behaviour. For scripting usage see Scripting (NWScript) above; for implementation details see Low-level structures and implementations.

Official Bioware Aurora Documentation

The following documents are official Bioware Aurora Engine file format specifications. These are authoritative references for the underlying file formats used by KotOR:

Odyssey Engine Basics (KotOR)

The following information describes the resource system used by KotOR and TSL. While KotOR is derived from the Aurora engine (Neverwinter Nights) and shares the same resource system, this section focuses on KotOR-specific behavior and file locations. Some details (like nwn.ini) are NWN-specific and are noted as such.

Application lifecycle (KotOR and TSL)

Both games use the same high-level flow: the executable initializes an application manager, creates a server (game world) and client (rendering, input, UI), then runs a main loop that pumps window messages, updates the render window, and drives the Aurora/Odyssey subsystems. Resource loading follows the resource resolution order; the resource manager services requests from override, then module RIM/ERF capsules, then KEY/BIF. Reinitializing the Aurora engine (e.g. after resolution or display changes) reloads or refreshes core subsystems while preserving the same client/server split. Scripts (NCS) and dialogues (DLG) run in the server context; the client handles display, camera, and input and receives updates from the server.

Client and server: The Odyssey engine (like Aurora) separates a server (game world, rules, scripts, resources) from a client (rendering, input, UI). The server owns area state, creatures, items, and script execution; the client displays the world and sends input. This split is important for modding and for understanding NCS execution and resource resolution.

Important Files

  • chitin.key: Master index file that maps resource names to BIF containers locations. Given a resource name, chitin.key can be used to locate the master data file (BIF) containing the resource.
  • dialog.tlk: Text resource file containing localized strings referenced by StrRef IDs. This centralizes strings for easy localization and allows changing text without modifying or recompiling scripts. Different language versions of dialog.tlk can be installed for localization support.
  • kotor.ini: Configuration file with [Alias] section mapping logical directory names to physical paths. This allows the game to locate data files regardless of installation directory structure.

Reference: xoreos-docs (Mirror: th3w1zard1/xoreos-docs): specs/torlack/basics.html - Tim Smith (Torlack)'s Aurora engine basics documentation (NWN-focused)

Resource system (see Concepts)

File format index

The linked table of contents for format pages (2DA anchors, GFF variants, archives, media) lives on Resource formats and resolution together with ResRef / resource type and the hex resource type ID table. Narrative resolution order: Concepts.

Low-level structures and implementations

Binary layout, engine behaviour, and implementation details for developers and reverse engineering. These pages are conceptual summaries for the wiki (no raw tool dumps); see Wiki Conventions and AGENTS.md for project policy.

Vendor Implementations

PyKotor is not the first of its kind, below you'll find other KotOR tools, resources, projects, and even full engine rewrites.

Engine Reimplementations

Complete game engine rewrites that can load and play KotOR:

File Format Libraries

Libraries focused on reading/writing KotOR file formats:

  • xoreos-tools - Command-line tools for extracting and converting Aurora file formats (Mirror: th3w1zard1/xoreos-tools)
  • Kotor.NET - .NET library for KotOR file formats with builder APIs
  • BioWare.NET - Another .NET library for KotOR file formats, intended to be a direct port of PyKotor
  • Rakata - A rust-native codebase for working with the Odyssey engine.

3D Modeling Tools

Tools for working with KotOR 3D models and textures:

Script Development

Tools and Resources for working with NWScript in KotOR:

Modding Tools

Tools for creating and installing mods:

  • PyKotorCLI (PyKotor) - CLI-first toolset for packing, conversion, Holocron kit generation, and GUI layout scaling. uvx --refresh pykotor kit-generate --installation <path> --module <module> --output <dir> runs headless; launching with no arguments opens the Tkinter kit generator GUI for interactive use. uvx --refresh pykotor gui-convert --input <gui_or_folder> --output <dir> --resolution ALL runs headless for GUI resizing; omitting args opens the converter GUI. Developers: uv run --directory Libraries/PyKotor/src --module pykotor for local source. (Implementations: kit_generator.py wraps Libraries/PyKotor/src/pykotor/tools/kit.py; Libraries/PyKotor/src/pykotor/cli/gui_converter.py delegates to pykotor.resource.formats.gff.)
  • HoloPatcher.NET - .NET reimplementation of TSLPatcher
  • Kotor-Patch-Manager - Alternative mod manager (Mirror: th3w1zard1/Kotor-Patch-Manager)
  • ModSync - Mod synchronization and installation
  • StarForge - Module editor and modding toolkit
  • KotorModTools - Collection of modding utilities (Mirror: th3w1zard1/KotorModTools)

Save Editors

Tools for editing KotOR save games:

Audio Tools

Tools for working with KotOR audio:

Community Resources

Guides, patches, and community-maintained resources:

Community sources and archives

For complete, comprehensive, and accurate wiki coverage, the following community sites and archives hold historical and ongoing KotOR/TSL modding knowledge. Use them to cross-check format behavior, tool usage, and engine quirks.

Source Description Use for
DeadlyStream Primary KotOR modding hub: mod releases, tutorials, Script Shack, tool discussions. File format questions, TSLPatcher/HoloPatcher usage, nwscript.nss and animation references, override practices.
LucasForums Container Archive of original LucasForums (StarWarsKnights.com) threads, reconstructed from the Wayback Machine. TSLPatcher history and changelogs, Stoffe’s posts, format and tool discussions (2004–2007).
LucasForums Archive Alternative archive project (Editing/Modding, Holowan Laboratories, tutorials). TSLPatcher thread, KotOR tool docs, mod-finding threads.
Holowan Laboratories / Mixmojo Historical KotOR modding forums (MixNMojo/Mixmojo). Early format and tool discussions; some content may be in archives or mirrors.
Reddit (e.g. r/kotor) General KotOR community. Mod installation, troubleshooting, links to DeadlyStream and wiki.

Further reading (community):

How to use these sources:

  • DeadlyStream: Search the forums for specific topics (e.g. "override folder", "TSLPatcher 2DA merge", "GFF struct", "nwscript"). The Script Shack and modding tools sections contain tutorials and tool releases. When the wiki documents a format or tool, DeadlyStream threads often provide real-world modder reports (e.g. which 2DA columns are safe to add, TSLPatcher setup gotchas). Cite threads in "See also" or "Further reading" when they are the best source for a given detail.
  • LucasForums Container / LucasForums Archive: Use for historical and authoritative context. The original TSLPatcher thread (Stoffe, etc.), KotOR Tool discussions, and early GFF/2DA explanations live in these archives. Search by keyword (e.g. "2da", "GFF", "TSLPatcher") in the Editing/Modding or Holowan Laboratories sections. Content may be fragmented across Wayback reconstructions; when a thread is cited, prefer stable archive URLs.
  • Holowan / Mixmojo: Early KotOR modding community; some content is preserved in archives or linked from LucasForums. Use for very old format or tool history when other sources do not cover it.
  • Reddit (r/kotor): Useful for installation help, troubleshooting, and links to DeadlyStream or this wiki. For format or engine-level accuracy, prefer this wiki and the format pages; for "how do I install X" or "why does my mod conflict with Y", community posts can complement the docs.

This wiki aims to consolidate and cite that knowledge where relevant. When adding or refining format or tool pages, prefer linking to authoritative specs (e.g. KEY-File-Format, GFF-File-Format, official BioWare Aurora docs) and to PyKotor/vendor implementation paths; for community consensus or historical context, link to DeadlyStream threads or LucasForums archive threads where appropriate.

External Documentation

Reference documentation from related projects (external sources):

  • xoreos-docs - Aurora engine format documentation repository containing file format specifications for reverse-engineering BioWare's Aurora engine games (Mirror: th3w1zard1/xoreos-docs). Part of the xoreos project. The repository includes:

    • Official BioWare specifications (specs/bioware/): Official Aurora Engine file format PDFs from the now-defunct nwn.bioware.com developer site. These documents are authoritative references for formats used across Aurora engine games including KotOR.
    • Torlack's reverse-engineered specs (specs/torlack/): Tim Smith (Torlack)'s reverse-engineered format documentation from his now-defunct website (torlock.com). These include detailed field-by-field breakdowns for formats like BIF, KEY, ERF (MOD), GFF (ITP), NCS, and binary MDL files.
    • KotOR-specific documentation (specs/kotor_mdl.html): Partial KotOR model format specifications with detailed field descriptions.
    • Binary templates (templates/): 010 Editor binary template files for analyzing binary file structures

    Note: Much of the KotOR-relevant content from xoreos-docs has been comprehensively integrated into this wiki. See individual format documentation pages for specific source references.

  • nwn-docs - Neverwinter Nights documentation (shares Aurora formats)

  • bioware-kaitai-formats - Kaitai Struct format specifications for GFF, 2DA, BIF, ERF, TLK, and other BioWare/KotOR formats; useful for parser generation and cross-tool validation.

See also

Add a custom footer
Add a custom sidebar

Clone this wiki locally