PerfHUD
A fully customisable, multi-list performance overlay for Fabric
What is PerfHUD?
PerfHUD puts a clean, configurable HUD on your screen showing real-time performance and world data. Unlike the vanilla debug screen, PerfHUD is designed to live on your screen permanently, unobtrusive, readable, and completely yours to configure.
You decide what stats appear, where they appear, and how many separate stat panels you want. Everything is controlled via a drag-and-drop in-game GUI. No config file editing required.
Stats
PerfHUD tracks 13 metrics across server, client, player, and system categories:
| Stat | Description | Notes |
|---|---|---|
| TPS | Server ticks per second | Color-coded green/yellow/red. On singleplayer, calculated from live MSPT. On multiplayer, read from the server's TickingState packet. |
| MSPT | Milliseconds per tick | Singleplayer / LAN only — automatically hidden on remote servers where the data is unavailable. |
| FPS | Client frames per second | Color-coded: ≥60 green, ≥30 yellow, <30 red. |
| Ping | Round-trip latency in ms | Color-coded: ≤80ms green, ≤150ms yellow, >150ms red. |
| Memory | JVM heap usage (used / max MB) | Color-coded by heap fill percentage. |
| CPU | JVM process CPU load % | Polled every 500ms via OperatingSystemMXBean. |
| Entities | Loaded entity count in your dimension | — |
| Chunks | Loaded chunk count | — |
| Rendered Sections | Number of chunk sections in the render pass | Pulled directly from LevelRenderer. |
| Coords | Your block XYZ position | Floor-rounded integers. |
| Facing | Cardinal + intercardinal direction | Full 8-way: N, NE, E, SE, S, SW, W, NW. |
| Speed | Horizontal movement speed in blocks/second | Calculated from deltaMovement × 20 ticks/s. |
| GC Time | Cumulative JVM garbage collection time in ms | Sums all GC beans via GarbageCollectorMXBean. |
Features
Multiple independent stat lists
Create as many separate HUD panels as you want. Each list is independently positioned, configured, and styled. Run a performance-focused panel in one corner and a coordinates/facing panel in another — entirely your call.
Drag-and-drop positioning
Open the editor (/perfhud gui) and drag any list anywhere on screen. Positions are saved relative to the nearest screen corner, so your layout survives window resizes and resolution changes without drifting.
Snap-to-centre
While dragging, lists snap to the vertical and horizontal centre lines of your screen with a visible guide line and hit marker. The snap axis is saved — centred panels stay centred regardless of window size.
Per-list stat control
Right-click any list in the editor to open its context menu:
- Reorder / Toggle — enable or disable individual stats, and move them up/down within the list
- Per-stat settings — toggle the label prefix (e.g. hide "TPS: " and show just the value)
- Rename — give each list a custom name
- Background — toggle the semi-transparent dark background per list
- Text Shadow — toggle text shadow per list
- Delete — remove the list entirely
Right-click to create
Right-click on any empty area of the editor screen to instantly create a new stat list at that location.
Color-coded values
TPS, FPS, Ping, Memory, CPU, and Speed all render in context-aware colors (green / yellow / red) based on thresholds — you can tell at a glance whether something's wrong without reading the number.
Zero overhead when not needed
The HUD renderer is skipped entirely when the vanilla debug screen (F3) is open, and the overlay is suppressed while the editor GUI is active. Slow metrics (CPU, GC) are polled on a 500ms throttle to avoid hammering OperatingSystemMXBean every frame.
Frame-coherent line cache
All stat string building is cached per-frame in a generation-keyed HashMap. The renderer and the editor GUI share the same cache, so the same strings are never built twice in one frame.
Installation
- Install Fabric Loader (≥ 0.18)
- Install Fabric API
- Drop the PerfHUD
.jarinto yourmodsfolder - Launch the game
Requirements:
- Minecraft ≥ 26.1
- Java 25 or newer
- Fabric API
PerfHUD is a client-side only mod. It does not need to be installed on servers.
Usage
Opening the editor
Run the command /perfhud gui in chat.
Controls in the editor
| Action | Result |
|---|---|
| Left-click + drag | Move a stat list |
| Right-click on a list | Open context menu (configure, rename, delete) |
| Right-click on empty space | Create a new list at that position |
| Escape | Close the editor and save |
Reorder / Toggle panel
Inside a list's context menu, click Reorder / Toggle stats to open the stat panel for that list:
- Click a stat row to toggle it on or off
- Click ▲ / ▼ to move a stat up or down in the display order
- Click ⚙ to open per-stat settings (currently: show/hide the label prefix)
- Click ✕ Close to return to the context menu
Config file
Settings are saved automatically to .minecraft/config/perfhud.json. You can inspect or back up this file, but there's no need to edit it manually — the in-game GUI covers everything.
Compatibility
- Client-side only — works on any server (vanilla, Paper, Fabric, etc.)
- MSPT is only displayed on singleplayer and LAN worlds — it's silently hidden on remote servers where the data isn't accessible
- Does not conflict with other HUD mods — PerfHUD registers its overlay via Fabric API's
HudElementRegistryand attaches before the chat layer