docs: client-perf analysis, bench harness and work journal
Everything the next agent needs to run the Phase 2 optimisation loop on a machine that can launch the client: - analysis/client-perf/: LEVERS (ranked levers + corrections), BENCH-MATRIX (world, scenes, config IDs, blocks B0-B14 with decision rules), PLAYER-TUNING, SPAWN-TUNING, research briefs, the jar scanner and its output, observed default configs, and proposed-configs/ (build.py generates tiers and bench variants and fails on unknown keys; apply_variant.py applies a variant and merges options.txt). - analysis/client-perf/bench/onion-bench/: bench-world datapack (scene teleports, Create grid, mob pen, sound storm, 120 s teleport tour). - analysis/audit/: the static recipe/dependency audit, including gen_fixes.py, which generates the shipped Paxi datapack and was never tracked. - phase0/: per-machine measurement harness (Steam Deck, 7700K/1060, 6700K/1080 Ti). - .pi/journal.md: running work log; read it first. All of it is packwizignored, so nothing here ships to players.
This commit is contained in:
logan committed
1 parent
d80f85b3f6
commit
611a1a5952
102 files changed
+25853
No files matched your search
@@ -0,0 +1,243 @@
|
||||
# Phase 0 — P1: i7-7700K / GTX 1060 6 GB (Windows)
|
||||
|
||||
Setup and measurement procedure for the VRAM-bound machine in the Onion MC client tuning
|
||||
fleet.
|
||||
|
||||
---
|
||||
|
||||
## Profile
|
||||
|
||||
| | |
|
||||
| --- | --- |
|
||||
| CPU | Intel i7-7700K, 4 cores / 8 threads, 4.2 GHz base (Kaby Lake) |
|
||||
| GPU | NVIDIA GTX 1060, **6 GB VRAM** (Pascal, GP106) |
|
||||
| RAM | 32 GB — **not a constraint on this machine** |
|
||||
| OS | **Windows** (the fleet's only Windows box) |
|
||||
| **Binding constraint** | **VRAM** |
|
||||
| **What this tier tests** | GPU/VRAM ladder steps with CPU and RAM held non-binding |
|
||||
| **Expected DH answer** | **On, with quality/distance reduced — VRAM is the wall** |
|
||||
|
||||
### Why this machine matters
|
||||
|
||||
- **32 GB of RAM removes RAM/GC as a confound**, so this machine isolates pure GPU and
|
||||
VRAM effects. That is where DH's quality preset and CTM/texture fidelity live.
|
||||
- **Its CPU is the same class as P2** (both 4C/8T ~4.2 GHz). Comparing this machine against
|
||||
P2 therefore isolates the GPU/VRAM axis while holding CPU-side mod cost roughly constant.
|
||||
That pairing is the fleet's built-in control — see the taxonomy self-check at the end.
|
||||
- **It is the only Windows machine**, so the OS axis is confounded with the GPU axis here.
|
||||
A result that differs from P2 could be the GPU or the driver stack, and this rig cannot
|
||||
separate them. Record it as a known limitation.
|
||||
|
||||
---
|
||||
|
||||
## Shared measurement protocol
|
||||
|
||||
Applies to every machine in the fleet. Duplicated here so this document stands alone.
|
||||
|
||||
1. **Uncapped, vsync off** during measurement. Apply the FPS cap only *after* tuning.
|
||||
2. **Metric is p99 frametime and 1% low, not average FPS.**
|
||||
3. **Discard 10–15 s of warmup** per scene — JIT, chunk load, initial GC.
|
||||
4. **Settle after any render-distance or DH change.**
|
||||
5. **Three runs per configuration, report median and spread.**
|
||||
6. **One variable per run.**
|
||||
7. Guardrails: FPS limiter active, power plan changed, or GPU throttling → invalid run.
|
||||
|
||||
---
|
||||
|
||||
## Step 1 — Windows power and background load
|
||||
|
||||
```powershell
|
||||
powercfg /list
|
||||
powercfg /setactive SCHEME_MIN # High performance
|
||||
```
|
||||
|
||||
- [ ] Power plan set to **High performance** (or Ultimate Performance) and recorded.
|
||||
- [ ] No pending Windows Update or reboot.
|
||||
- [ ] **Xbox Game Bar off:** Settings → Gaming → Xbox Game Bar → Off.
|
||||
- [ ] **Game DVR / background recording off:** Settings → Gaming → Captures →
|
||||
*Record in the background while I'm playing* → Off. This is a real frametime cost.
|
||||
- [ ] Close browsers, Discord, OneDrive, and any streaming/recording software.
|
||||
- [ ] **Exclude the instance folder from Windows Defender real-time scanning** to remove
|
||||
I/O spikes during chunk loading. Record that you did it.
|
||||
|
||||
## Step 2 — GPU settings
|
||||
|
||||
**NVIDIA Control Panel → Manage 3D settings → Program Settings → (Prism's `javaw.exe`):**
|
||||
|
||||
- [ ] Power management mode → **Prefer maximum performance**
|
||||
- [ ] Vertical sync → **Off**
|
||||
- [ ] Low Latency Mode → fixed value, recorded (it changes frame pacing — don't vary it)
|
||||
- [ ] **Threaded Optimization** → fixed value, recorded (it affects OpenGL apps directly)
|
||||
- [ ] Texture filtering quality → fixed value, recorded
|
||||
|
||||
**Hardware-Accelerated GPU Scheduling (HAGS):** Settings → System → Display → Graphics →
|
||||
*Change default graphics settings*. Record On/Off and **keep it constant**. HAGS changes
|
||||
frame pacing and will show up in your p99 numbers.
|
||||
|
||||
**Fullscreen:** run Minecraft in the **same display mode every session** (fullscreen at
|
||||
native resolution, or borderless — pick one). Also disable *Fullscreen optimizations* for
|
||||
`javaw.exe` (right-click → Properties → Compatibility) so Windows doesn't add compositor
|
||||
work. Record the choice.
|
||||
|
||||
## Step 3 — Confirm GPU state
|
||||
|
||||
`nvidia-smi` ships with the NVIDIA driver on Windows too. **Use the identical command as
|
||||
the Linux machine** so both NVIDIA rigs produce the same CSV schema:
|
||||
|
||||
```powershell
|
||||
& "$env:SystemRoot\System32\nvidia-smi.exe" -q -d PERFORMANCE # check for throttle reasons
|
||||
New-Item -ItemType Directory -Force ~\mcbench\logs | Out-Null
|
||||
& "$env:SystemRoot\System32\nvidia-smi.exe" `
|
||||
--query-gpu=timestamp,memory.used,clocks.sm,clocks.mem,power.draw,temperature.gpu,utilization.gpu `
|
||||
--format=csv -l 1 > ~\mcbench\logs\gpu-$(Get-Date -f yyyy-MM-dd-HHmmss).csv
|
||||
```
|
||||
|
||||
- [ ] No `SW Power Cap` or `HW Slowdown` in the throttle reasons.
|
||||
- [ ] `memory.used` logging running. **On a 6 GB card this is your headline metric** —
|
||||
peak VRAM tells you when DH, CTM and texture fidelity have crossed the line.
|
||||
|
||||
## Step 4 — Measurement tooling: PresentMon
|
||||
|
||||
MangoHud does not exist on Windows. Use **PresentMon** (open source, ETW-based, and it
|
||||
covers OpenGL as well as DX/Vulkan).
|
||||
|
||||
**Option A — the Frame Time Analysis package** (simplest; download from
|
||||
<https://boringboredom.github.io/Frame-Time-Analysis/>). It ships a `Run.bat`:
|
||||
|
||||
```bat
|
||||
pushd %~dp0
|
||||
cd captures
|
||||
..\presentmon.exe --multi_csv --no_console_stats --hotkey "F10"
|
||||
```
|
||||
|
||||
Run it **as Administrator** (ETW capture requires elevation), then press **F10** to
|
||||
start/stop each capture. `--multi_csv` writes a new CSV per capture cycle into `captures/`.
|
||||
|
||||
**Option B — target the Minecraft process explicitly** so only MC is captured:
|
||||
|
||||
```powershell
|
||||
presentmon.exe --process_name javaw.exe --output_file ~\mcbench\logs\pm.csv --timed 30
|
||||
```
|
||||
|
||||
- [ ] Confirm the process name. Prism launches Minecraft as **`javaw.exe`**; verify in Task
|
||||
Manager rather than assuming.
|
||||
- [ ] PresentMon emits **two CSVs per capture**: the raw per-frame data and a **stats
|
||||
summary that already contains average / min / max / percentile FPS**. Use the summary
|
||||
for a quick read and the raw file for the real analysis.
|
||||
- [ ] Verify a capture produces a CSV with a frametime column before collecting real data.
|
||||
|
||||
## Step 5 — Analysis: one tool for the whole fleet
|
||||
|
||||
Use **Frame Time Analysis** (<https://boringboredom.github.io/Frame-Time-Analysis/>). It
|
||||
reads CSV from **PresentMon, CapFrameX, OCAT, MangoHud** and FrameView, all in the browser,
|
||||
with no upload to a third party.
|
||||
|
||||
- [ ] Percentiles, **lows (1% / 0.1%)**, box plots, bar charts and summary tables.
|
||||
- [ ] **Merge multiple CSV files** — this is what lets you put the three runs of one
|
||||
configuration, and the MangoHud CSVs from the Linux machines, side by side on one
|
||||
chart.
|
||||
- [ ] Screenshot export for the record.
|
||||
|
||||
This tool is the reason the fleet does not need a custom analyzer: raw capture stays
|
||||
platform-native (MangoHud on Linux, PresentMon on Windows) and analysis is unified.
|
||||
|
||||
## Step 6 — Launcher and JVM
|
||||
|
||||
Use **Prism Launcher** and launch from a shell so the environment is under your control.
|
||||
|
||||
**Java:** 21 — the **same JVM build as the Linux machines** (Temurin 21 is a good choice for
|
||||
all three). A different JVM build is a confound.
|
||||
|
||||
**JVM arguments** (identical across the fleet except `-Xmx`):
|
||||
|
||||
```
|
||||
-Xmx8G
|
||||
-XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200
|
||||
-XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC
|
||||
-XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=8M
|
||||
-XX:G1ReservePercent=20 -XX:G1HeapWastePercent=5 -XX:G1MixedGCCountTarget=4
|
||||
-XX:InitiatingHeapOccupancyPercent=15 -XX:G1MixedGCLiveThresholdPercent=90
|
||||
-XX:G1RSetUpdatingPauseTimePercent=5 -XX:SurvivorRatio=32
|
||||
-XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1
|
||||
```
|
||||
|
||||
32 GB means heap is not a variable here. Keep `-Xmx8G` fixed and spend your attention on
|
||||
VRAM.
|
||||
|
||||
## Step 7 — Pin the in-game settings
|
||||
|
||||
Controlled variables — set once, record, do not change between runs unless the run is
|
||||
testing that setting.
|
||||
|
||||
- Graphics: Fancy
|
||||
- Render distance: 8
|
||||
- Particles: All
|
||||
- Clouds: Fancy
|
||||
- Entity shadows: On
|
||||
- Biome blend: fixed, recorded
|
||||
- Mipmap levels: 4
|
||||
- GUI scale: fixed number
|
||||
- **Max framerate: Unlimited**
|
||||
- **VSync: Off** (also off in the NVIDIA panel — check both)
|
||||
- FOV, resolution, fullscreen mode: fixed and recorded
|
||||
|
||||
## Step 8 — Verification run
|
||||
|
||||
- [ ] PresentMon capture produces a raw CSV **and** a stats summary CSV.
|
||||
- [ ] `nvidia-smi` VRAM logging is producing a CSV.
|
||||
- [ ] MangoHud is not expected here — confirm you are actually capturing through PresentMon.
|
||||
- [ ] Run the same configuration three times and record the spread. Establish this before
|
||||
interpreting anything.
|
||||
- [ ] Confirm peak VRAM is being recorded — it is the whole point of this machine.
|
||||
|
||||
## Step 9 — Per-session checklist
|
||||
|
||||
- [ ] Power plan = High performance
|
||||
- [ ] Game Bar and background recording off
|
||||
- [ ] Defender exclusion in place
|
||||
- [ ] NVIDIA power mode = prefer max performance; vsync off; HAGS and Threaded Optimization
|
||||
unchanged since last session
|
||||
- [ ] `nvidia-smi` throttle check clean
|
||||
- [ ] VRAM logging started
|
||||
- [ ] PresentMon running as Administrator
|
||||
- [ ] Display mode and resolution unchanged
|
||||
- [ ] No pending Windows Update
|
||||
|
||||
## Step 10 — Recording sheet
|
||||
|
||||
| Field | Example |
|
||||
| --- | --- |
|
||||
| Date / session | 2026-09-28-a |
|
||||
| Machine | P1-7700K-1060 |
|
||||
| Config ID | baseline / dh-low / ctm-off / emf-off / … |
|
||||
| Scene | A-base / B-terrain / C-gui |
|
||||
| Run # | 1 / 2 / 3 |
|
||||
| CSV file (raw + summary) | |
|
||||
| p50 / p95 / p99 frametime (ms) | |
|
||||
| 1% low FPS | |
|
||||
| Avg FPS | |
|
||||
| **VRAM peak (MB)** | the headline number for this rig |
|
||||
| Throttle flag | none / SW Power Cap / HW Slowdown |
|
||||
| Notes | |
|
||||
|
||||
---
|
||||
|
||||
## Machine-specific caveats
|
||||
|
||||
- **VRAM is the binding constraint, so watch for the cliff, not the slope.** On a 6 GB card
|
||||
the failure mode is a sharp p99 regression once DH + CTM + texture fidelity exceed
|
||||
capacity — not a smooth FPS decline. Record peak VRAM alongside every result.
|
||||
- **Two vsync switches exist** (in-game and NVIDIA panel). Verify both are off, every
|
||||
session. A single missed vsync makes every configuration look like it hits the target.
|
||||
- **Beware dynamic clocking.** Verify no throttle reasons before and after a block of runs.
|
||||
- **This is the only Windows machine, and it is also the weakest GPU** — the OS axis is
|
||||
confounded with the GPU axis. A divergence from P2 cannot be attributed to the OS.
|
||||
- **32 GB makes this the fleet's clean tier for GPU-only effects.** If a knob you classified
|
||||
as GPU/VRAM shows a large delta here and almost nothing on P2, the taxonomy is confirmed.
|
||||
If a knob you classified as CPU-render diverges between this machine and P2 *in direction*,
|
||||
the classification is wrong — both share the same CPU class, so CPU-side effects should
|
||||
track closely.
|
||||
- **Windows measurement is ETW-based** (PresentMon) while Linux is MangoHud-based. The two
|
||||
do not measure identically, and the fleet has no same-hardware cross-OS pair, so
|
||||
**absolute numbers are not cross-comparable between OSes — only within-OS comparisons
|
||||
are.** Derive ladder orderings per OS, then check that the *orderings* agree.
|
||||
Reference in new issue
Block a user