Bridge by PLAYCITY BLOCK

Bridge is a Paper plugin for connecting trusted web backends and other server plugins to Minecraft through small, typed actions and scoped events. It provides an integration boundary without exposing RCON or an arbitrary remote console.

Why use Bridge?

• Least-privilege access: each client receives its own credential, action and event allowlists, request rate, concurrency limit, and WebSocket connection limit.
• Backend-neutral REST API: any server-side language or framework that can send authenticated JSON over HTTP can discover and invoke permitted actions.
• Optional real-time events: a scoped WebSocket endpoint provides typed events, sequence numbers, bounded replay, heartbeat detection, and backpressure.
• JWT/JWKS support: deployments with a central issuer can validate short-lived signed access tokens while intersecting token scopes with local server allowlists.
• Retry-safe actions: caller-scoped request IDs coalesce concurrent retries and reject reuse with a different payload.
• Outbound-only networking: an optional relay protocol supports servers that cannot accept inbound connections, including acknowledged event batches and failure-safe action handling.
• Extensible provider API: other Paper plugins can register their own typed actions and events while Bridge owns authentication, authorization, limits, idempotency, and stable error handling.
• Secure defaults: fresh installations bind HTTP to loopback and leave WebSocket, JWT, relay, metrics, and mutating actions disabled.

Included capabilities

Bridge includes authenticated action discovery, a read-only player-status action, optional player teleportation with an explicit world allowlist, player join/leave events containing only UUIDs, privacy-bounded status information, and optional Prometheus metrics.

Bridge is not a browser login system, public Internet API, or generic command executor. Keep it on loopback whenever possible and place an HTTPS reverse proxy, VPN, or authenticated service mesh between Bridge and remote backends.

Requirements

• Paper 26.2
• Java 25

Folia is not currently supported. Bukkit, Spigot, and other server implementations are not claimed as compatible.

Getting started

1. Put the Bridge JAR in the Paper server's plugins directory.
2. Start and stop the server normally once so Bridge creates plugins/Bridge/config.yml.
3. Create a unique token file of at least 32 UTF-8 bytes for each trusted backend.
4. Configure a scoped client with only the actions and events it needs.
5. Start with the read-only minecraft.player_status action on loopback.
6. Add WebSocket, JWT, or outbound relay only when the deployment requires it.

Do not use plugin hot-reload tools. Bridge schedules Bukkit world and entity work on the Paper primary thread and should be loaded through a normal server start.

License

Bridge source code, binaries, and the provider API are licensed under the Apache License 2.0. Bundled third-party components remain subject to their respective notices.