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).