onion-mc/analysis/client-perf/HANDOFF.md

Onion MC client-perf — handoff (2026-10-15)

Self-contained brief for the next agent. Read .pi/journal.md (last sections) and BENCH-MATRIX.md too, but this file is the live state on this machine.

Goal

Finish the Phase 2 client-performance loop: measure the staged configs, decide by BENCH-MATRIX.md's rules, write winners into proposed-configs/build.py (DEFAULT / DECK / HIGH), build.py --ship, packwiz refresh, commit (Conventional Commits) and push. Pushes go live to players on their next Prism launch.

Repo / pack state

• Pack: 217 mods, MC 1.21.1, NeoForge 21.1.251. Git HEAD == origin/main == 8e8483d.
• 8e8483d fixed the one real boot blocker: the Critters & Companions partial spawn config used camelCase keys (biomeSpec) but YACL serialises with FieldNamingPolicy.LOWER_CASE_WITH_UNDERSCORES; every entry loaded biomeSpec = null and CACSpawnConfig$SpawnEntry.isTag() NPE'd in FMLCommonSetupEvent, leaving the client in a "broken mod state" (119 refused events). Fixed to snake_case; already pushed.
• The Alex's Mobs (TOML) and Fowl Play (YACL camelCase) spawn files are correct and were verified applied in-game. Do not commit the mod/server full re-saves of config/* (the running server rewrites them): always git checkout -- config/ before staging.
• Nothing was shipped this session. Shipped config/defaultoptions/** is unchanged from a01bc3b. build.py was only patched in the BENCH layer (below); the tiers are untouched.

Boot check (client, this machine) — essentially PASS

Reached main menu cleanly. Sound engine started 01:26:53; ModernFix "Game took 29.3 s to start"; blocks atlas 4096x4096x2; Default Options correctly seeded options.txt (renderDistance 8, maxFps 120, vsync true). No missing deps, no mixin apply failures, no ftbteams refs, no fishermans-haven biome errors, no YACL "Failed to deserialize". 22 ERROR lines, all benign (pride access-transformer, Controlify @Shadow, FTB Library legacy textures, 4 GeckoLib molang parses, icys-better-horses pack path, Xaero version expiry, Veil failing to recompile 2 lodestone nineslice shaders).

Open boot-adjacent issue (not yet fixed): an intermittent crash on world load:

java.io.FileNotFoundException: minecraft:shaders/core/particle.json
  at com.corosus.watut.ShaderInstanceBlur.<init>(ShaderInstanceBlur.java:27)
  at GameRenderer.handler$jhl000$watut$onLoadShaders(...)

First world load succeeded and measured; the next crashed during "Rendering overlay". WATUT is a LEVERS §5 removal candidate but the owner says remove no mods — look for a WATUT config/patch or a reliable retry. Confirm whether real players hit it before shipping.

Tooling installed on this machine (all user-local, no root)

• Prism Launcher 11.0.3 (/usr/bin/prismlauncher). Data root ~/onion-bench/prism, instance id OnionBench, game dir ~/onion-bench/prism/instances/OnionBench/.minecraft (214 jars). A valid Microsoft account is in ~/onion-bench/prism/accounts.json (device-code login, owner-approved).
• MangoHud 0.8.4 extracted to ~/.local/mangohud; wrapper ~/.local/bin/mangohud-local (exports MANGOHUD_CONFIG, LD_PRELOAD shim, vblank_mode=0). CSVs land in ~/onion-bench/mangologs/. The instance has WrapperCommand=mangohud-local.
• Bench world: ~/onion-bench/prism/instances/OnionBench/.minecraft/saves/onionbench (seed onionbench, creative, cheats). S2 Create floor (2304 kinetic BEs) and S3 mob pen (30 villagers/15 cows/15 sheep/10 allays) were placed via RCON and verified. S4 airships NOT built. Datapack lives in the world's datapacks/onion-bench.
• Temp server for worldgen: ~/onion-bench/server-bench (symlinks repo mods/ libraries, copies config), port 25566 / RCON 25576, currently stopped.
• Harness (this is new, untracked, packwizignored): analysis/client-perf/harness/
  • rcon.py — minimal RCON client.
  • run_scene.py — applies a variant, launches Prism into the bench world under MangoHud, drives scenes with xdotool chat, slices the CSV into p50/p95/p99/1%-low. Verified working end-to-end once (C1/S1).

Measurements so far — NOT decision-grade

One run: C1 / S1 p50 16.72 ms, p99 17.24 ms, peak 17.60 ms, avg 59.8 FPS, 1% low 57.5, n=1889. It was vsync-locked at ~60 FPS (tight 16.7 ms floor). vblank_mode=0 was added afterwards but the next launch crashed on world load, so uncapped data is not collected yet. Treat all of this as pipeline validation only.

Next steps (in order)

1. Resolve the WATUT world-load crash; re-run one C1/S1 and confirm FPS > 60 (vblank off).
2. Run the matrix in order, per BENCH-MATRIX.md: B0 noise floor (C0/S1 ×3) → B1 baseline (C0, S1–S6) → B2 composite (C1, and C1-deck/C1-high) → B3 DH radius (dh-r256, dh-r192, C1, dh-r64, dh-off on S1/S5) → B4 heap/GC (use jcmd/ jstat, or spark, at 5/6 G and J0–J3) → B6 ModernFix → B7 shaders → B8 entities → B9 Flywheel → B10 SPR → B11 Sodium/blend → B12a/b ablation and trials → B13 spark profile → B14 spawn counts.
3. Write winners into build.py, python3 build.py --ship, ~/go/bin/packwiz refresh, commit. Ship config/modernfix-mixins.properties only if B6 passes (see SHIP comment).
4. Update PLAYER-TUNING.md (tiers, heap/GC, shader profiles), LEVERS.md, BENCH-MATRIX.md, and append a journal section.

Fleet note

P0 (Steam Deck), P1 (7700K/1060) and P2 (6700K/1080 Ti) are not reachable from this box (no routes / no SSH targets). Everything measured here is a high-tier proxy on a Ryzen 9 9900X + RX 7800 XT, 91 GB RAM. Label results as proxies; absolute FPS floors do not map to tier decisions.

Gotchas learned this session

• Prism 11 --offline fails a fresh instance with "Required libraries are missing" (EnsureOfflineLibraries). Launch online once to download libs/assets; after that offline works.
• xdotool windowactivate --sync hangs under kwin; use windowactivate + windowfocus.
• MangoHud needs MANGOHUD_CONFIG set explicitly and LD_PRELOAD exported.
• The owner's dedicated server runs from the repo root (java @user_jvm_args.txt @libraries/.../unix_args.txt, port 25565). Never kill it; never touch world/. The temp bench server used separate ports/paths and is stopped.
• analysis/ is packwizignored (safe to commit); config/ is server-rewritten (restore before staging).