mirror of
https://github.com/valentderah/totk-pc-recomp.git
synced 2026-11-11 01:41:02 +00:00
Valiantsin DzerakhandClaude Opus 5.5
bdcfb42c07
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
44 lines
3.1 KiB
Markdown
44 lines
3.1 KiB
Markdown
# TotK Recomp
|
|
|
|
Static recompilation of *Tears of the Kingdom* (Switch, ARM64) into a native Windows x86-64 exe with a Vulkan renderer. Design: [docs/architecture.md](docs/architecture.md). Toolchain, build commands and tests: [docs/building.md](docs/building.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 the upstream checkouts (`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.
|
|
- `tools/vendor/` stays byte-identical to upstream; Windows changes go in `tools/extract.py`.
|
|
|
|
## Code
|
|
|
|
- Build C with MSYS2 UCRT64 Clang (`C:\msys64\ucrt64\bin`). Generated C uses GNU extensions, so `cl.exe` is out. Call Ninja from that directory by full path or put it first on PATH.
|
|
- Two Python environments: `.venv` (3.12) for the lifter and the build, `.venv-py314` for the extraction and shader scripts, which need `compression.zstd`.
|
|
- Generated C is never edited by hand: change the generator (`recomp/`).
|
|
- Every lifter change passes the differential tests against Unicorn ([docs/building.md](docs/building.md), "Checks"). After changing `recomp/jumptables.py`, `tests\jumptables_check.py` reports 0 disagreements on 1.2.1 and 1.4.3.
|
|
- `recomp/layout.py` alone decides module bases.
|
|
- Graphics bugs: [docs/maxwell.md](docs/maxwell.md) lists the Maxwell behaviour the Vulkan path must match and the TotK bugs other ports fixed.
|
|
- Comments say what the code does and why, in words that stand on their own. Cite our code by file plus function (a line number may follow as a hint) and upstream code by project, file and function: `refs/` moves, so its line numbers rot. Commit hashes belong to the attribution of copied code.
|
|
|
|
## Running and debugging
|
|
|
|
- Running the game, screenshots, frame dumps, timings: [docs/agents/running.md](docs/agents/running.md).
|
|
- Investigating a bug, glitch or crash: search [docs/agents/symptoms.md](docs/agents/symptoms.md) by the player's words first, then follow [docs/agents/debugging.md](docs/agents/debugging.md). Read the code before running the game.
|
|
|
|
## Pull requests
|
|
|
|
Preparing a pull request: target `dev`; the checks by changed area, the proof and the performance runs it carries are in [CONTRIBUTING.md](CONTRIBUTING.md), "Pull requests". Reviewing one: [docs/pr-review-kit/](docs/pr-review-kit/).
|
|
|
|
## Writing
|
|
|
|
Code, comments, docs and commit messages are in English. Commit messages are plain sentences without type prefixes.
|