release: prepare v0.2.1 cross-platform performance update

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -6,7 +6,7 @@ body:
     attributes:
       value: |
         **Do not attach game files, disc images, or `default.xex`**, and do not
-        ask where to obtain the game — those issues are closed without an answer.
+        ask where to obtain the game. Those issues are closed without an answer.
 
   - type: dropdown
     id: platform
@@ -24,7 +24,7 @@ body:
     id: version
     attributes:
       label: Version
-      placeholder: "e.g. v0.2.0, or a commit hash if you built it yourself"
+      placeholder: "e.g. v0.2.1, or a commit hash if you built it yourself"
     validations:
       required: true
 
@@ -33,8 +33,8 @@ body:
     attributes:
       label: Where
       options:
-        - Launcher — first-run setup
-        - Launcher — everything else
+        - "Launcher: first-run setup"
+        - "Launcher: everything else"
         - The game itself
         - Building from source
     validations:
@@ -52,7 +52,9 @@ body:
     id: logs
     attributes:
       label: Logs
-      description: Terminal output, and anything in the `logs/` folder.
+      description: >
+        In the launcher, choose Open logs folder. Paste the relevant text files
+        here, along with any terminal output. Do not attach game files.
       render: shell
 
   - type: checkboxes

.github/ISSUE_TEMPLATE/windows_report.yml

@@ -1,5 +1,5 @@
 name: Windows report
-description: You ran the Windows build. Tell us what happened — working or not.
+description: You ran the Windows build. Tell us what happened, working or not.
 title: "[Windows] "
 labels: [windows, needs-triage]
 body:
@@ -30,7 +30,7 @@ body:
     id: version
     attributes:
       label: Project8Recomp version
-      placeholder: "e.g. v0.2.0"
+      placeholder: "e.g. v0.2.1"
     validations:
       required: true
 
@@ -68,7 +68,8 @@ body:
     attributes:
       label: Output and logs
       description: >
-        Console output, and anything in the `logs/` folder of your install.
+        In the launcher, choose Open logs folder. Paste the relevant text files
+        here, along with any console output. Do not attach game files.
       render: shell
 
   - type: checkboxes

.github/PULL_REQUEST_TEMPLATE.md

@@ -10,4 +10,4 @@
 - [ ] The launcher builds and `ctest` passes.
 - [ ] If this touches a third-party dependency, `NOTICE` was regenerated.
 - [ ] If this changes anything input-driven in the launcher, I drove it myself
-      with a controller or a mouse — CI cannot verify that.
+      with a controller or a mouse. CI cannot verify that.

.github/workflows/launcher.yml

@@ -116,7 +116,7 @@ jobs:
         run: ctest --test-dir build/launcher --output-on-failure
 
       # Parses every RML/RCSS document and fails on any diagnostic. It cannot
-      # prove a control can be activated — no window manager, so synthetic input
+      # prove a control can be activated: no window manager, so synthetic input
       # never lands.
       - name: Check UI documents
         if: runner.os == 'Linux'

AGENTS.md

@@ -10,9 +10,9 @@ checkpointed releases.
 - **`src/`, `config/` and `patches/` are synchronised from the project's
   development tree.** Changes to them are applied there and arrive here in a
   release, so a pull request against those paths may be applied as a patch
-  rather than merged as a commit. It will be credited either way. Everything
-  else — the README, `docs/`, `tools/`, `.github/` and the licence files —
-  belongs to this repository and is edited here directly.
+  rather than merged as a commit. It will be credited either way. The README,
+  `docs/`, `tools/`, `.github/`, and the licence files belong to this repository
+  and are edited here directly.
 - **This repo has exactly one goal:** make it easy for someone who owns a legal
   copy to end up with a ready-to-play build. It is not a research dump.
 
@@ -31,11 +31,11 @@ If you are unsure whether something counts: it counts.
 ## Layout
 
 ```
-src/launcher/    the GUI launcher. Links no SDK — builds anywhere, needs no dump.
+src/launcher/    the GUI launcher. Links no SDK; builds anywhere, needs no dump.
 src/identify/    disc identity + extraction. Links the SDK; does what the GUI must not.
 src/game/        the game's host code. Needs the SDK and generated sources.
 src/common/      shared between the identity worker and the game's dump gate.
-config/          recompiler configuration — addresses, sizes, names.
+config/          recompiler configuration: addresses, sizes, names.
 patches/         patches against the SDK the port depends on.
 tools/           staging, licence generation, and the release gates.
 docs/            end-user and contributor documentation.
@@ -49,8 +49,8 @@ linker. Disc identity is answered by a separate binary that does link the SDK.
 Do not "simplify" this by merging them.
 
 **One dump table, two gates.** `src/common/supported_dumps.h` is used by both
-the launcher's identity check and the game's own startup gate. Never copy it —
-two copies means one of them is never tested.
+the launcher's identity check and the game's own startup gate. Never copy it;
+two copies mean one of them is never tested.
 
 **Settings render to argv by omission.** An unset setting emits no flag at all,
 never `--flag=`. An empty value is consumed as the next argument and silently
@@ -84,14 +84,14 @@ implying a machine confirmed it. Do not fake a screenshot, and do not describe a
 headless run as evidence that a control works.
 
 **Windows is unverified in the same way, only more so.** A community report
-confirms that v0.1.0 started on Windows 10, but the maintainers have not run the
-complete v0.2.0 build on real Windows hardware. Never describe it as verified,
+confirms that v0.1.0 started on Windows 10, but the maintainers have not run a
+current complete build on real Windows hardware. Never describe it as verified,
 and never describe a compatibility-layer result as evidence about real
 Windows.
 
 ## Comments
 
-Explain why, not what — particularly when the obvious approach was tried and
+Explain why, not what, particularly when the obvious approach was tried and
 failed. That history is the most valuable thing in a comment and the easiest to
 lose.
 

CHANGELOG.md

@@ -1,6 +1,98 @@
 # Changelog
 
-## v0.2.0 — Steam Deck performance and release packaging
+## v0.2.1: Steam Deck performance refresh
+
+This patch release pushes Steam Deck performance further in busy scenes. The
+exact Linux release archive averaged **25.00 ms per frame / 40.01 effective
+FPS** in a deterministic Funpark view with roughly 2,667 draws per frame. It
+also restores a complete Apple Silicon archive and improves the launcher's
+player-facing guidance. The supported disc identity, existing executable
+names, save locations, and launcher flow are unchanged.
+
+### Adjacent texture descriptor-set reuse
+
+The Performance preset now enables one additional default-off Vulkan path. It
+reuses a texture descriptor set only when the immediately preceding request in
+the same submission has the exact same descriptor-set layout and ordered image
+views, layouts, and samplers. Submission and transient-pool boundaries clear
+the entry, and every mismatch follows the original allocation/write path.
+
+On the deterministic 2,600–2,799-draw Funpark fixture, the path matched
+**39.17%** of non-empty texture stages and avoided about **1,001 descriptor
+writes per frame**. A same-binary, cool-start six-run gate moved the
+median-of-three mean from **25.630 to 25.332 ms (-1.16%)**, effective FPS from
+**39.02 to 39.48**, with process CPU flat at roughly **257%**. The wider
+hash-table design was not shipped: although it found another 450 exact sets per
+frame, it regressed mean frame time by 0.21% in all three ordered comparisons.
+
+The patch inventory now contains 37 entries. The four new source patches add
+the accepted adjacent reuse path, default-off sequence capture used to measure
+it, reproducible source-path mapping, and a usable clang-cl warning level;
+capture is inactive during normal play.
+
+### Steam Deck launches match the measured path
+
+SteamOS includes RenderDoc's Vulkan loader as a system library. The runtime
+probes for that library by name, so the v0.2.0 portable ZIP could attach the
+debugger during an ordinary player launch even though no capture was requested.
+That adds substantial per-draw overhead in the scenes where the Deck needs the
+performance work most.
+
+The Linux archive now carries a dependency-free guard library, and both
+`Project8Recomp` and the existing GUI launcher put it first for the game handoff.
+This makes the normal portable launch match the no-debugger condition used for
+the published Steam Deck measurements. Developers can still request the system
+RenderDoc library explicitly with `THPS_P8_RENDERDOC=1`.
+
+### Player-facing wording
+
+The launcher now says directly that the port contains no game content and does
+not download any. This is a wording clarification only: setup still reads a
+disc image supplied from the player's own copy, writes the extracted data into
+the portable install, and sends nothing elsewhere.
+
+The launcher copy has also been tightened across setup, settings, recovery, and
+error states. Its home screen now has separate **Open save folder** and **Open
+logs folder** buttons, and the issue forms direct reporters to the latter. Paths
+and display names are escaped before insertion into RML, so characters such as
+`<` and `&` in a local filename remain text instead of being parsed as markup.
+
+### Complete Apple Silicon release restored
+
+v0.2.1 again ships a complete `macos-arm64` archive, restoring the platform
+package that v0.1.0 had and v0.2.0 omitted. The archive now carries the Vulkan
+loader and MoltenVK itself, uses their adjacent manifest even when started from
+Finder, and ad-hoc signs every Mach-O file after its install names and symbols
+are normalised. A player does not need Homebrew; the archive is self-contained,
+but it remains neither Developer ID-signed nor notarized, so the documented
+right-click → Open step still applies.
+
+The exact release candidate was exercised on a 2020 Apple M1 MacBook Pro. Its
+packaged supervisor started the game, the bundled Vulkan loader and MoltenVK
+were loaded, and the marked fixture reached a visually verified Funpark frame
+at 2,704 draws. This restores functional support, but it is not a performance
+claim. Its 2,500-plus-draw rows averaged
+**236.79 ms / 4.22 effective FPS** (233.75 ms p50, 251.29 ms p95), while the
+process used roughly **317% CPU** during the run. Apple Silicon remains too
+slow for comfortable play in that severe scene.
+
+### Exact release archives exercised
+
+The complete Linux and Windows release candidates were unpacked and tested on
+a Steam Deck in Game Mode, using the same marked Funpark view as the performance
+work. The Linux archive averaged **24.996 ms / 40.01 effective FPS**, with
+24.998 ms p50, 27.003 ms p95, roughly 2,667 draws per frame, and **257.6%
+process CPU**. The Windows archive rendered all nine expected checkpoints
+through Proton 10. It held the player-default 30 FPS presentation mode at
+**33.31 / 34.49 ms p50 / p95**; uncapped, it measured **27.83 / 32.02 ms p50 /
+p95**, or 35.64 effective FPS.
+
+Proton reparents the Windows game outside the test supervisor, so this run does
+not provide a trustworthy process-CPU comparison. These results prove the
+archive, launcher handoff, Vulkan path, scene loading, and pacing under Proton.
+They still do not substitute for a test on real Windows hardware.
+
+## v0.2.0: Steam Deck performance and release packaging
 
 v0.2.0 promotes the runtime configuration measured on Steam Deck, fixes the
 resolution control that v0.1.0 exposed but did not actually apply, and replaces
@@ -26,7 +118,7 @@ release archives before tagging.
   binaries, so a clean player machine does not need a separate redistributable
   installer before the wrapper can start.
 
-### Resolution changes now take effect — resolves #2
+### Resolution changes now take effect (resolves #2)
 
 The launcher previously saved and emitted a resolution choice while the
 runtime remained in its default borderless-fullscreen mode. Borderless
@@ -41,13 +133,13 @@ was discarded and every selection looked identical.
 - Argument-rendering tests cover named modes, 1280x800, implicit windowed mode,
   and explicit-fullscreen precedence.
 
-### Windows pacing and CPU use — mitigates #1
+### Windows pacing and CPU use (mitigates #1)
 
 The v0.1.0 runtime disabled SDL's Windows timer resolution. A 16.67 ms vblank
 deadline could therefore wake at 31.25 ms, after which the worker delivered one
 vblank and discarded the other elapsed interval. The guest could be paced near
-32 Hz while threads waiting for that counter continued consuming CPU—the same
-shape reported in #1.
+32 Hz while threads waiting for that counter continued consuming CPU. This is
+the same shape reported in #1.
 
 v0.2.0 uses a high-resolution deadline timer on Windows, keeps SDL's timer
 resolution enabled, and performs bounded vblank catch-up after a late wake.
@@ -74,8 +166,8 @@ native vertex/index residency and unpack paths, upload prefetch, and exact
 reuse of adjacent sampler, texture-request, and Vulkan view work. Every lever
 can still be disabled through the launcher's Performance setting.
 
-On the deterministic late-game Funpark fixture, the accepted Steam Deck LCD
-build's three-run uncapped promotion median measured approximately 2,667 draws
+On the deterministic late-game Funpark fixture, the v0.2.0 Steam Deck LCD
+build's three-run uncapped median measured approximately 2,667 draws
 per frame, **25.307 ms mean**, **25.000 ms p50**, **27.015 ms p95**, **39.51
 effective FPS**, and **257.1% process CPU** (about 2.57 logical cores). With the
 player-default frame cap, the release-candidate archive held a stable 30 FPS
@@ -96,7 +188,7 @@ regression.
   GLIBC 2.39 / GLIBCXX 3.4.32 ceiling and redistribution boundary, and smoke
   tests the complete Linux and Windows ZIPs on Deck before any tag exists.
 
-## v0.1.0 — first public release
+## v0.1.0: first public release
 
 The port is playable start to finish on Linux and macOS from a copy of the game
 you own.
@@ -107,10 +199,10 @@ you own.
   disc, copies the game, and starts it. After the first run it is a Play button.
 - **Controller support** throughout the launcher and the game, including
   plugging one in after the launcher is already open.
-- **Display settings** — resolution, which monitor, windowed or fullscreen, and
-  the frame rate cap — saved in `config/settings.toml`.
+- **Display settings:** resolution, monitor, windowed or fullscreen mode, and
+  the frame rate cap, saved in `config/settings.toml`.
 - **Portable install.** Everything lives in one folder. Move it, copy it between
-  your own machines, delete it — nothing is written anywhere else.
+  your own machines, or delete it. Nothing is written anywhere else.
 
 ### Refusing bad input
 
@@ -129,7 +221,7 @@ Roughly 100 fps uncapped on a desktop Linux machine with a discrete GPU, up from
 they are in `patches/rexglue-sdk/`.
 
 macOS runs natively on Apple Silicon and is functionally correct but much
-slower — see [docs/KNOWN_ISSUES.md](docs/KNOWN_ISSUES.md).
+slower. See [docs/KNOWN_ISSUES.md](docs/KNOWN_ISSUES.md).
 
 ### Platforms
 

CONTRIBUTING.md

@@ -16,26 +16,26 @@ closed without an answer.
 
 **A Windows report.** This is the single most valuable thing anyone can send
 right now. v0.1.0 started on one reported Windows 10 machine but performed
-poorly; the complete v0.2.0 build has only been exercised under Proton. Whether
-it works or falls over on Windows, we want to know — see the Windows issue
-template.
+poorly; current complete builds have only been exercised under Proton. Whether
+one works or fails on Windows, we want to know. See the Windows issue template.
 
 **A hash from another regional disc.** The launcher accepts one release today.
 If you own a PAL or NTSC-J disc, the SHA-256 of its `default.xex` and the size
 of that file are enough to add a row. Do not send the file.
 
-**Bug reports with logs.** `logs/` in your install folder, plus the terminal
-output.
+**Bug reports with logs.** Choose **Open logs folder** on the launcher home
+screen, then include the relevant text files and any terminal output. Do not
+attach game files.
 
 **Fixes.** See the open issues.
 
 ## Where your change lands
 
 `src/`, `config/` and `patches/` are synchronised from the project's development
 tree. Pull requests against them are welcome and get read the same way as any
-other — but they may be applied as a patch and arrive in the next release,
-rather than appearing as your commit in this history. You will be credited in
-the change that carries them.
+other, but they may be applied as a patch and arrive in the next release rather
+than appearing as your commit in this history. You will be credited in the
+change that carries them.
 
 Everything else is edited here directly: the README, `docs/`, `tools/`,
 `.github/` and the licence files. A pull request against those is merged
@@ -70,7 +70,7 @@ once.
 **Headless testing cannot verify the launcher's UI.** There is no window manager
 in CI, so nothing delivers focus and synthetic input never reaches a control. CI
 proves the documents parse and the code paths run. Anything input-driven needs a
-human with a controller before it is called done — this has caught real defects
+human with a controller before it is called done. This has caught real defects
 that a full headless pass reported as green.
 
 **Settings render to argv by omission, not by empty values.** An unset setting
@@ -79,8 +79,8 @@ next argument and silently shifts the whole command line. `src/launcher/tests/`
 holds that rule; do not route around it.
 
 **The dump table is shared.** `src/common/supported_dumps.h` is used by both the
-launcher's identity check and the game's own gate. Do not copy it — two copies
-means one of them is untested.
+launcher's identity check and the game's own gate. Do not copy it; two copies
+mean one of them is untested.
 
 **The game's host code and the launcher are separate builds on purpose.** The
 launcher links no part of the SDK, so it still builds when the game does not.