# Installer A public release that turns the player's own game files into a playable TotK folder. The release carries no game data and no code derived from the game: the installer builds the game on the player's machine. On Windows the installed folder also holds the build kit, the installer's tools the game rebuilds itself with for code mods, so the setup folder can be deleted after the install and the install folder moved. ## What the player does 1. Downloads `TotK-Setup--windows.zip` from GitHub Releases (none is published yet), unpacks it anywhere and starts `TotK-Setup.exe`. 2. Picks: - the base game (XCI or NSP) and the 1.1.0, 1.2.1 or 1.4.3 update (NSP); an NSZ or XCZ (compressed by the nsz tool) works as it is, the setup unpacks it itself; - their `prod.keys`; - optionally the firmware folder (`system/Contents/registered` of an unpacked firmware or an emulator's install), needed for Chinese, Korean and Traditional Chinese text; - the game language and the install folder. 3. Waits for the setup, one time. The window shows each step and its progress. 4. Plays `totk.exe` from the install folder. The setup folder and the source NSP or XCI (or NSZ, XCZ) can be deleted, and the install folder can be moved: code mods rebuild the game with the build kit inside it. The install folder (`main.c` `portable_paths()` reads this layout; it stays portable): ``` / totk.exe, SDL3.dll, libopus-0.dll, totk_xlate.exe nvngx_dlss.dll NVIDIA DLSS, downloaded by the setup's DLSS step when the player keeps it ticked totk.ini language; the other keys as commented defaults (totk.ini.example) exefs/, romfs/ extracted from the player's files shared-fonts/ the Switch system fonts, with Chinese, Korean or Traditional Chinese text profile/ saves mods/ the player's mods, one folder per mod (created by the menu's "Open mods folder") logs/ totk.log of the last run, totk.1.log to totk.4.log of the runs before it shader and pipeline caches prepared by the setup; shader-cache/shader-cache.pack holds the translations totk-install.json what built this folder: release version, input hashes, finished steps build-kit/ Windows: the release folder without TotK-Setup.exe (about 0.65 GB); the game's rebuild for code mods runs the setup window from it build-cache/ what the rebuild built in (cheats.status, exefs.status, plugins.status), rebuild.txt, and work/: the generated C, the lift cache and the objects (about 1.6 GB, Windows) ``` ## Updating the port The player runs a newer installer on the same folder. It reads `totk-install.json`, keeps `romfs/`, `exefs/`, `shared-fonts/`, `profile/` and `totk.ini` after checking their hashes, replaces `build-kit/` with its own files, rebuilds `totk.exe` and re-prepares the shaders. The setup is an installer and updater: nothing after the install needs its folder. An install made by a setup before the build kit kept its temp folder in that setup's folder (`/temp/-`, the setup `build-cache/rebuild.txt` named); the first newer setup moves it into `build-cache/work` when both are on one disk (on another it starts empty) and writes the new `rebuild.txt`. Until then the old `rebuild.txt` keeps using the old setup folder. A newer release that changes nothing game-derived skips the rebuild. The window starts with the last install folder and the base, update, keys and firmware paths it ran with (paths only, never the keys file's contents), kept in `%LOCALAPPDATA%\TotK Recomp\setup.json` (`$XDG_STATE_HOME/totk-recomp/setup.json` elsewhere). Entries that no longer exist stay empty. A reinstall or a switch to another game version starts filled in. Given an update file other than the recorded one (1.1.0, then 1.2.1, then 1.4.3), the installer extracts and builds again from it and keeps `profile/`. Saves carry over both ways between 1.2.1 and 1.4.3: 1.4.3 converts a 1.2.1 save on load, and 1.2.1 loads the saves 1.4.3 wrote. ## Setup steps 1. **Check** before writing anything: an NSZ or XCZ input is unpacked first (below), the files open with the keys, the update is 1.1.0, 1.2.1 or 1.4.3 (by hash, as `tools/extract.py`), the keys are new enough for the update, enough space is free on the target disk (about 36 GiB at the peak of a first install, 20 GiB after it), the CPU is at least x86-64-v2 (SSE4.2; with AVX2/FMA the faster `v3` build is used, otherwise the `v2` one), a Vulkan 1.3 GPU exists. Each failure is one clear message. 2. **Kit** (Windows): copy the release folder without `TotK-Setup.exe` into `build-kit/` in the install folder (`installer/steps.py` `Kit`, `installer/layout.py` `KIT_ITEMS`); every step after it runs its tools from there, so the commands the build records (the compiler's path in the Ninja file) are the ones the game's rebuild runs later. A newer setup replaces the kit; the kit's own rebuild keeps it. The steps' keys fingerprint file contents, not paths (`runtime_key` leaves out the lines of `clang --version` that name its folder), so a rebuild from the kit or from a moved install folder keeps every step the setup recorded. 3. **Fonts** with Chinese, Korean or Traditional Chinese text and a firmware folder: extract the Switch system fonts from the firmware into `shared-fonts/` (MacNativeGames' `extract_shared_fonts.py`, which verifies every NCA layer and BFTTF header). Without a firmware folder the setup warns and goes on; the game then lacks those glyphs. 4. **Extract** ExeFS and RomFS into the install folder and verify the hashes. 5. **Lift** the ExeFS to C (`recomp/gen.py`, `recomp/patches-v121.txt` or `patches-v143.txt`) into the temp folder, `build-cache/work` in the install folder (`.setup-temp` on Linux, `--temp DIR` elsewhere). The code cheats of the mods' cheat files and the mods' ExeFS patch files become patch sets first (`tools/cheats.py`, `tools/exefs_patches.py`, status in `build-cache/cheats.status` and `exefs.status`); a file the tools refuse costs those cheats or patches, not the install. The patch files' writes into main's data go to `build-cache/exefs.data`, which the game stores into main at start; after the lift they are checked against the bytes the lifted code read as constants (`/main/folded.txt`, its jump tables). 6. **Compile** the generated C, `modules.c`, `romfs.c`, `patches.c` and `ov_zstd.c` (they bake the per-install layout, RomFS hashes and the game version's patch page) and link them with the prebuilt runtime library for the host's level (`libtotkrt.a` or `libtotkrt-v2.a`) into `totk.exe` (`build_game.py --runtime-lib`; about 3 min on 24 cores). 7. **Prepare** (only when the runtime, the translator or the game version changed, not for a new lift) the RomFS patches and the shaders (`tools/make_romfs_patches.py`, `tools/prepare_shaders.py`, `totk.exe --prepare-shaders`) in the install folder, then fold the shader cache's loose files (four per shader, about 117,000) into `shader-cache/shader-cache.pack` (`tools/pack_shader_cache.py`). totk.exe reads the pack first and writes the translations it makes in play as loose files; running the tool again with the game closed folds those in. The patches are written three times: `romfs-patches`, `romfs-patches-xbox` and `romfs-patches-xbox-label` (`--prompts`: Xbox button prompts for `prompts = xbox`, the first for `pad_layout = nintendo`, the second for `xbox` and `auto`). The prompt folders are optional: when one cannot be made, the setup warns and finishes. **PC prompts** (step `pc_prompts`): `romfs-patches-pc`, the keyboard and mouse prompts for `prompts = pc`, drawn from the `bind_` lines of `totk.ini` (`--binds`). Its key holds those lines, so a setup run after a change of the bindings draws only these again. Optional like the Xbox prompts. All four 16:9 folders are always written, so a switch of the prompts style at 16:9 needs no setup run. When the graphics driver crashes while building the shaders, `prepare_shaders.py` runs that part again without the variants it was building ([building.md](building.md), step 6), and the setup finishes with a warning that names how many were left out. 8. **Shapes**: the UI laid out for each screen shape this player needs, `romfs-patches-x` (`--aspect`), and with Xbox or PC prompts in `totk.ini` that layout with those prompts too, `romfs-patches-