Documentation
Plugin Implementation Snapshot
Current plugin release details, payload examples, schedules, and troubleshooting cheats.
# ServerStats Plugin Integration Snapshot
This document captures the implemented backend-facing flows, payloads, config, and debug tips for the ServerStats plugin as currently delivered. All operational endpoints and schedules are hardcoded to production (`https://ingest.serverstats.gg`) to minimize misconfiguration. Only credentials and a few toggles live in `config.yml`.
## Config Inputs (config.yml)
- `apiKey`, `shardToken`, `shardUuid`, `shardSecret`, `shardId`, `pluginVersion`
- `tebexSecret` (for shop revenue polling)
- Queue/dedupe paths: `queueFile`, `dedupeFile`, `identities.json`
- Identity mode: `playerIdentityMode` (`hash|uuid`) with synthetic fallback persisted
- LiteBans DB settings (if enabled)
- Command stream reconnect seconds
> Base URL, resolve path, command stream path, and all schedules are hardcoded in code (hourly telemetry/pull/health, 60s queue flush/batch). Changing them in YAML has no effect.
## Authentication & Headers
- Auth: `POST /api/plugin-auth` and `POST /api/plugin-auth/refresh`
- Required headers on all requests:
- `Authorization: Bearer <accessToken>`
- `X-Signature: HMAC_SHA256(body, shardSecret)` (empty string for GET)
- `X-Shard-ID`, `X-Shard-UUID`, `X-Plugin-Version`
## Ingest Payloads (examples)
```jsonc
// Players snapshot
{
"schemaVersion": 1,
"shardId": 2,
"collectedAt": "2024-08-04T19:02:11.213Z",
"online": 120,
"uniqueJoins": 340,
"tps": 19.8,
"latencyMs": 55.2,
"topPlayers": [
{
"playerId": "4939201834",
"playerKey": "4939201834",
"playerKeySource": "synthetic|mapped",
"uuid": "c31c6b0d-9f4b-45b4-bc58-e6ff89dca0ac",
"name": "QuartzLion",
"sessionMinutes": 64,
"vaultBalance": 684120.0,
"netWorth": 684120.0
}
]
}
```
```jsonc
// Performance
{
"schemaVersion": 1,
"shardId": 2,
"collectedAt": "2024-08-04T19:05:00Z",
"ticksPerSecond": 19.6,
"cpuPercent": 68.0,
"memoryPercent": 72.0,
"chunksLoaded": 4823,
"hopperCount": 600
}
```
```jsonc
// Economy (shop/auction volumes include session aggregates)
{
"schemaVersion": 1,
"shardId": 2,
"collectedAt": "2024-08-04T19:10:00Z",
"auctionVolume": 0,
"shopVolume": 182000.0,
"emeraldInflux": 0,
"flaggedVolume": 12000.0,
"onlineBalances": 92000.0,
"netWorth": 92000.0
}
```
```jsonc
// Chat
{
"schemaVersion": 1,
"shardId": 2,
"eventId": "chat:c31c...:msg:1722792000",
"channel": "PUBLIC",
"playerId": "4939201834",
"playerKey": "4939201834",
"playerKeySource": "mapped|synthetic",
"fromUuid": "c31c6b0d-9f4b-45b4-bc58-e6ff89dca0ac",
"fromName": "QuartzLion",
"message": "gg wp",
"sentimentScore": 0.6,
"toxicityScore": 0.0,
"timestamp": "2024-08-04T19:11:00Z"
}
```
```jsonc
// Vault transaction
{
"schemaVersion": 1,
"shardId": 2,
"eventId": "vault:c31c...:CREDIT1000shop",
"txnId": "1722792100000-1234",
"playerId": "4939201834",
"playerKey": "4939201834",
"playerKeySource": "mapped|synthetic",
"uuid": "c31c6b0d-9f4b-45b4-bc58-e6ff89dca0ac",
"amount": 1000.0,
"direction": "CREDIT",
"counterpart": "SHOP",
"createdAt": "2024-08-04T19:11:40Z"
}
```
```jsonc
// Punishment
{
"schemaVersion": 1,
"shardId": 2,
"eventId": "punishment:c31c...:BAN",
"eventType": "BAN",
"playerId": "4939201834",
"playerKey": "4939201834",
"playerKeySource": "mapped|synthetic",
"moderator": "console",
"timestamp": "2024-08-04T19:12:00Z",
"expiresAt": null,
"reason": "Griefing"
}
```
```jsonc
// Shop purchase (includes Tebex/webhook/command sources)
{
"schemaVersion": 1,
"shardId": 2,
"eventId": "shop:c31c...:order123",
"playerId": "4939201834",
"playerKey": "4939201834",
"playerKeySource": "mapped|synthetic",
"uuid": "c31c6b0d-9f4b-45b4-bc58-e6ff89dca0ac",
"sku": "rank-legend",
"price": 49.99,
"currency": "USD",
"paymentMethod": "Tebex",
"processor": "Xsolla",
"orderId": "123456",
"source": "TEBEX",
"createdAt": "2024-08-04T19:12:40Z"
}
```
```jsonc
// Health
{
"schemaVersion": 1,
"shardId": 2,
"queueDepth": 0,
"bufferedEvents": 0,
"lastPlayersAt": "2024-08-04T19:02:11Z",
"lastPerformanceAt": "2024-08-04T19:05:00Z",
"lastEconomyAt": "2024-08-04T19:10:00Z",
"lastVaultAt": "2024-08-04T19:11:40Z",
"lastChatAt": "2024-08-04T19:11:00Z",
"lastShopAt": "2024-08-04T19:12:40Z",
"lastPunishmentAt": "2024-08-04T19:12:00Z",
"lastPlayerEventAt": "2024-08-04T19:01:00Z"
}
```
## Command Stream & ACKs
- WebSocket to `/api/plugin/commands` with auth/signature headers.
- Supports messages like:
```json
{
"id": "cmd_e7f8615b",
"type": "COMMAND|MESSAGE|ALERT",
"command": "/alert staff",
"payload": { "priority": "HIGH", "body": "TPS dipped below 18", "target": "StaffName", "text": "Hello" },
"metadata": { "issuedAt": "...", "expiresAt": "...", "source": "console-user|automation" },
"ackToken": "ack_7b02cd0e"
}
```
- ACKs posted to `/api/plugin/shards/{shardId}/command-acks`:
```json
{
"ackToken": "ack_7b02cd0e",
"id": "cmd_e7f8615b",
"status": "SUCCESS|FAILED",
"details": "Executed",
"completedAt": "2024-08-04T18:01:32.921Z"
}
```
## Player Identity
- Attempts backend resolve (`/api/plugin/players/resolve`) with `{uuid,name}`; accepts `playerId` at root or `player.id`.
- On failure, generates a synthetic, salted playerId, stores it, and tags payloads with `playerKeySource: synthetic`.
## External Feeds
- Tebex polling (hourly, secret in config) -> shop purchase ingest; offset persisted to `tebex.offset`.
- Shop webhook listener (configurable in `webhooks.yml`) -> shop purchase ingest.
- LiteBans polling (optional) -> punishment ingest.
## Command-Line/Debug Tips
- `/serverstats status` shows last telemetry timestamps and queue/buffer sizes.
- `/serverstats diag` triggers a health ping; `/serverstats flush` flushes buffered/queued events.
- Health payload includes last-* timestamps for debugging ingest freshness.
- Event dedupe and queues persist to disk (`queue.json`, `dedupe.ids`, `identities.json`, `tebex.offset`).
## Known Gaps / To-Do
- ShopGUI+/AuctionHouse ingestion (awaiting formats) to populate auctionVolume/shopVolume/flaggedVolume and ledger.
- Sentiment remains heuristic (no external model).
- Schema validation uses bundled `schema.json`; payload contracts can be tightened further once backend schemas are finalized.
## Testing Checklist
- Configure `config.yml` secrets; start server; ensure auth succeeds (log).
- Verify periodic posts (hourly) for players/performance/economy and health.
- Send chat/punishment/vault/shop events; check queue stays at 0 and health timestamps advance.
- Exercise command stream: send COMMAND/MESSAGE payload with ackToken and confirm ACK arrives.