plugin-resourcepacks

The Grounds Velocity PackSet delivery plugin. It caches validated PackSet snapshots locally and delivers an ordered Adventure resource-pack request on player login.

Requirements

Install plugin-config alongside this plugin. It supplies ConfigDefinition at runtime and owns the authenticated configuration snapshot, reconciliation, and change-notification boundary.

Set GROUNDS_ENVIRONMENT to the deployment environment name, for example stage. The value is required, must be non-blank, and must not contain whitespace, /, or \\. It selects this exact configuration scope:

network/<env>/resourcepacks/global

The default document seeds the Stable Grounds PackSet only when no operator document exists:

{
  "schemaVersion": 1,
  "enabled": true,
  "source": {
    "baseUrl": "https://cdn.grounds.gg",
    "packSet": "grounds-global",
    "channel": "stable",
    "pin": null
  },
  "required": true,
  "prompt": "Grounds benötigt seine Resourcepacks."
}

For Stage, an operator changes only source.channel to edge; the deployment environment and PackSet channel are separate choices. A missing or null source.pin follows that channel. A release pin overrides the channel while retaining it as the explicit fallback to use when unpinned:

"source": {
  "baseUrl": "https://cdn.grounds.gg",
  "packSet": "grounds-global",
  "channel": "stable",
  "pin": { "type": "release", "id": "v0.7.0" }
}

Only release pins with canonical release IDs are accepted. Pin-aware rollout requires every target runtime to be verified first; operator mutation remains disabled by default until that gate is complete.

Runtime boundary

The Velocity runtime reads an immutable in-memory snapshot during player login: login does no synchronous configuration-service or CDN I/O. Stable and Edge channels continue periodic refreshes. A release pin validates an initial snapshot and reuses its immutable local cache when offline; release pins do not poll periodically. Configuration updates resolve in the background and are adopted only at the next safe transition. Validated CDN state is cached under the plugin data directory at packset-cache (normally plugins/plugin-resourcepacks/packset-cache).

An arbitrary HTTPS origin is an administrator capability. Until service-config has application-level administrator authorization, all configuration writes must remain inside the current authenticated/private service-config boundary. Do not expose this document for public or unauthenticated writes.

Runtime behavior

The plugin sends one ordered Adventure request through Player.sendResourcePacks, preserving each pack's UUID, URI and SHA-1 together with the configured prompt and required flag. It sends only a source-matched READY snapshot or source-matched DEGRADED fallback, suppresses duplicate fingerprints per player, and removes that record on disconnect. New snapshots and changed delivery settings are adopted on a player's next backend-server switch; they are never broadcast live to online players. A source change reconfigures the same client; it never offers the retained fallback from the old source. Velocity status events identify a pack UUID but not the request that sent it; if overlapping targets reuse the same UUID, target attribution is reported as unknown even for a terminal status until the player disconnects or delivery state is cleared, rather than guessing the newer target.

A genuinely NOT_READY configuration does not apply defaults, create a CDN client, or send packs. After callback installation the plugin probes the latest manager value through the same serialized delivery path as live changes, closing the registration-to-subscription race. That probe or the first later valid change starts exactly one client. Shutdown detaches plugin-owned listeners and closes that client. Local runtime diagnostics expose client status, current and fallback fingerprints, and requested/accepted/downloaded/failed/declined counters. Untrusted diagnostic text is replaced by bounded, allowlisted reason codes.

The required-pack unavailable disconnect reason remains localized, plain text. It is deliberately not a prefixed system message because the player is disconnected before normal chat presentation is available.

Current scope

There is no Minestom adapter and no gamemode or per-server PackSet overlay support yet.

Sidebar font confirmation

SIDEBAR_FONT_PACK_SHA1S is a comma-separated allowlist of lowercase SHA-1 hashes for platform packs carrying the new grounds:sidebar font. It is independent of CHAT_FONT_PACK_SHA1S; an old chat-font pack never enables sidebar glyphs. With no sidebar allowlist the lobby stays in readable text mode.

Only a successful load of an offered, allowlisted pack on Java protocol 777, with a positively identified non-Bedrock player, sets readiness. A replacement offer, load failure or disconnect revokes it. The revisioned, UUID-bound status is sent on grounds:sidebar_style to the player's actual current backend and resent after switching servers. Incoming client messages on this channel are consumed; they cannot enable graphics.

The backend must include the matching lobby receiver. Roll out the new pack and allowlisted hash, the proxy sender on every proxy, then the new lobby. An old receiver or sender continues to use text.