Compatibility
Minecraft: Java Edition
Platforms
Tags
Creators
Details
BasicStats
📊 Simple. Lightweight. Configurable.
BasicStats is a modern, standalone Minecraft statistics plugin and Minecraft server plugin for Java servers running Paper, Spigot, Purpur or Bukkit. Track meaningful player activity, playtime, kills, deaths, blocks, crafting and survival progress; build an ore-based rank progression; compare players; display stats in-game; and manage your server through an optional local dashboard. The current 2.9.0 release adds a safe Backup Center with verified backup listings, explicit restore confirmation and an automatic safety copy before every restore while retaining consent-first public player profiles, reliable metric boards and known-player coverage.
If you are looking for a Minecraft player stats plugin, survival statistics, a playtime tracker, death counter, Minecraft leaderboard plugin, ore rank system, CraftAttack-style tablist, PlaceholderAPI statistics, a Minecraft server dashboard, Discord webhook alerts, an Aternos-friendly stats plugin or Velocity/Bungee network statistics, BasicStats combines these tools in one configurable plugin.
🇩🇪 Deutsche Kurzbeschreibung
BasicStats ist ein übersichtliches Statistik- und Rangplugin für Minecraft Java Server mit Paper, Spigot, Purpur oder Bukkit. Es bietet Spielzeit, Kills, Tode, Blöcke, Crafting, Leaderboards, ein Erz-Rangsystem, einen CraftAttack-ähnlichen Todeszähler in der Tablist, Streaks, Achievements, Dashboard, Explorer, Discord-Webhooks und optionale PlaceholderAPI-Unterstützung. Die wichtigsten Funktionen bleiben einzeln konfigurierbar und sind standardmäßig serverfreundlich eingerichtet.
🎥 Preview the BasicStats Dashboard
🌟 Support the Project
Enjoying BasicStats? A follow on Modrinth helps the project gain visibility and makes it easier for other server owners to discover.
⭐ Follow BasicStats on Modrinth
Need help, want to report a bug or suggest a feature?
💬 Join the BasicStats Community Discord
✨ Features
BasicStats is designed for survival servers, SMPs, community servers, events and networks that want useful Minecraft statistics without forcing players to learn a large command system first.
📊 Player Statistics
- Lifetime, daily and weekly statistics
- Player kills, mob kills and deaths
- Persistent death log with causes, timestamps, coordinates and rank-point loss
- Jumps, playtime, sessions and walking distance
- Blocks broken and placed
- Items crafted
- Damage dealt and damage taken
- Optional historical import of exact vanilla-backed values from before BasicStats was installed
- First join date, online status and server uptime
- Configurable number, time and date formats
- Player profiles and player comparison
🏆 Ore-Based Rank System
- 27 rank stages based on Minecraft materials
- Stone, Coal, Copper, Iron, Gold, Redstone, Lapis, Quartz, Emerald, Diamond, Ancient Debris and Netherite
- Material sublevels such as cobblestone, stone, blocks, raw ores, scraps and ingots where available
- Configurable rank factors, weights and score targets
- The
balanced-v2model combines playtime, blocks, crafting, kills, distance, damage, jumps, goals, achievements and best streak - A capped diversity bonus rewards progress across multiple activities
- Configurable milestone gates prevent one farmed statistic from carrying every major rank section
- Detailed factor contributions and progress to the next rank
- Rank-ups and rank-downs through normal progression
- Deaths remove 50 rank points by default, with configurable penalties and cooldowns
- Rank announcements and personal notification settings
- Rank shown in menus, profiles, displays, tablist, leaderboards and dashboard
- Detailed breakdown of base score, factor coverage, diversity bonus and gate limits
🎮 In-Game Interface
- Paginated inventory GUI for statistics, ranks, goals, achievements, death logs and leaderboards
- Player profiles with rank progress and achievement progress
- Player comparison with statistics and ranks
- Rank overview with all available stages and factor details
- Configurable lifetime, daily and weekly leaderboards
- Personal display settings through
/basicstats settings - Clickable commands and links in help, setup, settings, dashboard and reward messages
- Interactive setup wizard through
/basicstats setup - Setup presets for Simple, Community and Full local feature set, with every choice still adjustable before saving
- New servers receive a clear setup reminder until the wizard is completed
- Health center through
/basicstats healthwith safe checks, actionable fixes and an optional admin repair pass - Admin-only
/basicstats import vanillawith preview, confirmation, safety backup and duplicate protection
📺 CraftAttack-Style Death Counter
Display every player's death count directly in the Minecraft player list/tablist.
- Familiar survival-event style, similar to what many players know from CraftAttack
- Updates automatically when players die
- Optional rank display next to player names
- Customizable tablist header, footer and player-name format
- Can be enabled or disabled in
config.yml
tab:
death-count-enabled: true
show-rank: true
🎭 Nickname and display-name integration
BasicStats uses the Bukkit display name for visible output by default. This lets nickname plugins such as NameMask or EssentialsX integrate without creating a second identity system.
- Nicknames are reflected in menus, tablist, displays, leaderboards, event feeds and dashboard views
- UUIDs, stored statistics and command targets remain tied to the real Minecraft account
- Nickname changes refresh visible BasicStats views automatically
- Protected dashboard profiles can optionally show the real username to administrators
names:
use-display-name: true
show-real-name-in-dashboard: true
🖥️ Displays
- Sidebar scoreboard
- Actionbar
- Bossbar
- Tablist header and footer
- Optional death counter and rank in the tablist
- Configurable default, compact and rank-focused layouts
- Personal display choices for every player
- Fully localizable messages and display text
🔥 Streaks and Rewards
- Daily login streaks
- Daily playtime streaks
- Daily activity streaks
- Configurable minimum playtime required to count a day
- Current streak, best streak and progress tracking
- Configurable console-command rewards at selected streak milestones
- Personal notification controls for streaks and records
👥 Team and Clan Statistics
BasicStats does not create a competing team system. It can use existing team data instead:
- Vanilla scoreboard teams
- A registered team/clan provider from another Bukkit plugin
- Shared team or clan points, kills, deaths, playtime and rank progress
- Team placeholders and dashboard information
- Keeps another plugin as the source of truth for memberships
🌐 Velocity and Bungee Network Mode
- Optional shared network statistics for multiple backend servers
- Compatible with Velocity and Bungee-style networks
- Shared MySQL/MariaDB storage
- Unique server IDs for every backend
- Player data aggregated by UUID
- Local YAML fallback when the shared database is unavailable
🏅 Achievements and Milestones
- Configurable achievements for playtime, kills, blocks, ranks and streaks
- Custom targets, labels, descriptions and icons
- Progress tracking in-game and in the dashboard
- Optional reward messages and console commands
- Achievement placeholders
- Rewards are stored safely and are not granted twice
🗓️ Optional Seasons
Seasons give a server a clear, time-limited progression goal without changing lifetime statistics or the normal ore-based rank system.
- Separate seasonal progress calculated from a saved start baseline
- Configurable
season-pointsformula with positive or negative weights - Seasonal views for points, playtime, kills, deaths, blocks, crafting, distance, damage and jumps
- Automatic expiry and safe reset support for administrators
- Archived results from the last completed season
- Configurable console-command rewards for the top three places
%player%,%uuid%,%season%,%place%and%season_points%reward placeholders/basicstats season status,top,history,start,end confirmandreset confirm- Seasonal status and player progress in the protected Dashboard snapshot
Seasons are disabled by default. Enable them in config.yml when the server is ready to start its first season.
🌐 Local or Hosted Web Dashboard
BasicStats includes an optional dashboard for server administrators. It is disabled by default and binds to 127.0.0.1 when enabled, so local access stays private by default. Hosted servers can expose it when their provider assigns an additional web port.
The dashboard includes:
- 📊 Live server overview
- 👥 Online and tracked players
- 👤 Clickable player detail pages
- 🏆 Visual rank-system ladder with materials, factors and progress
- 📈 Trend charts for online players, playtime, deaths and rank points
- ⏱️ 24-hour, 7-day and 30-day history views
- 🥇 Leaderboards filtered by rank, playtime, kills, deaths and period
- 🎯 Goals and progress
- 🏅 Achievements and milestone progress
- 💀 Deathlog
- 📰 Live server event feed
- 📦 Peak players, active sessions and backup information
- 💾 Local storage and database status
- 📤 JSON and CSV report exports
- ❓ Built-in help page with community Discord link
- ⚙️ Grouped administrator settings
Dashboard sections can be enabled or disabled individually by an administrator. These switches affect the dashboard only and do not remove Minecraft statistics or in-game commands.
The dashboard is split into focused pages instead of one overloaded screen:
- Dashboard: live server status, player count, total players, average playtime, uptime, peak players today, active sessions, latest/next backup and storage health
- Players: searchable player list and clickable detail pages with statistics, rank progress, goals, achievements, death history and comparison
- Leaderboards: Rank, Playtime, Kills or Deaths with Lifetime, Daily or Weekly filters
- Ranks: every ore/material stage as a visual ladder, weighted factors and progress to the next stage
- Goals, Achievements and Deathlog: progress, unlock state and recent deaths including rank-point loss
- Event Feed: joins, deaths, rank changes, goals, achievements, records and streak events
- Help and Settings: setup guidance, Discord support link, grouped controls and protected Discord webhook settings
Trend history is stored locally in dashboard-history.yml and can be sampled for 24 hours, 7 days or 30 days. JSON and CSV exports are protected by the temporary administrator session. Saving settings keeps that session active while the dashboard reconnects after a safe plugin reload.
To create a temporary administrator link, use:
/basicstats dashboard
The link and token are temporary and require the appropriate administrator permission. The dashboard can also be disabled completely:
dashboard:
enabled: false
When disabled, BasicStats does not open a dashboard port.
🌍 Hosted-server setup
The plugin cannot create a port that your hoster does not provide. If your host offers an additional TCP/web port, use the normal server address and assigned port directly:
dashboard:
enabled: true
bind-address: 0.0.0.0
port: 8765 # replace with the port assigned by your hoster
public-url: ""
For example, run /basicstats dashboard setup hosted BasicStats.enderman.cloud 33416. BasicStats creates the HTTP browser link automatically, so you do not need to type http:// or https://. Use HTTPS only when a reverse proxy provides it. If a shared host does not allow extra web ports or reverse proxies, the embedded dashboard cannot be reached from outside that host and must remain disabled.
⚙️ Dashboard Admin Settings
The protected Settings area groups server controls into General, Display, Features, Discord, Ranks, Leaderboards and Backups.
- Save settings without losing the administrator session
- Automatic browser reconnect after a safe plugin reload
- Server-side validation for protected settings
- Dashboard access and feature switches
- Display and leaderboard defaults
- Backup and history controls
- Discord webhook routing and event filters
- Hosted dashboard URL and remote-access guidance
🧭 Public Explorer Push
BasicStats 2.9.0 includes the recommended hoster-friendly integration for the BasicStats Explorer. Explorer Push is disabled by default and sends one small public snapshot through an outgoing HTTPS request. The configured minimum is 15 minutes, but Cloudflare Free quota protection spaces regular uploads to about 55 minutes or more. It never opens a Minecraft HTTP port, needs no reverse proxy and requires no TLS certificate on the server.
That makes it suitable for shared hosts such as FreeMCServer, Artisan-style hoster platforms and similar shared environments when outgoing HTTPS requests are allowed. Aternos does not need an extra port for this mode, but BasicStats still has to be available as an installable plugin.
explorer-push:
enabled: false
endpoint: "https://basicstats-explorer.pages.dev/api/publish/v1/summary"
public-address: "play.example.net:25565"
interval-seconds: 900
expose-player-names: true
expose-player-profiles: true
expose-player-heads: true
player-limit: 20
expose-recent-events: true
leaderboard-limit: 20
event-limit: 20
world-description: "A public Minecraft world."
Pair a server once with:
- Enable
explorer-push.enabledand setpublic-address. - Restart or reload BasicStats.
- Run
/basicstats explorer claimas an OP withbasicstats.explorer. - Open the one-time link and confirm the address.
- Check
/basicstats explorer statusfor pairing and upload diagnostics.
For troubleshooting, use /basicstats explorer diagnose. The safe self-test checks the local configuration, pairing state, snapshot size, daily quota and last upload result. When Explorer Push is enabled, it also probes the HTTPS endpoint without authentication. It never publishes a snapshot, consumes upload quota or displays secrets.
Player names are anonymous by default. When the privacy consent setting is active, each player receives a clickable one-time question. Use /basicstats explorer privacy to view the decision, /basicstats explorer privacy yes|no to change it and /basicstats explorer privacy reset to be asked again. An unanswered prompt becomes anonymous automatically. Admins with basicstats.explorer can inspect or reset another player with /basicstats explorer privacy <player> or /basicstats explorer privacy reset <player>. A public name is used only when both explicit consent and expose-player-names: true are present; otherwise the Explorer uses Player 1, Player 2, etc.
The consent defaults are privacy-first and can be adjusted by the server administrator:
privacy:
explorer-name-consent:
enabled: true
ask-on-first-join: true
default: false
timeout-seconds: 60
The Explorer stores only the newest snapshot per server in Cloudflare D1. It never receives UUIDs, IPs, coordinates, chat, dashboard tokens, admin tokens, secrets or private player data. When enabled, it can show bounded anonymous-or-consented player profiles with rank progress, deaths, kills, playtime, walked blocks, blocks, crafting, damage, Totems Used, achievements, goals and streaks. Names and optional mc-heads.net heads require explicit consent and the matching administrator switches; expose-player-profiles: false removes the profile grid while aggregate data remains available. Advanced K/D, deaths, playtime and blocks boards are opt-in and K/D uses player kills and deaths only. Snapshots expire after three hours without a successful upload; the free setup accepts at most 26 uploads per server and UTC day. Read the privacy explanation before enabling public profiles.
The old public-web-api remains available as an optional legacy/self-hosting feature, but it is no longer the standard Explorer path:
public-web-api:
enabled: false
bind-host: "127.0.0.1"
port: 8081
public-address: ""
allowed-origins:
- "https://basicstats-explorer.pages.dev"
expose-player-names: true
expose-recent-events: true
leaderboard-limit: 20
event-limit: 20
cache-seconds: 30
world-description: "A public Minecraft world."
The legacy endpoint is /basicstats/public/v1/summary. For self-hosting, an administrator must route the local API through HTTPS/443 with a reverse proxy or Cloudflare Tunnel. BasicStats does not provide TLS termination itself:
https://play.example.net/basicstats/public/v1/summary
Only aggregated totals, the configurable rank leaderboard and selected coordinate-free events are exposed. UUIDs, IP addresses, coordinates, inventories, chat, internal diagnostics and secrets are never returned. Validate the legacy route with curl -i https://<host>/basicstats/public/v1/summary; disable it with public-web-api.enabled: false when it is not needed.
🔔 Discord Notifications
BasicStats can send selected server events to Discord through standard Discord webhooks. Notifications are disabled by default and are delivered asynchronously.
The dashboard supports a legacy Default webhook plus separate targets for:
- 👥 Players
- 🏆 Ranks
- 🎯 Goals and Achievements
- 🔥 Streaks and Records
Each target has its own enabled state, webhook URL and event filters. Supported events include:
- 👋 Player joins
- 💀 Player deaths
- ⬆️ Rank-ups
- ⬇️ Rank-downs
- 🎯 Completed goals
- 🆕 Newly detected goals
- ✨ Achievement unlocks
- 🥇 New records
- 🔥 Long streaks
Webhook URLs are entered in the protected Dashboard Settings → Discord area. Saved URLs are never returned in settings responses or written to console logs. Only official Discord webhook hosts are accepted, mentions are disabled, and temporary rate limits are retried with bounded delays.
🧭 Commands
/basicstats– Show the interactive help menu/basicstats menu– Open the inventory GUI/basicstats stats [player]– View statistics/basicstats compare <player>– Compare statistics and ranks/basicstats profile [player]– View a player profile/basicstats rank [player]– View rank progress/basicstats rank list– View all rank stages/basicstats rank details– View rank-factor contributions/basicstats streak [player]– View the current and best streak/basicstats team [player]– View team or clan statistics/basicstats network– Show network synchronization status/basicstats season status– Show the active season and remaining time/basicstats season top [stat]– View the seasonal leaderboard/basicstats season history– View the last archived season results/basicstats season start <name> <days>– Start a season (operator)/basicstats season end confirm– End the active season and process rewards (operator)/basicstats season reset confirm– Reset seasonal progress without changing lifetime data (operator)/basicstats deathlog– View recent deaths/basicstats goals– View personal goals/basicstats achievements [player]– View achievement progress/basicstats topstats [stat] [lifetime|daily|weekly]– View configurable leaderboards/basicstats top [stat] [lifetime|daily|weekly]– Short alias fortopstats/basicstats daily– View today's statistics/basicstats weekly– View this week's statistics/basicstats settings– View personal display settings/basicstats settings toggle– Toggle your display/basicstats settings display <sidebar|actionbar|bossbar|none>– Choose a display mode/basicstats settings layout <layout>– Choose a configured layout/basicstats settings notifications [type] [on|off|toggle]– Manage personal notifications/basicstats display <sidebar|actionbar|bossbar|none>– Choose a display mode/basicstats playtime [player]– View playtime/basicstats firstjoin [player]– View first join date/basicstats online– List online players/basicstats uptime– View server uptime/basicstats session– View your current session/basicstats setup– Configure server defaults through the setup wizard (operator)/basicstats info– Show plugin, server, Java and storage information/basicstats debug– Show safe support diagnostics/basicstats health– Run the health center with repair guidance/basicstats health fix– Reapply missing defaults and config validation without changing player data (operator)/basicstats dashboard– Create a temporary dashboard link/basicstats dashboard setup <local|hosted> [address] [port]– Configure dashboard access/basicstats dashboard token– Show the temporary dashboard token directly/basicstats explorer claim– Open the one-time public Explorer pairing link (operator)/basicstats explorer status– Show safe Explorer push status and upload timing/basicstats explorer diagnose– Run a safe Explorer self-test without publishing a snapshot/basicstats explorer privacy [yes|no|reset]– Manage your Explorer name consent/basicstats explorer privacy <player>– Inspect a player's consent (admin)/basicstats explorer privacy reset <player>– Reset a player's consent (admin)/basicstats import vanilla [player] [confirm]– Preview or import historical vanilla statistics (operator)/basicstats reset <player> <stat|daily|weekly|all> confirm– Reset data/basicstats backup– Create a manual backup/basicstats backup list– List verified local backups/basicstats backup restore <file> confirm– Restore a backup after creating a safety copy (operator)/basicstats reload– Reload configuration and messages
The root command also accepts the aliases /bs and /bstats. Legacy commands such as /stats, /uptime, /session, /deathlog, /sidebar, /playtime, /firstjoin, /online, /topstats, /daily, /weekly, /goals and /achievements remain available.
🔗 PlaceholderAPI
PlaceholderAPI is completely optional. The expansion is registered automatically when PlaceholderAPI is installed.
Core and identity placeholders:
%basicstats_deaths% · %basicstats_player_kills% · %basicstats_mob_kills% · %basicstats_jumps%
%basicstats_walked_km% · %basicstats_playtime_hours% · %basicstats_blocks_broken% · %basicstats_blocks_placed%
%basicstats_items_crafted% · %basicstats_damage_dealt% · %basicstats_damage_taken%
%basicstats_display_name% · %basicstats_username% · %basicstats_real_name%
%basicstats_session% · %basicstats_uptime% · %basicstats_online% · %basicstats_playtime_rank% · %basicstats_display_mode%
Rank placeholders:
%basicstats_rank% · %basicstats_rank_next% · %basicstats_rank_max% · %basicstats_rank_score%
%basicstats_rank_progress% · %basicstats_rank_points_to_next% · %basicstats_rank_activity_score% · %basicstats_rank_death_penalty%
Progress placeholders:
%basicstats_goals_completed% · %basicstats_goals_total% · %basicstats_achievements_completed% · %basicstats_achievements_total%
%basicstats_streak% · %basicstats_best_streak% · %basicstats_streak_progress%
Season placeholders:
%basicstats_season_active% · %basicstats_season_name% · %basicstats_season_points% · %basicstats_season_days_remaining%
Team placeholders:
%basicstats_team% · %basicstats_team_members% · %basicstats_team_playtime_hours% · %basicstats_team_player_kills%
%basicstats_team_deaths% · %basicstats_team_rank_points%
Every core statistic also has a daily and weekly variant, for example %basicstats_daily_blocks_placed%, %basicstats_weekly_items_crafted%, %basicstats_daily_damage_taken% and %basicstats_weekly_playtime_hours%.
⚙️ Configuration and Storage
The generated config.yml supports:
- 🇬🇧 English and 🇩🇪 German localization
- First-run setup state and guided setup defaults
- Setup presets for simple, community and full local installations
- Health-center checks and safe configuration repair through
/basicstats health - Display layouts and update intervals
- Sidebar, actionbar, bossbar and tablist settings
- Nickname/display-name usage and protected real-username visibility
- Personal display and notification preferences
- Rank factors, targets and death penalties
- Goals, achievements and rewards
- Optional seasons, seasonal point weights, leaderboards and end-of-season rewards
- Leaderboard statistics and sizes
- Number, time and date formats
- Automatic rotating and manual backups
- Verified backup listing and safe restore with an automatic pre-restore safety copy
- Dashboard access, history and feature controls
- Discord webhook routing and event filters
- Streak rules and minimum daily playtime
- Team provider selection
- Velocity/Bungee network settings
- Explorer Push endpoint, pairing state and privacy consent
- Optional legacy public API settings
Existing configuration values and custom translations are preserved when new options are added. Data is stored locally in YAML files in standalone mode. Saves use temporary files and replacement steps, and damaged data can be recovered from valid backups.
On a new server, an operator receives a clickable setup reminder until /basicstats setup is completed. The wizard covers language, default display, core features and optional integrations, and can be reopened later without deleting player data. Set dashboard.enabled: false or explorer-push.enabled: false to keep those network-facing features disabled.
🔐 Permissions
Important permission nodes include:
basicstats.use · basicstats.menu · basicstats.stats · basicstats.stats.others
basicstats.compare · basicstats.profile · basicstats.rank · basicstats.streak
basicstats.team · basicstats.network · basicstats.achievements · basicstats.info
basicstats.debug · basicstats.health · basicstats.deathlog · basicstats.display · basicstats.settings
basicstats.setup · basicstats.topstats · basicstats.goals · basicstats.reset
basicstats.backup · basicstats.backup.restore · basicstats.import · basicstats.reload · basicstats.explorer
basicstats.dashboard.manage · basicstats.season · basicstats.season.admin
Viewing personal statistics and display settings is available to everyone by default. Setup, import, reset, backup, backup restore, reload and dashboard administration are operator-protected. Restores accept only verified BasicStats backup filenames and require an explicit confirm argument; a fresh safety backup is created before replacement.
Historical data import
Minecraft keeps many lifetime statistics in its own per-player statistics files. BasicStats already reads the vanilla values for deaths, kills, jumps, walking distance and playtime. For plugin-owned counters that can be recovered exactly, an operator can run /basicstats import vanilla to preview the available history and then confirm it. The importer never merges into an existing non-zero BasicStats counter, so it cannot silently double-count data. A detailed deathlog, block placements and historical timestamps are not available from the vanilla statistics API and are therefore not invented.
✅ Compatibility
- Minecraft Java Edition 1.17.1 and newer
- Spigot, Paper, Purpur and Bukkit-compatible servers
- Java 17 or newer
- Bukkit API baseline 1.17
- No NMS or version-specific internals
- PlaceholderAPI is optional
- One JAR for supported server versions
Always test the exact server version used by your network.
📥 Installation
- Download the latest
.jarfile. - Put it into your server's
pluginsfolder. - Start or restart the server.
- Run
/basicstats setupand save the guided setup. - Use
/basicstats menuin-game.
The small numbers shown on the right side of a Minecraft scoreboard sidebar are generated by Minecraft itself and are used for line ordering.
📄 License
BasicStats is licensed under the MIT License.


