BasicStats

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. The current 2.6.0 release also brings consent-first public player profiles to the hoster-friendly BasicStats Explorer.

🚀 In 30 Seconds

1. Download the plugin.
2. Put it into your server's plugins folder.
3. Run /basicstats setup as an operator.
4. Open the menu with /basicstats menu.
   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
• The balanced-v2 model 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
• 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 Features

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 & 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

🌐 Network Support (Velocity/Bungee)

• 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 & 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

🖥️ Dashboard & Explorer

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.6.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:

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 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 Integration

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.

❓ FAQ

Does it require a database?

No. Standalone mode stores data locally in YAML files and does not require an external database, telemetry service or web service. Velocity/Bungee network mode can optionally use shared MySQL/MariaDB storage.

Does it work on Aternos?

BasicStats can work on Aternos when the plugin is available in the Aternos plugin library and the selected server software is supported. Explorer Push does not require an additional public port, but outgoing HTTPS requests must be allowed by the host.

Is PlaceholderAPI required?

No. PlaceholderAPI is completely optional. BasicStats works without it and registers its expansion automatically when PlaceholderAPI is installed.

Can existing vanilla statistics be imported?

Yes. An operator can preview and confirm /basicstats import vanilla. Exact vanilla-backed values such as deaths, kills, jumps, walking distance and playtime can be imported without silently double-counting existing plugin data.

Does the dashboard open a port?

Only when the dashboard is enabled. It is disabled by default and binds locally by default. A hosted dashboard needs a web/TCP port provided by the hoster. Explorer Push is separate and sends outbound HTTPS snapshots without opening a port.

Is player data public by default?

No. The dashboard and Explorer Push are disabled by default. Explorer names are anonymous by default and become public only when Explorer Push is enabled, the server is paired and the individual player has explicitly consented.

⚠️ Limitations & Honest Notes

• A directly hosted dashboard needs an available web/TCP port from the hoster. BasicStats cannot create a public port that the host does not provide.
• Explorer Push is disabled by default and requires the server administrator to enable and pair it once.
• Historical block-placement data cannot be recovered from Minecraft's vanilla statistics files.
• Historical death locations, detailed death-log entries and historical timestamps are not available from the vanilla statistics API and are not invented by the importer.
• Always test the exact Minecraft version and server software used by your network before deploying to production.

🧭 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