tools/builder is the window (and its text mode) that checks the Mac and the player's files, runs build_app.py,
starts the game with its settings, and manages the player's mods and controls, for Tears of the Kingdom and Breath of
the Wild. What a player sees is in install.md. This page is for the people and the AI
assistants who change its code: how it is laid out and the rules every change keeps.
- It ships nothing of the game, and no mod. Every mod is one the player adds; the builder checks it, orders it and installs it. It has no built-in cheats or gameplay changes: the game's logic stays as it is (CONTRIBUTING), and a player who wants a cheat adds it as a mod.
- It does not do the repository's work a second way. A build is
build_app.py, run with the paths the checks approved. Mods are validated and installed bygames/totk/scripts'make_mod_manifest.pyandmod_folder.py, imported and called in process (mod_tools.py), so the builder accepts exactly what the game's installer accepts. - It stores paths and facts, never contents. Keys, game files and saves are read where they are and never copied.
The builder is MVC with the effects at the edges.
| Layer | Modules | Rule |
|---|---|---|
| Model | games, manifests, inputs, checks*, paths, command, progress, session, process, config, game_state, start_options, mod_*, controls_file, icons_*, updates, background |
No Tk. Pure where it can be; effects only through the ports it is given |
| Controller | controller (with build_run, build_request), controller_start, controller_mods, controller_controls, controller_icons |
Blocking work runs as jobs on one worker thread (jobs.py); the view calls tick(), which never waits; results come back as events |
| View | gui*.py (Tk), cli.py (text) |
Draws the state and events it receives and calls the controller. No rule lives in a view |
| Composition root | app.py |
The one place that creates the real adapters (ports.py: commands, clock, files) and wires them; tests pass fakes with the same methods |
| Texts | strings.py, strings_tabs.py |
Every visible text, in English, by id. A missing id is a bug that a test finds |
Each tab has its own part of the controller and its own job at a time: a second request while one runs is refused, not
queued. Work that may take long (an archive, a download, a build) runs in its own process group and can be cancelled
(cancellable.py, process.py).
- A contract per module. The module's docstring says what it promises, what it refuses and what it leaves to
others. Change the docstring with the code; a reader (or an assistant) should not need anything else to use the
module. Tags such as
S5.4 C2orE6name the step and rule that introduced a behaviour. - At most 300 lines per file, tests included. It is what can be read whole in one pass: a file read in parts ends
with a function or a class written twice. Split by responsibility before growing (
gui_controls_info.pycame out ofgui_controls.py,mod_applied.pyout of the Mods controller). Read the whole file before editing it, and search for what you are about to write. - One writer per file.
library.jsonis written only by the Mods part's job,settings.jsononly byconfig.save(atomically). Every Apply of the mods goes throughmod_applied.apply_and_record, and a test reads the source to make sure nothing callsmod_library.applydirectly. - Keep what you do not know.
config.loadandmod_library.open_librarykeep keys they do not know, so data written by a newer or another builder survives an older one. - Narrow exceptions. Catch only the errors the contract names, where they can happen. A broad
exceptstays only at a few boundaries, each with a comment that says why: a crashing check becomes a blocking result (checks.run_checks), the worker keeps a job's error for whoever reads its result (jobs.py), a job's error is published once instead of raised at every tick (build_run.py), and the views stay alive after an error (gui.py,cli.py). A cleanup that catchesBaseExceptionundoes its own work and raises again. - Processes. An argument list, never a shell, in a process group of its own. A cancel or a timeout tries to stop the whole group: a build gets SIGINT, then SIGKILL; an archive or the icons' script gets SIGKILL and is waited for. Nothing claims a cancel worked: the window says how the process ended and whether that matches the signals sent.
- The view's thread never waits. Checks, builds, reading the library, archives and downloads are jobs; a view asks the controller and draws the answer when it comes. The few effects a view does itself (opening the app or Finder, the clipboard) are injected, so tests replace them.
- Mirror, and test the mirror. Where the builder restates something of the repository (the versions of
build_app.py, the controller map's parser, the game's start options), a drift test reads the original source and fails when the two part.
| Path | What |
|---|---|
~/Library/Application Support/MacNativeGames/Builder/ |
settings.json (paths, the last build), the chosen picture, the Controls tab's state, the venv for the button icons |
~/Library/Application Support/MacNativeGames/<TOTK or BotW>/mod-library/<version>/ |
The player's mods, cloned when added, and library.json (order, switches, checks, what was applied) |
~/Library/Application Support/MacNativeGames/<TOTK or BotW>/ |
controls.txt and controller-type.txt, which the game reads |
~/Library/Logs/MacNativeGames/builder-<game>-<date>-<time>.log |
Each build's output |
python3.14 -m unittest discover -s tests -p 'test_builder_*.py'Python 3.14 is needed (compression.zstd); the window's tests need Tk. The whole suite is
python -m unittest discover -s tests, as in CONTRIBUTING.
- Real files in a temporary folder. Tests that touch the library or the game's folders point
HOMEinto a temporary folder and first assert that the paths resolve inside it, so no test can reach a player's data. - Fakes at the ports.
tests/builder_fakes.py(the ports),builder_fake_process.py,builder_fake_build.pyandbuilder_fake_controller.py(a view's tests drive a real Tk view against a fake controller);builder_tk_base.pygives a withdrawn Tk root and helpers to read what the view shows. - Integration first. A model that wraps the repository's own scripts is tested against them (the real installer, a
harness compiled from
runtime/controller_map.h), not against a copy of their behaviour. - A test must be able to fail. When a test guards a rule, break the rule once and see the test fail, then put it back and see it pass.
- A game or a version: start from
games.py, which mirrorsbuild_app.py(its drift test says what does not match). The Settings and Mods tabs name the version they serve (start_options.py,controller_mods.LATEST,mod_library.TITLE_IDS); a version they do not know is said in words, never guessed. - A tab: a model module with its contract, a controller part with its own job, a
gui_<tab>.pyview that only draws, its texts instrings_tabs.py, and the view registered ingui.py. - A mod layout or a mod check:
mod_find.pyfinds the mod's folders,mod_tools.pyvalidates it with the repository's scripts, and every refusal has a text that says why in words.