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 1 Commits 1 Files changed 25 +1019 -995

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.

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. ## 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 added 1 commit 2026-11-13 16:29:55 +00:00

docs(readme): a short front page, the reference sections moved to docs/ as they were ... 35e835f060

The README was 1,124 lines; this leaves 215. It keeps the top, the project status, the install
steps, what you need, how it works, how to help, the license and the credits,
and gains a table of guides. The rest moves, text unchanged, to:

- 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, the AMD
  texture workaround
- docs/menu.md: In-game menu and 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 change, plus two
lines of docs/menu.md whose "below" now names the page it points to. Links to
the moved anchors follow in CONTRIBUTING.md, docs/ and the udmabuf warning.
The checks and the website's menu page read the option table from docs/menu.md.

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.

Some checks are pending

Hide checks

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

Details

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

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 2s

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

Linux only

  

platform/steam-deck

Steam Deck

  

platform/windows

Windows only

  

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)

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/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

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.