feat(perf): add one-step tier setup script for existing players

Default Options only seeds configs when absent, so existing players never
got the tuned settings. build.py --ship now also writes the Deck/Mid/High
tier files to config/onion-perf/<tier>/, and onion-perf-setup.{sh,ps1,bat}
(installed into the instance folder) backs up and replaces the tier's
config files and merges only the tuned video keys into options.txt,
keeping keybinds, audio and vsync/max-FPS choices.

PLAYER-TUNING: point players at the script; bench B4 GC verdict (G1 for
everyone; ZGC/Shenandoah tested worse); 16 GB PCs 5-6 GB heap.

analysis/client-perf/PLAYER-TUNING.md

@@ -1,7 +1,7 @@
 # Onion MC: performance settings for players
 
 These are things the pack can't set for you, plus the settings to change for your machine.
-Values marked *(provisional)* are waiting on Phase 2 benchmarks and may change.
+All values below are final (benchmarked in Phase 2; see `RESULTS-proxy.md` in this folder).
 
 ## 1. Which tier are you?
 
@@ -12,24 +12,34 @@ Values marked *(provisional)* are waiting on Phase 2 benchmarks and may change.
 | **High** | 8 GB+ VRAM card | GTX 1080 Ti, RTX 3060+ |
 
 The pack's defaults are the **mid** tier. They're applied only when the config file doesn't
-exist yet. **If you played before the defaults shipped**, close the game and delete these
-files from the instance folder to pick them up on the next launch. This resets those mods'
-settings.
+exist yet. **If you played before the defaults shipped**, close Minecraft and run the
+tier setup script in the instance folder to apply a tier over your current settings:
+
+- **Windows:** double-click `onion-perf-setup.bat` in the instance folder.
+- **Linux / Steam Deck / macOS:** run `sh onion-perf-setup.sh` in the instance folder.
+
+Pick your tier when prompted. The script backs up everything it changes (to
+`onion-perf-backup/<date-time>/`), replaces these 7 config files (the **deck** tier also
+ships `config/sodium-options.json`; **high** has the same 7 as mid), and merges the tuned
+video keys into `options.txt` — your keybinds, audio and every other setting stay as
+they are. Nothing else is touched.
+
+Manual fallback: copy the files below from `config/onion-perf/<tier>/` in the instance
+folder over your own configs, and set the `options.txt` values from the table below by
+hand (don't copy a tier's `options.txt` over yours — that resets all your video, audio
+and control settings, keybinds included):
 
 ```
 config/DistantHorizons.toml
-config/sodium-options.json
 config/entity_model_features.json
 config/flywheel-client.toml
 config/lambdynlights.toml
 config/ssrd-common.toml
 config/sound_physics_remastered/soundphysics.properties
+config/sound_physics_remastered/sound_rates.properties
 ```
 
-Don't delete `options.txt`: that resets all your video, audio and control settings,
-keybinds included. Set the video values in the table below by hand instead.
-
-Then change these for your tier *(provisional)*:
+The whole tier table below is applied by the script:
 
 | Setting | Where | Deck | Mid | High |
 | --- | --- | --- | --- | --- |
@@ -55,25 +65,23 @@ each GC pause longer. Bench (B4h): **5 GB is enough; 4 GB is measurably worse**
 | Your machine | Max memory (`-Xmx`) | Min memory |
 | --- | --- | --- |
 | Steam Deck (16 GB shared with the GPU) | **5 GB**, never above 6 | leave low (512 MB) |
-| 16 GB PC | **6 GB** | leave low |
+| 16 GB PC | **5–6 GB** | leave low |
 | 32 GB PC | **6–8 GB** | may equal max |
 | PC with little free RAM (other apps/containers running) | min(6 GB, free RAM − 2 GB) | leave low |
 
-**JVM arguments** *(provisional; Phase 2 block B4 picks the winner)*. Paste one line into
-*Java arguments* (Prism adds `-Xmx` itself from the memory box):
+**JVM arguments** — bench block B4 settled this: the client-tuned G1 line below and the
+phase-0 G1 set tied (S5 tour 1 % low 226.8 vs 228.1 fps), while Generational ZGC and
+Shenandoah were measurably worse on the tour scene (1 % low 216.6 and 173.4 vs 226.8 fps).
+So: **the G1 line below, for everyone.** Paste it into *Java arguments* (Prism adds
+`-Xmx` itself from the memory box):
 
 - **Default (all machines):** client-tuned G1
   ```
   -XX:+UseG1GC -XX:MaxGCPauseMillis=37 -XX:G1HeapRegionSize=16M -XX:+UnlockExperimentalVMOptions -XX:G1NewSizePercent=23 -XX:G1ReservePercent=20 -XX:G1MixedGCCountTarget=3 -XX:G1HeapWastePercent=20 -XX:InitiatingHeapOccupancyPercent=10 -XX:G1RSetUpdatingPauseTimePercent=0 -XX:MaxTenuringThreshold=1 -XX:GCTimeRatio=99 -XX:+DisableExplicitGC -XX:+PerfDisableSharedMem
   ```
-- **32 GB machines, if you still get stutter:** Generational ZGC. Distant Horizons
-  recommends it in its log warning about G1.
-  ```
-  -XX:+UseZGC -XX:+ZGenerational -XX:+DisableExplicitGC -XX:+PerfDisableSharedMem
-  ```
-  `-XX:+ZGenerational` is required: on Java 21, `-XX:+UseZGC` alone selects the older
-  non-generational ZGC. Avoid ZGC on the Deck or on low-RAM PCs. It needs spare memory and
-  CPU those machines don't have.
+- Don't switch to Generational ZGC — not even on 32 GB machines. Distant Horizons
+  recommends it in a log warning about G1, but here it **tested worse** (tour 1 % low
+  216.6 fps vs 226.8 for G1; Shenandoah was worse still at 173.4).
 
 Don't add `-XX:+AlwaysPreTouch` on the Deck or on low-RAM PCs. Don't copy
 `-XX:ShenandoahGCMode=iu` from older guides: Java 21 refuses to start with it.