Home

Welcome to the PyKotor Wiki

Documentation

For End Users

• Installing Mods with HoloPatcher

For Mod Developers

• HoloPatcher README for Mod Developers
• TSLPatcher's Official Readme
• TSLPatcher Thread Complete Archive
• HoloPatcher Feature Coverage Overview
• TSLPatcher InstallList Syntax Guide ← Complete reference for file installation
• TSLPatcher TLKList Syntax Guide ← Complete reference for TLK (TalkTable) modifications
• TSLPatcher 2DAList Syntax Guide ← Complete reference for 2DA (Two-Dimensional array) patches
• TSLPatcher GFFList Syntax Guide ← Complete reference for GFF modifications
• TSLPatcher SSFList Syntax Guide ← Complete reference for SSF (sound set files) modifications
• Mod Creation Best Practices
• KotorDiff Integration in PyKotorCLI

Internal Documentation

• HoloPatcher
• Explanations on HoloPatcher Internal Logic

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:

• 2DA File Format - Official 2DA (Two-Dimensional array) format specification
• GFF File Format - Official Generic file format specification
• Common GFF Structs - Common GFF structure definitions
• Area File Format - Official ARE (Area) file format
• Creature Format - Official UTC (Creature) format
• Item Format - Official UTI (Item) format
• Door/Placeable Format - Official UTD/UTP formats
• Encounter Format - Official UTE (Encounter) format
• Trigger Format - Official UTT (Trigger) format
• Waypoint Format - Official UTW (Waypoint) format
• Store Format - Official UTM (Store) format
• Sound Object Format - Official UTS (Sound) format
• Journal Format - Official JRL (Journal) format
• Conversation Format - Official DLG (Dialogue) format
• IFO Format - Official module info format
• ERF Format - Official Encapsulated Resource format
• Key/BIF Format - Official KEY and BIF file formats
• TalkTable Format - Official TLK (Talk Table) format
• SSF Format - Official sound set files format
• Localized Strings Format - Official localized strings format
• Faction Format - Official faction data format
• Palette/ITP Format - Official palette and ITP formats

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.

Important Files

• chitin.key: Master index file that maps resource names to BIF archives 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: vendor/xoreos-docs/specs/torlack/basics.html - Tim Smith (Torlack)'s Aurora engine basics documentation (NWN-focused)

Resource Resolution Order

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 archive (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 archives (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 archive. 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 (archive, 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: vendor/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: vendor/xoreos-docs/specs/torlack/basics.html - Tim Smith (Torlack)'s NWN data file Basics documentation (Aurora engine fundamentals)

File Formats

• MDL/MDX File Format ← Complete reference for 3D model files
  • 2DA File Format ← Complete reference for Two-Dimensional array format (see also Official Bioware 2DA Documentation). All individual 2DA file documentation has been inlined into this document.
  • acbonus.2da
  • ambientmusic.2da
  • ambientsound.2da
  • ammunitiontypes.2da
  • animations.2da
  • appearance.2da
  • appearancesndset.2da
  • baseitems.2da
  • bindablekeys.2da
  • bodybag.2da
  • camerastyle.2da
  • classes.2da
  • classpowergain.2da
  • combatanimations.2da
  • creaturespeed.2da
  • cursors.2da
  • dialoganimations.2da
  • difficultyopt.2da
  • disease.2da
  • doortypes.2da
  • droiddischarge.2da
  • effecticon.2da
  • emotion.2da
  • encdifficulty.2da
  • exptable.2da
  • facialanim.2da
  • feat.2da
  • featgain.2da
  • feedbacktext.2da
  • footstepsounds.2da
  • forceshields.2da
  • fractionalcr.2da
  • gender.2da
  • genericdoors.2da
  • globalcat.2da
  • grenadesnd.2da
  • guisounds.2da
  • heads.2da
  • inventorysnds.2da
  • iprp_abilities.2da
  • iprp_acmodtype.2da
  • iprp_aligngrp.2da
  • iprp_ammotype.2da
  • iprp_combatdam.2da
  • iprp_costtable.2da
  • iprp_damagecost.2da
  • iprp_damagetype.2da
  • iprp_immunity.2da
  • iprp_lightcol.2da
  • iprp_monstdam.2da
  • iprp_mosterhit.2da
  • iprp_onhit.2da
  • iprp_paramtable.2da
  • iprp_protection.2da
  • iprp_saveelement.2da
  • iprp_savingthrow.2da
  • iprp_walk.2da
  • itempropdef.2da
  • itemprops.2da
  • keymap.2da
  • loadscreenhints.2da
  • loadscreens.2da
  • masterfeats.2da
  • modulesave.2da
  • movies.2da
  • pazaakdecks.2da
  • placeableobjsnds.2da
  • placeables.2da
  • planetary.2da
  • plot.2da
  • poison.2da
  • portraits.2da
  • prioritygroups.2da
  • racialtypes.2da
  • ranges.2da
  • regeneration.2da
  • repute.2da
  • skills.2da
  • soundset.2da
  • spells.2da
  • stringtokens.2da
  • subrace.2da
  • surfacemat.2da
  • texpacks.2da
  • traps.2da
  • tutorial.2da
  • upcrystals.2da
  • upgrade.2da
  • videoeffects.2da
  • visualeffects.2da
  • weaponsounds.2da
  • xptable.2da
• TLK File Format ← Complete reference for Talk Table format
• BIF File Format ← BioWare Infinity format
• KEY File Format ← KEY file format
• BWM File Format ← Complete reference for Binary walkmesh format
• GUI File Format ← Complete reference for Graphical User Interface format
• ERF File Format ← Encapsulated Resource format
• Kit Structure Documentation ← Complete reference for indoor kit structure and generation
• GFF File Format ← Generic file Format (see also Official Bioware GFF Documentation)
  • ARE (Area)
  • DLG (Dialogue)
  • GIT (Game Instance Template)
  • GUI (Graphical User Interface)
  • IFO (Module Info)
  • JRL (Journal)
  • PTH (Path)
  • UTC (Creature)
  • UTD (Door)
  • UTE (Encounter)
  • UTI (Item)
  • UTM (Merchant)
  • UTP (Placeable)
  • UTS (Sound)
  • UTT (Trigger)
  • UTW (Waypoint)
• LIP File Format ← LIP sync format
• LTR File Format ← Letter format
• LYT File Format ← Layout format
• NCS File Format ← NwScript Compiled Script format
• NSS File Format ← NwScript Source format (nwscript.nss, function/constant definitions)
• RIM File Format ← Resource index Manifest format
• SSF File Format ← sound set files format
• TLK File Format ← Talk Table format
• TPC File Format ← texture Pack Container format
• TXI File Format ← texture Info format
• VIS File Format ← Visibility format
• WAV File Format ← Wave audio format

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:

• xoreos - C++ reimplementation of BioWare's Aurora/Odyssey/Eclipse engine, supports multiple BioWare games including KotOR. (Mirror: th3w1zard1/xoreos)
• reone - Modern C++ KotOR engine with OpenGL rendering. Focus on performance and clean architecture. (Mirror: th3w1zard1/reone)
  • NOTE: This project seems to be abandoned by seedhartha, but was picked up by the community here: https://github.com/modawan/reone though I can't speak to its authority)
• KotOR.js - TypeScript/JavaScript engine running in browsers via WebGL. Enables playing KotOR directly in web browsers. (Mirror: th3w1zard1/KotOR.js)
• NorthernLights - .NET/C# engine implementation with Unity integration capabilities (based on KotOR-Unity project with further improvements) (Mirror: th3w1zard1/NorthernLights)
• KotOR-Unity - Unity-based KotOR engine rewrite. Leverages Unity's rendering and physics. (Mirror: th3w1zard1/KotOR-Unity)

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:

• kotorblender - Blender add-on for importing/exporting KotOR MDL files with full animation support (Mirror: th3w1zard1/kotorblender)
• mdlops - Legacy Python MDL toolkit for model conversions (Mirror: th3w1zard1/mdlops)
• tga2tpc - Standalone TGA to TPC texture converter (Mirror: th3w1zard1/tga2tpc)
• DLZ-Tool - DLZ file decompression tool (Mirror: th3w1zard1/DLZ-Tool)
• WalkmeshVisualizer - walkmesh viewing and debugging tool (Mirror: th3w1zard1/WalkmeshVisualizer)

Script Development

Tools and Resources for working with NWScript in KotOR:

• HoloLSP - Language Server Protocol implementation for NWScript, complete with all kotor-specific constants and functions, as well as everything else from each game's (k1/tsl's) nwscript.nss
• nwscript-mode.el - Emacs major mode for NWScript editing (Mirror: th3w1zard1/nwscript-mode.el)
• Vanilla_KOTOR_Script_Source - Decompiled vanilla KotOR scripts for reference (Mirror: th3w1zard1/Vanilla_KOTOR_Script_Source)

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:

• sotor - Terminal-based save editor (Mirror: th3w1zard1/sotor)
• KSELinux - KotOR Save Editor for Linux (Mirror: th3w1zard1/KSELinux)
• KotOR-Save-Editor - GUI save editor (Mirror: th3w1zard1/KotOR-Save-Editor)
• kotor-savegame-editor - Web-based save editor (Mirror: th3w1zard1/kotor-savegame-editor)

Audio Tools

Tools for working with KotOR audio:

• SithCodec - KotOR audio codec implementation (Mirror: th3w1zard1/SithCodec)
• SWKotOR-Audio-Encoder - Audio encoding tool for KotOR (Mirror: th3w1zard1/SWKotOR-Audio-Encoder)

Community Resources

Guides, patches, and community-maintained resources:

• K1_Community_Patch - Community bug fix patch for KotOR 1 (Mirror: th3w1zard1/K1_Community_Patch)
• TSL_Community_Patch - Community bug fix patch for KotOR 2 (Mirror: th3w1zard1/TSL_Community_Patch)
• KOTOR-utils - JCarter426's utility scripts and tools (Mirror: th3w1zard1/KOTOR-utils)
• KotOR-Bioware-Libs - BioWare library references (Mirror: th3w1zard1/KotOR-Bioware-Libs)
• kotor_combat_faq - Combat mechanics documentation (Mirror: th3w1zard1/kotor_combat_faq)
• ds-kotor-modding-wiki - DeadlyStream modding wiki archive (Mirror: th3w1zard1/ds-kotor-modding-wiki)

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