docs(readme): a short front page, the reference sections moved to docs/ as they were #236

Open

jarynclouatre wants to merge 1 commit from jarynclouatre/Longshot:docs/readme-for-players into main

pull from: jarynclouatre/Longshot:docs/readme-for-players

merge into: MagicBeanDev:main

MagicBeanDev:main

Conversation 5 Commits 1 Files changed 28 +1140 -1116

jarynclouatre commented 2026-11-13 16:29:53 +00:00

Contributor

• Copy link
• Copy Markdown

Why

The README is 1,124 lines. Someone who only wants to install the game scrolls past the whole menu reference, the command-line switches and the build instructions to find the four steps that matter to them. This leaves a front page of 215 lines and gives each reference section its own page under docs/.

What changed

• README.md: the top, Project status, Install and play (the download links and the four steps), What you need, How it works, Want to help?, License and Credits stay as they are. New: a Guides table. Build from source is one line with links.
• New pages holding the README's sections, text unchanged: docs/install.md (On Windows, On Linux, Updating, Release channels, RecompLauncher, Where the files go, What Longshot connects to), docs/troubleshooting.md (If something goes wrong, Low FPS or stutter, AMD texture workaround), docs/menu.md (In-game menu, Controls), docs/mods.md, docs/build-from-source.md, docs/command-line.md, docs/pipeline-list.md.
• Inside the moved text only heading levels and link targets differ, plus two lines of docs/menu.md whose "below" pointed at a section that is now another page (the "Save my pipeline list" row and the "ASTC as RGBA8" note): they link to it by name.
• Links to the moved anchors follow in CONTRIBUTING.md, docs/common-issues.md, docs/development.md, docs/getting-started.md, docs/graphics-and-controls.md, docs/saves-script.md, docs/updates-and-saves.md, and in the udmabuf warning of host/hos_main.c ("see docs/install.md, On Linux") with tests/test_udmabuf_warning.py.
• What reads the option table reads it from docs/menu.md: tests/test_readme_menu_rows.py (file name kept), tests/test_camera_speed.py, tests/test_stick_dead_zone.py, and the website's settings page (website/src/repo-docs/pages.ts, graphics-settings.ts and their tests).
• Left in the README on purpose: What you need (website/src/content/docs/requirements.mdx copies it) and the anchors other places link (#install-and-play, #project-status, #what-you-need, #build-from-source, #credits).

Flags and settings

None.

Measurements

main: 1ef93e79 (2026-11-13)
this PR: docs/readme-for-players @ 3b92826a
Hardware: none used (game-free checks on a Linux x86-64 PC, Python 3.14.4, Node 24.22.2)
Scene: none, the game was not run
Method: python3 -I -B tests/run_all.py --jobs 4 --timeout 120, two runs each, interleaved (main, PR, main, PR), both runs of a side gave the same counts; in website/, npm ci and node --test tests/*.test.ts on both, npm run build and node scripts/check-site.ts on the PR; two scripts of mine for the last two rows (below)
How to reproduce: the commands above in a checkout of each commit

	main @ 1ef93e79	this PR @ 3b92826a
README.md, lines	1,124	215
tests/run_all.py (run 1, run 2)	444 passed, 2 failed, 79 skipped (both)	444 passed, 2 failed, 79 skipped (both)
failing checks	test_bake_portability.py, test_display_pointer.py	the same two
website node --test tests/*.test.ts	47 of 47	47 of 47
website build and check-site.ts	not run	14 pages built; "Site check passed: 14 pages, 787 local links and assets, their anchors and edit links"
README lines of main missing from the new README and the seven pages (heading level and link targets ignored)	n/a	2, the two "below" lines named above
relative links and anchors that do not resolve, in the tracked .md files outside website/ and third_party/	0 of 198	0 of 210

suite main run 1: 444 passed, 2 failed, 79 skipped in 112 s (linux, 4 at once); failing: tests/test_bake_portability.py tests/test_display_pointer.py
suite PR   run 1: 444 passed, 2 failed, 79 skipped in 114 s (linux, 4 at once); failing: tests/test_bake_portability.py tests/test_display_pointer.py
suite main run 2: 444 passed, 2 failed, 79 skipped in 112 s (linux, 4 at once); failing: tests/test_bake_portability.py tests/test_display_pointer.py
suite PR   run 2: 444 passed, 2 failed, 79 skipped in 108 s (linux, 4 at once); failing: tests/test_bake_portability.py tests/test_display_pointer.py
website tests main: tests 47, pass 47, fail 0
website tests PR:   tests 47, pass 47, fail 0

test_bake_portability.py fails here for a missing Python module (zstandard); test_display_pointer.py fails to link on main as well (undefined rx_option).

Rebased since onto main 0edc1377 (this PR @ 35e835f0): the rebase carried #108's reworded "HDR tone mapper" row into docs/menu.md and changed nothing else of this PR. Run again at 35e835f0: the six checks that read the moved pages (readme_menu_rows, camera_speed, stick_dead_zone, udmabuf_warning, forge_pr, dev_packs: 6 passed), the two scripts (2 lines, 0 of 211 links), and the website's tests: 40 of 47 on main @ 0edc1377 and on this PR @ 35e835f0, the same seven failing on both with "names no condition for HDR tone mapper, which the menu shows only on some PCs" (see Reviewer notes).

Rebased again onto main d9648863 (this PR @ f596718e) after a conflict in README.md and website/tests/graphics-settings.test.ts: the rebase carried the ten README lines main gained since 0edc1377 into the pages they belong to (the "HDR tone mapper" row of #247, the "Damage taken" row of #138 and the paragraph on the Upscaler keeping its render scale of #55 into docs/menu.md; the Damage taken text of #138 into docs/command-line.md), kept main's new website test beside this PR's renamed one, and changed nothing else. Run at f596718e: the suite once, 452 passed, 2 failed, 79 skipped (test_bake_portability and test_menu_i18n, which fail the same way on main @ d9648863); the website's tests, 53 of 53; the site build and check-site.ts ("Site check passed: 14 pages, 788 local links and assets, their anchors and edit links"); a script found each of the ten lines in the new pages. The whole suite was not run again on main @ d9648863.

Rebased again onto main c0442078 (this PR @ f96169f8) after a conflict in README.md and docs/development.md: the rebase carried the README lines main gained since d9648863 into docs/menu.md (the "Audio output" row and its note with Mono of #136; the "Depends on this PC" paragraph of the bug report of #103; the Toggle paragraph, the toggle_a=0 line and the toggle_<button> sentences of #137), took the new Discord link into the README, kept main's toggle_<button> text in docs/development.md beside this PR's link to menu.md#controls, and changed nothing else. Run at f96169f8, main @ c0442078 against this PR, two interleaved runs each: the suite 458 passed, 3 failed, 80 skipped on both sides in both runs (test_bake_portability, test_menu_keys and test_pad_layout, which fail the same way on main: the last two since #137, with g++); the website's tests, 52 of 53 on both, the same one failing on both ("restart, coverage and condition drift ... stop publication"); the site build and check-site.ts on the PR ("Site check passed: 14 pages, 788 local links and assets, their anchors and edit links"). The two scripts: the lines of main's README missing from the new README and the pages are the same set as before the rebase (heading levels, link targets and the two "below" lines); 0 of 213 links unresolved.

Rebased again onto main cf605c85 (this PR @ de21ed58) after a conflict in README.md and website/src/repo-docs/pages.ts: the rebase carried the README lines main gained since c0442078 into the places they belong to. The Navi 23, Intel and slow-movie rows of the status table, the "Below the minimum" paragraph and the catalogue links (#219, #252, #96) are in the README, whose status and requirements parts stayed. The shader preparation sentence of #252 and the "Caches and logs" row and note of #321 are in docs/install.md; the logs folder, the three new table rows and the "Intel laptops" section (#321, #252) in docs/troubleshooting.md; the Output resolution texts of #292 and the "Intel shader compiles" row and note of #252 in docs/menu.md; the Damage taken text of #269 and the movie and Intel compiler paragraphs of #252 in docs/command-line.md. The three links to "Intel laptops" (README, docs/menu.md, website/src/content/docs/requirements.mdx) now point at docs/troubleshooting.md, pages.ts keeps main's new lines with docs/menu.md added to its source files, and nothing else of this PR changed. Run again on main @ cf605c85 and this PR @ de21ed58: the suite twice each, interleaved, 473 passed, 4 failed, 82 skipped on both (test_bake_portability.py, test_menu_keys.py, test_module_ids.py and test_pad_layout.py fail on main too); the website's tests 71 of 72 on both, the same check failing on both ("restart, coverage and condition drift ... stop publication"); the site build (15 pages) and check-site.ts pass on the PR (838 local links and assets); the two scripts: 2 lines, 0 of 219 links.

Rebased again onto main 5e072fc8 (this PR @ eff187d7) after a conflict in docs/development.md: #59 added the actor motion switches to the RX_VK_DLSS row, where this PR had changed "the readme's NVIDIA DLSS section" to "command-line.md's NVIDIA DLSS section". The row now has main's new sentence and this PR's link words; nothing else of this PR changed. Run again on main @ 5e072fc8 and this PR @ eff187d7: the suite twice each, interleaved, 474 passed, 4 failed, 83 skipped on both (the same four files fail on main too); the website's tests 71 of 72 on both; the site build (15 pages) and check-site.ts pass on the PR (838 local links and assets).

Rebased again onto main 543846eb (this PR @ 880a583a) after a conflict in README.md and docs/development.md: the rebase carried the README lines main gained since 5e072fc8 into the pages they belong to (the "Custom output size" row and its paragraph of #51, the "Skip title screen" row and paragraph of #399, and the "Walk mode" and "Walk speed" rows, their paragraph and the Walk wording under Controls of #66 into docs/menu.md; the sentence on where the NGX SDK goes of #465 into docs/command-line.md), kept main's Custom output size text in docs/development.md beside this PR's link to menu.md#controls, and pointed two checks that are new on main and read the README for those rows (tests/test_skip_title.py, tests/test_walk_key.py) at docs/menu.md. Nothing else changed. Run on main @ 543846eb and this PR @ 880a583a, the suite twice each: main 484 passed, 3 failed, 84 skipped (test_bake_portability, test_walk_key, test_crash_record); this PR 485 passed, 2 failed, 84 skipped (test_bake_portability, test_walk_key). test_crash_record waits on a signalled child and failed in main's two runs on this PC, not in this PR's two, which ran after them and not in turn with main. The website's tests: 64 of 72 on both, the same eight failing with "graphics coverage mismatch at Custom output size": since #51 the settings page's reader does not take the menu's new text row. For the same reason npm run build stops at that check on this PR, so the built site and check-site.ts were not checked on this rebase; the build was not run on main.

Testing

Tested: the game-free suite, the website's tests, the site build and its link check, as in Measurements, on a Linux PC. Every line of main's README was compared by script with the new README and the seven pages. Every relative link and anchor in the tracked Markdown files outside website/ and third_party/ was resolved by script before and after.

Not tested: the game was not run, and host/hos_main.c was not compiled: its change is the wording inside one string literal, the udmabuf warning's "see README, On Linux". The deployed website: built here, not deployed. How Forgejo renders the new pages was not looked at page by page.

Needs other testers: None.

Screenshots

Nothing on screen.

Risk and rollback

An open pull request that adds a row to the README's option table, or edits one of the moved sections, will conflict; its lines belong in docs/menu.md or the matching page now, and tests/test_readme_menu_rows.py says so when a menu row has no line there. Links from outside the repository to a moved README anchor (#in-game-menu, #controls, #if-something-goes-wrong, #on-windows, #on-linux, #mods) land at the top of the README, where the Guides table is. Reverting the commit puts everything back.

Reviewer notes

• The moved text is easiest to check with git diff --color-moved=zebra main...HEAD -- README.md docs/.
• No sentence of the moved sections was reworded here, on purpose: this is the move only. Tightening the wording of the guides can be its own pull request.
• Seen on the way, not part of this: on main @ 0edc1377 seven website tests fail since #108 reworded the "HDR tone mapper" row (its cell no longer has the "(shown only with ...)" form the settings page reads the condition from). They pass since: 53 of 53 on this PR @ f596718e.

Issues

None.

Checklist

For everyone

• One topic.
• The title is a Conventional Commit (type(scope): description).
• Rebased on current main.
• python -I -B tests/run_all.py run and passing (any failure that also fails on main is named above).
• Tested in the game, or what wasn't is named under Testing.
• Testing filled in: what was tested, what wasn't, and what needs other testers (with test requests).
• Measured: main and this PR at named commits, on the same PC, scene and settings, at least 2 interleaved runs each, the median reported.
• No game files, dumps, build output or generated files.
• third_party/ untouched (a new folder with a PROVENANCE.md instead).
• The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

If applicable

• A check under tests/ that reads changed source updated in this PR, not weakened.
• Docs updated.

## Why The README is 1,124 lines. Someone who only wants to install the game scrolls past the whole menu reference, the command-line switches and the build instructions to find the four steps that matter to them. This leaves a front page of 215 lines and gives each reference section its own page under `docs/`. ## What changed - `README.md`: the top, Project status, Install and play (the download links and the four steps), What you need, How it works, Want to help?, License and Credits stay as they are. New: a Guides table. Build from source is one line with links. - New pages holding the README's sections, text unchanged: `docs/install.md` (On Windows, On Linux, Updating, Release channels, RecompLauncher, Where the files go, What Longshot connects to), `docs/troubleshooting.md` (If something goes wrong, Low FPS or stutter, AMD texture workaround), `docs/menu.md` (In-game menu, Controls), `docs/mods.md`, `docs/build-from-source.md`, `docs/command-line.md`, `docs/pipeline-list.md`. - Inside the moved text only heading levels and link targets differ, plus two lines of `docs/menu.md` whose "below" pointed at a section that is now another page (the "Save my pipeline list" row and the "ASTC as RGBA8" note): they link to it by name. - Links to the moved anchors follow in `CONTRIBUTING.md`, `docs/common-issues.md`, `docs/development.md`, `docs/getting-started.md`, `docs/graphics-and-controls.md`, `docs/saves-script.md`, `docs/updates-and-saves.md`, and in the udmabuf warning of `host/hos_main.c` ("see docs/install.md, On Linux") with `tests/test_udmabuf_warning.py`. - What reads the option table reads it from `docs/menu.md`: `tests/test_readme_menu_rows.py` (file name kept), `tests/test_camera_speed.py`, `tests/test_stick_dead_zone.py`, and the website's settings page (`website/src/repo-docs/pages.ts`, `graphics-settings.ts` and their tests). - Left in the README on purpose: What you need (`website/src/content/docs/requirements.mdx` copies it) and the anchors other places link (`#install-and-play`, `#project-status`, `#what-you-need`, `#build-from-source`, `#credits`). ## Flags and settings None. ## Measurements main: 1ef93e79 (2026-11-13) this PR: docs/readme-for-players @ 3b92826a Hardware: none used (game-free checks on a Linux x86-64 PC, Python 3.14.4, Node 24.22.2) Scene: none, the game was not run Method: `python3 -I -B tests/run_all.py --jobs 4 --timeout 120`, two runs each, interleaved (main, PR, main, PR), both runs of a side gave the same counts; in `website/`, `npm ci` and `node --test tests/*.test.ts` on both, `npm run build` and `node scripts/check-site.ts` on the PR; two scripts of mine for the last two rows (below) How to reproduce: the commands above in a checkout of each commit | | main @ 1ef93e79 | this PR @ 3b92826a | |---|---|---| | `README.md`, lines | 1,124 | 215 | | `tests/run_all.py` (run 1, run 2) | 444 passed, 2 failed, 79 skipped (both) | 444 passed, 2 failed, 79 skipped (both) | | failing checks | `test_bake_portability.py`, `test_display_pointer.py` | the same two | | website `node --test tests/*.test.ts` | 47 of 47 | 47 of 47 | | website build and `check-site.ts` | not run | 14 pages built; "Site check passed: 14 pages, 787 local links and assets, their anchors and edit links" | | README lines of main missing from the new README and the seven pages (heading level and link targets ignored) | n/a | 2, the two "below" lines named above | | relative links and anchors that do not resolve, in the tracked `.md` files outside `website/` and `third_party/` | 0 of 198 | 0 of 210 | ``` suite main run 1: 444 passed, 2 failed, 79 skipped in 112 s (linux, 4 at once); failing: tests/test_bake_portability.py tests/test_display_pointer.py suite PR run 1: 444 passed, 2 failed, 79 skipped in 114 s (linux, 4 at once); failing: tests/test_bake_portability.py tests/test_display_pointer.py suite main run 2: 444 passed, 2 failed, 79 skipped in 112 s (linux, 4 at once); failing: tests/test_bake_portability.py tests/test_display_pointer.py suite PR run 2: 444 passed, 2 failed, 79 skipped in 108 s (linux, 4 at once); failing: tests/test_bake_portability.py tests/test_display_pointer.py website tests main: tests 47, pass 47, fail 0 website tests PR: tests 47, pass 47, fail 0 ``` `test_bake_portability.py` fails here for a missing Python module (zstandard); `test_display_pointer.py` fails to link on main as well (undefined `rx_option`). Rebased since onto main 0edc1377 (this PR @ 35e835f0): the rebase carried #108's reworded "HDR tone mapper" row into `docs/menu.md` and changed nothing else of this PR. Run again at 35e835f0: the six checks that read the moved pages (`readme_menu_rows`, `camera_speed`, `stick_dead_zone`, `udmabuf_warning`, `forge_pr`, `dev_packs`: 6 passed), the two scripts (2 lines, 0 of 211 links), and the website's tests: 40 of 47 on main @ 0edc1377 and on this PR @ 35e835f0, the same seven failing on both with "names no condition for HDR tone mapper, which the menu shows only on some PCs" (see Reviewer notes). Rebased again onto main d9648863 (this PR @ f596718e) after a conflict in `README.md` and `website/tests/graphics-settings.test.ts`: the rebase carried the ten README lines main gained since 0edc1377 into the pages they belong to (the "HDR tone mapper" row of #247, the "Damage taken" row of #138 and the paragraph on the Upscaler keeping its render scale of #55 into `docs/menu.md`; the Damage taken text of #138 into `docs/command-line.md`), kept main's new website test beside this PR's renamed one, and changed nothing else. Run at f596718e: the suite once, 452 passed, 2 failed, 79 skipped (`test_bake_portability` and `test_menu_i18n`, which fail the same way on main @ d9648863); the website's tests, 53 of 53; the site build and `check-site.ts` ("Site check passed: 14 pages, 788 local links and assets, their anchors and edit links"); a script found each of the ten lines in the new pages. The whole suite was not run again on main @ d9648863. Rebased again onto main c0442078 (this PR @ f96169f8) after a conflict in `README.md` and `docs/development.md`: the rebase carried the README lines main gained since d9648863 into `docs/menu.md` (the "Audio output" row and its note with Mono of #136; the "Depends on this PC" paragraph of the bug report of #103; the Toggle paragraph, the `toggle_a=0` line and the `toggle_<button>` sentences of #137), took the new Discord link into the README, kept main's `toggle_<button>` text in `docs/development.md` beside this PR's link to `menu.md#controls`, and changed nothing else. Run at f96169f8, main @ c0442078 against this PR, two interleaved runs each: the suite 458 passed, 3 failed, 80 skipped on both sides in both runs (`test_bake_portability`, `test_menu_keys` and `test_pad_layout`, which fail the same way on main: the last two since #137, with g++); the website's tests, 52 of 53 on both, the same one failing on both ("restart, coverage and condition drift ... stop publication"); the site build and `check-site.ts` on the PR ("Site check passed: 14 pages, 788 local links and assets, their anchors and edit links"). The two scripts: the lines of main's README missing from the new README and the pages are the same set as before the rebase (heading levels, link targets and the two "below" lines); 0 of 213 links unresolved. Rebased again onto main cf605c85 (this PR @ de21ed58) after a conflict in `README.md` and `website/src/repo-docs/pages.ts`: the rebase carried the README lines main gained since c0442078 into the places they belong to. The Navi 23, Intel and slow-movie rows of the status table, the "Below the minimum" paragraph and the catalogue links (#219, #252, #96) are in the README, whose status and requirements parts stayed. The shader preparation sentence of #252 and the "Caches and logs" row and note of #321 are in `docs/install.md`; the `logs` folder, the three new table rows and the "Intel laptops" section (#321, #252) in `docs/troubleshooting.md`; the Output resolution texts of #292 and the "Intel shader compiles" row and note of #252 in `docs/menu.md`; the Damage taken text of #269 and the movie and Intel compiler paragraphs of #252 in `docs/command-line.md`. The three links to "Intel laptops" (README, `docs/menu.md`, `website/src/content/docs/requirements.mdx`) now point at `docs/troubleshooting.md`, `pages.ts` keeps main's new lines with `docs/menu.md` added to its source files, and nothing else of this PR changed. Run again on main @ cf605c85 and this PR @ de21ed58: the suite twice each, interleaved, 473 passed, 4 failed, 82 skipped on both (`test_bake_portability.py`, `test_menu_keys.py`, `test_module_ids.py` and `test_pad_layout.py` fail on main too); the website's tests 71 of 72 on both, the same check failing on both ("restart, coverage and condition drift ... stop publication"); the site build (15 pages) and `check-site.ts` pass on the PR (838 local links and assets); the two scripts: 2 lines, 0 of 219 links. Rebased again onto main 5e072fc8 (this PR @ eff187d7) after a conflict in `docs/development.md`: #59 added the actor motion switches to the `RX_VK_DLSS` row, where this PR had changed "the readme's NVIDIA DLSS section" to "command-line.md's NVIDIA DLSS section". The row now has main's new sentence and this PR's link words; nothing else of this PR changed. Run again on main @ 5e072fc8 and this PR @ eff187d7: the suite twice each, interleaved, 474 passed, 4 failed, 83 skipped on both (the same four files fail on main too); the website's tests 71 of 72 on both; the site build (15 pages) and `check-site.ts` pass on the PR (838 local links and assets). Rebased again onto main 543846eb (this PR @ 880a583a) after a conflict in `README.md` and `docs/development.md`: the rebase carried the README lines main gained since 5e072fc8 into the pages they belong to (the "Custom output size" row and its paragraph of #51, the "Skip title screen" row and paragraph of #399, and the "Walk mode" and "Walk speed" rows, their paragraph and the Walk wording under Controls of #66 into `docs/menu.md`; the sentence on where the NGX SDK goes of #465 into `docs/command-line.md`), kept main's Custom output size text in `docs/development.md` beside this PR's link to `menu.md#controls`, and pointed two checks that are new on main and read the README for those rows (`tests/test_skip_title.py`, `tests/test_walk_key.py`) at `docs/menu.md`. Nothing else changed. Run on main @ 543846eb and this PR @ 880a583a, the suite twice each: main 484 passed, 3 failed, 84 skipped (`test_bake_portability`, `test_walk_key`, `test_crash_record`); this PR 485 passed, 2 failed, 84 skipped (`test_bake_portability`, `test_walk_key`). `test_crash_record` waits on a signalled child and failed in main's two runs on this PC, not in this PR's two, which ran after them and not in turn with main. The website's tests: 64 of 72 on both, the same eight failing with "graphics coverage mismatch at Custom output size": since #51 the settings page's reader does not take the menu's new text row. For the same reason `npm run build` stops at that check on this PR, so the built site and `check-site.ts` were not checked on this rebase; the build was not run on main. ## Testing **Tested:** the game-free suite, the website's tests, the site build and its link check, as in Measurements, on a Linux PC. Every line of main's README was compared by script with the new README and the seven pages. Every relative link and anchor in the tracked Markdown files outside `website/` and `third_party/` was resolved by script before and after. **Not tested:** the game was not run, and `host/hos_main.c` was not compiled: its change is the wording inside one string literal, the udmabuf warning's "see README, On Linux". The deployed website: built here, not deployed. How Forgejo renders the new pages was not looked at page by page. **Needs other testers:** None. ## Screenshots Nothing on screen. ## Risk and rollback An open pull request that adds a row to the README's option table, or edits one of the moved sections, will conflict; its lines belong in `docs/menu.md` or the matching page now, and `tests/test_readme_menu_rows.py` says so when a menu row has no line there. Links from outside the repository to a moved README anchor (`#in-game-menu`, `#controls`, `#if-something-goes-wrong`, `#on-windows`, `#on-linux`, `#mods`) land at the top of the README, where the Guides table is. Reverting the commit puts everything back. ## Reviewer notes - The moved text is easiest to check with `git diff --color-moved=zebra main...HEAD -- README.md docs/`. - No sentence of the moved sections was reworded here, on purpose: this is the move only. Tightening the wording of the guides can be its own pull request. - Seen on the way, not part of this: on main @ 0edc1377 seven website tests fail since #108 reworded the "HDR tone mapper" row (its cell no longer has the "(shown only with ...)" form the settings page reads the condition from). They pass since: 53 of 53 on this PR @ f596718e. ## Issues None. ## Checklist ### For everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`). - [x] Rebased on current `main`. - [x] `python -I -B tests/run_all.py` run and passing (any failure that also fails on `main` is named above). - [x] Tested in the game, or what wasn't is named under Testing. - [x] Testing filled in: what was tested, what wasn't, and what needs other testers (with test requests). - [x] Measured: main and this PR at named commits, on the same PC, scene and settings, at least 2 interleaved runs each, the median reported. - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### If applicable - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [x] Docs updated.

jarynclouatre changed title from WIP: docs(readme): a short front page, the reference sections moved to docs/ as they were to docs(readme): a short front page, the reference sections moved to docs/ as they were 2026-11-13 16:30:21 +00:00

jarynclouatre force-pushed docs/readme-for-players from 35e835f060 to f596718e08 2026-11-13 18:50:36 +00:00 Compare

jarynclouatre commented 2026-11-13 18:51:09 +00:00

Author

Contributor

• Copy link
• Copy Markdown

Rebased onto main d9648863 after a conflict in README.md and website/tests/graphics-settings.test.ts (now f596718e). The rebase carried the ten README lines main gained since 0edc1377 into the pages they belong to: the "HDR tone mapper" row (#247), the "Damage taken" row (#138) and the Upscaler paragraph (#55) into docs/menu.md, the Damage taken text (#138) into docs/command-line.md. Main's new website test is kept beside this PR's renamed one. Nothing else changed. Run at f596718e: suite 452 passed, 2 failed, 79 skipped (test_bake_portability, test_menu_i18n; both fail on main @ d9648863 too), website tests 53 of 53, site build and check-site.ts pass. The description has the detail.

Rebased onto main d9648863 after a conflict in `README.md` and `website/tests/graphics-settings.test.ts` (now f596718e). The rebase carried the ten README lines main gained since 0edc1377 into the pages they belong to: the "HDR tone mapper" row (#247), the "Damage taken" row (#138) and the Upscaler paragraph (#55) into `docs/menu.md`, the Damage taken text (#138) into `docs/command-line.md`. Main's new website test is kept beside this PR's renamed one. Nothing else changed. Run at f596718e: suite 452 passed, 2 failed, 79 skipped (`test_bake_portability`, `test_menu_i18n`; both fail on main @ d9648863 too), website tests 53 of 53, site build and `check-site.ts` pass. The description has the detail.

jarynclouatre force-pushed docs/readme-for-players from f596718e08 to f96169f84a 2026-11-14 01:27:39 +00:00 Compare

jarynclouatre commented 2026-11-14 01:27:59 +00:00

Author

Contributor

• Copy link
• Copy Markdown

Rebased onto main c0442078 after a conflict in README.md and docs/development.md (now f96169f8). The rebase carried main's new README lines into docs/menu.md: the "Audio output" row and note with Mono (#136), the "Depends on this PC" paragraph (#103), and the Toggle paragraph, toggle_a=0 and the toggle_<button> sentences (#137). The new Discord link is in the README, and docs/development.md keeps main's toggle_<button> text. Nothing else changed. The suite and the website's tests give the same counts on main and on the branch, two runs each; the numbers are in the description.

Rebased onto main c0442078 after a conflict in `README.md` and `docs/development.md` (now f96169f8). The rebase carried main's new README lines into `docs/menu.md`: the "Audio output" row and note with Mono (#136), the "Depends on this PC" paragraph (#103), and the Toggle paragraph, `toggle_a=0` and the `toggle_<button>` sentences (#137). The new Discord link is in the README, and `docs/development.md` keeps main's `toggle_<button>` text. Nothing else changed. The suite and the website's tests give the same counts on main and on the branch, two runs each; the numbers are in the description.

mooki added the

area/install

area/menu

kind

docs

labels 2026-11-14 01:45:24 +00:00

bibiburl referenced this pull request 2026-11-14 02:07:34 +00:00

docs(guides): illustrate installation, settings and save transfer #264

bibiburl referenced this pull request 2026-11-14 02:07:35 +00:00

docs(guides): illustrate installation, settings and save transfer #264

jarynclouatre force-pushed docs/readme-for-players from f96169f84a to de21ed5857 2026-11-14 02:52:11 +00:00 Compare

jarynclouatre commented 2026-11-14 02:52:36 +00:00

Author

Contributor

• Copy link
• Copy Markdown

Rebased onto main cf605c85 after a conflict in README.md and website/src/repo-docs/pages.ts (now de21ed58). The rebase carried main's new README lines into the places they belong to: the status rows, the "Below the minimum" paragraph and the catalogue links stay in the README (#219, #252, #96); the shader preparation sentence and "Caches and logs" are in docs/install.md (#252, #321); the logs folder, three table rows and the "Intel laptops" section in docs/troubleshooting.md (#321, #252); the Output resolution texts and the "Intel shader compiles" row and note in docs/menu.md (#292, #252); the Damage taken text and the movie and Intel compiler paragraphs in docs/command-line.md (#269, #252). The three links to "Intel laptops" now point at docs/troubleshooting.md. Nothing else changed. The suite and the website's tests give the same counts on main and on the branch, two suite runs each; the numbers are in the description.

Rebased onto main cf605c85 after a conflict in `README.md` and `website/src/repo-docs/pages.ts` (now de21ed58). The rebase carried main's new README lines into the places they belong to: the status rows, the "Below the minimum" paragraph and the catalogue links stay in the README (#219, #252, #96); the shader preparation sentence and "Caches and logs" are in `docs/install.md` (#252, #321); the `logs` folder, three table rows and the "Intel laptops" section in `docs/troubleshooting.md` (#321, #252); the Output resolution texts and the "Intel shader compiles" row and note in `docs/menu.md` (#292, #252); the Damage taken text and the movie and Intel compiler paragraphs in `docs/command-line.md` (#269, #252). The three links to "Intel laptops" now point at `docs/troubleshooting.md`. Nothing else changed. The suite and the website's tests give the same counts on main and on the branch, two suite runs each; the numbers are in the description.

mooki added the

priority

low

label 2026-11-14 04:18:17 +00:00

jarynclouatre force-pushed docs/readme-for-players from de21ed5857 to eff187d7a8 2026-11-14 13:39:00 +00:00 Compare

jarynclouatre commented 2026-11-14 13:39:23 +00:00

Author

Contributor

• Copy link
• Copy Markdown

Rebased onto main 5e072fc8 after a conflict in docs/development.md (now eff187d7). #59 added the actor motion switches to the RX_VK_DLSS row; the row keeps that sentence and this PR's "command-line.md's NVIDIA DLSS section" wording. Nothing else changed. The suite (twice each) and the website's tests give the same counts on main and on the branch; the numbers are in the description.

Rebased onto main 5e072fc8 after a conflict in `docs/development.md` (now eff187d7). #59 added the actor motion switches to the `RX_VK_DLSS` row; the row keeps that sentence and this PR's "command-line.md's NVIDIA DLSS section" wording. Nothing else changed. The suite (twice each) and the website's tests give the same counts on main and on the branch; the numbers are in the description.

jarynclouatre force-pushed docs/readme-for-players from eff187d7a8 to 880a583a4b 2026-11-14 18:01:03 +00:00 Compare

jarynclouatre commented 2026-11-14 18:01:16 +00:00

Author

Contributor

• Copy link
• Copy Markdown

Rebased onto main 543846eb after a conflict in README.md and docs/development.md (now 880a583a). The rebase carried main's new README lines into docs/menu.md (Custom output size of #51, Skip title screen of #399, the Walk rows and text of #66) and docs/command-line.md (the NGX SDK folder of #465), and pointed tests/test_skip_title.py and tests/test_walk_key.py, new on main, at docs/menu.md for those rows. Nothing else changed. The suite's and the website's counts on main and on the branch are in the description; the website's tests fail the same eight cases on both since #51 (the settings page does not take the Custom output size row yet), so the site build could not be checked this time.

Rebased onto main 543846eb after a conflict in `README.md` and `docs/development.md` (now 880a583a). The rebase carried main's new README lines into `docs/menu.md` (Custom output size of #51, Skip title screen of #399, the Walk rows and text of #66) and `docs/command-line.md` (the NGX SDK folder of #465), and pointed `tests/test_skip_title.py` and `tests/test_walk_key.py`, new on main, at `docs/menu.md` for those rows. Nothing else changed. The suite's and the website's counts on main and on the branch are in the description; the website's tests fail the same eight cases on both since #51 (the settings page does not take the Custom output size row yet), so the site build could not be checked this time.

jarynclouatre referenced this pull request 2026-11-14 18:07:57 +00:00

fix(website): the settings page takes the menu's text row, so the site builds again #533

mooki added the

platform/linux

platform/windows

labels 2026-11-14 18:22:35 +00:00

Some checks are pending

Hide checks

CI / Conventional Commit title (pull_request) Blocked by required conditions

Details

CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions

Details

CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions

Details

CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions

Details

CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions

Details

Third-party parts / The same as upstream (pull_request) Blocked by required conditions

Details

Third-party parts / As their notes say (pull_request) Blocked by required conditions

Details

Website / Website on Cloudflare (pull_request) Blocked by required conditions

Details

PR description / Description follows the template (pull_request_target) Successful in 16s

Details

Website / Website on Cloudflare (pull_request_target) Has been skipped

Details

This pull request doesn't have enough approvals yet. 0 of 1 approvals granted.

Some workflows are waiting to be reviewed.

This branch is out-of-date with the base branch

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u 'docs/readme-for-players:jarynclouatre-docs/readme-for-players'

git switch 'jarynclouatre-docs/readme-for-players'

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area/accessibility

Barriers for people with disabilities

  

area/audio

Sound and music

  

area/input

Controllers, keyboard, mouse

  

area/install

Installing, updating, building from your game

  

area/menu

In-game menu and settings

  

area/renderer

Vulkan renderer, shaders, effects

  

area/saves

Save files

  

area/upscaling

DLSS, FSR, frame generation

  

good first issue

A good start for a new contributor

  

gpu/amd

AMD GPUs

  

gpu/igpu

Integrated GPUs

  

gpu/intel

Intel GPUs

  

gpu/nvidia

NVIDIA GPUs

  

help wanted

Extra hands or knowledge wanted

  

kind

bug

Something doesn't work as it should

  

kind

chore

Build, CI, dependencies, tidying

  

kind

docs

Documentation

  

kind

feature

A new feature or an improvement

  

kind

performance

Frame rate, frame time, loading, memory

  

kind

question

A question rather than a change

  

needs measurements

Waiting for before/after measurements

  

platform/linux

Affects Linux (a change for every system carries both Windows and Linux)

  

platform/macos

macOS (Apple silicon or Intel Macs)

  

platform/steam-deck

Steam Deck

  

platform/windows

Affects Windows (a change for every system carries both Windows and Linux)

  

preview

Maintainers: deploy a preview of this PR's website (read its changes first). Removed after the run.

  

priority

critical

Crashes, data loss, or blocks most players

  

priority

high

Important: next in line

  

priority

low

Nice to have

  

status

blocked

Waits on something else first

  

status

confirmed

Reproduced or agreed on

  

status

duplicate

Already reported or proposed

  

status

invalid

Not a problem in this project

  

status

needs-info

Waiting for more information from the reporter

  

status

wontfix

Will not be worked on

  

testing wanted

Wanted: a test on other hardware (posts a test request in #test-requests)

  

ci: approved

No labels

area/accessibility

area/audio

area/input

area/install

area/menu

area/renderer

area/saves

area/upscaling

good first issue

gpu/amd

gpu/igpu

gpu/intel

gpu/nvidia

help wanted

kind

bug

kind

chore

kind

docs

kind

feature

kind

performance

kind

question

needs measurements

platform/linux

platform/macos

platform/steam-deck

platform/windows

preview

priority

critical

priority

high

priority

low

status

blocked

status

confirmed

status

duplicate

status

invalid

status

needs-info

status

wontfix

testing wanted

ci: approved

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

MagicBeanDev/Longshot!236

No description provided.