Bridge Plugin

The Nimbus Bridge is a Velocity proxy plugin that connects the proxy to the Nimbus cloud system. It provides in-game cloud management commands, automatic player routing, permission integration, and proxy synchronization features.

Installation

The bridge is automatically deployed to every proxy service at runtime. On each service prepare, ServiceFactory.resolveModulePlugins() copies nimbus-bridge.jar into the proxy's plugins/ directory with REPLACE_EXISTING — so deletions self-heal on next start and updates roll out automatically. Templates are user-owned; the bridge JAR is never written into templates/global_proxy/plugins/.

If a proxy service's plugins/nimbus-bridge.jar is missing, it's redeployed on the next service start.

Configuration

The bridge reads its API connection from plugins/nimbus-bridge/bridge.json:

{
  "api_url": "http://127.0.0.1:8080",
  "token": "your-api-token"
}

This file is auto-generated by Nimbus Core during deployment. The values come from your config/nimbus.toml API configuration.

Alternatively, the bridge auto-discovers its connection from JVM system properties and environment variables (set by Nimbus when launching the proxy process):

The bridge checks for the environment variable first, then falls back to the system property. If either is set, bridge.json is not read.

Commands

All commands require the base permission nimbus.cloud. The /cloud command is also available as /nimbus.

Service management

Player management

Network management

Permission management

Maintenance management

Hub command

The hub command finds the lobby server with the fewest players (least-players load balancing) and connects the player. If the player is already on any lobby, they're told they're already there.

Connection handling

The bridge manages player connections automatically:

Initial connection

When a player joins the proxy, the bridge detects the connection type via Velocity's internal ConnectionType (set during the FML handshake). Connection types are:

Modded clients (LEGACY_FORGE or MODERN_FORGE) are routed using mod list matching:

1. Filter modded groups by protocol version (client protocol must match the group's MC version)
2. Filter by connection type compatibility (LEGACY_FORGE only matches Forge; MODERN_FORGE matches Forge or NeoForge)
3. Read the client's mod list via player.getModInfo() and compute a match score against each group's server mod list: |clientMods ∩ serverMods| / |serverMods|
4. The group with the highest score (minimum 0.5) wins — the client is sent to the least-loaded instance of that group
5. If no group scores above 0.5 but exactly one group matches protocol + type, route there (fallback for older Forge versions that don't report mod lists)
6. If no match is found, fall back to lobby

Vanilla clients are routed to the lobby with the fewest players. If no suitable server is available, the player is disconnected with an error message.

The modded groups cache (including mod IDs from ModScanner) is fetched from GET /api/groups on startup and refreshed on controller reconnect.

Kicked from server

When a modded client is kicked from a modded server:

1. The bridge tries to find an alternate modded group at the same protocol version
2. If an alternate exists, the client is redirected there
3. If no alternate is found, the client is disconnected (not sent to a vanilla lobby where they'd get kicked again)

When a vanilla client is kicked from a non-lobby server:

1. The bridge attempts to redirect them to the lobby with the fewest players
2. If a lobby is available, the player is sent there with a message
3. If no lobby is available, the player is disconnected

When kicked from a lobby server (e.g. during a restart), the bridge redirects the player to a different lobby. If no other lobby is available, the player is disconnected with the kick reason.

Permission integration

The bridge integrates with Nimbus's permission system by providing a custom Velocity PermissionProvider:

1. On login -- Fetches the player's permissions from the Nimbus API
2. On permission check -- Resolves permissions including wildcard matching
3. On disconnect -- Invalidates the permission cache
4. On permission update -- WebSocket events trigger real-time cache refresh

Permission changes (via /cloud perms or the API) are pushed to all proxies instantly. No restart or rejoin required.

Proxy synchronization

The bridge handles real-time synchronization of:

Tab list

• Applies header/footer from config/modules/syncproxy/tablist.toml to all players
• Formats player display names using the configured player_format
• Supports per-player overrides via the SDK's Nimbus.setTabName()
• Refreshes periodically (default: every 5 seconds)
• Placeholders: {player}, {prefix}, {suffix}, {server}, {group}, {online}, {max}

MOTD

• Intercepts proxy ping events and applies the configured MOTD
• Supports MiniMessage formatting
• Configurable max_players and player_count_offset
• Placeholders: {online}, {max}

Chat format

• Formats chat messages using the configured format (when enabled = true)
• Supports prefix/suffix from permission groups
• Supports MiniMessage and legacy & color codes

Maintenance mode

• Global maintenance: Overrides the MOTD with a maintenance message, sets the version protocol to show a red "x" in the server list, and disconnects non-whitelisted players on join
• Group maintenance: Blocks players from connecting to servers of a specific group (e.g. during template updates), redirects them back to the lobby
• Players with nimbus.maintenance.bypass permission or on the whitelist can bypass both
• Configuration is part of config/modules/syncproxy/motd.toml under the [maintenance] section

Real-time updates

All proxy sync settings are updated in real-time via WebSocket events:

• TABLIST_UPDATED -- Tab config changed
• MOTD_UPDATED -- MOTD config changed
• CHAT_FORMAT_UPDATED -- Chat format changed
• PLAYER_TAB_UPDATED -- Per-player tab override changed
• MAINTENANCE_ENABLED -- Maintenance enabled (global or group)
• MAINTENANCE_DISABLED -- Maintenance disabled (global or group)
• PERMISSION_GROUP_UPDATED -- Permission group changed (re-fetch display info)
• PLAYER_PERMISSIONS_UPDATED -- Player permissions changed

Architecture

NimbusBridgePlugin (entry point)
├── CloudCommand          Dynamic forwarding via /api/commands; maintenance + events are Bridge-local
├── HubCommand            Uses ProxyServer to find lobby
├── ConnectionListener    Handles initial connect + kick fallback + maintenance blocking
├── MaintenanceHandler    Proxy-side maintenance state cache (synced via API + events)
├── PermissionListener    Injects NimbusPermissionProvider
├── ProxySyncListener     Tab list + MOTD + chat sync + maintenance MOTD override
└── Shared clients:
    ├── NimbusApiClient   HTTP client (bridge-specific, returns Result)
    ├── NimbusClient      SDK HTTP client (shared with CloudCommand)
    └── NimbusEventStream WebSocket event stream (shared across features)

The bridge uses a single shared NimbusEventStream connection for all features (permissions, proxy sync, cloud command). This minimizes WebSocket connections to the Nimbus API.

Next steps

• SDK -- Backend server plugin API
• Proxy Setup -- Proxy configuration guide
• Permissions -- Permission system configuration