Server Connection

Overview

The Server Connection Plugin is the central proxy plugin for SimpleCloud v3 networks. It keeps your proxy’s registered child servers in sync with SimpleCloud’s server registry and handles all player routing logic. The plugin:

Automatically registers and unregisters SimpleCloud servers on your proxy
Routes players to the correct server on network join
Redirects players to fallback servers when their server becomes unavailable
Provides configurable navigation commands for players to switch servers
Supports flexible server name matching via configurable operations

Supported Software

Software	Support
Velocity	✅ Full
BungeeCord	✅ Full
Waterdog PE	✅ Full
Gate	🔄 Planned

Want to add support for another proxy software? Submit an pull request on GitHub!

Quick Setup

Download the plugin from GitHub
Place it in your proxy template’s plugins folder
Start your proxy server
Edit config.yml, commands.yml and messages.yml to your needs

Configuration

config.yml

The main configuration file. Controls server registration, connections, network join routing and fallback behavior.

version: '1'

# ─────────────────────────────────────────────────────────────────────────────
# Server Registration
# Keeps your proxy's registered child servers in sync with SimpleCloud.
# ─────────────────────────────────────────────────────────────────────────────
registration:
    # If false, no SimpleCloud servers will be registered on the proxy.
    enabled: true

    # Pattern used to name dynamically started servers on the proxy.
    # Available placeholders: <group>, <numerical_id>, <id>, <name>
    server-name-pattern: '<group>-<numerical_id>'

    # Pattern used for persistent servers.
    persistent-server-name-pattern: '<name>'

    # Server groups and persistent servers that should not be registered on the proxy.
    ignore-server-groups-and-persistent-servers: []

    # Non SimpleCloud servers to register manually.
    additional-servers: []
    #   - name: 'build'
    #     address: '127.0.0.1'
    #     port: 25565

# ─────────────────────────────────────────────────────────────────────────────
# Subdomain Routing
# Routes players to a connection based on the hostname they connected with.
# ─────────────────────────────────────────────────────────────────────────────
address:
  routes:
    - subdomain: 'build.example.com'
      target-connection: build

# ─────────────────────────────────────────────────────────────────────────────
# Connections
# Named groups that reference a set of servers by a name matcher.
# These are referenced by network-join-targets, fallback and commands.yml.
# ─────────────────────────────────────────────────────────────────────────────
connections:
  - name: lobby
    server-name-matcher:
        # Operation to match server names.
        # Available: STARTS_WITH, ENDS_WITH, CONTAINS, EQUALS, REGEX, PATTERN, GREATER_THAN
        operation: STARTS_WITH
        value: lobby
        # If true, inverts the match result.
        negate: false
    # Rules that must pass before a player can use this connection.
    # See "Connection Rules" section below for details.
    rules: []

# ─────────────────────────────────────────────────────────────────────────────
# Network Join Targets
# Defines where players are sent when they first join the network.
# ─────────────────────────────────────────────────────────────────────────────
network-join-targets:
    enabled: true
    target-connections:
      - name: lobby      # Must match a connection name defined above
        priority: 0      # Higher number = tried first.

# ─────────────────────────────────────────────────────────────────────────────
# Fallback
# Defines where players are sent when their current server becomes unavailable.
# ─────────────────────────────────────────────────────────────────────────────
fallback:
  enabled: true
  target-connections:
    - name: lobby
      priority: 0
      # Optional: only use this fallback if the player is coming from one of these servers.
      from: []

Matcher Operations

The server-name-matcher supports the following operations:

Operation	Description	Example value
`STARTS_WITH`	Server name starts with the value	`lobby`
`ENDS_WITH`	Server name ends with the value	`-1`
`CONTAINS`	Server name contains the value	`hub`
`EQUALS`	Exact match	`lobby-1`
`REGEX`	Full Java regex match	`lobby-\d+`
`PATTERN`	Glob style pattern match	`lobby-*`
`GREATER_THAN`	Numeric comparison	`5`

Set negate: true to invert any operation e.g. match all servers that do not start with lobby.

Connection Rules

Connections can have rules that must pass before a player is allowed to use them. If a rule fails, the connection is skipped and the next priority is tried. There are two rule types: Permission Rule Checks whether a player has a specific permission.

rules:
  - type: PERMISSION
    name: server.join.vip        # Permission to check
    value: 'true'                # Expected result (true or false)
    bypass-permission: rank.admin # Optional: skip this rule if the player has this permission

Environment Variable Rule Checks a system environment variable against a value using a matcher operation.

rules:
  - type: ENV
    name: SERVER_STATE           # Environment variable name
    value: maintenance           # Value to compare against
    operation: EQUALS            # Any matcher operation (EQUALS, STARTS_WITH, CONTAINS, etc.)
    negate: true                 # If true, inverts the match result
    bypass-permission: rank.admin # Optional: skip this rule if the player has this permission

Rules are evaluated in order. If any rule fails and no bypass-permission applies, the entire connection is skipped.

Priority & Fallback Resolution

Both network-join-targets and fallback support multiple target connections with priorities:

Target connections are tried highest priority first
If multiple targets share the same priority, one is picked randomly among them
If a target connection has no available server, the next lower priority is tried automatically
The optional from list on fallback targets restricts them to players coming from specific servers

commands.yml

Configures player navigation commands.

version: '1'

commands:
  - name: lobby
    aliases:
      - hub
      - l
    permission: ''   # Leave empty to allow everyone
    messages:
        already-connected: '<color:#dc2626>You are already connected to this lobby!'
        no-target-connection-found: '<color:#dc2626>Couldn''t find a target server!'
    target-connections:
      - name: lobby
        priority: 0
        # Optional: only allow this target if the player is currently on one of these servers
        from: []

Commands follow the same logic as network-join-targets and fallback.

Introduction

Setup

Configuration

Plugins

Overview

Supported Software

Quick Setup

Configuration

config.yml

Matcher Operations

Connection Rules

Priority & Fallback Resolution

commands.yml

​Overview

​Supported Software

​Quick Setup

​Configuration

​config.yml

​Matcher Operations

​Connection Rules

​Priority & Fallback Resolution

​commands.yml

Overview

Supported Software

Quick Setup

Configuration

config.yml

Matcher Operations

Connection Rules

Priority & Fallback Resolution

commands.yml