onion-mc/analysis/state/05-decisions-and-rules.md

Settled decisions, rules of the road, traps

Owner decisions (2026-10-14) — settled, do not relitigate

1. Delivery mechanism = Default Options (+ enforced config/modernfix-mixins.properties after B6 passes). Done in a01bc3b.
2. Puzzles Lib 21.1.64 — done (bugfix only; no NeoForge perf change, LEVERS #14 corrected).
3. Shaders: opt-in (packwiz downloads them; nothing enables them). B7 produces the policy data; owner decision still pending that data.
4. Spawn tuning allowed if not detrimental to gameplay — done, moderate (d80f85b: alexsmobs/fowlplay/crittersandcompanions partial files). B14 measures it.
5. Remove no mods. LEVERS §5 removal candidates are reference only. (This includes WATUT — so the WATUT crash must be fixed, not removed away.)
6. Add any helpful mods — the five Add-verdict mods went in a01bc3b (Sodium Extra, Reese's Sodium Options, BadOptimizations, Particle Core, + Default Options). Trial mods are B12b's call; the agent may add trial winners.

Rules of the road (iteration rules from the journal)

• Change tuned defaults only via analysis/client-perf/proposed-configs/build.py (DEFAULT / DECK / HIGH layers) → build.py --ship → packwiz refresh → commit. Never hand-edit proposed-configs/out/* or shipped files.
• Shipped defaults are copy-if-absent: changes reach fresh installs only. Existing players follow PLAYER-TUNING §1 (delete 7 re-seeding config files; do NOT delete options.txt; set tier video values by hand).
• git checkout -- config/ before staging — the server's mods re-save partial spawn files in full on boot; committing those expansions is the known mistake.
• packwiz update in bulk resets hand-set side = "server" on petprotect, c2me-neoforge, noisium. Single-mod updates are safe.
• Any new mod: verify NeoForge 1.21.1 build + neoforge.mods.toml ranges against pins, check side, then re-run B0 (new mod set invalidates the noise floor).
• One recorded commit per matrix row; label all data as proxy-machine data.
• Never kill the dedicated server (tmux onion-mc, repo root, port 25565) and never touch world/. sp-world.tar.gz (650 MB, untracked) — leave alone.
• .pi/journal.md is the running log — append a session entry when you finish.

Verified facts / traps (don't re-derive, don't re-trip)

• packwiz preserve: settable only by hand-editing index.toml; survives refresh and unrelated updates; silently dropped if the file is absent/ignored at refresh time; installer writes the file only if absent. Index files have no side, so shipped configs land on the server too (this repo IS the server).
• Default Options 21.1.8: copy-if-absent for config/defaultoptions/options.txt (key_ lines stripped) and config/defaultoptions/extra/**; runs before NeoForge constructs mods — too late for modernfix-mixins.properties (hence B6 gating).
• Observed defaults were generated from the same jar versions as current pins (DH 3.3.2, Sodium 0.8.13, EMF 3.3.9, Create 6.0.10/Flywheel 1.0.6, Sable 2.0.5, SPR 1.5.1). DH numberOfThreads true default = ceil(nproc/2) = 4 here (observed 2 came from a 4-thread box).
• Flywheel 1.0.x disables both GPU backends when any shaderpack is active (verified in Backends.java). No Iris Flywheel Compat in the pack (B12b trial).
• SSRD 1.8.7 → config/ssrd-common.toml (COMMON; server reads it too; slider floor 16). LambDynamicLights 4.8.11 → config/lambdynlights.toml (lowercase modes). SPR merges partial sound_rates.properties over generated defaults.
• More Culling is unusable: its NeoForge build declares minecraft [1.21,1.21.1).
• -XX:ShenandoahGCMode=iu aborts JDK 21 without UnlockExperimentalVMOptions — J3 uses plain -XX:+UseShenandoahGC.
• Prism 11 --offline fails a fresh instance ("Required libraries are missing"); launch online once, then offline works.
• xdotool windowactivate --sync hangs under kwin — use windowactivate + windowfocus.
• MangoHud needs MANGOHUD_CONFIG explicit + LD_PRELOAD exported — use the wrapper ~/.local/bin/mangohud-local; system mangohud is not installed.
• cdn.modrinth.com 501s Range requests — download whole jars. No unzip; use python zipfile. lodestonelib is the real slug (lodestone has no 1.21.1 build).
• Duplicate version_number traps: tarotcards-remastered, room-for-two, too-many-bows reuse version strings across MC versions — pin exact filenames by hand.
• Iris 1.8.14-beta.1 ↔ Sodium 0.8.13 mixin incompatibility reported on NeoForge (r5) — check when testing shaders (B7).

Open owner-facing deliverables (owed from Phase 2)

• B7 shader-policy data → owner decision on default-off vs opt-in messaging.
• B12b trial-mod verdicts (which trials earned a permanent add).
• B14 spawn-tuning measurement (keep/back-off call).
• Any B13 "mod >5% of render thread" findings.