pykotor 2.2.1

Read, modify and write files used by KotOR's game engine.

PyKotor

PyKotor is a modern Python library and toolset for reading, writing, and modding resources from the Star Wars: Knights of the Old Republic (KOTOR, K1) and The Sith Lords (KOTOR II, TSL) game engines.

---

Features

• Read and write almost all K1/TSL resource and file formats (BIF, ERF, GFF, KEY, TLK, DLG, UTC, UTP, UTI, UTS, etc.)
• Support for both K1 (swkotor.exe) and TSL (swkotor2.exe) with unified APIs
• High-fidelity, reverse-engineered format logic and type safety
• Command-line toolkit (pykotorcli) for file conversion, inspection, and batch operations
• Programmatic API for advanced automation and mod tooling
• Modern, type-checked, actively maintained, and well-tested codebase

Documentation & Community

• 📚 Docs / Usage: Wiki & Getting Started
• 🐛 Bugs: GitHub Issues
• 💬 Community Discord: Invite Link
• 🌟 Changelog: Releases

Quick Install

pip install pykotor

Or with extras for format encodings and update tool:

pip install "pykotor[encodings,updater]"

CLI Example

# Convert a BIF file to readable resources
pykotorcli extract-bif --input KOTOR1/BIFs/data.bif --output ./output_dir

# Inspect a GFF (generic file format)
pykotorcli gff-dump --file some_file.uti

# See all CLI features
pykotorcli --help

Python Usage Example

from pykotor.tsl.gff import GFF

# Parse a .utc (creature) file
gff = GFF.parse("dan13_01.utc")
print(gff.root["FirstName"].string)  # Accessing the field value

# Modify and save
gff.root["FirstName"].string = "HK-47"
gff.write("hk_utc.gff")

Supported Formats

Major types:

• Containers: BIF, ERF, KEY, MOD, RIM
• Resources: GFF/UT*, GIT, DLG, ARE, UTP, UTI, UTC, UTS, UTM, UTR, UTT, JRL, TLK, etc.
• 2DA, SSF, NCS/NSS, NDB, models, textures, etc. See Wiki Format Coverage.

Development & Contributing

1. Clone the repo and install Poetry or use uv.
2. poetry install or uv pip install -e .[dev]
3. Run pytest and ruff check . and mypy --strict before submitting PRs.

For feature requests, new formats, or reverse-engineering findings, see CONTRIBUTING.md.

---

License

LGPL-3.0-or-later (see LICENSE)

---

This project follows unified K1/TSL reverse engineering practices. All resource logic is verified across both game engines using REVA MCP tools. See the Wiki for details on our protocol.