404Stats Wiki
From a fresh Paper server to live signs, custom achievements and displays built from your own statistics.
Getting started
- Run a supported Paper server with its required Java version. This beta targets Paper 26.3 and Java 26; Bukkit, Spigot and Folia are not supported.
- Put the 404Stats plugin JAR in your server's
plugins/folder and restart. Do not use/reloadto install or replace the JAR. - Check startup logs for 404Stats, then open
http://localhost:8088on the server machine. Set a password before exposing the dashboard outside your trusted network. - Optional: install PlaceholderAPI to use the variables below. It is not needed for the dashboard or live signs.
The plugin stores its local H2 database in plugins/404Stats/. Stop the server before backing up or replacing database files. The dashboard is served by the plugin; the demo dashboard and this wiki are static examples, not a replacement for your own server.
Dashboard & admin access
The bundled website shows server totals, player pages, trends, rankings, world maps, areas, projects and achievements. The usual local address is http://localhost:8088. Change the listener in plugins/404Stats/webserver.yml.
/404stats webadminAn operator (or a player with 404stats.webadmin) runs this in game. The command generates a one-use admin link valid for five minutes. Open it in your browser to access the achievement editor. Keep the link private; generate another after expiry.
webpanel.password in config.yml, use HTTPS through a reverse proxy, and restrict who can reach the port. webserver.public_url only changes the displayed link; it does not secure the listener.What the modules track
Dashboard support is broader than the current live-sign and PlaceholderAPI value catalogs. The supported value tables below are authoritative for those integrations.
Commands
/404stats is the main command. /blockstats and /mcstats are aliases. Player commands require 404stats.command.use (granted by default); administrative actions require operator permission or their specific admin node.
| Command | Use |
|---|---|
/404stats me [blocks|npcs|movement|production] [survival|creative|all] | Show your own summary in chat. |
/404stats player [blocks|npcs|movement|production] <name> [survival|creative|all] | Look up another player; requires 404stats.command.other. |
/404stats panel | Show the dashboard URL. dashboard is an alias. |
/bossbar [blocks|npcs|movement] | Toggle or choose the live bossbar. /404stats bossbar also works. |
/404stats project add <name> | Create/select a block project and enable its tracking. |
/404stats project join <name> | Join/select an existing project. |
/404stats project toggle|current|leave|remove [name] | Control tracking, inspect, leave or remove a project. |
/404stats map share on|off|status | Opt in or out of public map position and area player details. |
/404stats area map | Get the vanilla-map area selector. |
/404stats area pos1|pos2 | Set corners at your feet. |
/404stats area create <slug> [project-slug] | Create a tracked region from the selection; operator only. |
/404stats area list|archive <slug>|restore <slug> | List regions or pause/resume tracking; all Area commands require 404stats.admin. |
/404stats map fullrender [world|all] | Render already-generated chunks without creating terrain; operator only. |
/404stats map status|cancel | Inspect or stop a full render; operator only. |
/404stats webadmin | Get a temporary, one-use achievement-admin link. |
/404stats reload | Reload plugin and web-server settings; operator only. |
Configuration
Edit plugins/404Stats/config.yml and webserver.yml, then use /404stats reload for supported settings. A full server restart is safest after changing database paths or module availability.
config.yml
| Key | Default | What it changes |
|---|---|---|
server.name | My Minecraft Server | Display name for this server. |
local.database_file | 404stats | H2 database basename; H2 creates a .mv.db file. |
local.sync_interval_seconds | 30 | Maximum normal wait before batched statistics are saved. |
local.max_batch_size | 500 | Maximum events processed per sync batch. |
movement.sample_interval_ticks | 20 | Movement sampling frequency; 20 ticks is approximately one second. |
movement.ignore_spectator | true | Exclude Spectator movement. |
server_life.afk_after_seconds | 300 | Idle threshold before AFK time begins. |
server_life.together_radius_blocks | 24 | Distance for shared-time tracking. |
server_life.spawn_exclusion_radius_blocks | 96 | Ignore shared time near world spawn. |
server_life.max_together_group_size | 10 | Ignore groups larger than this for shared time. |
signs.enabled | true | Enable live statistics signs. |
signs.refresh_interval_seconds | 10 | Refresh interval for signs in loaded chunks. |
modules.blocks.enabled | true | Collect block mining and placing activity, including projects. |
modules.npc_combat.enabled | true | Collect mob/NPC combat activity. |
modules.movement.enabled | true | Collect travel distances and movement events. |
modules.production.enabled | true | Collect crafting and processing output. |
modules.interactions.enabled | true | Collect tracked player interactions. |
modules.worlds.enabled | true | Collect world-related statistics. |
modules.server_life.enabled | true | Collect playtime, AFK, community time and social activity. |
modules.vital_signs.enabled | true | Collect health, damage and healing activity. |
modules.pvp.enabled | true | Collect detailed player-versus-player combat. |
modules.achievements.enabled | true | Evaluate lifetime goals from collected statistics. |
modules.world_map.enabled | true | Build world terrain tiles and worldwide block-activity map data. |
modules.areas.enabled | true | Enable selected regions and their area statistics; separate compatibility switch from world map. |
modules.pvp.recovery_window_seconds | 20 | Window in which healing after PvP damage counts as PvP recovery. |
assets.use_minecraft_assets | false | Legal opt-in for Minecraft game assets on the website. |
assets.minecraft_version | latest_release | Minecraft asset version to request when opted in. |
companion.update_interval_ticks | 40 | How often the server sends companion HUD data. |
debug.enabled | false | Additional diagnostic logging. |
webpanel.password | empty | Dashboard password; set before public access. |
webserver.yml
| Key | Default | What it changes |
|---|---|---|
enabled | true | Run the built-in website. |
bind | 0.0.0.0 | Network interface; use 127.0.0.1 behind a local reverse proxy. |
port | 8088 | HTTP listening port. |
public_url | http://localhost:8088 | Link shown to users. Set your HTTPS public URL when proxied. |
Live signs
Place or edit an ordinary sign with exactly four lines. PlaceholderAPI is not required.
| Line | Input | Rule |
|---|---|---|
| 1 | [404Stats] | Case-insensitive header. |
| 2 | Module | Blocks, Combat/NPC, Movement, Production, Interactions, Server Life, Level. |
| 3 | Value | Use a value below. Blank or all selects the module default. |
| 4 | Target | Player name, Server (or blank) for everyone, or #1–#100 for a ranking. |
Values by module
| Module | Blank value | Accepted line-3 values |
|---|---|---|
| Blocks | total | mined, broken, placed, total |
| Combat / NPC | total | kills, deaths, total, mob_kills, npc_kills, mob_deaths, npc_deaths |
| Movement | distance | distance, walk, sprint, elytra, swim, boat, creative_fly, jumps, events |
| Production | amount | amount, actions, crafting, smelting, smithing, stonecutting |
| Interactions | actions | actions, containers, doors, entities, animals, buckets, utility, special |
| Server Life | play | play, afk, together, words, commands, joins |
| Level | xp | xp, level, survival_xp, creative_xp, progress_percent |
For Level, the Server target supports only xp and level. The other Level values require a player or rank. Signs always combine Survival and Creative. A sign's original selection survives restart, but only signs in loaded chunks refresh. With default database sync and sign refresh, allow roughly 40 seconds for a change to appear.
PlaceholderAPI
Install PlaceholderAPI alongside 404Stats. The 404stats expansion registers automatically; no separate expansion download is required. Test with /papi parse <player> %404stats_self_blocks_mined%.
%404stats_self_<module>_<metric>%%404stats_player_<name>_<module>_<metric>%%404stats_top_<module>_<metric>_<rank>%A player name may contain underscores, or use a UUID. Rank is 1–100 and each metric has its own ranking. Add an output suffix such as _formatted or _line; then optionally add _survival or _creative at the very end. The default is combined all. Level has no mode suffix because it already has separate Survival and Creative XP fields.
| Suffix | Result |
|---|---|
none / _value | Raw value for self/player; a ready-made line by default for top. |
_formatted | Readable number or unit, such as metres or duration. |
_line | Rank, player and formatted value in one display string. |
_rank | Position in this metric's ranking. |
_name / _uuid | The resolved player name or UUID. |
Structured modules and metrics
| Module | Metrics |
|---|---|
blocks | mined, placed, total |
combat | kills, deaths, total, mob_kills, npc_kills, mob_deaths, npc_deaths |
movement | distance_cm, events, walk_cm, sprint_cm, elytra_cm, swim_cm, boat_cm, creative_fly_cm, jumps |
production | amount, actions, crafting, smelting, smithing, stonecutting |
interactions | actions, containers, doors, entities, animals, buckets, utility, special |
server_life | play_seconds, afk_seconds, together_seconds, chat_words, commands, joins |
level | level, xp, total_xp, survival_xp, creative_xp, level_xp, next_level_xp, xp_to_next_level, progress_percent, progress_bar |
Raw movement distances ending in _cm are centimetres; formatted output is metres. Raw Server Life times ending in _seconds are seconds; formatted output is a duration. progress_bar produces a ten-segment colored bar. For level rankings, only xp and level are available; use xp for the XP leaderboard. Only level, xp and total_xp support self/player _rank.
Useful examples
%404stats_self_blocks_mined_rank%%404stats_top_movement_swim_cm_1_line%%404stats_player_Steve_production_crafting_formatted_creative%%404stats_self_level_progress_bar%Compatibility & utility variables
These older or standalone variables remain available, but the maker generates the structured forms for new stat displays.
| Variable or form | Result |
|---|---|
%404stats_storage_mode%, %404stats_webserver% | Storage description and webserver enabled/disabled status. |
%404stats_bossbar_enabled% | Whether this player's bossbar is enabled. |
%404stats_project_name%, %404stats_project_slug%, %404stats_project_enabled% | Current player's project fields. |
%404stats_mined%, %404stats_placed%, %404stats_total%, %404stats_rank% | Legacy block totals and rank; the current player's game mode is used when online. |
%404stats_name%, %404stats_uuid%, %404stats_line% | Legacy identity and ready-made block summary. |
%404stats_mined_player_Steve%, %404stats_player_Steve% | Legacy named-player block values and summary. |
%404stats_top_1_line%, %404stats_top_mined_1_name% | Legacy block leaderboard; defaults to Survival rather than combined mode. |
Placeholder maker
Choose a valid combination; unsupported choices disappear automatically.
Achievements
404Stats includes 133 built-in achievement cards. A five-tier goal is one card that evolves through Stone, Copper, Iron, Diamond and Emerald. Goals draw on existing module data instead of writing another copy of game statistics. Historic statistics can unlock eligible goals retroactively; a historic timestamp may be estimated and does not trigger a new chat announcement.
Create a custom achievement
- Run
/404stats webadminas an operator and open the one-use link within five minutes. - Open Achievements in the admin panel and choose Create achievement.
- Set the public title, description and fixed category. Choose player, server or both.
- Choose whether existing stored statistics count immediately. For new-only goals, progress begins after publishing.
- Select a statistic and any available detail filter, then enter one threshold or five strictly increasing tier thresholds.
- Preview the result and publish it. Test with a real event or an existing statistic that should count retroactively.
The metric picker includes blocks, combat, movement, production, interactions, activity, social time, survival and PvP, with detail filters where supported. For a one-time-style event, use an event-count metric and a threshold of 1—for example drowning damage events. A very small swim-distance threshold can represent first swimming, but it is still distance-based. Server achievements announce new unlocks to everyone; personal achievements notify the player. Contributor names appear only when attribution is reliable.
Fabric companion
The optional client mod displays configurable 404Stats HUD modules, a level XP bar, and map data from a compatible 404Stats server. It offers minimap/world map choices during onboarding and can detect supported third-party map mods. Install the matching Fabric mod in the Minecraft client's mods/ folder; it is not installed on Paper. The plugin works without it.
HUD layout, scale and visibility are client settings. Map features require the server's world_map and areas modules where appropriate. Use /404stats map share on only if you want your live position and eligible area statistics shown publicly.
Troubleshooting
A sign stays on “Loading…”
Check that its chunk is loaded, signs.enabled is true, and the metric/target is supported. Allow the database sync plus refresh interval (about 40 seconds by default). Inspect server logs if it never updates.
A placeholder is displayed literally
Confirm PlaceholderAPI is installed and the expansion registered at startup. Test with /papi parse <player> %404stats_self_blocks_mined%. Use this wiki's maker to avoid an unsupported metric or suffix.
The dashboard cannot be reached
Check webserver.yml for enabled, bind and port. Use localhost only from the server machine; use the host's reachable address or reverse proxy from other devices. Check firewall and startup logs.
My statistics have not changed yet
Statistics are batched, and some views cache short-lived query results. Wait at least the configured sync interval, then refresh. Disabled modules do not collect new events.
Can this run on Spigot?
No. The plugin targets Paper and checks for Paper APIs at startup, even though its metadata uses a Bukkit-compatible plugin.yml descriptor.