ServerWrapped

ServerWrapped is a lightweight Paper plugin that turns Minecraft server statistics into funny, shareable, Spotify Wrapped-style recaps.

Your players already make memories. ServerWrapped turns them into shareable season recaps.

Features

• Personal recap cards with /wrapped, framed with hover details and clickable share/book buttons
• Flip-through book recap with /wrapped book, including adventure, odd-jobs, and achievements pages
• Public compact recap sharing with /wrapped share
• Dramatic slideshow reveal with /wrapped reveal: one stat every few seconds with sounds, a cliffhanger, and a full-screen archetype reveal
• Head-to-head comparisons with /wrapped compare <player>: nine categories, winners marked, verdict line
• Server milestone broadcasts ("This server just mined its 1,000,000th block!") in-game and to Discord, following a 1/2.5/5 ladder with silent baselining on install
• Spotify-style server ranks: "You're in the top 5% of miners on this server"
• "Copy for Discord" button that puts a ready-to-paste emoji recap on the clipboard
• Discord webhook integration (no bot needed): /wrapped share posts a rendered PNG image card (player head, stat grid, top-percent badge, archetype-colored design) with automatic text-embed fallback; season end posts the server-wide recap
• Server-wide recap with /wrapped server: combined playtime, blocks, deaths, most active player, and more
• Wrapped Day: ending a season freezes everyone's final stats, announces the drop to all players, and lets everyone view their final recap with /wrapped recap (with a one-time join reminder) for a configurable window
• Configurable share cooldowns
• Roast comments that scale with roast-mode.intensity
• Season baselines for monthly or SMP-season recaps
• ~30 unlockable achievements (Diamond Hands, Ace Pilot, Creeper Magnet, Untouchable, ...) shown on the card and in the book
• 17 player archetypes with per-player rotating recap titles
• 14 leaderboard categories: deaths, playtime, mined, placed, kills, distance, damage taken, damage dealt, elytra distance, fish caught, animals bred, villager trades, jumps, and totem uses
• Death reason tracking with killer mob/projectile context where available
• Totem use tracking
• Distance breakdowns across walking, sprinting, swimming, elytra, boats, horses, and minecarts
• Write-behind player data cache with periodic async saves, so events never block on disk I/O
• Offline stats cache so recaps and leaderboards for offline players never trigger expensive stat scans
• Configurable leaderboard result caching
• YAML config and data storage in the plugin data folder
• No database, NMS, packet libraries, or external runtime dependencies

Requirements

• Java 26
• Paper API 26.2 compatible server
• Gradle 9.4 or newer for building

Build

./gradlew build

The plugin jar is produced in:

build/libs/ServerWrapped-1.1.jar

If your checkout only has Gradle wrapper metadata, install Gradle locally or regenerate the wrapper scripts before using ./gradlew.

Commands

Command	Description	Permission
/wrapped	Shows your personal wrapped card.	serverwrapped.use
/wrapped book	Opens your wrapped as a flip-through book.	serverwrapped.use
/wrapped share	Posts a compact recap to public chat.	serverwrapped.share
/wrapped reveal	Plays your recap as a dramatic slideshow.	serverwrapped.use
/wrapped compare <player> [player]	Head-to-head comparison (one name: against yourself).	serverwrapped.compare
/wrapped top <category>	Shows a leaderboard for a supported category.	serverwrapped.top
/wrapped server	Shows the server-wide recap.	serverwrapped.top
/wrapped recap	Shows your final recap of the last ended season.	serverwrapped.use
/wrapped <player>	Shows another player's recap.	serverwrapped.view.other
/wrapped season	Shows current season state.	serverwrapped.admin
/wrapped season start <id> <displayName...>	Starts a new season and saves baseline snapshots.	serverwrapped.admin
/wrapped season end	Ends the active season.	serverwrapped.admin
/wrapped reload	Reloads config.	serverwrapped.admin
/wrapped help	Lists available subcommands.	none

Supported leaderboard categories:

deaths
playtime
mined
placed
kills
distance
damage_taken
damage_dealt
elytra
fish
bred
trades
jumps
totems

Aliases include death, time, mine, place, kill, walk, damage, dealt, fly, fishing, breeding, trading, jump, and totem.

Permissions

serverwrapped.use:
  default: true
serverwrapped.share:
  default: true
serverwrapped.compare:
  default: true
serverwrapped.top:
  default: true
serverwrapped.view.other:
  default: op
serverwrapped.admin:
  default: op

Configuration

Default config.yml:

prefix: "<gold><bold>ServerWrapped</bold></gold> <dark_gray>></dark_gray> "
season-mode: false
current-season-id: ""
last-ended-season-id: ""
leaderboard-size: 5

# Shown in share texts and Discord embeds ("Top 5% miner on <server-name>").
# Leave empty for "this server".
server-name: ""

# How long computed leaderboards are cached before being recalculated (seconds).
leaderboard-cache-seconds: 30

# How often the stats of online players are written to the offline cache (minutes).
stats-cache-refresh-minutes: 5

share:
  enabled: true
  cooldown-seconds: 60

# Spotify-style server ranks ("Top 5% miner") on cards and share texts.
percentiles:
  enabled: true

# After a season ends, players can still view their final recap with /wrapped recap
# for this many days, and get a one-time reminder on join.
recap:
  window-days: 7
  join-reminder: true

# Post wrapped cards to Discord via a channel webhook (no bot needed).
# Create one in Discord: Channel Settings > Integrations > Webhooks.
discord:
  webhook-url: ""
  share-to-discord: true      # /wrapped share also posts an embed to Discord
  post-season-recap: true     # season end posts the server-wide recap
  avatar-thumbnails: true     # show the player's head (via mc-heads.net) in embeds
  image-cards: true           # render shares as PNG image cards (falls back to text embeds on failure)
  post-milestones: true       # server milestones are also posted to the webhook

# Broadcast a celebration when the server crosses big round totals,
# e.g. "The server just mined its 1,000,000th block!"
milestones:
  enabled: true
  check-minutes: 10

roast-mode:
  enabled: true
  intensity: 2

Settings:

• prefix: MiniMessage prefix used for plugin chat messages.
• season-mode: Whether wrapped cards should use the active season baseline.
• current-season-id: Internal ID of the active season.
• last-ended-season-id: Set automatically when a season ends; drives /wrapped recap.
• leaderboard-size: Number of players shown in /wrapped top.
• server-name: Server name used in share texts and Discord embeds.
• leaderboard-cache-seconds: How long leaderboard results and the percentile distribution are cached (0 disables caching).
• stats-cache-refresh-minutes: How often online players' stats are persisted for offline lookups.
• share.enabled: Enables or disables /wrapped share.
• share.cooldown-seconds: Per-player share cooldown.
• percentiles.enabled: Enables the "top X%" server ranks (needs at least 3 known players).
• recap.window-days: How long /wrapped recap stays available after a season ends.
• recap.join-reminder: One-time clickable reminder on join while a recap is available.
• discord.webhook-url: Discord channel webhook URL; leave empty to disable Discord posting.
• discord.share-to-discord: Whether /wrapped share also posts an embed to Discord.
• discord.post-season-recap: Whether ending a season posts the server recap to Discord.
• discord.avatar-thumbnails: Whether embeds show the player's head via mc-heads.net.
• discord.image-cards: Whether shares are posted as rendered PNG image cards instead of text embeds.
• discord.post-milestones: Whether server milestones are also posted to the webhook.
• milestones.enabled: Enables server milestone broadcasts.
• milestones.check-minutes: How often server totals are checked for freshly crossed milestones.
• roast-mode.enabled: Enables funny recap comments.
• roast-mode.intensity: How savage the death comments get, from 0 (off) to 5 (merciless).

Use /wrapped reload after editing the config.

Data Storage

ServerWrapped stores YAML files in the plugin data folder:

plugins/ServerWrapped/
  config.yml
  milestones.yml
  players/
    <uuid>.yml
  seasons/
    <season-id>.yml

Player files contain last known identity, death reason counts, custom stats such as totem uses, season snapshots, and a stats cache used to serve recaps and leaderboards for offline players. Season snapshots include Bukkit statistics plus plugin-tracked death reason and totem baselines. Season files contain display names and start/end timestamps.

Player data is held in an in-memory write-behind cache and flushed to disk asynchronously every 20 seconds, on player quit, and on plugin shutdown.

Example Output

The in-game card is a framed, hoverable chat card (hover a line for extra detail, click the footer buttons to share or open the book version):

────────────────────────────────────────────────────────
✦ NICO'S SERVER WRAPPED ✦
Season: June 2026
────────────────────────────────────────────────────────
▸ You played for 42.3 hours.
▸ You mined 12,442 blocks, mostly Stone.
▸ You placed 8,901 blocks.
▸ You traveled 118.4 km.
▸ You defeated 312 mobs, mostly Zombie.
▸ You died 37 times. The respawn screen knows you personally.
▸ Totems saved you 3 times.
▸ Your natural predator was: Entity Attack Creeper.
▸ You're in the top 5% of miners on this server.
▸ You unlocked 6 achievements. (hover)
▸ Your personality type: Cave Goblin.
▸ Your server title: Minister of Questionable Mining Decisions.
────────────────────────────────────────────────────────
[ ✦ Share in Chat ]   [ Open as Book ]   [ Copy for Discord ]   [ ▶ Play Reveal ]

The "Copy for Discord" button copies a ready-to-paste emoji card:

✨ Nico's June 2026 Wrapped ✨
⏰ 42 hours played
⛏️ 12,442 blocks mined (mostly Stone)
💀 37 deaths — natural predator: Entity Attack Creeper
🎖️ 6 achievements unlocked
📊 Top 5% miner on this server
🏆 Cave Goblin — "Minister of Questionable Mining Decisions"

/wrapped book gives the same recap as an in-game written book with one theme per page for a slide-like flip-through experience, including pages for adventure stats, odd jobs, and unlocked achievements.

Compact share:

Nico's June 2026 Wrapped: 42h played | 12.4k mined | 37 deaths | 6 achievements | Cave Goblin