Files
totk-pc-recomp/AGENTS.md
T
2026-10-23 23:08:22 +03:00

6.3 KiB

TotK Recomp

Static recompilation of Tears of the Kingdom (Switch, ARM64) into a native Windows x86-64 exe with a Vulkan renderer. Plan: docs/architecture.md.

Game content boundary

This repository is public. Game data lives outside it and every derived file stays in ignored folders.

  • The user's game and key paths are in config.local.toml (ignored). Pass the keys file path to tools; the tools read it themselves. Key values stay out of your output, logs, commands and files.
  • Everything extracted or generated goes under build/ or generated/.
  • Every file the code generator emits carries the marker defined as GENERATED_MARKER in tools/check_content.py.
  • Run python tools/check_content.py --staged before proposing a commit. It is the same check CI runs.

Reusing code

refs/ holds upstream checkouts at the commits the research notes cite (tools/fetch_refs.sh recreates it). Read-only.

  • Copy only MIT, BSD, ISC, zlib or Apache-2.0 code, keep its header, and add a row to THIRD_PARTY_NOTICES.md.
  • yuzu, suyu, OpenSmash-Ultimate and other GPL code: read for behaviour, write our own.

Research notes

Read the note before working on its area; each cites file:line in refs/.

Toolchain

Setup and verify commands: docs/toolchain-windows.md, docs/toolchain-msys2-python.md.

  • Build C with MSYS2 UCRT64 Clang (C:\msys64\ucrt64\bin). Generated C uses GNU extensions, so cl.exe is out.

  • A 32-bit winlibs cmake/ninja sits early on the user PATH. Call CMake and Ninja from C:\msys64\ucrt64\bin by full path or put that directory first.

  • Two Python environments: .venv (3.12) for the lifter and LAS Recomp tools, .venv-py314 for MacNativeGames' extraction scripts, which need compression.zstd.

  • Game extraction: .venv-py314\Scripts\python tools\extract.py writes verified ExeFS and RomFS to build/extracted/v0 (1.0.0) and build/extracted/v121 (1.2.1, the primary target). tools/vendor/ stays byte-identical to upstream; Windows changes go in tools/extract.py.

  • Lifter (recomp/) and CPU headers (runtime/) start from LAS Recomp. Every lifter change passes the differential tests against Unicorn, all run with .venv:

    • tests\diff\lift.py: instructions sampled from the extracted 1.2.1 modules (one per opcode signature, then random); --coverage lists every word the lifter rejects or turns into a trap.
    • tests\diff\simd.py: the whole FP/SIMD encoding space; needs no game files.
    • tests\diff\atomic.py: exclusive load/store sequences and ARMv8.1 atomics; needs no game files.
    • tests\diff\func.py: whole leaf functions as the generator emits them, loops and jump tables included.
    • tests\excl_mt.py: the exclusive monitor helpers of cpu.h under contention and ABA, on several threads; needs no game files.
  • Game code build (.venv): recomp\gen.py --exefs build\extracted\v121\exefs --out generated\v121 --patches recomp\patches-v121.txt writes the C (about 15 s). The patch table holds the 60 fps and real-time frame step code patches, switchable at run time (recomp/patches.py); .venv-py314\Scripts\python tools\make_romfs_patches.py writes their RomFS half to build\v121\romfs-patches. tools\build_game.py compiles and links build\v121\totk.exe with Ninja (about 200 s clean, incremental after). recomp/layout.py alone decides module bases. Jump tables are resolved by recomp/jumptables.py; after changing it, tests\jumptables_check.py must report 0 disagreements with its Unicorn oracle.

  • Shader census (.venv-py314): tools\shader_census.py --version v121 [--translate] extracts every Maxwell shader to build/v121/shaders/ and runs it through build\xlate\totk_xlate.exe and spirv-val; failure groups go to failures.txt. tools\xlate_smoke.py checks the translator alone, without game files.

  • Shader preparation (.venv-py314, once per build dir and translator): tools\prepare_shaders.py build\v121 translates the variants of the MacNativeGames shared shader list (read from refs/ at run time) into the build's shader cache and builds their stage libraries into the driver cache (totk.exe --prepare-shaders, about 5 min, 1.3 GB); play then translates and compiles only variants the list lacks.

  • The plan by stage and the proposed fixes with their evidence: docs/backlog.md.

  • Running, measuring or frame-dumping the game, save backups, task worktrees and their builds: docs/agent-playbook.md.

  • Project skills (.claude/skills/): private-build before changing runtime/ or tools/ code and building totk.exe (one git worktree per task); run-game to run a build into gameplay from a save.

  • hactool: toolchain/hactool/hactool.exe. From an MSYS2 shell pass -k <keys> explicitly; the shell's HOME hides the default key location.

  • Ghidra 12.1.2 with SwitchLoader: toolchain/ghidra/ghidra_12.1.2_PUBLIC. Game modules (NSO) open here, headless or GUI.

  • REA (reverse-engineer-anything skill + MCP server) analyses our own x86-64 builds. On Windows its Ghidra provider admits PE files only, so NSO analysis goes through Ghidra directly. Register the MCP server once per clone, at local scope:

    claude mcp add --scope local rea -e "GHIDRA_INSTALL_DIR=<repo>\toolchain\ghidra\ghidra_12.1.2_PUBLIC" -e "JAVA_HOME=<jdk-21>" -- cmd.exe /d /c npx -y rea-agents@6.7.0 mcp
    

Writing

Code, comments, docs and commit messages are in English. Commit messages are plain sentences without type prefixes.