Showcase Overview

Showcase Sync Pipeline

Showcase syncs Pokemon data from your Minecraft server to web endpoints. The frontend is only a renderer over synced player data.

Flow API Contract Clone Guide Domain Setup

How It Works In The Mod

Service Startup

ShowcaseService starts during mod initialization.

Enable Check

Sync starts only when showcase.isShowcaseEnabled is true and apiSecret is valid.

Sync Interval

The task runs every max(syncIntervalMinutes, 1) minutes.

Login And Logout

Additional syncs run on login after 10 seconds and on logout.

Visibility Toggle

Players toggle visibility with /showcase on and /showcase off.

Config Fields

From your server showcase config JSON

showcase.isShowcaseEnabled (bool)
showcase.apiSecret (string)
showcase.syncIntervalMinutes (int, minimum effective value: 1)
showcase.debug (bool)

Page Layers

Server showcase landing page
Player list with search and filtering
Player detail page with party and PC boxes
Pokemon cards with sprite, nature, type, moves, and optional stats

API Contract Sent By The Mod

Base URL: https://your-domain.com/api

POST `/api/sync`

Authorization: Base64(apiSecret) (not Bearer)
Content-Type: application/json (payload is compressed base64 text)
Body: Base64 string of zlib-deflated JSON

{
  "players": [
    {
      "uuid": "player-uuid",
      "name": "PlayerName",
      "party": [null, {}, {}, null, {}, {}],
      "pc": [[null, {}, "... 30 slots"], "... boxes"],
      "lastUpdated": 1730000000000
    }
  ]
}

Pokemon data contains Cobblemon save JSON plus extra fields like Nature, DexNumber, Ability, FormName, Type1 and Type2, and MoveSet entries.

POST `/api/player`

Authorization: Base64(apiSecret)
Content-Type: application/json

{
  "uuid": "player-uuid",
  "showcaseEnabled": true
}

Option A: UI-Only Duplicate

Rebuild layout and components with mock data.
Keep rendering logic isolated from backend assumptions.
Connect to your own read API later.

Option B: Full Compatible Clone

Implement write endpoints: /api/sync and /api/player.
Decode sync payload as raw text, then base64 decode and zlib inflate.
Validate decoded authorization secret.
Store by (serverId, playerUuid).
Persist showcaseEnabled and expose read endpoints.

Included Starter Endpoints

POST /api/showcase/sync POST /api/showcase/player GET /api/public/servers GET /api/public/players?server=<serverId> GET /api/public/player/:uuid?server=<serverId>

Starter pages: / and /player.html

Switch To challenged-gamers.com

Set SITE_URL=https://challenged-gamers.com in .env.
Set CORS_ORIGIN=https://challenged-gamers.com.
Set SHOWCASE_API_PREFIX=/api/showcase.
Set your secret in SHOWCASE_SECRETS.
Set mod config showcase.apiBaseUrl to https://challenged-gamers.com/api/showcase.
Restart server and web app.

{
  "showcase": {
    "apiBaseUrl": "https://challenged-gamers.com/api/showcase"
  }
}

Node/Express Decode Example

import express from "express";
import zlib from "node:zlib";

const app = express();

app.post("/api/sync", express.text({ type: "*/*", limit: "20mb" }), (req, res) => {
  const encoded = req.body;
  const compressed = Buffer.from(encoded, "base64");
  const inflated = zlib.inflateSync(compressed).toString("utf8");
  const payload = JSON.parse(inflated);

  // TODO: validate auth header and upsert payload.players
  res.status(200).json({ ok: true, players: payload.players?.length ?? 0 });
});

Notes And Pitfalls

apiSecret is expected to include a UUID suffix in the current validation path.
/api/sync body is compressed text even with JSON header.
Periodic sync includes online players only; login and logout handlers send per-player updates.
/showcase command exists only when showcase is enabled in config.

Create Cobblemon Mods with AI