Server Connection

Supported software

Software	Support
Velocity	Full
BungeeCord	Full
Waterdog PE	Full
Gate	Planned

Install the plugin

Install the proxy plugins

Download Server Connection from GitHub and place it in the proxy template’s plugins/ folder. Standard SimpleCloud templates already include simplecloud-api; add it through the target’s Plugins setting or the CLI if you use a custom template.

Generate the configuration

Start a matching proxy. The plugin creates config.yml, commands.yml, and messages.yml under plugins/simplecloud-connection/.

Match your lobby servers

The default connection matches proxy registration names that start with lobby. If your lobby group uses another name, change the lobby connection and keep its name consistent in network-join-targets, fallback, and commands.yml.

Keep the configuration in the template

For a group proxy, copy plugins/simplecloud-connection/ from the running proxy to the same path in its template before the proxy stops. See Templates for the complete workflow.

Restart and test the proxy

Restart after changing registration or player command settings. Join the network to test the initial route, then run /lobby from another backend to test the generated navigation command. The proxy uses the same connection when it needs a fallback server.

With registration.enabled: true, Server Connection replaces the proxy’s registered server list with SimpleCloud servers. Add every external backend to registration.additional-servers, or set registration to false when another plugin manages the list.

Configuration

config.yml

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

version: 2

# ─────────────────────────────────────────────────────────────────────────────
# 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: 'play.example.com'
        target-connection: lobby

# ─────────────────────────────────────────────────────────────────────────────
# 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: []

Subdomain routes

The address.routes section selects a connection from the hostname a player uses to join the proxy. Each subdomain must be the complete, exact hostname. For example, use new.example.com, not only new. The target-connection value references a name from the connections list. It does not reference a server directly. The connection’s server-name-matcher then selects an available server.

address:
    routes:
      - subdomain: 'play.example.com'
        target-connection: lobby
      - subdomain: 'new.example.com'
        target-connection: smp-2026

connections:
  - name: lobby
    server-name-matcher:
        operation: STARTS_WITH
        value: lobby
        negate: false
    rules: []

  # Persistent server registered on the proxy as exactly "smp-2026".
  - name: smp-2026
    server-name-matcher:
        operation: EQUALS
        value: smp-2026
        negate: false
    rules: []

With this configuration, players joining through play.example.com are sent to an available lobby server. Players joining through new.example.com are sent to the persistent server registered as smp-2026. Point every routed hostname to the proxy with an A, AAAA, or CNAME DNS record. If the proxy does not use Minecraft’s default port, configure an appropriate Minecraft SRV record as well.

Routing behavior

Config version: Subdomain routing requires version 2. Let the plugin migrate an existing version 1 file before you add routes because the migration does not retain them.
Exact matching: Specify the complete hostname. Wildcard routes such as *.example.com are not supported.
Default target: If no route matches, its target connection does not exist, or no matching server is available, the plugin continues with network-join-targets.
Connection rules: Subdomain routes do not evaluate connection rules. A permission rule on the target connection does not restrict players joining through that hostname. Use prioritized network-join-targets when routing should depend on a permission.

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. For example, it can 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 and 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: 2

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. Changes to connection matching, rules, join targets, fallback targets, and messages can be loaded with:

/connection reload

Restart the proxy after any change to commands.yml. The reload reads the file, but already registered proxy commands keep their previous settings. Also restart after changing registration.additional-servers or registration name patterns so the proxy rebuilds its registered server list.

Permissions

Permission	Description
`simplecloud.connection.reload`	Use `/connection reload`
Value from `commands.yml`	Use that player navigation command; an empty value allows everyone

Troubleshooting

Players join the proxy but no server is selected

Confirm that network-join-targets.enabled is true, its connection names exist, and each matcher selects at least one registered server. The default matcher expects registration names beginning with lobby.

A new navigation command does not exist

An external backend disappeared from the proxy

Add it under registration.additional-servers and restart. When registration is enabled, Server Connection rebuilds the proxy’s registered server list at startup.

A subdomain route always uses the normal join target

Use the complete hostname in address.routes, point that hostname to the proxy, and confirm that target-connection names an existing connection with an available server. Wildcards and connection rules do not apply to subdomain routes.

Introduction

Setup

Configuration

Plugins

Supported software

Install the plugin

Configuration

config.yml

Subdomain routes

Routing behavior

Matcher operations

Connection rules

Priority and fallback resolution

commands.yml

Permissions

Troubleshooting

​Supported software

​Install the plugin

​Configuration

​config.yml

​Subdomain routes

Routing behavior

​Matcher operations

​Connection rules

​Priority and fallback resolution

​commands.yml

​Permissions

​Troubleshooting

Supported software

Install the plugin

Configuration

config.yml

Subdomain routes

Matcher operations

Connection rules

Priority and fallback resolution

commands.yml

Permissions

Troubleshooting