BasicStats

📊 Simple. Lightweight. Configurable.

BasicStats is a modern, standalone statistics plugin for Bukkit-compatible Minecraft Java servers. Track player activity, display meaningful statistics, compare players, build rank progression and manage everything through an optional local dashboard.

🎥 Preview the BasicStats Dashboard

🌟 Support the Project

Enjoying BasicStats? A follow on Modrinth helps the project become more visible 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 and mob kills
• Deaths and persistent death history
• Jumps, playtime and walking distance
• Blocks broken and placed
• Items crafted
• Damage dealt and damage taken
• First join date, online status and session time
• Configurable number, time and date formats

🏆 Ore-Based Rank System

• 36 rank stages based on Minecraft materials
• Stone, Coal, Copper, Iron, Gold, Redstone, Lapis, Quartz, Emerald, Diamond, Ancient Debris and Netherite
• Material-based sublevels such as blocks, raw ores and ingots
• Configurable rank factors and score targets
• Playtime, blocks, crafting, kills, distance, damage and other factors
• Rank progress and weighted factor contributions
• Players can rank up or lose rank points
• Deaths remove 50 rank points by default
• Configurable death cooldown to prevent repeated point loss
• Rank announcements for promotions and demotions
• Rank displayed in menus, profiles, displays, leaderboards and the dashboard

🎮 In-Game Interface

• Paginated inventory GUI
• Statistics overview
• Player profiles
• Player comparison
• Deathlog with causes, timestamps, coordinates and rank-point loss
• Personal goals and progress tracking
• Rank overview with all available stages
• Configurable leaderboards
• /basicstats settings for personal display preferences

📺 CraftAttack-Style Death Counter

Show 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
• Can be enabled or disabled in config.yml
• Optional rank display next to player names
• Customizable tablist header, footer and player-name format

tab:
  death-count-enabled: true
  show-rank: true

🖥️ Displays

• Sidebar scoreboard
• Actionbar
• Bossbar
• Tablist header and footer
• Optional death counter in the tablist
• Configurable layouts:
  • Default
  • Compact
  • Rank-focused
• Players can choose which display they want to use
• All display messages are fully localizable

🌐 Local Web Dashboard

BasicStats includes an optional local dashboard for server administrators.

The dashboard is disabled by default and binds to 127.0.0.1 when enabled.

It includes:

• 📊 Live server overview
• 👥 Online and tracked players
• 👤 Clickable player detail pages
• 🏆 Visual rank-system ladder
• 📈 Charts for online players, playtime, deaths and rank points
• ⏱️ 24-hour, 7-day and 30-day history
• 🥇 Leaderboards for rank, playtime, kills and deaths
• 📅 Lifetime, daily and weekly leaderboard filters
• 🎯 Goals and 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 settings for:
  • General
  • Display
  • Features
  • Ranks
  • Leaderboards
  • Backups

Administrators can enable or disable individual dashboard areas. These switches are enforced server-side and do not disable Minecraft statistics or in-game commands.

To access the dashboard, open:

BasicStats Dashboard Preview

The preview shows the planned dashboard experience without requiring a Minecraft server.

To access the local dashboard on your own server, use:

/basicstats dashboard

This creates a temporary 15-minute dashboard link and token for authorized administrators.

To disable the dashboard completely:

dashboard:
  enabled: false

When disabled, no dashboard port is opened.

🔔 Discord Notifications

BasicStats can send selected server events to a Discord channel through a standard Discord webhook.

Supported events include:

• 👋 Player joins
• 💀 Player deaths
• ⬆️ Rank-ups
• ⬇️ Rank-downs
• 🎯 Completed goals
• ✨ Newly detected goals

Discord notifications are disabled by default and can be configured individually:

notifications:
  discord:
    enabled: true
    webhook-url: "https://discord.com/api/webhooks/<id>/<token>"
    username: BasicStats
    events:
      player-join: true
      player-death: true
      rank-up: true
      rank-down: true
      goal-completed: true
      new-goal: false

Webhook messages are sent asynchronously so Discord problems cannot block the Minecraft server.

For security:

• Only official Discord webhook URLs are accepted
• Webhook URLs are never shown in the dashboard
• Webhook URLs are never written to console logs
• Discord mentions are disabled
• Temporary rate limits are retried automatically
• Treat the webhook URL like a password

🧭 Commands

• /basicstats – Show the 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 deathlog – View recent deaths
• /basicstats goals – View personal goals
• /basicstats topstats [stat] [lifetime|daily|weekly] – View leaderboards
• /basicstats settings – View personal display settings
• /basicstats display <sidebar|actionbar|bossbar|none> – Choose a display mode
• /basicstats info – Show plugin, server, Java and storage information
• /basicstats dashboard – Create a temporary dashboard link
• /basicstats dashboard token – Show the temporary dashboard token
• /basicstats reset <player> <stat|daily|weekly|all> confirm – Reset data
• /basicstats backup – Create a manual backup
• /basicstats reload – Reload configuration and messages

Legacy aliases remain available:

/stats, /uptime, /session, /deathlog, /sidebar, /playtime, /firstjoin, /online, /topstats, /daily, /weekly and /goals.

🔗 PlaceholderAPI

PlaceholderAPI is completely optional.

📊 Statistics

%basicstats_name%
%basicstats_player%
%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%

🏆 Rank

%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%
%basicstats_playtime_rank%

🎯 Other Values

%basicstats_goals_completed%
%basicstats_goals_total%
%basicstats_session%
%basicstats_uptime%
%basicstats_online%
%basicstats_display_mode%

Daily and weekly variants are also available, for example:

%basicstats_daily_blocks_placed%
%basicstats_daily_items_crafted%
%basicstats_weekly_damage_dealt%
%basicstats_weekly_playtime_hours%

⚙️ Configuration

BasicStats provides a fully configurable config.yml with support for:

• 🇬🇧 English and 🇩🇪 German localization
• Display layouts and update intervals
• Sidebar, actionbar, bossbar and tablist settings
• Personal display preferences
• Tablist death counter and rank display
• Rank factors and rank targets
• Death penalties and cooldowns
• Goals and progress tracking
• Leaderboard statistics and size
• Number, time and date formats
• Automatic rotating backups
• Manual backups
• Dashboard access and feature controls
• Dashboard history collection
• JSON and CSV exports
• Discord webhook notifications

Existing configuration values and custom translations are preserved when new options are added.

Statistics are stored locally in YAML files. BasicStats does not require an external database, telemetry service or public web server.

🔐 Permissions

Important permission nodes include:

basicstats.use
basicstats.menu
basicstats.stats
basicstats.stats.others
basicstats.compare
basicstats.profile
basicstats.rank
basicstats.info
basicstats.deathlog
basicstats.settings
basicstats.display
basicstats.topstats
basicstats.goals
basicstats.reset
basicstats.backup
basicstats.reload
basicstats.dashboard.manage

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

✅ Compatibility

• Minecraft Java Edition 1.17.1 and newer
• Spigot
• Paper
• Purpur
• Bukkit-compatible server software
• Java 17 or newer
• Bukkit API 1.17
• No NMS or version-specific internals
• PlaceholderAPI is optional

BasicStats uses one JAR across older and modern Bukkit-compatible Minecraft versions. Always test the exact server version used by your network.

ℹ️ Display Note

The small numbers shown on the right side of a Minecraft scoreboard sidebar are generated by Minecraft itself. BasicStats uses them for line ordering. They are not additional statistics and cannot be removed without breaking the sidebar ordering.

📥 Installation

1. Download the latest .jar file.
2. Put it into your server's plugins folder.
3. Start or restart the server.
4. Edit plugins/basicstatsundso/config.yml if needed.
5. Use /basicstats menu in-game.

📄 License

BasicStats is licensed under the MIT License.