diff --git a/.github/ISSUE_TEMPLATE/1-crash.yml b/.github/ISSUE_TEMPLATE/1-crash.yml index 05366944..14055cc4 100644 --- a/.github/ISSUE_TEMPLATE/1-crash.yml +++ b/.github/ISSUE_TEMPLATE/1-crash.yml @@ -77,7 +77,6 @@ body: - The log of the run that crashed is `logs\totk.log` in the folder of `totk.exe` (F1, Advanced tab, Open log folder). Copy it before you start the game again: the next start renames it to `totk.1.log`, and after five starts it is gone. - Attach the whole file. Do not cut or edit it: the crash report is at the end, the GPU and driver lines are at the start. - The log says `device lost` or `VK_ERROR_DEVICE_LOST` and the GPU is an NVIDIA one: set GPU pass marks to On (F1, Advanced tab, Diagnostics), restart the game, make it crash again and attach that log. The `vk: pass marks` lines then name what the GPU was drawing. - - The crash happens at the same point every time: also attach the input recording and the save described in the Other bug template. - type: textarea id: log attributes: @@ -85,3 +84,17 @@ body: description: Drag totk.log into this field. validations: required: true + - type: markdown + attributes: + value: | + ### Save and input recording + + When the crash comes back at one place in the game (an area, a shrine, a cutscene, a quest step), the save that gets there lets us crash it on our machine. + + 1. Zip the `profile` folder next to `totk.exe` and attach it. Say which slot you load, or that you use the autosave. + 2. If it takes more than walking a few steps from the save: turn on Input recording (F1, Advanced tab, Diagnostics), restart the game, load the save, make it crash, and attach `input-record.txt` from the logs folder together with the `totk.log` of that run. + - type: textarea + id: save + attributes: + label: Save and input recording + description: Drag the zipped profile folder and input-record.txt into this field, when the crash comes back at one place. diff --git a/README.md b/README.md index 0529473c..9b0c3f9d 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,10 @@ Report problems as issues, following [CONTRIBUTING.md](CONTRIBUTING.md). - 16:10 (Steam Deck, handhelds), 3:2 (Surface, Framework), 21:9 and 32:9 (ultrawide) game resolutions, with the camera and the interface in that shape - Anisotropic texture filtering up to 16x, for sharp ground into the distance - In-game settings menu (F1) and performance overlay (F10) +- Discord Rich Presence ("Playing TotK Recomp" with the play time), off by default, own application id supported - Setup and in-game menu in English, Russian, Brazilian Portuguese and Simplified Chinese - Keyboard, mouse and gamepad with remapping, rumble and gyro +- Stereo or 5.1 surround sound output - Xbox button prompts: LB, RB, LT, RT, Menu and View, and A, B, X and Y as labelled on the button to press, with either button layout - Shaders prepared at install instead of during play - Mods made for emulators: unpack a mod into the `mods` folder next to `totk.exe`; switch and order them in the menu. RomFS diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index 2d890f97..8b5e93b7 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -103,3 +103,4 @@ folder's `licenses/` and in each component's own folder. | `totk_xlate` (NativeAOT linux-x64 build of `tools/xlate/`, linked with the folder's clang, lld and sysroot) | built by `tools/build_xlate.py --llvm --sysroot` | MIT | `bin/totk_xlate` | | AppImage type-2 runtime (static; includes libfuse and squashfuse), the AppImage's first part; appimagetool packs the folder and is not distributed | https://github.com/AppImage/type2-runtime | MIT; libfuse LGPL-2.1; squashfuse BSD-2-Clause | the AppImage header | | MacNativeGames shader variant list | as in the installer release row above | MIT | `data/shader_list.tsv` | +| Weeping of the Empire menu cursor: eui's focus box read through ScreenMgr, BoxCursorMgr and the screens' node lists, AnimButton's hit test, the stale-hit-pane fallback to the parts panes, the three writes of moveBoxCursor, the structure offsets (1.0.0; the ScreenMgr instance placed in 1.4.3 by us) | https://github.com/daniel-madrid-07/weeping-of-the-empire @ `df0586cdc5702ca19bbebfa59697e0b6980f6237` (`engine/runtime/totk_menu_cursor.cpp`), Copyright (c) 2026 daniel-madrid-07 | MIT | `runtime/menu_cursor.c` | diff --git a/VERSION b/VERSION index 42045aca..0f826853 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.3.4 +0.3.7 diff --git a/docs/architecture.md b/docs/architecture.md index 949aff73..fb1afd42 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -84,7 +84,7 @@ Every guest thread is a host thread. TotK assumes Horizon's scheduler: three app - NVN front end from MacNativeGames (`nvn_api_*.c`, `nvn_obj.h`, texture layout and deswizzle). The game records command buffers through it; nothing reaches the GPU until the game submits. - Vulkan 1.3 back end in place of MacNativeGames' Metal one. At `QueueSubmitCommands` the recorded NVN commands are replayed into Vulkan command buffers (`vk_exec*.c`). - Memory pools. Apple's unified memory let MacNativeGames use the game's pools zero-copy. The back end imports the pools as host memory (`VK_EXT_external_memory_host`). On a discrete GPU, pools bound as buffers are mirrored in device-local memory and the pages the CPU wrote (write watch, above) are uploaded before a replay; idle pool regions are made read-only so the write-watch queries skip them (`vk_memory.c`). GPU-rendered textures are written back when the CPU reads them: on a pool invalidate, on a CPU copy, and for small targets once the CPU waits for a fence (`vk_texture.c`). -- Replay thread. `TOTK_REPLAY_ASYNC=1` moves the replay off the submitting thread onto a queue at most one frame behind the game; reads of GPU results wait for the newest writer instead of draining the queue (`vk_backend.c`). It is on by default: where the game waits for the GPU it overlaps the replay with the game threads (a GTX 1650 in the Depths, issue #88), elsewhere it is neutral; it adds up to a frame of latency, and `replay_async = 0` turns it off. +- Replay thread. `TOTK_REPLAY_ASYNC=1` moves the replay off the submitting thread onto a queue at most one frame behind the game; reads of GPU results wait for the newest writer instead of draining the queue (`vk_backend.c`). It is off by default. Where the game waits for the GPU it overlaps the replay with the game threads (a GTX 1650 in the Depths, issue #88), a gain measured only there; while it was the default, a GTX 1660 Ti at the 60 fps cap with the GPU at 26 % reported uneven motion (#659). It adds up to a frame of latency; `replay_async = 1` turns it on. - Recorder thread. The Vulkan calls the replay makes into its command buffer are made by a thread of their own (`vk_rec.c`, after Savage Wind Recomp and LAS Recomp): each `vkCmd*` copies its arguments into a packet of a ring and the recorder makes the calls in order; calls into other command buffers are made at once; the recorder also ends the command buffer, and the submit waits until it has. In the town on an RX 9070 the replay takes 17% less time on the submitting thread. It is off by default on AMD GPUs, where the driver loses the device or hangs the GPU at startup with it (`TOTK_VK_RECORDER=1` forces it on, `=0` makes every call on the submitting thread). - Uniform snapshot. The game rewrites per-object uniform blocks on other threads soon after it submits the frame that reads them, while the replay still records it. At the start of a submission's replay every uniform range it @@ -118,8 +118,13 @@ Every guest thread is a host thread. TotK assumes Horizon's scheduler: three app - DLAA (`vk_dlaa.c`, `dlaa`, off by default). NVIDIA DLSS at the scene's own size, through the driver's NGX core loaded at run time (no SDK code compiled in). It runs on the R11G11B10F light target right before the bloom chain's first pass, so post effects and the HUD read the anti-aliased picture. The scene's draws get a sub-pixel Halton viewport - jitter; motion vectors are camera-only, reprojected from the scene depth through this and last frame's - view-projection of the scene camera block (constant bank c4). `fxaa` switches the game's own FXAA pass. + jitter; camera motion vectors are reprojected from the scene depth through this and last frame's view-projection of + the scene camera block (constant bank c4), in double precision on the CPU. Per-object motion (`dlaa_objmv`, + `vk_mvprev.c`, the per-object section of `vk_exec_draw.c`, translator patch 0015): solid scene draws whose position + reads an object's own uniform blocks (bones c5, place c7, c6) are drawn a second time with a vertex shader variant + that computes last frame's position from last frame's blocks (the game writes them into two copies that take turns; + the uniform snapshot keeps both) and writes the difference into the motion image. `TOTK_MV_CHECK` measures the + vectors against the picture, `TOTK_DLAA_TIMES` times the passes on the GPU. `fxaa` switches the game's own FXAA pass. - Occlusion queries never block the CPU; a result that is not ready counts as visible. - ASTC textures are uploaded as they are where the device reports `textureCompressionASTC_LDR`, and decoded by a compute shader everywhere else (`vk_astc.c`, `TOTK_ASTC`). The CPU decoder (`tex_astc*.c`) is the fallback and the test oracle. - Draw state. A draw whose program, bound state and textures repeat reuses the previous draw's shaders and skips rebuilding its descriptor sets; descriptor sets are written through update templates (`vk_exec_draw.c`, `vk_pipeline.c`). diff --git a/docs/building.md b/docs/building.md index 75585d71..30b8584f 100644 --- a/docs/building.md +++ b/docs/building.md @@ -115,7 +115,8 @@ of them. `SDL3.dll`, `libiconv-2.dll` and `libopus-0.dll` next to the exe. For Xbox button prompts, run `make_romfs_patches.py` twice more, with `--prompts xbox` and `--prompts xbox-label`: they write `build\\romfs-patches-xbox` and `romfs-patches-xbox-label` ([controls.md](controls.md), "Xbox - button prompts"), which `build_game.py` copies next to `totk.exe` like `romfs-patches`. + button prompts"), which `build_game.py` copies next to `totk.exe` like `romfs-patches`. `--prompts pc` writes + `romfs-patches-pc`, the keyboard and mouse prompts ([controls.md](controls.md), "PC button prompts"). 6. Prepare the shaders (once per build folder and translator). It needs `refs\MacNativeGames` (`tools\fetch_refs.sh`) for the shared shader list: @@ -150,6 +151,33 @@ your machines without MSYS2, Python or .NET. `romfs.bin` stays out unless you pa `romfs\` next to the exe or point `TOTK_ROMFS` at its folder. Run `totk.exe --prepare-shaders` once in the copied folder. The folder holds code and data derived from your game: for your own machines only. +### Profile-guided build + +`build_game.py --pgo .profdata` compiles the generated code at -O2 with an execution profile, and the runtime +with it too: hot paths laid out straight, hot calls inlined, code that never ran compiled for size. On 1.4.3 the fight +bench ran 12-15% faster per frame and a fight outside the training about 6%. The installer builds with +`data/pgo-.profdata` of the release when the update has one, else at -O1. + +A profile only fits the generated C it was trained on: functions are matched by name and control-flow hash, so a +function whose C changes loses its counts without a warning. Retrain after a lifter or generator change, from a clean +`recomp/`. The instrumented build needs llvm-mingw, as MSYS2's clang has no profile runtime: + +```powershell +$llvm = "toolchain\llvm-mingw-\llvm-mingw--ucrt-x86_64" +.venv\Scripts\python tools\build_game.py --version v143 --out build\v143-pgogen --toolchain $llvm --pgo gen +``` + +Play `build\v143-pgogen\totk.exe` through varied scenes (fights, towns, riding, building, the Depths, menus) for 20-30 +minutes; it is slower than a normal build. It writes `build\v143-pgogen\pgo\*.profraw` every minute and at exit. +Scripted runs from saves (`tools/run_game.py`) add to the same file. Then: + +```powershell +.venv\Scripts\python tools\pgo.py merge build\v143-pgogen --version v143 +``` + +writes `build\pgo\pgo-v143.profdata` and its record (`.json`: the `recomp/` tree it fits). `make_release.py` ships every +profile of `build\pgo` in `data\` and warns when a record names another `recomp/` tree than the one released. + ## Linux (in progress) The runtime builds and runs on x86-64 Linux with a window, input and menu on SDL3 (`*_sdl.c`) in place of the Win32 diff --git a/docs/controls.md b/docs/controls.md index 12c4d7c0..b1fc07fb 100644 --- a/docs/controls.md +++ b/docs/controls.md @@ -27,12 +27,13 @@ The log names the layout in effect (`input: gamepad layout ...`); the menu shows | D-pad left, up, right, down | D-pad | 1 2 3 4 | quick-select | | Plus | Start | Tab | menu, inventory | | Minus | Back | M | map | +| Right stick shaken left and right | shake the right stick | G | detach a fused part from what Ultrahand holds | Esc is unbound in the game; it opens the settings menu and releases the mouse cursor (see Mouse camera). Z and X duplicate ZL and ZR so menu pages turn with two neighbouring keys; the menu tabs (L, R) are Q and R. The mouse wheel is unbound. The bindings are the tables of `input_map` in `runtime/input_map.c`: the keys (platform-neutral key ids) and one gamepad table per layout (gamepad inputs by position); `runtime/input_win.c` translates Win32 virtual keys and SDL buttons. ## Xbox button prompts -`TOTK_PROMPTS` (`prompts`, the *Button prompts* row on the Controls tab, read at start) picks the controller whose buttons the game's prompts show: `nintendo` (default) keeps the game's own, `xbox` shows an Xbox controller's. +`TOTK_PROMPTS` (`prompts`, the *Button prompts* row on the Controls tab, read at start) picks the controller whose buttons the game's prompts show: `nintendo` (default) keeps the game's own, `xbox` shows an Xbox controller's, `pc` the keyboard and mouse (PC button prompts, below). - L, R, ZL, ZR, Plus and Minus become LB, RB, LT, RT, Menu and View, and the d-pad prompts a cross with an arrow for each direction meant. The letters on the keys are cut out in the game's own text font. - A, B, X and Y name the label of the button the pad layout presses, so each prompt names the button to press. `pad_layout = nintendo` plays an Xbox pad by position: the right button, labelled B, does Switch A (interact, confirm), and the bottom one, labelled A, does Switch B (run, cancel), so the prompts swap A with B and X with Y. `xbox` and `auto` put Switch A on the button labelled A, and the letters stay. @@ -56,6 +57,24 @@ The game reads its UI archive and fonts once at boot, so the prompts change at t The Switch prompts stay, with a note under *Button prompts* and a `RomFS overlay: ...` line in the log, when the folder is missing (an install made by an older setup, or one where the setup could not prepare it and showed a warning; running the setup again on the install folder writes it), when it fails its check, with a game resolution of another shape than 16:9 (its own UI layout wins; 16:10 and 21:9), and when the `romfs_mods` folder replaces one of its files: `romfs-patches` then loads in its place, where two overlays replacing one file would stop the game. In a source build, `.venv-py314\Scripts\python tools\make_romfs_patches.py --version --prompts xbox` (and `--prompts xbox-label`) writes `build\\romfs-patches-xbox` (`-label`); it needs fontTools from `tools/requirements-py314.txt`. `--xbox-prompts` is the older name of `--prompts xbox`. +## PC button prompts + +`prompts = pc` (*PC* on the *Button prompts* row) shows the key or mouse button the default keyboard bindings press each Switch button with, whatever the pad layout. The game loads `romfs-patches-pc` in place of `romfs-patches`, written by `tools/make_romfs_patches.py --prompts pc` (`button_icons.py`, `pc_icons`), which the setup runs next to the Xbox ones: + +| Switch | Prompt | +|---|---| +| A, B, X, Y | E, Shift, Space, left click | +| L, R, ZL, ZR | Q, R, right click, F | +| Plus, Minus | Tab, M | +| D-pad | 1 (left), 2 (up), 3 (right), 4 (down), as a cross or the keys of the directions meant | +| Left stick, its press | W A S D (or the keys of the directions meant), Ctrl | +| Right stick, its press | the mouse, with an arrow for each direction meant, C | + +- The glyphs keep the width of the game's own, so the right-aligned guides do not run into their text. A key is a rounded square with its label cut out in the game's own text fonts; a mouse button is a mouse with that button filled and the others hollow. +- The button guide in play draws every button from images of the Common archive (`Nt_KeyTexA/B/X/Y/L/ZL_00`, `Nt_KeyTexLSt_00` and `_01`, the stick tilted and pressed): all of them are painted with the same icons. The letters of the action prompt's diamond are one character of the Normal font each: E, an arrow for Shift, a bar for Space, L and R for the mouse buttons. +- Like the Xbox prompts they follow the defaults and not the bindings. `--binds ` draws the first key of each `bind_` line of that file instead, for a folder made by hand. +- At a game resolution of another shape than 16:9 the game loads `romfs-patches-pc-x` in place of `romfs-patches-x` when it is there: the same prompts with that shape's UI layout, `make_romfs_patches.py --prompts pc --aspect x --out \romfs-patches-pc-x`. The setup does not write those, so without one the Switch prompts stay (*off at a game resolution not 16:9*). + ## Window keys | Key | Gamepad | Action | @@ -68,9 +87,9 @@ The Minus+Plus combo never reaches the game. In the menu the arrow keys, the D-p ## Remapping -The *Controls* tab of the settings menu lists, under the button layout, every Switch button and the eight stick directions the keys drive (movement and camera), each with two key cells and a controller cell. Select a cell, press A or Enter, then press the new key, mouse button or controller button; Esc or five seconds without a press cancel, and a controller button cancels a key cell. Delete, Backspace or X clears the selected cell. A key another action has moves to the new one (the description names the action it left); a controller button swaps with the one it replaces. A remapped controller button is physical: from then on the face buttons (A B X Y) stay where they are in both layouts, until the buttons are put back as the layout in use has them or *Reset all buttons* is chosen. F1, F8, F10, F11 and Esc cannot be bound (the menu, the flight recorder and the window keep them). Punctuation keys are named by their place on a US keyboard; the menu shows the character the keyboard layout in use puts there. +The *Controls* tab of the settings menu lists, under the button layout, every Switch button, the eight stick directions the keys drive (movement and camera) and the shake key, each with two key cells and a controller cell. Select a cell, press A or Enter, then press the new key, mouse button or controller button; Esc or five seconds without a press cancel, and a controller button cancels a key cell. Delete, Backspace or X clears the selected cell. A key another action has moves to the new one (the description names the action it left); a controller button swaps with the one it replaces. A remapped controller button is physical: from then on the face buttons (A B X Y) stay where they are in both layouts, until the buttons are put back as the layout in use has them or *Reset all buttons* is chosen. F1, F8, F10, F11 and Esc cannot be bound (the menu, the flight recorder and the window keep them). Punctuation keys are named by their place on a US keyboard; the menu shows the character the keyboard layout in use puts there. -The tab writes `totk.ini` lines, one per Switch button or stick direction: `bind_