Your server, in your game.

Install & connect

1. Install Minecraft 26.3, Fabric Loader and Fabric API on your client.
2. Place the 404Stats-Companion-<version>-b<build>.jar from the 404Stats release in your Minecraft mods/ folder.
3. Join a server running the matching 404Stats Paper plugin. Wait for the first server snapshot; then the setup guide opens automatically.

This mod is client-side. Do not put its JAR in the Paper server's plugins/ folder. Other players can join without installing it. The server's website password is not needed; statistics arrive over your normal Minecraft connection. The Paper plugin and companion share a version but have separate build numbers.

First-run setup

The welcome guide appears once after connecting to a compatible server. Choose the initial HUD size and whether the Level and PvP cards are visible. Then choose providers independently for the minimap and world map: 404Stats, an installed Xaero mod, JourneyMap, or Off. Unavailable providers cannot be selected. You can skip the guide and change everything later.

Finishing or skipping sets onboarding=false in your local settings. To see it again, open Esc → 404Stats HUD → Map & Area settings → Welcome guide.

Controls at a glance

Change conflicting key bindings in Minecraft's normal Controls screen. When the built-in world map is enabled, it also has a button in the pause menu.

HUD, size & layout

The HUD uses the website's dark, framed card style. Level, PvP and the built-in Minimap start visible; every other preset starts hidden. The Level card shows overall activity level, XP progress toward the next level and a brief +X XP gain animation. The first snapshot is treated as a baseline, not an earned XP event. Area entry and exit briefly appear on the Level card.

1. Open 404Stats HUD → Module visibility to toggle each preset, or switch its Box / No box frame.
2. Use the − and + buttons on the settings home screen to set HUD size from 50% to 200%. This is independent of Minecraft GUI scale.
3. Choose Move HUD over the game, then drag cards directly to where you want them. Arrow keys fine-tune the selected card; F toggles its frame.
4. Choose Save & exit to return to the game, or Esc to save and return to settings.

Layout, visibility, frame state and scale are saved locally for this client. The minimap visibility switch is disabled when another minimap provider is selected.

Preset modules & available values

Presets give each topic a compact starting card. To show a specific value from a topic—or mix topics—make a custom card. The value picker offers the following server-provided fields:

Distance values display in metres or kilometres, time values in minutes or hours, and XP as XP. Missing server fields show a dash rather than an invented value. This picker is not the same catalog as PlaceholderAPI or live signs.

Build custom cards

Go to 404Stats HUD → Custom cards → New card. Name the card and use Add statistic to pick a module and a value. A card accepts 1–8 different metrics, including values from unrelated modules—for example Blocks mined, Playtime and PvP kills together. Save it, then move it with the HUD editor.

You can keep up to 32 custom cards. The Custom cards list lets you show/hide, edit or delete each one. These cards only arrange statistics the server already supplies; they do not create new tracked statistics or upload a new metric to Paper.

Built-in minimap & world map

Choose 404Stats separately for Minimap and World map under Map & Area settings. The minimap follows you in the HUD. Press M for the full-screen map: drag to pan, use the wheel or zoom buttons to change scale, choose Center to return to your position, and use Heat layers to select a statistic or Terrain only. A click opens details for a visible heat cell or Area.

The client samples terrain you have visited and caches it locally; unvisited terrain remains dark. The server supplies world identities, Area outlines and aggregate heat data, not terrain tiles. Map detail offers Low, Normal and High. Low is the default and the better starting point for limited-RAM devices. If neither built-in map is active, 404Stats stops its own terrain scanning and cache updates.

Xaero & JourneyMap

Xaero's Minimap, Xaero's World Map and JourneyMap are optional separate mods; their APIs are not bundled with 404Stats Companion. The first-run guide and Map & Area settings only offer a provider when its mod is detected. You may choose different providers for minimap and world map, or turn either map Off.

The common controls are at Esc → 404Stats HUD → Map & Area settings → Map layers. Use Areas: ON/OFF, Heat: OFF, or pick one heat metric. An external map provider draws and caches its own terrain; the 404Stats terrain cache is not needed when both built-in maps are disabled.

Areas & activity heatmaps

Staff create tracked Areas on the Paper server. The companion displays their boundaries on maps and can change applicable HUD values to the shared totals of the Area you are standing in. Enable Area stats in HUD under Map & Area settings; it is off by default. Level XP and achievements stay global. The Level card briefly announces when you enter or leave an Area.

Heatmaps represent aggregate activity, not named player routes. Available layers cover Blocks placed/mined; NPC kills/deaths; movement distance/events; production items; interactions; Server Life playtime, together time, AFK time, chat words and commands; Vital Signs damage, healing and deaths; and PvP kills, damage dealt and recovery. Turn heat Off to see only terrain and enabled Area outlines. On the built-in world map, click a heat cell to inspect its value.

Settings & local files

All client preferences are stored in your Minecraft instance's config/404stats-companion.properties. Use the in-game menu for normal changes; if editing the file directly, close Minecraft first. Built-in map terrain is cached under config/404stats-companion/maps/<hashed-server>/<world-UUID>/, with world names in worlds.properties. Server and world subfolders keep caches separate.

Preset visibility, frames, positions and custom-card definitions also live in this file. Turn Debug logging on from Map & Area settings only while diagnosing an issue, then turn it off. On the Paper side, companion.update_interval_ticks: 40 is the default HUD update cadence—roughly two seconds. Achievement totals may update less often.

Where the data comes from

The Paper plugin calculates authoritative statistics and sends HUD snapshots through the Minecraft connection. The companion does not upload its own gameplay statistics or need the website password. Your HUD layout and sampled terrain stay in local client files. Map heatmaps use aggregated server data rather than individual travel paths.

Your public live map position and eligible personal Area details are controlled by the Paper command /404stats map share on|off|status, not by choosing a map provider in the companion. Sharing is off unless you opt in. See the Paper plugin commands for server-side controls.

Troubleshooting