onion-mc/analysis/client-perf/PLAYER-TUNING.md

# Onion MC: performance settings for players

These are things the pack can't set for you, plus the settings to change for your machine.
All values below are final (benchmarked in Phase 2; see `RESULTS-proxy.md` in this folder).

## 1. Which tier are you?

| Tier | Typical machine | Examples |
| --- | --- | --- |
| **Deck** | handheld or integrated graphics, shared RAM | Steam Deck, laptop iGPU |
| **Mid** (pack default) | 4–6 core CPU, ~6 GB VRAM graphics card | GTX 1060 6 GB, RX 580 |
| **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 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/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
```

The whole tier table below is applied by the script:

| Setting | Where | Deck | Mid | High |
| --- | --- | --- | --- | --- |
| LOD render distance | Options → Distant Horizons button | 64 | 128 | 128 (192–256 if you have ≥16 GB free RAM and 6+ cores) |
| DH ambient occlusion (SSAO) | DH → Advanced → Graphics | off | off | on |
| DH quality preset | DH quick options | Low | Medium | Medium |
| Biome blend | Video Settings | off | 3×3 | 5×5 |
| Mipmap levels | Video Settings | 2 | 2 | 4 |
| Particles / entity shadows | Video Settings | Decreased / off | All / on | All / on |
| Leaves & weather quality | Sodium → Quality | Fast | Default | Default |
| Sub-level (airship) render distance | Sodium video settings slider | 16 | 16 | 32 |
| Dynamic lights | LambDynamicLights settings | Fastest, entities off | Fast | Fast, entities off |

Leave **render distance at 8**. The server sends 8 chunks, so anything higher loads nothing
extra in multiplayer. Distant Horizons draws everything beyond that.

## 2. Java memory and garbage collector (Prism → Edit Instance → Settings → Java)

Use **Java 21** (Temurin 21 recommended). More memory is *not* faster: a bigger heap makes
each GC pause longer. Bench (B4h): **5 GB is enough; 4 GB is measurably worse** (tour 1 % low
−23 fps); 6 and 8 GB were no faster than 5. Don't go below 5 GB on any machine.

| 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 | **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** — 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
  ```
- 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.

## 3. Shaders

*Pending the owner's shader policy. Interim advice:* **shaders off** is the pack default.
They cost more in this pack than usual:

- On its own, Flywheel (Create's GPU renderer) **switches off when any shaderpack is on**.
  The pack now ships **Iris Flywheel Compat**, which keeps it working under shaders (bench:
  Create floor p99 13.3 → 4.0 ms with MakeUp). It's unofficial, so it may lag behind
  Create/Iris updates; if Create machines render wrong with shaders, report it.
- Shader **shadows corrupt airships** (Sable sub-levels; Iris issue #3164).
- Distant Horizons adds a shadow pass over all its terrain.

If you want shaders anyway:

| Tier | Pack | Profile (shader settings screen) |
| --- | --- | --- |
| Deck | MakeUp – Ultra Fast | `shadowless_low` or `shadowless_medium`. These have no shadows, so no airship corruption. |
| Mid | MakeUp – Ultra Fast | `shadowless_medium`, or `low` if you accept shadow artefacts on airships |
| High | Complementary Reimagined | `LOW` or `MEDIUM` (MEDIUM = 8-chunk shadows). Avoid `HIGH` and above near Create builds. |

## 4. Resource packs

The pack downloads these but doesn't enable them:

- **Fresh Animations** (+ **FA: Extensions**): re-models and animates every vanilla mob. It's
  the most expensive optional visual in the pack, especially with shaders and near villages
  or farms. **Deck: don't use it.** Mid: Fresh Animations alone is OK, but skip Extensions.
  High: fine.
- **Better Leaves**: much denser leaves. The pack has no leaf-culling mod for it yet, so
  **avoid it on Deck and mid** until one is added.

## 5. Steam Deck

- Run Prism in **Desktop Mode** (flatpak from prismlauncher.org).
- Prism → Edit Instance → Settings → **Environment variables**: `mesa_glthread=true`.
  Minecraft uses Mesa's OpenGL driver (radeonsi), and glthread helps the Deck's CPU-bound
  draw path.
- Prism → Custom Commands → **Wrapper command**: `gamemoderun` (the flatpak reaches GameMode
  through the desktop portal).
- Native 1280×800. Cap FPS at the panel rate (60 LCD / 90 OLED) **after** tuning.
  Uncapped only matters for benchmarks.

## 6. Other platforms

- **Windows + NVIDIA**: NVIDIA Control Panel → Manage 3D settings → Program settings → your
  Java `javaw.exe` → *Power management mode: Prefer maximum performance*. Leave *Threaded
  optimization* alone: the driver ignores it for Minecraft, and Sodium handles it.
- **Linux + NVIDIA**: use the proprietary driver, not nouveau. Sodium already sets
  `__GL_THREADED_OPTIMIZATIONS=0`, so you don't need to.

## 7. Still slow? Change these first

1. Turn shaders off.
2. Lower the Distant Horizons LOD distance (biggest always-on cost).
3. Disable Fresh Animations.
4. Lower the airship render distance (Sodium video settings).
5. Lower biome blend (helps stutter while flying, not steady FPS).