diff --git a/docs/architecture.md b/docs/architecture.md index 114dfe64..b3523b6b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -109,11 +109,13 @@ Every guest thread is a host thread. TotK assumes Horizon's scheduler: three app RCAS) on the present. An `output_res` that is not 16:9 (more than 1% off, `res_is_16x9`) also switches on the `aspect` patch set, which hands the output's ratio to the camera, and `romfs.c` `overlay_init` loads the `romfs-patches-x` overlay for it when it exists (`tools/make_romfs_patches.py --aspect`, laid out by - `tools/ultrawide_layout.py`; the installer builds fifteen sizes: 21:9 2560x1080, 3440x1440, 3840x1600, 5120x2160, - 32:9 3840x1080, 5120x1440, 16:10 1280x800, 1680x1050, 1920x1200, 2560x1600 and 3:2 1920x1280, 2160x1440, 2256x1504, - 2880x1920, 3000x2000). A wider layout moves the HUD to the - screen's corners, a narrower one to its top and bottom edges. Other sizes get the camera of their shape and the 16:9 - HUD stretched over it. The `aspect` setting (`fit`, the default; `stretch`) decides what the present does + `tools/ultrawide_layout.py`; installer/steps.py Shapes builds one canonical folder per needed display/output shape, + chosen by installer/screens.py). A wider layout moves the HUD to the + screen's corners (`hud_width = 21:9` or `16:9` keeps it in the middle of the screen instead, from the `-hud21x9` or + `-hud16x9` variant of the folder), a narrower one to its top and bottom edges. Shapes generates a capped variant + only when selected, alongside the full layout and selected button prompts. `romfs.c` `shaped_name` checks the exact + size then its canonical shape; a missing cap falls back to full, while the menu still offers preparation for the cap. + Without any matching layout the output falls back to 16:9. The `aspect` setting (`fit`, the default; `stretch`) decides what the present does when the window's shape differs from the output's: `fit` letterboxes, where a 16:9 game in a wider window used to be stretched. - HDR (`hdr = 1`, `vk_hdr.c`). The game tonemaps its scene into an r11g11b10f target, upscales it and draws the HUD diff --git a/docs/building.md b/docs/building.md index 76d17b9c..25157289 100644 --- a/docs/building.md +++ b/docs/building.md @@ -126,12 +126,20 @@ of them. 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`. `--prompts pc` writes `romfs-patches-pc`, the keyboard and mouse prompts ([controls.md](controls.md), "PC button prompts"). + `--aspect x` writes the UI laid out for a game resolution of another shape; with `--hud 16:9` or `--hud 21:9` + (a screen wider than that) the HUD stays within the middle 16:9 or 21:9 instead of the screen's corners. The default + `--out` then is `build\\romfs-patches-x-hud16x9` (`-hud21x9`), which the game loads for `hud_width = 16:9` + (`21:9`) in `totk.ini` ([totk.ini.example](../totk.ini.example)). + Setup's Shapes step builds only the currently selected cap for the canonical shapes needed by connected displays + and `output_res`, together with the selected prompts. `full` generates no capped folders. After changing the HUD + width, use the Screen tab's layout preparation action or rerun setup before restarting the game. Lookup prefers + the selected cap at the exact or canonical size before falling back to a full-width layout. A build from source has no layouts for other shapes than 16:9. At an `output_res` such as 5120x1440 the game then draws the largest 16:9 size inside it (2560x1440) and the present adds bars, instead of a wide camera over a stretched HUD (`runtime/resolution.c`, `shape_fallback`). For the full shape make `romfs-patches-x` once per size: `make_romfs_patches.py --version --aspect x --out build\\romfs-patches-x` (the sizes - the installer makes are `ASPECT_SIZES` in `installer/steps.py`); `build_game.py` copies every `romfs-patches*` + the installer maps to are in `installer/screens.py`); `build_game.py` copies every `romfs-patches*` folder next to `totk.exe`. 6. Prepare the shaders (once per build folder and translator). It needs `refs\MacNativeGames` (`tools\fetch_refs.sh`) @@ -226,7 +234,13 @@ 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` 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). A change to the mods' ExeFS patches +when a setting is described neither in `totk.ini.example` nor in [settings.md](settings.md). +HUD pane/animation and generator naming regressions run with Python 3.14+: `tests/hud_layout_test.py`. +Set `HUD_TEST_ROMFS` to a verified extracted RomFS directory to include a real-archive comparison against the +pre-port layout generator; all game-derived temporary data stays under `build/`. +`python tests/romfs_shapes_check.py --cc ` compiles the production folder-selection and preparation helpers +to check canonical aliases, capped/full fallback, prompt arguments and generation deduplication without game files. +A change to the mods' ExeFS patches (`tools/exefs_patches.py`, `runtime/mods.c`, the `folded.txt` of `recomp/gen.py`) passes `.venv\Scripts\python tests\exefs_patches_test.py`, which makes its own modules and runs `gen.py` on one with a jump table (no game files), and `totk.exe --probe-mods`. A change to the cheat VM or the cheat opcode tables diff --git a/docs/settings.md b/docs/settings.md index 857cfee7..81cd68cf 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -14,6 +14,12 @@ Many rows below are developer tools that only act together with another setting `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. +## HUD placement + +| Setting | What it does | Effect of changing it | Safety | +| --- | --- | --- | --- | +| `hud_width` (default `full`) | `full` places the HUD at the screen's edges; `21:9` or `16:9` constrains it to that centered area on a wider game resolution. A cap that is not narrower than the screen, and 16:9 or taller output, keep the full layout. | Read at start. The Shapes installer step builds the selected cap only for needed screen shapes and button prompts. Changing it in the Screen tab may require preparing the layout there or rerunning setup before restarting. If a capped folder is missing the full layout loads with a log message. Explicit overlay overrides and player UI mods keep their precedence. | Safe | + ## Diagnostics and logging | Setting | What it does | Effect of changing it | Safety | diff --git a/installer/steps.py b/installer/steps.py index c67c95b6..3588a2df 100644 --- a/installer/steps.py +++ b/installer/steps.py @@ -1404,7 +1404,24 @@ class PcPrompts(Step): # ---- 6b. screen shapes -SHAPED_FOLDER = re.compile(r'^romfs-patches(?:-xbox|-xbox-label|-pc)?-\d+x\d+$') +SHAPED_FOLDER = re.compile(r'^romfs-patches(?:-xbox|-xbox-label|-pc)?-\d+x\d+(?:-hud(?:16|21)x9)?$') + + +def hud_width(dest): + """The selected HUD cap, with the same default as runtime/cfg.c.""" + try: + text = (dest / 'totk.ini').read_text(encoding='utf-8-sig', errors='replace') + except OSError: + text = '' + value = (screens.ini_value(text, 'hud_width') or 'full').lower() + return value if value in ('16:9', '21:9') else 'full' + + +def shape_hud(size, hud): + """The selected cap when at least 1% narrower than the shape, as make_romfs_patches.py requires.""" + w, h = (int(v) for v in size.split('x')) + cap = {'16:9': 16 / 9, '21:9': 21 / 9}.get(hud) + return hud if cap and cap < w / h * 0.99 else None class Shapes(Step): @@ -1412,7 +1429,7 @@ class Shapes(Step): in totk.ini, romfs-patches-