Server Stats

Server Stats

The server stats feature maintains a live-updating embed in a Discord channel showing your Minecraft server's current status — players online, TPS, memory usage, and more.

---

How It Works

1. On startup, the plugin posts a stats embed in the configured Discord channel.
2. A scheduled task updates the embed at the configured interval.
3. If the embed message is deleted, the plugin automatically reposts it.
4. On server shutdown, the embed updates to show the server as offline.

---

Configuration

Server stats settings live in config.yml:

server-stats:
  enabled: true
  channel-id: "DISCORD_CHANNEL_ID"
  update-interval: 60          # Seconds between embed updates

  embed:
    title: "%server_name% — Live Stats"
    color-online: "#57F287"    # Green when server is running
    color-offline: "#ED4245"   # Red when server is offline
    thumbnail: ""              # URL to a server logo image (optional)

    fields:
      - name: "Players"
        value: "%online_players% / %max_players%"
        inline: true
      - name: "TPS"
        value: "%server_tps%"
        inline: true
      - name: "MSPT"
        value: "%server_mspt% ms"
        inline: true
      - name: "Uptime"
        value: "%server_uptime%"
        inline: true
      - name: "Memory"
        value: "%server_ram_used% / %server_ram_max% MB"
        inline: true
      - name: "Version"
        value: "%server_version%"
        inline: true

    footer:
      text: "Last updated"
      show-timestamp: true     # Adds a Discord timestamp to the footer

---

Available Placeholders

Placeholder	Description	Example
%server_name%	Server name from config	Survival
%online_players%	Current player count	42
%max_players%	Server max players	100
%server_tps%	Current TPS (1-minute average)	19.98
%server_mspt%	Milliseconds per tick	2.4
%server_uptime%	Time since server started	3h 12m
%server_ram_used%	JVM memory currently in use (MB)	2048
%server_ram_max%	JVM max memory (MB)	8192
%server_version%	Minecraft / Paper version	Paper 1.21.4

---

TPS Colour Coding

The embed automatically adjusts the TPS field colour based on performance:

TPS Range	Colour	Meaning
18.0 – 20.0	Green	Healthy
15.0 – 17.9	Yellow	Slightly degraded
Below 15.0	Red	Performance issues

Note: TPS colouring is applied inside the field value using Discord formatting (e.g., bold text or emoji indicators) rather than changing the embed accent colour.

---

Channel Setup

1. Create a dedicated read-only channel (recommended name: #server-status).
2. Deny Send Messages for @everyone so users cannot clutter it.
3. Set the channel-id in config.
4. The plugin will post and manage the embed automatically.

---

Offline Status

When the server is shut down gracefully, the embed updates one final time to show:

• Embed colour changes to color-offline (red)
• Player count shows 0 / max
• TPS shows —
• A "Server Offline" indicator is shown

This gives Discord users a clear visual signal that the server is down.