Skip to content

Installing Mods with HoloPatcher

Jump to bottom Edit New page
Benjamin Auquite edited this page Mar 31, 2026 · 18 revisions

Using HoloPatcher: Installation and Reversion

This page explains how to install mods with HoloPatcher. If you are packaging a mod, see HoloPatcher README for Mod Developers.

HoloPatcher is the modern PyKotor implementation of the TSLPatcher workflow. For players, the important part is simple: point it at the right game folder, install one mod option at a time, and use its restore flow before retrying or switching variants.

Before you install

  • Point HoloPatcher at your game root directory: the folder containing swkotor.exe or swkotor2.exe, plus folders such as override, modules, and lips.
  • Keep a clean backup or a disposable test install if you are testing several mods.
  • Install one mod at a time when checking compatibility.
  • If a mod offers multiple options, use the built-in backup/restore before changing options or reinstalling.

Verified against source files:

  • Libraries/PyKotor/src/pykotor/tslpatcher/ - patching semantics and install workflow
  • Tools/HoloPatcher/src/holopatcher/ - application behavior, backup/restore flow, and iOS utilities
  • Libraries/PyKotor/src/pykotor/extract/installation.py - game-root detection context used elsewhere in the toolchain

See Mod Creation Best Practices for compatibility guidance and Concepts for override and resource-order background.

Community downloads and player-oriented guides

Install a mod

  1. Select the mod folder. This is the folder that contains tslpatchdata.
  2. Select the game directory. Choose your KotOR game root, not the override folder by itself.
  3. Choose an installation option, if present. Mods with namespaces.ini expose one or more variants in the first dropdown.
  4. Run Install. Review the log if anything fails instead of immediately retrying.

If the author ships extra instructions for Steam, GOG, Aspyr, or mobile builds, follow those too. HoloPatcher handles merge-aware patching, but it cannot correct a mod package that targets the wrong game version or wrong install path.

KotORModSync (optional)

KotORModSync (th3w1zard1/KotORModSync) helps manage many mods or multiple install targets (profiles, sync between folders, team handoffs). It is complementary to HoloPatcher: you still need a valid TSLPatcher/HoloPatcher INI workflow for merges inside tslpatchdata. If you only install a handful of mods, following each mod’s readme + HoloPatcher is enough; if you maintain parallel installs or large lists, ModSync can reduce manual bookkeeping. See HoloPatcher README for Mod Developers (first-mod walkthrough section) for author-side packaging context.

Reverting Mod Installations

To undo the most recent installation, use Tools -> Uninstall Mod/Restore Backup. That restores files to the state they were in immediately before that install ran.

Why reinstalling without restoring is risky

  • Interrupted installs can duplicate changes. If you close the app mid-install and then run the same option again, merge targets such as appearance.2da can end up with duplicate rows or repeated edits.
  • Retrying the same option stacks changes. HoloPatcher treats each install as a new operation and keeps a backup for each one.

If you installed the same thing twice by mistake, restore twice:

  1. The first restore undoes the most recent installation.
  2. The second restore undoes the earlier one and returns you to the pre-install state.

Installing Mods on iOS Devices

iOS builds are case-sensitive in ways the desktop releases are not. If KotOR asset names keep uppercase characters where the mobile port expects lowercase, the game can crash immediately after you press Play.

HoloPatcher includes an iOS fix-up utility for this:

  • Go to Tools -> Fix iOS Case Sensitivity.
  • Point it at your KotOR install folder.
    • ! If you are instead patching the mobile TSLRCM layout, point it at the mtslrcm folder when the mod instructions call for that layout.

Run that fix before troubleshooting deeper compatibility issues on iOS. A surprising number of "instant crash on launch" reports turn out to be filename-case problems rather than bad mod content.

See also

Add a custom footer
Add a custom sidebar

Clone this wiki locally