?
Host a server
Modrinth App
Sign in
ModsPluginsData PacksShadersResource PacksModpacks
Settings
PerfHUD

PerfHUD

Highly customizable performance HUD for Minecraft.

35
1

Compatibility

Minecraft: Java Edition

26.1

Platforms

Supported environments

Client-side

Links

View source

Creators

bottledpepsi
bottledpepsiMember

Details

Licensed GPL-3.0-only
Published 3 days ago
Updated 3 days ago

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

  1. Install Fabric Loader (ā‰„ 0.18)
  2. Install Fabric API
  3. Drop the PerfHUD .jar into your mods folder
  4. 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 HudElementRegistry and attaches before the chat layer