Skip to content

Home

Jump to bottom Edit New page
Benjamin Auquite edited this page Mar 23, 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. 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 resolution order below; the resource manager services requests from override, then module/ERF, 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 Resolution Order

The engine satisfies every resource request (by ResRef and type) in this order. See KEY File Format for how demand flows through the resource manager.

  1. Override folder (override/)
  2. Currently loaded MOD/ERF files
  3. Currently loaded SAV file (if in-game)
  4. BIF files via KEY lookup
  5. Hardcoded defaults

Resource Types

KotOR uses hexadecimal resource type identifiers derived from the Aurora engine and further expanded upon for its Odyssey engine. The following table lists resource types valid in the four BioWare engines. Due to this, some of these are obviously not supported in KotOR.

Resource Name type ID Description
RES 0x0000 Used for .res within the saves
BMP 0x0001 Bitmap image
MVE 0x0002 Movie/video file Not used in KotOR
TGA 0x0003 TarGA image format
WAV 0x0004 Wave audio file (see WAV File Format)
INI 0x0007 Configuration file (e.g., swkotor.ini, swkotor2.ini)
BMU 0x0008 Unknown Not used in KotOR
MPG 0x0009 MPEG video Not used in KotOR
TXT 0x000A Text file Not used in KotOR
PLH 0x07D0 Placeable header Not used in KotOR
TEX 0x07D1 Texture
MDL 0x07D2 3D model file (see MDL/MDX File Format)
THG 0x07D3 Unknown Not used in KotOR
FNT 0x07D5 Font file Not used in KotOR
Lua 0x07D7 Lua script Not used in KotOR
SLT 0x07D8 Unknown Not used in KotOR
NSS 0x07D9 NWScript source code (see NSS File Format)
NCS 0x07DA Compiled NWScript bytecode (see NCS File Format)
MOD 0x07DB Module container (ERF variant, see ERF File Format)
ARE 0x07DC Area definition (see GFF-ARE)
SET 0x07DD Unknown Not used in KotOR
IFO 0x07DE Module information (see GFF-IFO)
BIC 0x07DF Character template Not used in KotOR
WOK 0x07E0 Walkmesh (see BWM File Format)
2DA 0x07E1 Two-dimensional array data (see 2DA File Format)
TLK 0x07E2 Talk table (localized strings, see TLK File Format)
TXI 0x07E6 texture information (see TXI File Format)
GIT 0x07E7 game instance template (see GFF-GIT)
BTI 0x07E8 Blueprint trigger Not used in KotOR
UTI 0x07E9 item templates (see GFF-UTI)
BTC 0x07EA Blueprint creature Not used in KotOR
UTC 0x07EB creature templates (see GFF-UTC)
DLG 0x07ED Dialogue/conversation (see GFF-DLG)
ITP 0x07EE ITP format (legacy name for GFF) Not used in KotOR
BTT 0x07EF Blueprint trigger Not used in KotOR
UTT 0x07F0 Trigger template (see GFF-UTT)
DDS 0x07F1 DirectDraw Surface texture (see DDS File Format)
UTS 0x07F3 Sound template (see GFF-UTS)
LTR 0x07F4 Letter format (see LTR File Format)
GFF 0x07F5 Generic file format (container, see GFF File Format)
FAC 0x07F6 Faction
BTE 0x07F7 Blueprint encounter
UTE 0x07F8 encounter template (see GFF-UTE)
BTD 0x07F9 Blueprint door Not used in KotOR
UTD 0x07FA door templates (see GFF-UTD)
BTP 0x07FB Blueprint placeable Not used in KotOR
UTP 0x07FC placeable templates (see GFF-UTP)
DTF 0x07FD Unknown Not used in KotOR
GIC 0x07FE Unknown Not used in KotOR
GUI 0x07FF User interface definition (see GFF-GUI)
CSS 0x0800 Unknown Not used in KotOR
CCS 0x0801 Unknown Not used in KotOR
BTM 0x0802 Blueprint merchant Not used in KotOR
UTM 0x0803 Merchant/store template (see GFF-UTM)
DWK 0x0804 Door walkmesh (see BWM File Format)
PWK 0x0805 Placeable walkmesh (see BWM File Format)
BTG 0x0806 Blueprint trigger Not used in KotOR
UTG 0x0807 Unknown Not used in KotOR
JRL 0x0808 Journal/quest log (see GFF-JRL)
SAV 0x0809 Save game containers (see ERF File Format)
UTW 0x080A Waypoint Template
4PC 0x080B Unknown Not used in KotOR
SSF 0x080C Sound Set Files (see SSF File Format)
HAK 0x080D Hak pak container. Not used in KotOR
NWM 0x080E Neverwinter Nights module (ERF variant, not used in KotOR)
BIK 0x080F Bink video format
PTM 0x0811 Unknown Not used in KotOR
PTT 0x0812 Unknown Not used in KotOR
ERF 0x270D Encapsulated Resource File (see ERF File Format)
BIF 0x270E Bioware Index File (container, see BIF File Format)
KEY 0x270F KEY table (BIF index, see KEY File Format)

Language IDs

This language ID usually is represented as an enum. It is equivalent within all engines and all games, with some newer games specifying more formats but always staying backwards compatible with the others.

KotOR (odyssey) specifically can only support

Reference: xoreos-docs (Mirror: th3w1zard1/xoreos-docs): specs/torlack/basics.html - Language ID definitions (NWN-focused but applicable to KotOR)

| Language | ID | Notes | | --------------- | -- | | | English | 0 | | | French | 1 | | | German | 2 | | | Italian | 3 | | | Spanish | 4 | | | Polish | 5 | cp-1250, only released for KotOR 1 |

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

File Formats

Low-level structures and implementations

Binary layout, engine behaviour, and implementation details for developers and reverse engineering:

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