Skip to content

Home

Jump to bottom Edit New page
Benjamin Auquite edited this page Apr 15, 2026 · 47 revisions

Welcome to the PyKotor Wiki

PyKotor is a source-available KotOR and TSL modding toolchain. It exists to make the ecosystem less fragmented: one place for file-format documentation, installer behavior, tool workflows, and implementation-backed reference material that can be improved by the community instead of disappearing into forum archaeology.

The documentation is organized around what you are trying to do, not around whichever executable or legacy tool you happened to open first. Start from the table below, then follow the deeper format and engine-reference pages when you need exact behavior.

This wiki is part of the shipped Holocron Toolset help payload rather than website-only prose: the Toolset build step copies the repo-root wiki/ directory into src/toolset/help/wiki, setuptools package-data includes help/wiki/**/*.md, MANIFEST.in includes the same tree for source distributions, and the generated source manifest lists concrete copied pages such as Home.md, 2DA-File-Format.md, and GFF-File-Format.md. [Holocron Toolset setup.py, Holocron Toolset pyproject.toml, Holocron Toolset MANIFEST.in, Holocron Toolset SOURCES.txt]

Start here

If you need to... Start here Then read
Install or troubleshoot a mod Installing Mods with HoloPatcher Concepts, Mod Creation Best Practices
Author a patcher-based mod HoloPatcher README for Mod Developers TSLPatcher 2DAList Syntax Guide, TSLPatcher TLKList Syntax Guide, TSLPatcher GFFList Syntax Guide
Edit resources in a GUI Holocron Toolset: Getting Started Holocron Toolset: Core resources, Holocron Toolset: Module resources
Work headlessly or automate a workflow CLI quickstart KotorDiff Integration, Explanations on HoloPatcher Internal Logic
Understand why a file wins in-game Concepts Resource formats and resolution, KEY File Format
Look up a binary format or game resource type Resource formats and resolution The relevant format page for that extension

Toolchain map

  • PyKotor is the library and CLI foundation: parsers, writers, extraction helpers, automation commands, and format conversion.
  • HoloPatcher is the safe installer layer for merge-sensitive resources like 2DA, TLK, and GFF.
  • Holocron Toolset is the GUI editing layer for modules, resources, and area content.
  • KotorDiff is the comparison layer for install state, emitted patch data, and regression checking.

That split is deliberate. The goal is not “use only PyKotor tools forever”; the goal is to make format knowledge and mod workflows portable across tools, while still giving you a modern stack when you want one.

Workspace packages

  • PyKotor publishes the pykotor package, exposes pykotor and pykotorcli console scripts, and declares bioware-kaitai-formats, defusedxml, kaitaistruct, and ply as core dependencies. [PyKotor pyproject.toml]
  • PyKotor implements installation discovery and resource search in pykotor.extract.installation, defines engine/resource typing in pykotor.resource.type, and keeps format readers and writers under pykotor.resource.formats. [pykotor.extract.installation, pykotor.resource.type, pykotor.resource.formats]
  • HoloPatcher publishes the holopatcher console script, depends on pykotor[encodings,updater], and describes itself as a faster, cross-platform alternative to TSLPatcher. [HoloPatcher pyproject.toml]
  • HoloPatcher routes install, uninstall, and validate requests through its CLI path, otherwise attempts to launch the GUI application and falls back to a warning when GUI execution is unavailable. [holopatcher.__main__]
  • Holocron Toolset publishes the holocron-toolset application, standalone editor entry points such as are-editor, mdl-editor, utc-editor, tpc-editor, and twoda-editor, and standalone applications such as module-designer and indoor-builder. [Holocron Toolset pyproject.toml]
  • Holocron Toolset keeps its standalone editor registry in toolset.gui.editors.standalone, where file extensions such as .2da, .utc, .dlg, .mdl, .mdx, .tlk, .tpc, .dds, .rim, and .erf are mapped to concrete editor classes and launcher names. [toolset.gui.editors.standalone]
  • KotorDiff publishes the kotordiff console script as a thin package over shared pykotor.diff_tool functionality. [KotorDiff pyproject.toml]
  • KotorDiff drives diff generation through pykotor.diff_tool.app, which imports installation loading, GFF handling, resource typing, reference caches, TSLPatcher diff generation, and incremental writer support from the shared PyKotor codebase. [pykotor.diff_tool.app]
  • bioware-kaitai-formats is a workspace package of generated Python parsers, while the authoritative .ksy specifications are maintained in the upstream OpenKotOR/bioware-kaitai-formats repository. [workspace bioware-kaitai-formats README, upstream OpenKotOR/bioware-kaitai-formats]

Core reference pages

Contributor maintenance

  • Wiki Conventions defines editorial rules for structure, evidence placement, preserved-source handling, and link style.

Learning paths

Workflow guides

Preserved source documents

Cross-reference: other tools and engines

PyKotor is one part of a larger KotOR tooling ecosystem. This section is a compact directory to adjacent projects, not an attempt to duplicate their documentation.

Engine reimplementations

  • xoreos is a C++ Aurora/Odyssey/Eclipse reimplementation with KotOR support.
  • reone is a community-maintained modern C++ KotOR engine.
  • KotOR.js is a TypeScript/WebGL engine implementation.
  • NorthernLights and KotOR-Unity are Unity/.NET-based engine projects.

File-format libraries and related tooling

Community projects and tools

Community sources and archives

Older communities still matter for release history, workflow pitfalls, and examples that never became formal documentation.

Source Why it matters How to use it
DeadlyStream Primary KotOR modding hub for releases, tutorials, tool discussions, and troubleshooting threads. Use for workflow context, release history, and real-world modder reports; keep normative format semantics on this wiki.
KOTOR Community Portal Community-maintained landing page for FAQs, troubleshooting links, and player-facing resource directories. Use its FAQ and links pages for player support context and discovery. Exclude its mod-build recommendation lists when writing normative wiki guidance here.
LucasForums Container Wayback-backed reconstruction of the original LucasForums communities. Use for historical TSLPatcher, tool, and modding discussions when the wiki needs provenance or original author commentary.
LucasForums Archive Alternate archive of Editing/Modding, Holowan Laboratories, and tutorial threads. Use as historical support, especially when a thread is easier to cite or search here than in the container.
PCGamingWiki for KotOR and KotOR II Player-facing path, launcher, widescreen, and install-layout guidance. Use for player environment context only; cross-check binary or resource-system claims against Concepts, KEY File Format, and the relevant format pages.
r/kotor Large active player and mod-user community with install guides, troubleshooting posts, and community-maintained build notes. Use as workflow context and to discover common failure cases; do not treat Reddit posts as authoritative for file formats or engine behavior.
Holowan Laboratories / MixNMojo mirrors Early KotOR modding discussion history. Use when newer documentation does not preserve the original context for a tool, technique, or format note.
Other general forums Current troubleshooting and installation chatter. Use as workflow context or discovery paths, not as the primary source for file-format or engine behavior.

External documentation

  • xoreos-docs preserves official BioWare specifications, Torlack reverse-engineered notes, and auxiliary format material used throughout Aurora-family reverse engineering.
  • nwn-docs is helpful for older Aurora-family background where KotOR behavior inherits the same storage conventions.
  • bioware-kaitai-formats provides Kaitai Struct specifications for many BioWare and KotOR formats and is useful for parser cross-checking.

See also

Add a custom footer
Add a custom sidebar

Clone this wiki locally