From 501f0d3e6f03d02cb0d6d83643a26149627003d8 Mon Sep 17 00:00:00 2001 From: Valiantsin Dzerakh Date: Tue, 17 Nov 2026 10:54:17 +0300 Subject: [PATCH 1/3] The setup installs a build kit into the game folder, and the game's rebuild for code mods runs from it (#845) The rebuild for ExeFS patches, code cheats and mod plugins ran the setup window from the setup folder, whose absolute path build-cache/rebuild.txt held, with the generated C and objects in that folder's temp/. A moved or deleted setup folder left code mods without a rebuild. - A new Kit step after the check copies the release folder without TotK-Setup.exe into /build-kit (installer/layout.py KIT_ITEMS), and every later step runs its tools from there. A newer setup replaces the kit, the kit's own rebuild keeps it. - The release's temp folder is /build-cache/work, so the lift cache and the objects stay with the game. - rebuild.txt names the kit relative to the game folder; runtime/cheats.c and runtime/romfs.c resolve relative entries against the exe's folder. - runtime_key drops the lines of clang --version that name its folder, so a rebuild from the kit or a moved game folder keeps the compile and prepare steps the setup recorded. - An update over an install of an older setup moves that setup's temp folder into build-cache/work when both are on one disk. Co-Authored-By: Claude Opus 5.5 --- docs/installer.md | 60 ++++++++++----- docs/mods.md | 8 +- installer/cli.py | 24 ++---- installer/gui.py | 4 +- installer/guilogic.py | 2 +- installer/layout.py | 50 ++++++++++-- installer/runner.py | 6 ++ installer/steps.py | 146 ++++++++++++++++++++++++++++++++---- installer/text/en.json | 4 + installer/text/pt-BR.json | 4 + installer/text/ru.json | 4 + installer/text/zh-Hans.json | 4 + runtime/cheats.c | 10 ++- runtime/platform/platform.h | 11 +++ runtime/romfs.c | 11 ++- tests/installer_test.py | 126 ++++++++++++++++++++++++++++++- tools/make_release.py | 1 + 17 files changed, 410 insertions(+), 65 deletions(-) diff --git a/docs/installer.md b/docs/installer.md index 347e9434..24b3a22d 100644 --- a/docs/installer.md +++ b/docs/installer.md @@ -1,8 +1,9 @@ # 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. The installed folder -holds only the game; the installer and its tools stay outside it. +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 @@ -16,7 +17,8 @@ holds only the game; the installer and its tools stay outside it. 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 installer and the source NSP or XCI (or NSZ, XCZ) can be deleted. +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): @@ -32,14 +34,22 @@ The install folder (`main.c` `portable_paths()` reads this layout; it stays port 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, rebuilds `totk.exe` and re-prepares the -shaders. 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 +`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. @@ -53,21 +63,27 @@ loads the saves 1.4.3 wrote. `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. **Fonts** with Chinese, Korean or Traditional Chinese text and a firmware folder: extract the Switch system fonts +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. -3. **Extract** ExeFS and RomFS into the install folder and verify the hashes. -4. **Lift** the ExeFS to C (`recomp/gen.py`, `recomp/patches-v121.txt` or `patches-v143.txt`) into a temp folder next - to the installer. The code cheats of the mods' cheat files and the mods' ExeFS patch files become patch sets first +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). -5. **Compile** the generated C, `modules.c`, `romfs.c`, `patches.c` and `ov_zstd.c` (they bake the per-install layout, RomFS +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). -6. **Prepare** (only when the runtime, the translator or the game version changed, not for a new lift) the RomFS +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 @@ -82,7 +98,7 @@ loads the saves 1.4.3 wrote. 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. -7. **Shapes**: the UI laid out for each screen shape this player needs, `romfs-patches-x` +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-