mirror of
https://github.com/valentderah/totk-pc-recomp.git
synced 2026-11-18 12:08:38 +00:00
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
73 lines
3.7 KiB
Markdown
73 lines
3.7 KiB
Markdown
# Tester guide: running TotK Recomp on your GPU
|
|
|
|
This guide is for testing the build on a GPU other than the developer's (AMD RX 9070). You build it from source with
|
|
your own copy of the game and your own console keys. Nothing from the game is in this repository, and nothing you build
|
|
from it may be shared.
|
|
|
|
## What you need
|
|
|
|
- Windows 10 or later, an x86-64 CPU with AVX2, about 60 GB free.
|
|
- A GPU with Vulkan 1.3 and `VK_EXT_external_memory_host`, with a current driver.
|
|
- *Tears of the Kingdom* base game (1.0.0) and the 1.2.1 update, dumped from your own Switch as NSP or XCI.
|
|
- `prod.keys` dumped from your own Switch. Never send it to anyone, and never paste it into a log or an issue.
|
|
|
|
## Build
|
|
|
|
1. Install the toolchain: [toolchain-windows.md](toolchain-windows.md) and
|
|
[toolchain-msys2-python.md](toolchain-msys2-python.md).
|
|
2. Follow steps 1-5 of "Building from source" in the [README](../README.md): Python environments, `config.local.toml`
|
|
with your own paths, extraction, the shader translator, then lifting and linking. The result is
|
|
`build\v121\totk.exe`.
|
|
3. Check the build without the game: `build\v121\totk.exe --selftest` must print a pass.
|
|
4. To run the build on another of your machines, `.venv\Scripts\python tools\package_build.py` writes
|
|
`build\v121-portable` (about 2.4 GB). Copy it over; it needs no MSYS2, Python or .NET. The 16 GB RomFS is not in it:
|
|
copy `build\extracted\v121\romfs\romfs.bin` into `romfs\` there, or run the packager with `--with-romfs`.
|
|
Then run `totk.exe --prepare-shaders` once in the copied folder (about a minute): the driver caches pipeline
|
|
libraries per exe path, and without it the first fights stutter.
|
|
The folder holds game code: for your own machines only.
|
|
|
|
## Run and collect the log
|
|
|
|
The log goes to stderr. Run from `cmd.exe` in the repository root, so the log lands in a file:
|
|
|
|
```bat
|
|
set TOTK_VK_VALIDATION=1
|
|
build\v121\totk.exe 2> totk-log.txt
|
|
```
|
|
|
|
`TOTK_VK_VALIDATION=1` turns on the Vulkan validation layer (it comes with the Vulkan SDK). It makes the game slower;
|
|
do one run with it and one without (`set TOTK_VK_VALIDATION=`).
|
|
|
|
Keep the window in the foreground: an unfocused window stalls the game. The first launch spends minutes on shaders.
|
|
Play into the open field (load a save, walk around for a minute, fight something if you can), then close the window.
|
|
|
|
## Choosing the GPU
|
|
|
|
A laptop with an iGPU and a discrete GPU, or two cards, lists every GPU at the top of the log (`vk: gpu 0: ...`).
|
|
|
|
- `set TOTK_GPU_NAME=Radeon` picks the first usable GPU whose name contains that text (case does not matter).
|
|
- `set TOTK_GPU_INDEX=1` picks GPU 1 from that list.
|
|
|
|
The line `vk: using gpu N: <name>` says which one ran.
|
|
|
|
## What to send back
|
|
|
|
1. `totk-log.txt` from each run. It contains no keys and no game files. The lines that matter most start with
|
|
`vk caps:` (GPU, driver, features and the fallbacks taken), `vk: gpu`, `validation` and `gfx_shader:`.
|
|
2. GPU model, driver version, CPU, RAM, and whether it is a laptop.
|
|
3. What you saw: how far it got (menu, loading, field), roughly how smooth it ran, and screenshots of anything wrong
|
|
(black or missing areas, flickering, wrong colours, missing grass). Win+Shift+S is fine.
|
|
4. If it crashed or hung: the last 50 lines of the log and what you were doing.
|
|
|
|
## Switches for the developer's questions
|
|
|
|
Only set these when asked; each forces a fallback the build picks by itself on GPUs that need it.
|
|
|
|
| Variable | Effect |
|
|
|---|---|
|
|
| `TOTK_VK_NO_FLOAT64=1` | Translate shaders without 64-bit floats |
|
|
| `TOTK_VK_SSBO_ALIGN=64` | Treat storage buffers as needing 64-byte alignment |
|
|
| `TOTK_VK_SUBGROUP_PIN=0` | Do not pin shaders to 32 lanes; tell the translator the GPU's own subgroup size |
|
|
|
|
Each switch makes the first launch translate every shader again.
|