Valiantsin DzerakhandClaude Opus 5.5
f646e521f0
The README is a front page now: a general status, a short feature list, install steps from a release, credits as a list of links that points to THIRD_PARTY_NOTICES.md, the build steps last. The licence table moved into the notices. The build steps take the game version as <ver>; 1.4.3 is the primary version in the architecture doc, which also gains the zstd host decoder, the settings table and menu, spin gates, the uniform snapshot and the resolution patches. Controls list F1, F10, F11 and the menu keys; the tester guide and CONTRIBUTING point to logs\totk.log. THIRD_PARTY_NOTICES.md: the four code rows that sat in the installer table move to the main table, the zstd rows cover ov_zstd.c and the release package, the MacNativeGames resolution commit is given in full, the NVN proc list and the compiler runtime of a source build are listed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4.2 KiB
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 or 1.4.3 update, dumped from your own Switch as NSP or XCI.
prod.keysdumped from your own Switch. Never send it to anyone, and never paste it into a log or an issue.
Build
- Follow building.md: the toolchain, then build steps 1-6 (Python environments,
config.local.tomlwith your own paths, extraction, the shader translator, lifting and linking, shader preparation). The result isbuild\<ver>\totk.exe, with<ver>the game version you built (v143orv121). - Check the build without the game:
build\<ver>\totk.exe --selftestmust print a pass. - To run the build on another of your machines, package a portable folder (building.md, "Portable folder"). The folder holds game code: for your own machines only.
- The installer (installer.md) is the other route to a machine without the toolchain: it builds the game there from your own files. No installer release is published yet.
Run and collect the log
Every run writes its log to logs\totk.log next to totk.exe; the four runs before it are kept as totk.1.log to
totk.4.log, and Open log folder in the settings menu's Advanced tab (F1) shows them. Copy the log before you start the
game again. A file stops at 64 MiB. Started with 2> file, the game writes its log to that file instead.
From cmd.exe in the repository root, with the validation layer on:
set TOTK_VK_VALIDATION=1
build\<ver>\totk.exe
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. Shaders the preparation did not cover compile on first use, so the first minutes of play can stutter. 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=Radeonpicks the first usable GPU whose name contains that text (case does not matter).set TOTK_GPU_INDEX=1picks GPU 1 from that list.
The line vk: using gpu N: <name> says which one ran.
What to send back
logs\totk.logfrom each run. It contains no keys and no game files. The lines that matter most start withvk caps:(GPU, driver, features and the fallbacks taken),vk: gpu,validationandgfx_shader:.- GPU model, driver version, CPU, RAM, and whether it is a laptop. Copy system info in the settings menu's Advanced tab (F1) puts these and your changed settings on the clipboard. Say which game update you ran.
- 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.
- If it crashed or hung: what you were doing. The log of that run ends with the crash report, so send it whole.
- For a bug you can trigger again: a recording of your input (
set TOTK_INPUT_RECORD=input.txt, see controls.md, "Scripted input") and the save you started from.
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.