KotOR II Switch Modding Tools

KotOR II Switch Modding Tools
KotOR II Switch Modding Tools
General
Author	DrSnuggly
Type	Hack Utilities
Version	2.3.0
License	GPL-3.0
Last Updated	2023/07/13
Links
	Download
	Website
	Source

KotOR II Switch Modding Tools is a set of tools designed to simplify the modding process for the Nintendo Switch version of Star Wars: Knights of the Old Republic II (KotOR II).

With the help of these tools, players can finally enjoy mods such as The Sith Lords: Restored Content Mod and many others on the Nintendo Switch platform.

These tools are based on and inspired by the work of jacqylfrost.

Note: These modding tools are intended only for use on modded Nintendo Switch consoles.

Features

Provide a folder structure that modding tools expect.
Once modding is done, restructure the game folder to what the Nintendo Switch version of the game expects.
Call out potential issues along with instructions on how to fix them.
Easy backups and restores during the modding process, to better see where things went wrong.

Usage instructions

NOTE: It's highly recommended to read this entire section before starting.

Prerequisites

A computer to install mods with — mods cannot be installed directly on the Nintendo Switch).
- NOTE: this project currently ONLY works with Bash, which is available by default on Linux and macOS. For Windows, please use either WSL (recommended) or Cygwin.
  - An issue is already open for porting these scripts to PowerShell — contributions welcome via pull request.
A modded Nintendo Switch with the Atmosphere Switch custom firmware installed.
- NOTE: other custom firmwares will likely work but are unsupported.
A copy of KotOR II already installed on the Nintendo Switch with all updates applied.
NXDumpTool Switch installed on the Nintendo Switch to extract some game files needed for some mods.
A way to interact with and transfer files to and from the Nintendo Switch. Examples:
- ftpd Switch
- Hekate's tool to mount the SD Card to a PC, under Tools | USB Tools | SD Card (requires rebooting the Nintendo Switch into Hekate).
- NX-Shell Switch (only for interacting with existing files)

Pre-flight

On your computer, download and extract the most recent release from GitHub.
Open a terminal window and navigate to the extracted folder from step 1.
- e.g. cd "~/Downloads/KotOR II Switch modding"
Run the following command to initialize the folder structure:
```
./bin/initialize
```
- This will create a folder named 0100B2C016252000, which is the title ID of the game on the Nintendo Switch.
On the Nintendo Switch, do the following in the nxdumptool app:
- Navigate to Dump installed SD card /eMMC content | Star Wars™️ - Knights of the Old Republic™️ II | RomFS options.
- Change the Use update/DLC option to the installed game update.
- Select Browse RomFS section.
- Dump the following files:
  - ./swplayer.ini
  - ./Localized/<language>/dialog.tlk
- Transfer these files from /atmosphere/contents/0100B2C016252000 on the Nintendo Switch to your computer using a file transfer option of your choice (common options listed above in the Prerequisites section).
- Place both transferred files into the 0100B2C016252000/romfs folder.
  - Make sure to place the dialog.tlk directly in the above folder, not Localized/<language>.

Mod installation

Start installing mods like usual. General notes:
- Linking the 0100B2C016252000/romfs folder to the desktop is very useful for TSLPatcher that some mods use, which always defaults to the desktop, e.g. ln -s "$(pwd)/0100B2C016252000/romfs" ~/Desktop/romfs.
- When using mods that use TSLPatcher, make sure to pay attention to the installation logs — warnings are common and not usually anything to worry about, but errors can occur due to missing files that the mod installer expects (known mods listed below). If this occurs:
  - In the TSLPatcher window, make a note of the filepath associated with the error (e.g. lips/003EBO_loc.mod.
  - Dump the file from your Nintendo Switch.
    - You may need to look under Localized/<language> due to how the Nintendo Switch version of the game implemented other languages).
  - Transfer the dumped file to your computer and place it in the location that the mod installer expected in 0100B2C016252000/romfs.
  - Re-run the TSLPatcher installer.
Recommended, but not required: periodically archive currently installed mods between mod installations with the following command:
```
./bin/archive "recommended-optional-description"
```
- At any point, you can restore an archive with the following command:
```
./bin/restore
```

Wrapping up

Once all desired mods have been installed, run the following command:
```
./bin/finalize
```
- To undo finalization (e.g. for further adjustments), run the following command to restore a backup that was automatically created by the finalization script:
```
./bin/restore 0
```
- Make sure to pay attention to any warnings that appear.
  - The most common warning will be texture files that aren't in the .tpc format when the Nintendo Switch version of the game already has the same texture in that format. These pre-existing .tpc files on the Nintendo Switch will always override any .tga or .dds texture files — the solution is to convert these files to .tpc where possible (e.g. using tga2tpc 4.0.0).
On the Nintendo Switch, delete the /atmosphere/contents/0100B2C016252000 folder, if it exists.
Copy the 0100B2C016252000 folder from your computer to the /atmosphere/contents folder on your Nintendo Switch's SD card.
- NOTE: network-based file transfers (e.g. FTP) will work with no issues, but for larger mod packs, you may want to use the Hekate option mentioned above for faster and more reliable transfers.

Known issues

Platform-specific known issues and fixes

The Sith Lords Restored Content Mod (TSLRCM)
- Button prompts are either missing or showing buttons for the incorrect platform
  - Fix: after installing this mod, use the dialog.tlk in the Fixed dialog for TSLRCM on Nintendo Switch.zip attached to the latest release — thanks, seriouslyunderappreciated!

There are likely more than what is listed here. Please don't hesitate to create an issue or pull request with any of these platform-specific issues you find.

Mods that require additional dumped files

Assumes The Sith Lords: Restored Content Mod (TSLRCM) is installed. If you find any more of these, please feel free to create a GitHub issue or a pull request.

Darth Sion and Male Exile Mod 1.2.3
- lips\702kor_loc.mod
- lips\907mal_loc.mod
Extended Korriban arrival 1.2
- Lips\003EBO_loc.mod
Handmaiden and Female Exile - Disciple and Male Exile Romance
- lips\262TEL_loc.mod
- lips\402DXN_loc.mod
- lips\903MAL_loc.mod
- lips\localization.mod

Usage in other mods

Feel free to reference or link this mod to any other projects. However, please note that this project uses the GNU GPL v3 license. You can view a layman's terms breakdown of the license, but the most important thing to note is that any projects or distributions that modify or include code from this project must also have their source code published and publicly available with the same license. Please don't hesitate to contact me if this causes major issues for a mod you're creating.

Changelog

v2.3.0

Include TSLRCM dialog.tlk fixes provided by seriouslyunderappreciated — much appreciated!

v2.2.2

Fix .txi files associated with invalid .tga textures (i.e. ones that would be overridden by stock Nintendo Switch .tpc files) not being correctly moved to the _INVALID directory for later manual processing.

v2.2.1

Finish removing traces of the bundled assets folder, which in turn fixes issues with the initialization script.

v2.2.0

Enhancements
- Script now auto-removes redundant texture files
Documentation
- Added section detailing how some mod components may not work
- Add file dump requirements for Handmaiden and Female Exile - Disciple and Male Exile Romance
- Clarified purpose and attribution
- Clarified licensed usage

v2.1.0

Move .txi files with any .tga textures that would be ignored by the Nintendo Switch version of the game, since they should be removed when replacing the texture with a .tpc file — thanks JC!

v2.0.1

Add missing attribution to jacqylfrost.

v2.0.0

First Release.

External links

Github - https://github.com/DrSnuggly/kotor-ii-switch-modding