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 KotorCLI

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

Aurora Engine Basics (KotOR)

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

KEY 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. Note: nwn.ini is the Neverwinter Nights equivalent and is not used in KotOR.

Reference: vendor/xoreos-docs/specs/torlack/basics.html - Tim Smith (Torlack)'s Aurora engine basics documentation (originally NWN-focused, but resource resolution order and key file concepts apply to KotOR)

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 inherited from the Aurora engine. The following table lists resource types used in KotOR (some types may be legacy from earlier BioWare games or shared with Neverwinter Nights):

Resource Name	type ID	Description
RES	0x0000	Generic resource (legacy)
BMP	0x0001	Bitmap image (legacy)
MVE	0x0002	Movie/video file (legacy)
TGA	0x0003	Targa image format (legacy)
WAV	0x0004	Wave audio file (see WAV File Format)
PLT	0x0006	texture palette (Neverwinter Nights only, NOT used in KotOR - see PLT File Format)
INI	0x0007	Configuration file (e.g., kotor.ini)
BMU	0x0008	Unknown (legacy)
MPG	0x0009	MPEG video (legacy)
TXT	0x000A	Text file (legacy)
PLH	0x07D0	Placeable header (legacy)
TEX	0x07D1	Texture (legacy, replaced by TPC)
MDL	0x07D2	3D model file (see MDL/MDX File Format)
THG	0x07D3	Unknown (legacy)
FNT	0x07D5	Font file (legacy)
LUA	0x07D7	Lua script (legacy)
SLT	0x07D8	Unknown (legacy)
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 (legacy)
IFO	0x07DE	Module information (see GFF-IFO)
BIC	0x07DF	Character template (legacy)
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 (legacy)
UTI	0x07E9	item templates (see GFF-UTI)
BTC	0x07EA	Blueprint creature (legacy)
UTC	0x07EB	creature templates (see GFF-UTC)
DLG	0x07ED	Dialogue/conversation (see GFF-DLG)
ITP	0x07EE	ITP format (legacy name for GFF, see GFF File Format)
BTT	0x07EF	Blueprint trigger (legacy)
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 (legacy)
BTE	0x07F7	Blueprint encounter (legacy)
UTE	0x07F8	encounter template (see GFF-UTE)
BTD	0x07F9	Blueprint door (legacy)
UTD	0x07FA	door templates (see GFF-UTD)
BTP	0x07FB	Blueprint placeable (legacy)
UTP	0x07FC	placeable templates (see GFF-UTP)
DTF	0x07FD	Unknown (legacy)
GIC	0x07FE	Unknown (legacy)
GUI	0x07FF	User interface definition (see GFF-GUI)
CSS	0x0800	Unknown (legacy)
CCS	0x0801	Unknown (legacy)
BTM	0x0802	Blueprint merchant (legacy)
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 (legacy)
UTG	0x0807	Unknown (legacy)
JRL	0x0808	Journal/quest log (see GFF-JRL)
SAV	0x0809	save game archives (see ERF File Format)
UTW	0x080A	waypoint template (see GFF-UTW)
4PC	0x080B	Unknown (legacy)
SSF	0x080C	sound set files (see SSF File Format)
HAK	0x080D	Hak pak archive (ERF variant)
NWM	0x080E	Neverwinter Nights module (ERF variant, not used in KotOR)
BIK	0x080F	Bink video format
PTM	0x0811	Unknown (legacy)
PTT	0x0812	Unknown (legacy)
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:

Localized strings use language identifiers:

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

Language	ID
English	0
French (Male)	2
French (Female)	3
German (Male)	4
German (Female)	5
Italian (Male)	6
Italian (Female)	7
Spanish (Male)	8
Spanish (Female)	9

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
• 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)
• KEY File Format ← KEY file format
• 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

Internal Documentation

• HoloPatcher
• Explanations on HoloPatcher Internal Logic

Vendor Implementations

PyKotor includes many vendor submodules that provide alternative implementations of KotOR tools and engines. These serve as reference implementations and enable comparison of different approaches to the same problems.

Engine Reimplementations

Complete game engine rewrites that can load and play KotOR:

• xoreos - C++ reimplementation of BioWare's Aurora engine, supports multiple Aurora games including KotOR. Focus on accuracy and cross-platform compatibility. (Mirror: th3w1zard1/xoreos)
• reone - Modern C++ KotOR engine with OpenGL rendering. Focus on performance and clean architecture. (Mirror: th3w1zard1/reone)
• 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

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 for writing and editing NWScript:

• HoloLSP - Language Server Protocol implementation for NWScript (enables IDE integration)
• 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:

• KotorCLI (PyKotor) - CLI-first toolset for packing, conversion, Holocron kit generation, and GUI layout scaling. python -m kotorcli kit-generate --installation <path> --module <module> --output <dir> runs headless; launching with no arguments opens the Tkinter kit generator GUI for interactive use. python -m kotorcli gui-convert --input <gui_or_folder> --output <dir> --resolution ALL runs headless for GUI resizing; omitting args opens the converter GUI. (Implementations: Tools/KotorCLI/src/kotorcli/kit_generator.py wraps Libraries/PyKotor/src/pykotor/tools/kit.py; Tools/KotorCLI/src/kotorcli/gui_converter.py delegates to pykotor.resource.formats.gff.)
• TSLPatcher - Original Perl mod installer (reference implementation) (Mirror: th3w1zard1/TSLPatcher)
• HoloPatcher.NET - .NET reimplementation of TSLPatcher
• Kotor-Patch-Manager - Alternative mod manager (Mirror: th3w1zard1/Kotor-Patch-Manager)
• KotORModSync - 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

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 (NWN1, NWN2, Jade Empire formats - NOT KotOR-specific).

  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)