# Client performance analysis — Phase 1 (static baseline)

Goal: map the **client-side optimisation surface** of Onion MC (212 mods, MC 1.21.1 /
NeoForge 21.1.251) and rank the levers *before* benchmarking. Nothing here has been
measured on a client yet; Phase 2 benchmarks it (see `../../phase0/` for the fleet harness).

**Start with [`LEVERS.md`](LEVERS.md)**: the prioritised lever list, plus add and remove
candidates.

## Layout

| Path | What |
| --- | --- |
| `LEVERS.md` | Synthesis: ranked levers, per-machine expectations, add/remove candidates, corrections |
| `proposed-configs/` | **Phase 1b**: staged tuned configs (tiers + bench variants, generated by `build.py`) and the delivery-mechanism decision (README §1) |
| `BENCH-MATRIX.md` | **Phase 1b**: the Phase 2 run sheet (world, scenes S1–S6, config IDs, blocks B0–B13, decision rules) |
| `bench/onion-bench/` | Datapack for the bench world: scene teleports, `/fill` setups, sound storm, 120 s tour |
| `SPAWN-TUNING.md` | Shipped server spawn tuning (Alex's Mobs, Fowl Play, Critters): evidence and the B14 measurement plan |
| `PLAYER-TUNING.md` | **Phase 1b**: player guide (tiers, JVM/heap, shaders, resource packs, Deck) |
| `data/jarscan-report.md` | Static scan of every pinned jar: per-frame mixins, per-frame event hooks, atlas/model/shader/sound payloads, entity counts |
| `data/jarscan.json` | Raw scan output (re-generate, don't hand-edit) |
| `data/observed-default-configs/` | Generated defaults from the last real client launch (2026-09-24, older 110-mod pack). Use these to see actual default values |
| `research/r1-render-core.md` | Sodium / Iris + shaderpacks / Flywheel / ModernFix / ImmediatelyFast / EntityCulling / mipmaps |
| `research/r2-dh-xaero.md` | Distant Horizons 3.3.2 client + Xaero's minimap / world map |
| `research/r3-entity-animation.md` | EMF/ETF + Fresh Animations, GeckoLib, player animation mods, LambDynamicLights |
| `research/r4-effects-audio-hud.md` | Sound Physics, AmbientSounds, Subtle Effects, Perception, WATUT, TF / Alex's Caves visuals, HUD mods |
| `research/r5-candidate-mods.md` | Perf mods *not* in the pack (availability on NeoForge 1.21.1, compat, verdict) |
| `research/r6-jvm-platform.md` | GC / heap / JVM, Mesa / NVIDIA driver, Steam Deck platform levers |
| `research/r7-sable-create-client.md` | Sable / Aeronautics / SSRD / Create + Flywheel client cost |
| `research/r8-sweep-content-mobs.md` | Known-issue sweep: mob and content mods |
| `research/r9-sweep-libs-ui-misc.md` | Known-issue sweep: libraries, UI, misc client hooks |
| `scripts/jarscan.py`, `scripts/report.py` | The scanner |
| `scripts/jx.py` | Jar inspection without unzip/java: `ls`, `cat`, `str` (class-file string constants); nested jars as `outer.jar!inner.jar` |

Re-run the scan after the mod set changes:

```sh
# jars: download every mods/*.pw.toml url into a dir (analysis/audit/fetch.py does this)
python3 scripts/jarscan.py /tmp/onion/jars ../.. data/jarscan.json
python3 scripts/report.py data/jarscan.json data/jarscan-report.md
```

## Method and confidence

- **Static scan.** The scanner parses class-file annotations to get real `@Mixin` targets and
  injector kinds. It reads constant pools for event-type references and PNG headers for
  texture sizes, and it skips the Fabric-only payloads of multi-loader jars. The numbers are
  *surface*, not cost: a mixin on `LevelRenderer` may be a one-line early-return.
- **Research.** Nine subagent briefs (deepseek-v4.1-flash / glm-5.3-flash) are tagged
  VERIFIED / DOCUMENTED / COMMUNITY / INFERENCE with URLs. Load-bearing claims were
  spot-checked by the orchestrator. Corrections are listed in `LEVERS.md` §7.
- **Observed defaults.** These come from the old Prism instance's generated configs. They
  are the authoritative "what a player gets today" values for the mods that existed then.