PyKotor

A Python library for reading and modifying file formats used by the game Knights of the Old Republic and its sequel.

Table of Contents

• PyKotor
  • Table of Contents
  • Features
  • Requirements
  • Installation
    • Quick Install
    • Standard Install
  • Quick Start
    • Using the Library
    • Using the Tools
  • Available Tools
  • Documentation
  • Contributing
  • License

Features

• Complete file format support for KotOR and TSL game files
• Cross-platform (Windows, macOS, Linux)
• Holocron Toolset for modding and development
• Modern Python (3.8+)
• Type-annotated API with extensive documentation

Requirements

• Python 3.8+
• Windows 7+, macOS, or Linux

Installation

Quick Install

The fastest way to get started is using uvx (no installation required). Install uv from astral-sh/uv installation, then run tools with --refresh to ensure you're using the latest version:

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uvx --refresh holocrontoolset

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh
uvx --refresh holocrontoolset

Standard Install

Install the library:

pip install pykotor

Install tools:

pip install holocrontoolset holopatcher kotordiff

Or use pipx for isolated tool installation:

pipx install holocrontoolset
pipx install holopatcher
pipx install kotordiff

Note: The PyKotor CLI is included with the pykotor package and accessible via pykotor or pykotorcli commands.

See CONTRIBUTING.md for development installation. If cloning the repo is slow or stalls, use a shallow clone: git clone --depth 1 <repo-url> (see CONTRIBUTING for details).

Quick Start

Using the Library

from pykotor.resource.type import ResourceType
from pykotor.extract.installation import Installation
from pykotor.resource.formats.tpc import write_tpc

# Load game installation
inst = Installation("C:/Program Files (x86)/Steam/steamapps/common/swkotor")

# Extract a texture
texture = inst.texture("C_Gammorean01")
write_tpc(texture, "./C_Gammorean01.tga", ResourceType.TGA)

Using the Tools

HolocronToolset - GUI editor for KotOR files:

uvx --refresh holocrontoolset

HoloPatcher - Cross-platform TSLPatcher alternative:

uvx --refresh holopatcher --help

PyKotor CLI - Command-line build tool (included with pykotor):

uvx --refresh pykotor --help
# Example: convert 2DA to CSV
uvx --refresh pykotor 2da2csv "path/to/file.2da"

KotorDiff - Compare and generate patches:

uvx --refresh kotordiff
# or if installed via pip/pipx
kotordiff

See individual tool documentation for detailed usage.

Available Tools

Tool	Description	Documentation
HolocronToolset	Full-featured GUI editor for KotOR files	README
HoloPatcher	Fast, cross-platform mod installer	README
PyKotor CLI	Command-line build tool (part of pykotor package)	Docs
KotorDiff	File comparison and TSLPatcher data generator	README

Documentation

User Documentation

• Installation & Usage - Detailed library documentation
• Contributing Guide - Development setup and guidelines
• Project Wiki - Community documentation
• PowerShell Setup - Windows PowerShell configuration

Design & Architecture

• Figma Integration Summary - Complete Figma tools integration overview
• FigJam Diagrams - 22 architectural diagrams covering all components
• Design System Rules - Comprehensive UI design system documentation
• Code Connect Examples - Figma-to-code mapping examples

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for:

• Development environment setup
• Code style guidelines
• Testing procedures
• Pull request process

License

This project is licensed under the LGPL-3.0-or-later License.