✦ ServerWrapped ✦

What is ServerWrapped?

ServerWrapped is a lightweight Paper plugin that turns the statistics your server already collects into funny, personal, shareable recaps — like Spotify Wrapped, but for your SMP. Every player can run /wrapped and instantly get a framed chat card with their playtime, mining stats, deaths, a personality archetype, a generated title, unlocked achievements, and a "top X% on this server" rank.

It needs no database, no bot, no other plugins, and no client mods. Everything works out of the box; Discord posting is a single config line.

Quick start for server owners

1. Download the jar and drop it into your server's plugins/ folder.
2. Restart the server. The data folder and config.yml are created automatically.
3. Done — players can use /wrapped immediately (lifetime stats).

Two optional upgrades:

• Seasons: run /wrapped season start june-2026 June 2026 so recaps cover only the current season/month. See the seasons guide.
• Discord: paste a channel webhook URL into config.yml so shares and season recaps get posted automatically. See Discord integration.

Requirements: Paper 26.2 or compatible Java 26 No dependencies

Your Wrapped card Players

Run /wrapped to see your personal card. Every line describes one part of your journey during the current season (or your whole lifetime on the server, if no season is active). Hover over the lines — many of them hide extra details:

The footer has three clickable buttons: [ ✦ Share in Chat ] posts a compact recap publicly, [ Open as Book ] opens the book version, and [ Copy for Discord ] copies an emoji share card to your clipboard.

The book version Players

/wrapped book opens your recap as a written book — one theme per page, like flipping through Wrapped stories:

1. Title page — your name and the season
2. Time played — hours and days of your life
3. Mining & building — mined/placed totals, top block, diamond ore
4. Adventure — travel distance breakdown and jumps
5. Survival — deaths, natural predator, mob kills, totems
6. Odd jobs — fishing, breeding, trading, enchanting, raids, sleep
7. Achievements — up to 8 unlocked achievements
8. Your type — archetype and server title
9. Outro — that's a wrap!

The reveal show Players

/wrapped reveal plays your recap as a dramatic slideshow instead of showing everything at once — the same suspense as Spotify's Wrapped stories. One stat appears every few seconds with a sound effect, the death line lands with an anvil clang, and after a cliffhanger ("And your personality type this season is…") your archetype is revealed with a full-screen title and the challenge-complete fanfare.

The whole show takes about 20 seconds and ends with the usual share buttons. You can also start it from the [ ▶ Play Reveal ] button on your card. It's the perfect way to experience Wrapped Day together in a voice call — everyone runs it at the same time and reacts to their reveals live.

Sharing your Wrapped Players

In-game: /wrapped share

Posts a one-line compact recap to public chat, visible to everyone online:

Justin's June 2026 Wrapped: 42h played | 12.4k mined | 37 deaths | 6 achievements | top 5% miner | Cave Goblin

There is a per-player cooldown (60 seconds by default) so chat doesn't get flooded. If the server has Discord integration enabled, your share is also posted to the server's Discord channel as a rich embed with your player head.

Anywhere else: the "Copy for Discord" button

Click [ Copy for Discord ] on your card and a full emoji version is placed on your clipboard — paste it into Discord, WhatsApp, or anywhere else:

✨ Justin'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"

Head-to-head compare Players

/wrapped compare <player> puts your wrapped next to another player's, category by category: playtime, blocks mined and placed, distance, mob kills, fish, totem saves, achievements, and deaths (where fewer wins). The better value in each row is highlighted with a gold ✦, and a verdict line declares the overall winner:

During a season the comparison uses season stats, so a rematch next season starts from zero. From console (or to compare two other players) use /wrapped compare <player> <player>. Categories neither player has touched count for nobody.

Server ranks — "top X%" Players

Just like Spotify's "top 0.05% of listeners", ServerWrapped ranks you against everyone who has played on the server, in five categories:

Your card shows your best rank; hover over the line to see all five. The math: if you rank 3rd of 60 players in mining, you're in the top 5%. Ranks only appear once the server knows at least 3 players, and only for categories where your value is above zero. During a season, ranks compare season stats, not lifetime stats. Server owners can disable ranks entirely (percentiles.enabled).

All 31 achievements Players

Achievements are computed from your stats for the current wrapped period — during a season, only what you did that season counts, so every season is a fresh hunt. They appear on your card (hover the achievements line), in the book, and in your share texts.

Tiered achievements

These come in pairs — you always get the strongest tier you qualify for, never both:

Mining, building & time

Survival & combat

Travel

Odd jobs

All 17 archetypes & titles Players

Your archetype is your Wrapped personality — chosen by comparing every part of your playstyle against thresholds and picking the trait where you stand out the most (the stat that exceeds its threshold by the largest factor wins). Each archetype has three possible server titles; which one you get is stable for your account, so your title doesn't change every time you look.

Leaderboards Players

/wrapped top <category> shows the server's top players (5 by default). During a season, leaderboards rank season stats. Available categories and their aliases:

There's also /wrapped server — the whole server's combined recap: total playtime, blocks, distance, deaths with the most common cause, and the most active player.

Wrapped Day & /wrapped recap Players

When a season ends, that's Wrapped Day:

• Everyone online gets a ✦ WRAPPED DAY ✦ announcement with a clickable [ Open your Wrapped ] button (plus a celebration sound).
• Your stats for that season are frozen at the moment it ends — anything you do afterwards doesn't change your recap.
• /wrapped recap shows your final season recap for the next 7 days (configurable). The card is labeled "(Final)".
• If you weren't online for the drop, you get a one-time clickable reminder the next time you join.
• If Discord integration is on, the server-wide recap is posted to Discord automatically.

Installation Owners

1. Requirements: a Paper 26.2-compatible server running Java 26. Spigot is not supported (the plugin uses Paper's Adventure API).
2. Place ServerWrapped-1.0.jar in plugins/ and restart (a reload also works, but restart is recommended).
3. On first start the plugin creates plugins/ServerWrapped/config.yml and the data folders. No further setup is required.

Building from source: ./gradlew build produces build/libs/ServerWrapped-1.0.jar; ./gradlew test runs the unit tests; ./gradlew runServer spins up a local test server with the plugin installed.

Commands Owners

/serverwrapped is an alias for /wrapped. Full tab completion is included, including known player names and season ID suggestions.

Permissions Owners

Configuration reference Owners

Everything lives in plugins/ServerWrapped/config.yml. Apply changes with /wrapped reload. Invalid values fall back to safe defaults — the plugin never crashes on bad config.

prefix: "<gold><bold>ServerWrapped</bold></gold> <dark_gray>></dark_gray> "
season-mode: false
current-season-id: ""
last-ended-season-id: ""
leaderboard-size: 5
server-name: ""
leaderboard-cache-seconds: 30
stats-cache-refresh-minutes: 5

share:
  enabled: true
  cooldown-seconds: 60

percentiles:
  enabled: true

recap:
  window-days: 7
  join-reminder: true

discord:
  webhook-url: ""
  share-to-discord: true
  post-season-recap: true
  avatar-thumbnails: true
  image-cards: true
  post-milestones: true

milestones:
  enabled: true
  check-minutes: 10

roast-mode:
  enabled: true
  intensity: 2

Seasons guide Owners

Seasons let you run monthly or SMP-season recaps without resetting anyone's statistics. The trick is baseline snapshots: seasonValue = currentValue − baselineValue.

Lifecycle

1. Start: /wrapped season start june-2026 June 2026
   • june-2026 is the internal ID (lowercase letters, numbers, -, _); "June 2026" is the display name shown on cards.
   • The plugin snapshots the current stats of every known player as the season baseline — including death reasons and totem counts.
   • From now on, all cards, leaderboards, ranks, achievements, and archetypes are computed from season deltas.
   • Players who join mid-season simply have a zero baseline — their whole activity counts.
2. During: /wrapped season shows ID, name, status, and start time.
3. End: /wrapped season end — this is the Wrapped Day moment:
   • Final stats of every known player are frozen in a second snapshot, so the recap can never be polluted by post-season play.
   • All online players get the ✦ WRAPPED DAY ✦ broadcast with a clickable button.
   • The server-wide recap is posted to Discord (if configured).
   • /wrapped recap works for recap.window-days days; players who missed the drop get a one-time reminder on join.
   • Regular /wrapped switches back to lifetime stats (or start the next season right away).

Discord integration Owners

ServerWrapped posts to Discord through a plain channel webhook — no bot account, no bot token, no extra plugin, no library.

Setup (2 minutes)

1. In Discord, open the target channel → Edit Channel → Integrations → Webhooks → New Webhook.
2. Give it a name (the plugin posts as "ServerWrapped" regardless) and Copy Webhook URL.
3. Paste it into config.yml:

   discord:
     webhook-url: "https://discord.com/api/webhooks/1234567890/AbCdEf..."

4. Run /wrapped reload. Test it with /wrapped share.

What gets posted

• On /wrapped share (if share-to-discord is on): by default a rendered PNG image card — player head, season, big stat numbers, "TOP X%" badge, and the archetype with its title on an archetype-colored background. Real images get shown around, screenshotted, and reposted far more than text ever does. Set discord.image-cards: false to post the classic text embed with the emoji stat card instead. The in-game cooldown also throttles Discord posts, so the webhook rate limit (30/min) is never an issue.
• On /wrapped season end (if post-season-recap is on): a gold embed with the server-wide recap — players, combined playtime, blocks, distance, deaths, top death cause, and the most active player.
• On a server milestone (if post-milestones is on): a short celebration embed, e.g. "⛏️ This server just mined its 1,000,000th block!".

How image cards work

• The card is rendered on your server with Java's built-in 2D graphics — no external image service, no extra dependency.
• Rendering and uploading happen entirely on a background thread; the main thread is never touched.
• With avatar-thumbnails: true the player's head is downloaded from mc-heads.net once per share (5-second timeout); if that fails, the card simply renders without a head.
• If rendering or the upload fails for any reason, the plugin automatically falls back to the text embed and logs a console warning — a share never silently disappears.

Safety & failure behavior

• Requests are sent fully asynchronously — a slow or down Discord can never lag the server.
• Failures (bad URL, deleted webhook, HTTP errors) only produce a console warning; gameplay is unaffected.
• The URL is validated to be a real Discord webhook before anything is sent.

Server milestones Owners

Milestones celebrate the whole community: whenever the server's lifetime totals cross a big round number, everyone online gets a broadcast (with the challenge-complete sound), the console logs it, and — if configured — the Discord webhook posts it too.

Details worth knowing:

• Milestones follow a 1 / 2.5 / 5 ladder per power of ten (10,000 → 25,000 → 50,000 → 100,000 → …), so they stay rare and meaningful as the server grows.
• They always use lifetime totals — starting or ending a season never makes milestones jump or repeat.
• The first check after installing baselines silently: a mature server does not get flooded with milestones it passed years ago. Only totals crossed after installation are celebrated.
• At most one milestone per check is announced; if several are crossed at once they trickle out over the following checks instead of spamming chat.
• The last announced value per metric is persisted in milestones.yml, so restarts never re-announce.

Data storage Owners

Everything is plain YAML in the plugin data folder — no database, trivially backupable, human-readable:

plugins/ServerWrapped/
  config.yml
  milestones.yml      # last announced value per milestone metric
  players/
    <uuid>.yml        # one file per player
  seasons/
    <season-id>.yml   # display name, start/end timestamps

A player file contains:

Distances are stored in centimeters (100,000 cm = 1 km), playtime in ticks (72,000 ticks = 1 hour), damage in Minecraft's internal damage points (10 = 1 heart).

Performance & internals Owners

• Write-behind cache: player files are held in memory; events (deaths, totems, joins) only mark data dirty. A background task writes dirty files asynchronously every 20 seconds — events never block on disk I/O. Everything is flushed on player quit and plugin shutdown.
• Offline stats cache: reading Bukkit statistics for offline players is expensive (per-material disk reads). ServerWrapped therefore persists each player's stats on quit, every stats-cache-refresh-minutes while online, and at shutdown — recaps and leaderboards for offline players are served from this cache and never trigger the expensive scan.
• Result caching: leaderboards and the percentile distribution are cached for leaderboard-cache-seconds, so command spam can't cause recomputation storms.
• No movement listeners: all distance/mining/combat numbers come from Bukkit's built-in statistics. The plugin only listens to joins, quits, deaths, and totem resurrections.
• Async networking & rendering: Discord webhook calls, avatar downloads, and PNG card rendering all run on background threads with timeouts.
• No NMS, no reflection into server internals, no external runtime dependencies — version bumps are low-risk.

FAQ & troubleshooting Owners

Players see no "top X%" line

Ranks need at least 3 known players with recorded stats, percentiles.enabled: true, and a non-zero value in at least one category. On a fresh server, ranks appear once three people have played.

Nothing arrives in Discord

1. Check the console for a warning — a malformed URL is reported there.
2. The URL must start with https://discord.com/api/webhooks/ (or the ptb./canary. variants).
3. Make sure the webhook still exists in Discord (deleting the channel deletes its webhooks) and run /wrapped reload after editing the config.

The Discord post is text instead of an image card

That's the automatic fallback. Check the console for a warning around the time of the share — typical causes are the JVM missing fonts (very minimal container images) or Discord rejecting the upload. Rendering works headless out of the box on normal JVMs; no display server is needed.

An offline player's card looks outdated

Offline players are served from the stats cache, which is refreshed every stats-cache-refresh-minutes while they play and once more when they quit. A card can therefore lag a few minutes behind their last session at most.

/wrapped recap says there's nothing to recap

Recaps exist only after a season was ended with /wrapped season end, and only for recap.window-days days. Seasons ended before updating to this version have no frozen final stats; recaps work from the first season you end on this version.

Can I edit or reset a player's data?

Yes — stop the server (or wait for a flush), edit players/<uuid>.yml, and start again. Deleting a player's file resets their plugin-tracked data (death reasons, totems, snapshots); their Bukkit statistics are untouched, since those belong to the vanilla world save.

Does it work on Spigot / Folia / older versions?

No — ServerWrapped targets Paper's Adventure API on Paper 26.2+. Folia is not supported.

Is any data sent anywhere?

If you configure a Discord webhook, share/recap/milestone posts go to that webhook. Player heads come from mc-heads.net: for text embeds Discord fetches them, for image cards your server downloads them while rendering (disable either with discord.avatar-thumbnails: false). Beyond that, the plugin reports anonymous usage statistics (server count, player count, versions) to bStats, like most public plugins — opt out globally in plugins/bStats/config.yml. No player names, UUIDs, or stats ever leave your server.