BasicStats

📊 Simple. Lightweight. Configurable.

BasicStats is a modern, standalone statistics plugin for Minecraft Java servers. Track meaningful player activity, build an ore-based rank progression, compare players, display survival stats in-game and manage your server through an optional local dashboard.

🎥 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

📊 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
• Progress based on playtime, blocks, crafting, kills, distance, damage and other statistics
• 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

🎮 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
• New servers receive a clear setup reminder until the wizard is completed
• Admin-only /basicstats import vanilla with 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

🌐 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.4.3 includes the recommended hoster-friendly integration for the BasicStats Explorer. Explorer Push is disabled by default and sends one small public snapshot every 15 minutes through an outgoing HTTPS request. 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 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-recent-events: true
  leaderboard-limit: 20
  event-limit: 20
  world-description: "A public Minecraft world."

Pair a server once with:

1. Enable explorer-push.enabled and set public-address.
2. Restart or reload BasicStats.
3. Run /basicstats explorer claim as an OP with basicstats.explorer.
4. Open the one-time link and confirm the address.
5. Check /basicstats explorer status for pairing and upload diagnostics.

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, skins or player heads. 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.

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 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 for topstats
• /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 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 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 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%

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
• 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
• Leaderboard statistics and sizes
• Number, time and date formats
• Automatic rotating and manual backups
• 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.deathlog · basicstats.display · basicstats.settings
basicstats.setup · basicstats.topstats · basicstats.goals · basicstats.reset
basicstats.backup · basicstats.import · basicstats.reload · basicstats.explorer
basicstats.dashboard.manage

Viewing personal statistics and display settings is available to everyone by default. Setup, import, reset, backup, reload and dashboard administration are operator-protected.

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

1. Download the latest .jar file.
2. Put it into your server's plugins folder.
3. Start or restart the server.
4. Run /basicstats setup and save the guided setup.
5. Use /basicstats menu in-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.