usage

User-facing guide: install, the in-game editor, themes, benchmark mode, compatibility. For the internals behind any of this, follow the links to the other pages.

requirements + install

1. Install Fabric Loader.
2. Put Fabric API and Cloth Config API in your mods folder.
3. Optionally add ModMenu for a settings entry in the mod list.
4. Drop the MineTuner jar into mods and launch.

Client-side only: nothing is needed on the server, and it works on any server.

the editor

Open with /minetuner gui or the Open Editor keybind (default H).

list context menu

• ⚙ Edit Stats — category-grouped, searchable panel (performance / player / world / position). Toggle stats, reorder them, and open per-stat settings: label prefix, decimal places, render as graph, custom color thresholds where supported. In template mode this row becomes Edit Template Lines.
• ▤ Appearance » — rename, background, text shadow, custom color, text scale (0.5×–2.0×), Theme », template mode toggle, horizontal/vertical snap.
• ⧉ Duplicate — clone the list with all its stats and settings.
• ✕ Delete — remove the list (asks for confirmation).

list themes

A theme is a named bundle of everything about how a list looks: background, text shadow, custom color, text scale, and every stat's graph styling. It does not include which stats are shown, their order, the list's name, or its position — applying a theme never moves a list or changes its stats.

In Appearance » Theme »:

• apply — click a theme to give the current list that appearance.
• save — click + Save as new theme, type a name, press Enter. Using the name of an existing user theme re-saves it in place instead of duplicating it.
• delete — click the ✕ next to a user theme. Built-ins are marked (built-in) and can't be deleted, renamed, or overwritten.

The Default List Theme setting (full config screen) is applied to every brand-new list; changing it never touches existing lists. Every field a theme captures is also editable directly in the Appearance / Color-Scale panels or the config screen.

toggling the overlay

The Toggle Overlay keybind (unbound by default) shows/hides the HUD without opening the editor. The editor still opens and previews your lists while the overlay is hidden.

settings screen + config file

Open the Cloth Config screen via /minetuner config, ModMenu's mod list, or right-click empty space in the editor → Open Full Config. It covers every field in minetuner.json: general settings, hardware sensors, editor GUI tuning, and every list's full configuration (including graph styling, which has no control in the custom editor).

Settings save automatically and atomically to .minecraft/config/minetuner.json. You never need to hand-edit it. If it fails to parse it's backed up as minetuner.json.bak-<timestamp> and defaults are used. See config-schema.html.

template mode

Per-list alternative to the one-line-per-stat layout: write your own text with stat tokens such as {tps} interpolated anywhere. Enable it in Appearance »; edit lines in Edit Template Lines (Enter confirms, Esc cancels).

FPS: {fps} | TPS: {tps:2} | {ping}ms     →     FPS: 144 | TPS: 19.86 | 42ms

Modifiers: :N decimals, graph=true, color=#RRGGBB. Literal braces are doubled ({{, }}). Unknown or malformed tokens render as literal text and log a one-time warning. Full grammar: template-mode.html; token names: the token column in stats.html.

benchmark mode

A start/stop performance run, independent of the overlay's rolling stats. Press Start, play, press Stop to freeze the result. Unlike the overlay's session Avg/Min/Max FPS (which reset on world join/disconnect), a benchmark result stays frozen until you start another run. Starting while a result is showing discards it; stopping with nothing running does nothing.

A finished run reports:

• Avg FPS — total frames ÷ total time, so long stalls are weighted by duration.
• 1% Low / 0.1% Low — the same percentile calculation as the overlay's {fps_1pct_low}/{fps_01pct_low}, over the run only. N/A if the run is too short for a meaningful percentile.
• Frametime.
• CPU (process) — the game process's load (JVM getProcessCpuLoad, normalised across cores), time-weighted. Not whole-system CPU, so it differs from Task Manager.
• GPU — N/A unless hardware sensors are available.
• Duration and sample count.

Saving writes summary.txt and samples.csv on a background thread (the screen shows "Saving…" until done).

Bind whichever you need in Minecraft's Controls settings. Start and Stop work anywhere in-game without the screen open; the screen is for watching a run live and reviewing the result. It shows the state (Idle / Recording / Stopped) and the Start/Reset, Stop/Freeze and Save buttons.

compatibility

• Client-side only; works on vanilla, Paper, Fabric servers, etc.
• MSPT is only available in singleplayer and LAN worlds; hidden on remote servers.
• GPU/VRAM stats are opt-in and need LibreHardwareMonitor's Remote Web Server running; hidden otherwise. See hardware-sensors.html for setup and troubleshooting.
• The overlay registers through Fabric API's HudElementRegistry, just before the chat layer, so it doesn't conflict with other HUD mods.
• Stats are sampled once per client tick (ping and CPU/GC/percentile readings at most every 500 ms), whether or not the overlay is visible, but only while something needs them: a visible list (including template tokens) or a recording benchmark. See architecture.html#sampling.