MagicBeanDev/Hookshot
Archived
Watch
2
0
Fork
You've already forked Hookshot
 0
Code Issues 125 Pull requests 205 Activity

docs: rewrite the docs: player docs in docs/user/, developer docs in docs/dev/, the readme as a front page #2561

Open
Joey-Magnus wants to merge 7 commits from Joey-Magnus/docs/rewrite into main
pull from: Joey-Magnus/docs/rewrite
merge into: MagicBeanDev:main
Conversation 2 Commits 7 Files changed 97 +3700 -3910
Joey-Magnus commented 2026-11-11 23:16:04 +00:00 (Migrated from github.com)

hckrman101 asked in #dev-work for the docs to be rewritten, split into docs for players and docs for developers, with the junk cleaned out. This is that rewrite.

Drafted by _trash.panda's agent; _trash.panda reviewed the outline and the first page and set the style.

The new layout

readme.md is now a front page (148 lines, was ~900): what Hookshot is, a short status, getting started, an index of the docs, how it works, credits and license. It still ships in the AppImage.

docs/user/, for players:

Page
install.md Requirements, the Windows and Linux builders with their current labels and options, the first start, updating and update tracks, portable mode, where files go, uninstalling
settings.md Every menu row on main, by tab, with its choices, default and what it does. The readme's table was missing about 22 rows
upscaling.md Which upscaler to pick, getting DLSS and FSR 4, frame generation, Reflex and Anti-Lag 2
controls.md Default keys and controller layout, rebinding, mouse, motion, rumble, Steam Input
saves.md Save locations, backups, moving saves to and from emulators (was docs/saves.md)
mods.md Installing mods, order, and the resource size table
troubleshooting.md What to put in a bug report, then problems by symptom, the Linux udmabuf fix, low FPS, the AMD texture workaround

Screenshots (docs/images/user/): the Linux builder and each menu tab, taken from a headless run of a game built from current main, with default settings and no mods.

docs/dev/, for developers: README.md (index), building.md, running.md, switches.md, automation.md (was docs/control.md), architecture.md, testing.md, releasing.md (was docs/versioning.md), workflow.md (was docs/workflow.md), plus cpu-profile.md, portable-builder.md and writeback-observations.md moved in unchanged.

CONTRIBUTING.md is cut to the PR rules and links (111 lines, was ~300). AGENTS.md points at docs/dev/.

Also moved into docs/dev/: windows-builder-runtime.md unchanged, and main's new test-requests.md with its links fixed. Unchanged: docs/worklist.md, docs/tested-configurations.md, CHANGELOG.md (one path in its hand-written intro updated), BAKE.md.

What went

  • The 33 one-topic notes in docs/ were PR write-ups committed beside their fixes. Nothing referenced them. The facts worth keeping are in architecture.md, switches.md and building.md. The three rules most of them repeat are now stated once in architecture.md: mapped memory isn't assumed coherent, a failed Vulkan creation is never cached, and GPU lifetimes come from fences and the timeline, not frame counts.
  • design.md's dated plan and lab-notebook sections (§5-6, §8-12). Its architecture and replay rules are in architecture.md.
  • Build setup that existed in three copies (readme, CONTRIBUTING, development.md) now exists once, in building.md.
  • History, issue numbers and anecdotes in player-facing text.

Stale facts fixed along the way

  • The Linux builder's labels, the Windows builder's update track, build workers/memory, Prepare shaders now and FSR 4 options, and that both builders need 45 GB
  • The menu opens with Esc by default too, and with the Guide button, Back+Start or a PlayStation touchpad click on a controller
  • Cards without mesh shaders now run the compute fallback ("not supported" was out of date)
  • RX_VK_VRAM_MB's default is 45% on cards of 8.5 GB or less, 70% above
  • The game loads SDL3 first and falls back to SDL2
  • Linux can't get FSR 4 through the builder yet; it needs a source build
  • References to files and scripts that don't exist (scripts/pipeline_tour.py, third_party/PROVENANCE.md, host/nvn2.c)

Code touched

Only comments and doc paths in strings, plus tests that read docs:

  • Code comments, scripts and workflows that cited the old paths now cite the new ones.
  • The Linux udmabuf warning links the troubleshooting page.
  • test_camera_speed.py and test_stick_dead_zone.py read the settings table from docs/user/settings.md.
  • test_udmabuf_warning.py checks for the new link.
  • test_readme_menu_rows.py (#2105) is now test_settings_menu_rows.py: the same checks on docs/user/settings.md's per-tab tables, and the Motion and Controls pages' rows too.
  • The two issue forms link the install and troubleshooting pages instead of readme anchors that moved.

Checks

  • python3 -I tests/run_all.py on Linux: all pass (test_lift_cache.py needs the project's Python with numpy, as on main).
  • Every relative link and #anchor in the readme, CONTRIBUTING, AGENTS and docs/** resolves (script check).
  • Every menu row, default, switch, command and path in the new pages was checked against main's code.

Overlaps

  • #2083 (@bibigurl-yum, the Starlight site): its website/content-sources.mjs imports readme.md, docs/saves.md and CONTRIBUTING.md, and its guides link into readme sections this PR moves. Proposal: the site stays as the way the docs are presented, with docs/user/ (and docs/dev/ if wanted) as its content, in place of its five separate guides. Then there's one copy of each fact, and the site keeps its search, compatibility checker and progress pages. Happy to help adapt content-sources.mjs once one of these lands.
  • #2105 (merged) completed the readme's settings table and added a test for it; docs/user/settings.md has every row on main, and the test reads it there.

Open questions

  1. Is the shader bake (BAKE.md) still used? Two tests and two source files cite it, so it's left as it is.
  2. Which environment switches should be supported for players? switches.md marks the ones that look safe.
  3. A Windows builder screenshot for install.md needs someone on Windows (there's a placeholder comment).

Commits: player docs, developer docs, the menu screenshots, then a merge of main that carries today's doc changes (the HDR tone mapper, Aspect ratio, Save my pipeline list, the -O1 development build, the presenter thread, the Windows builder runtime note) into the new pages, and later merges that do the same for main's doc changes since. Each merge commit's message says where main's content went. Review them one at a time if that's easier.

🤖 Generated with Claude Code

hckrman101 asked in #dev-work for the docs to be rewritten, split into docs for players and docs for developers, with the junk cleaned out. This is that rewrite. Drafted by _trash.panda's agent; _trash.panda reviewed the outline and the first page and set the style. ## The new layout **`readme.md`** is now a front page (148 lines, was ~900): what Hookshot is, a short status, getting started, an index of the docs, how it works, credits and license. It still ships in the AppImage. **`docs/user/`**, for players: | Page | | |---|---| | `install.md` | Requirements, the Windows and Linux builders with their current labels and options, the first start, updating and update tracks, portable mode, where files go, uninstalling | | `settings.md` | Every menu row on main, by tab, with its choices, default and what it does. The readme's table was missing about 22 rows | | `upscaling.md` | Which upscaler to pick, getting DLSS and FSR 4, frame generation, Reflex and Anti-Lag 2 | | `controls.md` | Default keys and controller layout, rebinding, mouse, motion, rumble, Steam Input | | `saves.md` | Save locations, backups, moving saves to and from emulators (was `docs/saves.md`) | | `mods.md` | Installing mods, order, and the resource size table | | `troubleshooting.md` | What to put in a bug report, then problems by symptom, the Linux udmabuf fix, low FPS, the AMD texture workaround | Screenshots (`docs/images/user/`): the Linux builder and each menu tab, taken from a headless run of a game built from current main, with default settings and no mods. **`docs/dev/`**, for developers: `README.md` (index), `building.md`, `running.md`, `switches.md`, `automation.md` (was `docs/control.md`), `architecture.md`, `testing.md`, `releasing.md` (was `docs/versioning.md`), `workflow.md` (was `docs/workflow.md`), plus `cpu-profile.md`, `portable-builder.md` and `writeback-observations.md` moved in unchanged. **`CONTRIBUTING.md`** is cut to the PR rules and links (111 lines, was ~300). **`AGENTS.md`** points at `docs/dev/`. Also moved into `docs/dev/`: `windows-builder-runtime.md` unchanged, and main's new `test-requests.md` with its links fixed. Unchanged: `docs/worklist.md`, `docs/tested-configurations.md`, `CHANGELOG.md` (one path in its hand-written intro updated), `BAKE.md`. ## What went - The 33 one-topic notes in `docs/` were PR write-ups committed beside their fixes. Nothing referenced them. The facts worth keeping are in `architecture.md`, `switches.md` and `building.md`. The three rules most of them repeat are now stated once in `architecture.md`: mapped memory isn't assumed coherent, a failed Vulkan creation is never cached, and GPU lifetimes come from fences and the timeline, not frame counts. - `design.md`'s dated plan and lab-notebook sections (§5-6, §8-12). Its architecture and replay rules are in `architecture.md`. - Build setup that existed in three copies (readme, CONTRIBUTING, development.md) now exists once, in `building.md`. - History, issue numbers and anecdotes in player-facing text. ## Stale facts fixed along the way - The Linux builder's labels, the Windows builder's update track, build workers/memory, Prepare shaders now and FSR 4 options, and that both builders need 45 GB - The menu opens with Esc by default too, and with the Guide button, Back+Start or a PlayStation touchpad click on a controller - Cards without mesh shaders now run the compute fallback ("not supported" was out of date) - `RX_VK_VRAM_MB`'s default is 45% on cards of 8.5 GB or less, 70% above - The game loads SDL3 first and falls back to SDL2 - Linux can't get FSR 4 through the builder yet; it needs a source build - References to files and scripts that don't exist (`scripts/pipeline_tour.py`, `third_party/PROVENANCE.md`, `host/nvn2.c`) ## Code touched Only comments and doc paths in strings, plus tests that read docs: - Code comments, scripts and workflows that cited the old paths now cite the new ones. - The Linux udmabuf warning links the troubleshooting page. - `test_camera_speed.py` and `test_stick_dead_zone.py` read the settings table from `docs/user/settings.md`. - `test_udmabuf_warning.py` checks for the new link. - `test_readme_menu_rows.py` (#2105) is now `test_settings_menu_rows.py`: the same checks on `docs/user/settings.md`'s per-tab tables, and the Motion and Controls pages' rows too. - The two issue forms link the install and troubleshooting pages instead of readme anchors that moved. ## Checks - `python3 -I tests/run_all.py` on Linux: all pass (`test_lift_cache.py` needs the project's Python with numpy, as on main). - Every relative link and `#anchor` in the readme, CONTRIBUTING, AGENTS and `docs/**` resolves (script check). - Every menu row, default, switch, command and path in the new pages was checked against main's code. ## Overlaps - **#2083 (@bibigurl-yum, the Starlight site):** its `website/content-sources.mjs` imports `readme.md`, `docs/saves.md` and `CONTRIBUTING.md`, and its guides link into readme sections this PR moves. Proposal: the site stays as the way the docs are presented, with `docs/user/` (and `docs/dev/` if wanted) as its content, in place of its five separate guides. Then there's one copy of each fact, and the site keeps its search, compatibility checker and progress pages. Happy to help adapt `content-sources.mjs` once one of these lands. - **#2105** (merged) completed the readme's settings table and added a test for it; `docs/user/settings.md` has every row on main, and the test reads it there. ## Open questions 1. Is the shader bake (`BAKE.md`) still used? Two tests and two source files cite it, so it's left as it is. 2. Which environment switches should be supported for players? `switches.md` marks the ones that look safe. 3. A Windows builder screenshot for `install.md` needs someone on Windows (there's a placeholder comment). Commits: player docs, developer docs, the menu screenshots, then a merge of main that carries today's doc changes (the HDR tone mapper, Aspect ratio, Save my pipeline list, the -O1 development build, the presenter thread, the Windows builder runtime note) into the new pages, and later merges that do the same for main's doc changes since. Each merge commit's message says where main's content went. Review them one at a time if that's easier. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Joey-Magnus commented 2026-11-11 23:38:41 +00:00 (Migrated from github.com)

Merged main in twice more today to carry its doc changes into the new pages: the Graphics tab's new section headings, Field of view, the presenter thread now off by default, and the new switches (RX_VK_GPU_HANG_SEC, the vendor workarounds, RX_VK_LOW_VRAM_MIPS, RX_VK_REFLEX_SUBMIT_IDS, RX_VK_FALLBACK_PHI_LIMIT).

Since this moves the readme's tables and deletes docs/development.md, every PR that edits those will conflict with it, and it with them. It gets cheaper the sooner it lands; until then I'll keep merging main and porting what changes.

The Graphics tab screenshot still shows the layout before the section headings. A retake from current main follows once the machine is free.

(_trash.panda's agent)

Merged main in twice more today to carry its doc changes into the new pages: the Graphics tab's new section headings, Field of view, the presenter thread now off by default, and the new switches (RX_VK_GPU_HANG_SEC, the vendor workarounds, RX_VK_LOW_VRAM_MIPS, RX_VK_REFLEX_SUBMIT_IDS, RX_VK_FALLBACK_PHI_LIMIT). Since this moves the readme's tables and deletes docs/development.md, every PR that edits those will conflict with it, and it with them. It gets cheaper the sooner it lands; until then I'll keep merging main and porting what changes. The Graphics tab screenshot still shows the layout before the section headings. A retake from current main follows once the machine is free. (_trash.panda's agent)
github-sync commented 2026-11-12 17:58:03 +00:00
Owner

@Joey-Magnus commented on GitHub · 2026-11-12 17:09 UTC · original

Merged main in three times today (0146b030, bc77fced, 043ab8f2); the branch is level with main and has no conflicts. Each merge kept this PR's pages and carried main's doc changes into them. The old files (docs/development.md, control.md, versioning.md, workflow.md) stay deleted. Here is where main's content went.

docs/user/settings.md: the Game language, Menu language, Skip opening (#2827, which had no doc line) and Bug report rows on the Gameplay tab, with a note on languages (HOS_LANGUAGE, the CJK fonts). Also the Keyboard choice of Button prompts, Anti-Lag 2 working with frame generation, the Native mouse camera's handover, #2105's Mesh shaders and Discord status details, and the Teleport minimap repair under Debug.

docs/user/controls.md: the five Ocarina note rows and their note_* lines in hookshot_options.ini, the Keyboard button prompts, and the mouse camera handover.

docs/user/troubleshooting.md: what the Bug report row writes and what it leaves out, and RX_VK_ASTC_BC7 beside the AMD texture workaround. upscaling.md: DLSS Frame Generation's runtime, and Anti-Lag 2 with frame generation. install.md: "What Hookshot connects to" (linked from the readme's index), and the Linux Play hand-off to a systemd scope (#2643). mods.md: size tables for several game versions (#2592).

docs/dev/switches.md: RX_VK_IMPORT_CHUNK_MB, RX_VK_NATIVE_FADD, RX_VK_CAPTURE_KEEP_OLD/RX_VK_CAP_BLOCKS, the new RX_VK_VRAM_MB defaults with RX_VK_COUNT_BY_ESTIMATE, RX_VK_NO_DRAWN_WRITEBACK, RX_VK_WB_MAX_KB's learned write-back with RX_VK_WB_PROBATION and RX_VK_LOG_WB_SKIPS, RX_VK_MIRROR_TRIM, RX_VK_EVICT_EXCESS, RX_VK_PROGRAM_CACHE_ZSTD, HOOKSHOT_FORCE_PROMPTS and HOS_SKIP_OPENING; also the frame generation runtime in RX_VK_DLSS_DIR.

docs/dev/building.md: button prompts kept in source builds, the Docker/Podman AppImage build, and the DLSS Frame Generation runtime with NGX's search folders and the ASCII-path rule. automation.md: the bridge's age command, with its client line and example. releasing.md: the nightly tag that only moves forward. running.md: the controller GUID/mapping log line (#2678). workflow.md: the two Matrix rooms, and agents reading #agent-updates before claiming.

AGENTS.md and CONTRIBUTING.md: AGENTS.md keeps this PR's version and gains main's Team updates and Test requests sections, plus "a pull request is tested before it is opened". CONTRIBUTING.md gains the test requests link, the in-game testing sentence in step 6, "rebase or merge main", and #2105's rule that a new menu row needs a line in settings.md. Main's new docs/test-requests.md is now docs/dev/test-requests.md, with its links fixed and listed in the developer index. The links to it, and to the moved workflow and development pages, are updated in the testing and team-updates skills and in scripts/team_chat.py. The two issue forms linked readme anchors this PR moved, so they now link the install and troubleshooting pages. The worklist and tested configurations merged cleanly and match main.

Tests: #2105's tests/test_readme_menu_rows.py is now tests/test_settings_menu_rows.py. It reads settings.md's per-tab tables and keeps all five checks. Since settings.md lists the Motion and Controls pages, it now checks their rows and order too. I checked that it fails on a row removed, two rows swapped, a stale row and a renamed Motion row.

CI: the three failing Python jobs on the last head were main's own failures, not this PR's: test_env_on.py (HOS_FPS_LOG, fixed on main by #2575), and on Windows test_pcache_header_read.py and test_psychov35.py (MSVC deprecation errors, fixed by #2562). The merges bring those fixes in.

Tested: the full tests/run_all.py on Linux gives 468 passed, 2 failed. test_lift_cache.py fails on main here too (it needs the project's Python with numpy). test_updater_asset_digest.py fails here on main as well, because this machine's .NET can't restore its reference packages; it passed in CI. Every relative link and #anchor in the readme, CONTRIBUTING, AGENTS, docs/** and the skills resolves.

Still open: the Graphics tab screenshot still shows the layout from before the section headings. It needs a retake from current main on a real machine, and I haven't faked one. The open questions in the description (BAKE.md, which switches are for players, a Windows builder screenshot) still stand.

(_trash.panda's agent)

> [@Joey-Magnus](https://github.com/Joey-Magnus) commented on GitHub · 2026-11-12 17:09 UTC · [original](https://github.com/NotRexed/Hookshot/pull/2561#issuecomment-6830465465) Merged main in three times today (0146b030, bc77fced, 043ab8f2); the branch is level with main and has no conflicts. Each merge kept this PR's pages and carried main's doc changes into them. The old files (`docs/development.md`, `control.md`, `versioning.md`, `workflow.md`) stay deleted. Here is where main's content went. **docs/user/settings.md:** the Game language, Menu language, Skip opening (#2827, which had no doc line) and Bug report rows on the Gameplay tab, with a note on languages (`HOS_LANGUAGE`, the CJK fonts). Also the Keyboard choice of Button prompts, Anti-Lag 2 working with frame generation, the Native mouse camera's handover, #2105's Mesh shaders and Discord status details, and the Teleport minimap repair under Debug. **docs/user/controls.md:** the five Ocarina note rows and their `note_*` lines in `hookshot_options.ini`, the Keyboard button prompts, and the mouse camera handover. **docs/user/troubleshooting.md:** what the Bug report row writes and what it leaves out, and `RX_VK_ASTC_BC7` beside the AMD texture workaround. **upscaling.md:** DLSS Frame Generation's runtime, and Anti-Lag 2 with frame generation. **install.md:** "What Hookshot connects to" (linked from the readme's index), and the Linux Play hand-off to a systemd scope (#2643). **mods.md:** size tables for several game versions (#2592). **docs/dev/switches.md:** `RX_VK_IMPORT_CHUNK_MB`, `RX_VK_NATIVE_FADD`, `RX_VK_CAPTURE_KEEP_OLD`/`RX_VK_CAP_BLOCKS`, the new `RX_VK_VRAM_MB` defaults with `RX_VK_COUNT_BY_ESTIMATE`, `RX_VK_NO_DRAWN_WRITEBACK`, `RX_VK_WB_MAX_KB`'s learned write-back with `RX_VK_WB_PROBATION` and `RX_VK_LOG_WB_SKIPS`, `RX_VK_MIRROR_TRIM`, `RX_VK_EVICT_EXCESS`, `RX_VK_PROGRAM_CACHE_ZSTD`, `HOOKSHOT_FORCE_PROMPTS` and `HOS_SKIP_OPENING`; also the frame generation runtime in `RX_VK_DLSS_DIR`. **docs/dev/building.md:** button prompts kept in source builds, the Docker/Podman AppImage build, and the DLSS Frame Generation runtime with NGX's search folders and the ASCII-path rule. **automation.md:** the bridge's `age` command, with its client line and example. **releasing.md:** the nightly tag that only moves forward. **running.md:** the controller GUID/mapping log line (#2678). **workflow.md:** the two Matrix rooms, and agents reading `#agent-updates` before claiming. **AGENTS.md and CONTRIBUTING.md:** AGENTS.md keeps this PR's version and gains main's Team updates and Test requests sections, plus "a pull request is tested before it is opened". CONTRIBUTING.md gains the test requests link, the in-game testing sentence in step 6, "rebase or merge main", and #2105's rule that a new menu row needs a line in settings.md. Main's new `docs/test-requests.md` is now `docs/dev/test-requests.md`, with its links fixed and listed in the developer index. The links to it, and to the moved workflow and development pages, are updated in the testing and team-updates skills and in `scripts/team_chat.py`. The two issue forms linked readme anchors this PR moved, so they now link the install and troubleshooting pages. The worklist and tested configurations merged cleanly and match main. **Tests:** #2105's `tests/test_readme_menu_rows.py` is now `tests/test_settings_menu_rows.py`. It reads settings.md's per-tab tables and keeps all five checks. Since settings.md lists the Motion and Controls pages, it now checks their rows and order too. I checked that it fails on a row removed, two rows swapped, a stale row and a renamed Motion row. **CI:** the three failing Python jobs on the last head were main's own failures, not this PR's: `test_env_on.py` (`HOS_FPS_LOG`, fixed on main by #2575), and on Windows `test_pcache_header_read.py` and `test_psychov35.py` (MSVC deprecation errors, fixed by #2562). The merges bring those fixes in. **Tested:** the full `tests/run_all.py` on Linux gives 468 passed, 2 failed. `test_lift_cache.py` fails on main here too (it needs the project's Python with numpy). `test_updater_asset_digest.py` fails here on main as well, because this machine's .NET can't restore its reference packages; it passed in CI. Every relative link and `#anchor` in the readme, CONTRIBUTING, AGENTS, `docs/**` and the skills resolves. **Still open:** the Graphics tab screenshot still shows the layout from before the section headings. It needs a retake from current main on a real machine, and I haven't faked one. The open questions in the description (BAKE.md, which switches are for players, a Windows builder screenshot) still stand. (_trash.panda's agent) <!-- github-sync:c:6830465465 -->
Commenting is not possible because the repository is archived.
Reviewers
No reviewers
Labels
Clear labels   
accessibility
Barrier affecting people with disabilities

  
autorelease: pending

   
autorelease: tagged

   
bug
Something isn't working

  
dependencies
Pull requests that update a dependency file

  
documentation
Improvements or additions to documentation

  
duplicate
This issue or pull request already exists

  
enhancement
New feature or request

  
github_actions
Pull requests that update GitHub Actions code

  
good first issue
Good for newcomers

  
help wanted
Extra attention is needed

  
invalid
This doesn't seem right

  
question
Further information is requested

  
testing wanted

   
wontfix
This will not be worked on

No labels
accessibility
autorelease: pending
autorelease: tagged
bug
dependencies
documentation
duplicate
enhancement
github_actions
good first issue
help wanted
invalid
question
testing wanted
wontfix
Milestone
Clear milestone
No items
No milestone
Assignees
Clear assignees
No assignees
2 participants
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/Hookshot!2561
No description provided.