diff --git a/VERSION b/VERSION index 5503126d..20805912 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.3.10 +0.3.11 diff --git a/docs/building.md b/docs/building.md index 30b8584f..37c05e9f 100644 --- a/docs/building.md +++ b/docs/building.md @@ -230,7 +230,8 @@ Before a commit: A change to the button prompts (`tools/make_romfs_patches.py --prompts`, `tools/button_icons.py`) passes `.venv-py314\Scripts\python tests\romfs_prompts_test.py`, which runs the tool on a RomFS it makes itself (no game -files); a change to the settings passes `totk.exe --probe-cfg`. +files); a change to the settings passes `totk.exe --probe-cfg` and `python tests\settings_doc_check.py`, which fails +when a setting is described neither in `totk.ini.example` nor in [settings.md](settings.md). The lifter (`recomp/`) and the CPU headers (`runtime/cpu.h`, `runtime/simd.h`) are checked against Unicorn. Every lifter change passes these, all run with `.venv`: diff --git a/docs/controls.md b/docs/controls.md index b1fc07fb..8b8439cf 100644 --- a/docs/controls.md +++ b/docs/controls.md @@ -29,7 +29,7 @@ The log names the layout in effect (`input: gamepad layout ...`); the menu shows | 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. +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 zooms the Purah Pad's map and is unbound elsewhere. 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 @@ -109,31 +109,83 @@ bind_Y = pad:north, key:mouse_l ## Mouse camera -`mouse_mode = direct` (the default) turns the camera by the raw mouse motion on game 1.4.3, through hooks in the game's camera code (`runtime/mouse_direct.c`, the `mouse_direct` sites of `recomp/patches-v143.txt`). None of them changes a step of the gamepad alone. The free-orbit camera receives raw-count -angular increments at its final spherical-angle output: 0.08 degrees per count on both axes at sensitivity 1, with -no time multiplier, curve or carry into later frames. The controller's persistent pitch/yaw move with the output. -Mouse input is removed from its stick path first, so the camera's later vertical signed-square curve and velocity -filters cannot process it a second time. Other camera modes receive input after the radial dead zone, unit-circle -clamp and stick response exponent; Ultrahand has a separate hook after its manipulation input's power curves. -The game's camera inversion and gamepad response remain in effect. `mouse_sens` scales raw counts; its scale -differs from the stick-emulation mode. Start at 1. +`mouse_mode = direct` (the default) turns the camera by the raw mouse motion on games 1.4.3 and 1.2.1, through hooks in the game's camera code (`runtime/mouse_direct.c`, the `mouse_direct` sites of `recomp/patches-v143.txt` and `recomp/patches-v121.txt`). None of them changes a step of the gamepad alone. The free-orbit camera receives raw-count +angular increments at its final spherical-angle output: 0.08 degrees per count on both axes at sensitivity 1 (about +14.3 cm a turn at 800 DPI), with no time multiplier, curve or carry into later frames. The controller's persistent pitch/yaw move with +the output. Mouse input is removed from its stick path first, so the camera's later vertical signed-square curve and +velocity filters cannot process it a second time. +The aiming camera (bow, throwing), the Purah Pad camera, the scope, the ability camera (Ultrahand, Fuse, Ascend, +Recall, Autobuild), the horse camera, lock-on, the bow drawn while locked on, climbing (walls and objects), the +waterfall's turn, shield surfing, the wakeboard and the dialogue cameras take the mouse the same way, at the same +degrees per count: each turns by +the stick times its own speeds and the frame time and adds that to a base angle, so the load of the stick it turns by +gets the gamepad's part only and the load of that base angle gets the mouse's degrees (`camera_load`, two sites per +axis per camera). Their speeds, time step, slow motion (bullet time) and, for the Purah Pad camera and the abilities, +the eased curve their pitch moves along do not touch the mouse; their own limits, collision and blends apply to the +result. Past the pitch limit of the scope or the ability camera the stick moves the camera's distance; the mouse's +motion past the limit keeps doing that through the stick. Recall's cursor is the ability camera's offset mode: the +camera keeps a direction, the stick moves the cursor across the screen (ReverseRecorderCursorSpeed, within +ReverseRecorderCursorRange) and the camera follows it by up to ReverseRecorderCameraRange (10 degrees across, 7.8 up). +The mouse moves the cursor so that its aim, the camera's follow plus the cursor's angle from the screen's centre (the +offset taken as the screen's half width or height at the camera's 50 degree view and aspect ratio), turns as many +degrees a count as the camera does elsewhere. The follow range is read from the game each step (until it has been read +once, the mouse is stick input there). The stick loads that only test for input keep the mouse in the stick. A step with mouse motion that no +direct hook took is logged (`mouse: step N with mouse motion took the stick path`, the first 30, then one in 600, with +the player's state), so the cameras still on stick input show in `logs/totk.log`. +Lock-on keeps pointing the camera at the target; the stick, and so the mouse, adds an offset around that direction, +which the game limits and lets return: the mouse's degrees are the step's turn the game adds to the offset and judges +the return by. +Shield surfing and the wakeboard turn their pitch by the square of the stick's y and move a second camera parameter +with it: their stick y keeps the mouse (that parameter and the camera's state follow it as before), the pitch gets +the degrees, and the pitch turn the game made from y is cut to the gamepad's share (p |p| / t |t|). Their stick x, and +the dialogue camera's (which is also its test for input), give a tiny value in the mouse's direction when the +gamepad's axis is at rest, so the camera still sees input without a stick turn. +Two inputs stay stick input: the waterfall's vertical axis moves the camera's height, not an angle, and the horse's +lock-on without a target (HorseLockOnEmpty) turns the stick's position into an offset that returns when the stick +does, which a mouse has no position for. +Those receive input after +the radial dead zone, unit-circle clamp and stick response exponent: x is 0.0343 stick units a count over the frame +ratio (the stick turns yaw 70 x / 30 degrees a step) and y 70 / 51 times that, linear like their pitch (51 y / 30 +degrees a step), so both axes turn by the same amount for the same motion. `stick_sens` (which scales the game's +stick turn rates) is divided out. While the player uses an ability and the ability camera's hooks do not take the +mouse, its part is scaled by 1 / 0.8 and 70 / (1.5 x 51), the ability camera's own stick scales. +The player's verbs are read every 50 ms from the player actor (the player root's GOT slot main+0x3969918, the +component array +0x228, its AS component +0x158 and the verbs of its five slots). Ultrahand has a separate hook after +its manipulation input's power curves; it gets 0.01 stick units a count over the frame ratio, at most three full tilts +a step. +`mouse_aim_scale` (0.1 to 3, default 1) multiplies the mouse's motion while the bow is drawn (the verb UseBow or +DrawnBow with ZR held). The game's camera inversion and gamepad response remain in effect. `mouse_sens` scales raw +counts, with the same meaning as in 0.3.10 (the free camera turns 0.08 degrees a count at 1, and now every other camera +does too); its scale differs from the stick-emulation mode. The Controls tab switches between *Direct* and *Stick emulation* (`mouse_mode = stick`). The orbit camera keeps its desired pitch at the final angular output, including stationary frames, so a later game filter cannot recenter it. The persistent filter state accounts for the camera's current vertical offset instead of -accumulating corrections. A gamepad vertical input or the game's lock-on/override releases that mouse target. -While L is held, mouse counts move the ability wheel's virtual cursor, which stays where it was when the mouse stops. +accumulating corrections. A gamepad vertical input releases that mouse target to the game's own. The game's +lock-on, recenter and override (aiming) drive the camera themselves: the mouse stops holding without restoring its +earlier target, and when they end (or after the camera went 100 ms without a step) it holds the pitch the camera has +then, so the camera does not spring back to a pitch from before the aim or to the game's default after a shot. +While the ability wheel is open (L held and its screen, ShortCutMainItem_00 or ShortCut_00, has the focus), mouse +counts move its virtual cursor, which stays where it was when the mouse stops. L or the D-pad held with no wheel or +strip on screen (L soothes the horse, turns menu tabs) leaves the mouse on the camera; with the menu cursor off +(`menu_cursor = 0`) the screens are not read and the buttons alone decide. The horizontal quick lists (D-pad up/left/right: materials, shields and weapons) use separate 32 ms right-stick steps, with at least 32 ms of neutral between them. At sensitivity 1, 32 horizontal counts request a step; a large flick cannot queue continued scrolling after the mouse stops. Vertical movement is ignored in these lists. Switching or releasing a selector resets its cursor/step state without sending the last movement to the camera. Selector input is not consumed by the direct camera or Ultrahand hooks. -The mouse never stands in for a stick shake: to detach a fused part, press G (`bind_SHAKE`). A press swings the right -stick left and right for 0.8 s, holding the key keeps it swinging. The arrow keys or the gamepad's right stick shaken by -hand work too. A mouse gesture for it would also fire while a held object is turned back and forth. +To detach a fused part from what Ultrahand holds, shake the mouse left and right, or press G (`bind_SHAKE`). A press +swings the right stick left and right for 0.8 s, holding the key keeps it swinging. With `mouse_mode = direct` a shake +of the mouse while Ultrahand holds an object swings the right stick with it: once the swings (10 degrees of camera turn +or more each, 125 counts at sensitivity 1) change direction twice within 0.35 s, the stick goes full tilt the +way the mouse moves, each side held at least two frames so the game reads it, and goes neutral as soon as the mouse +rests. Only your own swings reach the stick, so nothing keeps swinging after you stop; shake until the part comes off. +The camera hooks ignore that swing (the mouse turns the camera in degrees already). Turning a held object back and +forth at an ordinary pace is slower and does not count. The arrow keys or the gamepad's right stick shaken by hand +work too. A step of the gamepad alone, with no mouse motion and no pitch the mouse holds, reaches the camera exactly as without the hooks. The mapping below is still used when the camera-input hook is unavailable or the game disables camera input. -Games 1.1.0 and 1.2.1 have no hooks and keep stick emulation whatever `mouse_mode` says. +Game 1.1.0 has no hooks and keeps stick emulation whatever `mouse_mode` says. On 1.2.1 `mouse_aim_scale` has no effect (the bow-in-hand state is not read there). In stick-emulation mode, mouse motion (raw input) becomes right-stick deflection. Each presented frame takes the counts moved since the last frame, divides by the frame time and sets the deflection to `counts per second * TOTK_MOUSE_SENS / 3000` of full, held for that frame, so the turn rate does not depend on the frame rate. This is not mouselook: the game's stick curve and dead zone still apply, so very slow movements do nothing and a fast flick saturates. The mouse deflection competes with the gamepad and arrow keys by the larger-deflection rule. @@ -145,7 +197,7 @@ The stick direction bits (`StickLLeft` to `StickRDown`) are derived from the sti ## Mouse in the game's menus -On game 1.4.3, while one of the game's menus has its focus box (the frame the d-pad moves: the title, the save list, the inventory and its System tab, Options, shops, dialogue choices), the cursor is released from the mouse camera and shown in the middle of the window. The item under the pointer takes the focus as if the d-pad had moved there, with the game's highlight, sound and description; a left click is A on it, a right click is B. The keys and the pad keep working, and the focus moves only when the pointer moves. This happens only while the keyboard and mouse are the device used last: after a gamepad button press or a stick pushed past half way the menus are as on the console, with no pointer, until the mouse moves or a key is pressed (`input_kbm_last` in `runtime/input.c`). The ability wheel, the d-pad strips, Autobuild, the Purah Pad's camera and the map stay gameplay: the mouse keeps the camera there. When the menu closes the cursor is captured again. +On game 1.4.3, while one of the game's menus has its focus box (the frame the d-pad moves: the title, the save list, the inventory and its System tab, Options, shops, dialogue choices), the cursor is released from the mouse camera and shown in the middle of the window. A focus gap of up to 300 ms (a tab switch, a popup opening: the game drops the focus box for a frame or two) keeps the pointer where it is instead of capturing and centring it again. The item under the pointer takes the focus as if the d-pad had moved there, with the game's highlight, sound and description; a left click is A on it, a right click is B. The keys and the pad keep working, and the focus moves only when the pointer moves. This happens only while the keyboard and mouse are the device used last: after a gamepad button press or a stick pushed past half way the menus are as on the console, with no pointer, until the mouse moves or a key is pressed (`input_kbm_last` in `runtime/input.c`). The ability wheel, the d-pad strips, Autobuild and the Purah Pad's camera stay gameplay: the mouse keeps the camera there. The map has no focus box; it is found in `eui::ScreenMgr`'s list of open screens (every 100 ms: the Purah Pad's frame `AppMenuOverlay_00` with `AppMap_00` and the menu background `AppMenuBG_00`), and there the mouse moves the map's cursor as the left stick does, with the cursor still captured, and the scroll wheel zooms: each notch is a full-tilt push of the right stick (the map's zoom) for 100 ms with 50 ms of neutral after it, up (in) for a turn away from you; a fast scroll's notches wait their turn (at most four), a turn the other way drops them. The Scope opens the same map screen without the menu background and keeps the mouse camera. When the menu closes the cursor is captured again. `runtime/menu_cursor.c` reads eui's screens at each pad read and moves the focus with the writes `eui::BoxCursorMgr::moveBoxCursor` makes, so no game code is called. `menu_cursor = 0` (`TOTK_MENU_CURSOR=0`, live; the *Mouse in the game's menus* row of the Controls tab) turns it off; `TOTK_MENU_CURSOR_LOG=1` logs every screen it reads (by default the first six), with the layout size, the node count and the hit panes it uses. diff --git a/docs/installer.md b/docs/installer.md index 374065df..790faa88 100644 --- a/docs/installer.md +++ b/docs/installer.md @@ -38,7 +38,10 @@ The install folder (`main.c` `portable_paths()` reads this layout; it stays port The player runs a newer installer on the same folder. It reads `totk-install.json`, keeps `romfs/`, `exefs/`, `shared-fonts/`, `profile/` and `totk.ini` after checking their hashes, rebuilds `totk.exe` and re-prepares the -shaders. A newer release that changes nothing game-derived skips the rebuild. +shaders. A newer release that changes nothing game-derived skips the rebuild. The window starts with the last install folder +and the base, update, keys and firmware paths it ran with (paths only, never the keys file's contents), kept in +`%LOCALAPPDATA%\TotK Recomp\setup.json` (`$XDG_STATE_HOME/totk-recomp/setup.json` elsewhere). Entries that no longer exist +stay empty. A reinstall or a switch to another game version starts filled in. Given an update file other than the recorded one (1.1.0, then 1.2.1, then 1.4.3), the installer extracts and builds again from it and keeps `profile/`. Saves carry over both ways between 1.2.1 and 1.4.3: 1.4.3 converts a 1.2.1 save on load, and 1.2.1 @@ -129,9 +132,12 @@ python -m installer --base FILE --update FILE --keys FILE --lang CODE --dest DIR English as the game language, because Chinese game text needs the Switch shared fonts, which the setup extracts only from a firmware folder. A folder with `totk-install.json` needs only the folder. `--selftest [--shots DIR]` builds every screen in every language and - closes itself. -- `tests/installer_gui_test.py`: event model, form, catalogs, cancel, the self-closing window and one end-to-end run - of the CLI in `--verify` mode (needs `build/install-test` and `build/extracted/v121`; see its docstring). + closes itself. The window is not stretched on a display whose scale is the system DPI: `installer/dpi.py` makes the + process system DPI aware before Tk starts, Tk then draws the fonts at the display's scale and `dpi.px` sizes the + paddings and wrap widths with it; the launcher does the same for its error box. +- `tests/installer_gui_test.py`: event model, form, catalogs, cancel, the display scale, the self-closing window and + one end-to-end run of the CLI in `--verify` mode (needs `build/install-test` and `build/extracted/v121`; see its + docstring). - `tests/installer_test.py`: bookkeeping with fake steps. `tests/installer_e2e.py`: a dev-mode run with the files of `config.local.toml`. @@ -212,7 +218,8 @@ bin/ totk_xlate, hactool, ninja, libSDL3.so.0 ## Constraints -- The installer steps contain no Win32 calls: Linux runs the same steps with its own compiler ("Linux release"). +- The installer steps contain no Win32 calls; only the window's DPI awareness (`installer/dpi.py`) is Windows-only, and + it does nothing elsewhere. Linux runs the same steps with its own compiler ("Linux release"). - The keys file path is passed to the tools; key values never appear in the UI, logs or files. - The window is a front end over the CLI (`python -m installer --base ... --update ... --keys ... --lang ... --dest ...`), which prints one JSON progress event per line. Tests and CI use the CLI. @@ -236,3 +243,5 @@ bin/ totk_xlate, hactool, ninja, libSDL3.so.0 ## Later - Re-warm the driver cache on start after a move, GPU or driver change. +- Per-monitor DPI in the setup window: Tk 9 has none, so a display whose scale differs from the primary one still gets + the window stretched. diff --git a/docs/mods.md b/docs/mods.md index 72f9eca6..d26553db 100644 --- a/docs/mods.md +++ b/docs/mods.md @@ -48,7 +48,10 @@ Two mods that edit the same game file do not combine: the higher one wins the wh (`.tkcl` files) go the same way. The port merges the resource size table on its own: at every start with mods on, it combines the tables the mods ship -and raises the entries for files a mod made larger or added. A separate RESTBL mod is not needed. +and raises the entries for files a mod made larger or added, the files inside a mod's packs (`Pack\**\*.pack.zs`) +included. A separate RESTBL mod is not needed. The table tells the game how much memory each file needs: a file that +outgrew its entry crashes the game when it loads, which can be long after the start, when the game first needs it. The +log line `RomFS: resource size table: ...` says how many entries were raised and names the first files inside packs. ## Code patches (ExeFS) diff --git a/docs/settings.md b/docs/settings.md new file mode 100644 index 00000000..e51c339c --- /dev/null +++ b/docs/settings.md @@ -0,0 +1,194 @@ +# Settings reference + +`totk.ini.example` describes the settings for players. This page lists the rest: diagnostics, test hooks, paths and experiments. Set one as `name = value` in `totk.ini`, or as the environment variable `TOTK_NAME`, which wins over the file. Remove the line to go back to the default. + +## Safety + +- **Safe**: changes only what the row says, with no effect on stability or saves. +- **Caution**: can slow the game, grow files, or change the picture, and undoes cleanly when removed. +- **Risky**: can crash or hang the game, or break the picture or game logic, while it is set. +- **Save risk**: can damage or lose saves, or point the game at other game or save files. +- **Unknown**: the code did not settle it. + +Many rows below are developer tools that only act together with another setting or a command-line mode (for example a trace mode or the DLSS path). The row says so where the code does. The rows come from reading the code, and most effects have not been checked in a run. + +`tests/settings_doc_check.py` fails when a name in `known[]` (`runtime/cfg.c`) is described neither here nor in `totk.ini.example`, or when a default here differs from the code. + +## Diagnostics and logging + +| Setting | What it does | Effect of changing it | Safety | +| --- | --- | --- | --- | +| `astc_time` | `1` times the GPU dispatches of each ASTC texture decode and logs the time per block footprint and the largest call. | Adds GPU timestamp queries around every decode; if the queue has no timestamps or no `hostQueryReset`, the log says the decodes are not timed and nothing is measured. | Caution | +| `bind_stats` | `1` counts bindings and descriptors per draw of each stage and how much of the bound state changes between draws. | Adds per-draw bookkeeping to the render thread and extra log output; frames get slower. | Caution | +| `contact_debug` | `1` draws the contact-shadow factor in grey in place of the picture. | The frame shows a grey debug image while it is set; has no effect when contact shadows are off. | Caution | +| `core_diag` | `1` records why ready guest threads wait for a virtual core and for how long, with a histogram every 60 presents. | Turns on host-call and SVC depth tracking and writes many log lines (one per present over 25 ms); frames get slower. | Caution | +| `menu_cursor_log` | `1` logs what the menu cursor code reads at every screen change. | Only adds log lines. | Safe | +| `perf_slow_ms` (default `50`) | Frames at least this many milliseconds long get a `perf: slow frame` log line with the time blocked per cause. | Changes how many frames are logged; a small value fills the log. | Safe | +| `replay_check` | `1` reads every texture read-back a second time after a full drain of the replay queue and compares the two. | Stalls the replay queue at every read-back, so frames get much slower; mismatches are only counted and logged. | Caution | +| `resolve_check` | `1` compares every cached pool lookup with the locked lookup and stops on a difference. | Slows every pool lookup; the game stops if the two ever differ. | Caution | +| `speed_probe` | `1` adds the player's position and ground speed to the frame-rate line that `TOTK_TRACE=perf` prints every 120 presents. | Only adds log text; has no effect without `TOTK_TRACE=perf`. | Safe | + +## Profiling and measurement + +| Setting | What it does | Effect of changing it | Safety | +| --- | --- | --- | --- | +| `ab` | Splits game time into blocks of this many seconds in the order A B B A and lets settings written as `ab` take effect only in the B blocks. | Settings that accept `ab` flip on and off every few seconds, so frame times and the picture change with the block; without such a setting it does nothing. | Caution | +| `crit` | `-` frame range (with `TOTK_TRACE=sched`) that records every state change and wake of the guest threads, then writes a file at the last frame. | Recording adds overhead to every thread switch in the range and writes one file; `tools/crit_path.py` reads it. | Caution | +| `crit_out` (default `crit.bin`) | Path of the file that `crit` writes. | Only moves the file; nothing is written without `crit`. | Safe | +| `profile` | Path of a sampling profile file; the profiler suspends threads to unwind their stacks. | Frames get slower while it samples and the profile file grows; `tools/prof_report.py` reads it. | Caution | +| `profile_chains` | `1` keeps call chains of every thread in the profile. | Larger profile file and more work per sample; has no effect without `profile`. | Caution | +| `profile_frames` | `-` samples only while presents lo to hi-1 are pending; `w-` uses world-clock seconds. | Limits the profile to a window; has no effect without `profile`. | Safe | +| `profile_main` | `1` samples only the guest main thread. | Narrows the profile; has no effect without `profile`. | Safe | +| `profile_render` | `1` samples only the render thread and keeps its call chains. | Narrows the profile and makes it larger; has no effect without `profile`. | Caution | + +## Capture and frame dumps + +| Setting | What it does | Effect of changing it | Safety | +| --- | --- | --- | --- | +| `dump` | Frame number to dump: every render pass target and storage image of that frame is copied out as PNG, with `passes.txt` and `images.txt`. | Writes many PNG files and shader hashes to disk and slows the dumped frame; size is capped by the dump code. | Caution | +| `dump_buf` | `:[::::]` snapshots one GPU buffer range after every logged pass of a dump. | Writes `buf_.bin` files and `bufs.txt`; has no effect without `dump`. | Caution | +| `dump_dir` (default `dump`) | Folder that receives the frame dump files. | Only moves the output. | Safe | +| `dump_log` | Frame number; logs the frames from there up to the dumped frame into `passes.txt`, with PNGs only of targets up to 64K texels. | Writes a longer `passes.txt` and more PNGs; has no effect without `dump`. | Caution | +| `flight_at` | Comma-separated frame numbers that trigger a flight-recorder dump. | Writes a dump folder when each frame is reached; has no effect unless the flight recorder (`TOTK_FLIGHT=1`) is on. | Caution | +| `flight_dir` | Folder for flight-recorder dumps; the default is `flight` beside the folder of `totk.exe`. | Only moves the output. | Safe | +| `flight_frames` (default `600`) | Number of presents the flight recorder keeps. | A larger ring keeps more history and more thumbnails in memory; has no effect unless `TOTK_FLIGHT=1`. | Caution | +| `flight_thumbs` (default `1`) | `0` turns off the 320x180 thumbnail the flight recorder saves for each present. | Dumps hold only `frames.tsv`; thumbnails cost a GPU blit per present when on. | Safe | +| `rdoc` | Comma-separated frame numbers to capture with RenderDoc, which is loaded before Vulkan starts. | The game runs under RenderDoc, with its capture options set to keep `VK_EXT_external_memory_host` available and to reference all resources, and captures are written to disk. | Caution | +| `rdoc_dir` | Output folder for RenderDoc captures (the default is `build/captures`). | Only moves the output. | Safe | +| `rdoc_dll` | Path of the RenderDoc library, for when it is not found by default. | A wrong path logs that the library cannot be loaded and no capture is taken. | Safe | +| `shots` | `-:` saves every step-th present in the range as `f.png`, scaled to 480x270; `w-:` takes them by world-clock seconds. | Writes one PNG per step and adds a readback of the window texture; the pictures clip highlights in HDR. | Caution | +| `shots_dir` (default `.`) | Folder for the `shots` pictures; it is created when needed. | Only moves the output. | Safe | +| `shots_full` | Set to any value to save `shots` at full size instead of 480x270. | Files get far larger and writing them takes longer; has no effect without `shots`. | Caution | + +## Automated tests and test hooks + +| Setting | What it does | Effect of changing it | Safety | +| --- | --- | --- | --- | +| `background_window` | `1` keeps the window behind the user's windows, never fullscreen at start, and F11 keeps its place; SDL windows ignore it. | The window does not come to the front or flash, so it is easy to miss; meant for unattended runs. | Caution | +| `gpu` | `vulkan` or `null`: the graphics back end; `null` has no GPU, completes every submit at once and returns zeros for texture reads. | `null` shows no picture; any other value stops the start with an error. | Caution | +| `input` | `none` reports no input from the keyboard, mouse or controllers. | The game gets no controller input and the menu cursor stops following the mouse; `input_script` still applies. | Caution | +| `input_script` | Path of a file with lines `