Server Connection

Unterstützte Software

Software	Unterstützung
Velocity	Vollständig
BungeeCord	Vollständig
Waterdog PE	Vollständig
Gate	Geplant

Plugin installieren

Proxy-Plugins installieren

Lade Server Connection von GitHub herunter und lege die JAR-Datei im Ordner plugins/ des Proxy-Templates ab. Die Standard-Templates enthalten simplecloud-api bereits. Füge es bei einem eigenen Template über die Einstellung Plugins des Ziels oder über die CLI hinzu.

Konfiguration erzeugen

Starte einen passenden Proxy. Das Plugin legt config.yml, commands.yml und messages.yml unter plugins/simplecloud-connection/ an.

Lobby-Server abgleichen

Die Standardverbindung wählt Proxy-Registrierungsnamen aus, die mit lobby beginnen. Verwendet deine Lobby-Gruppe einen anderen Namen, ändere die Verbindung lobby und verwende denselben Namen unter network-join-targets, fallback und in commands.yml.

Konfiguration ins Template übernehmen

Kopiere bei einem Gruppen-Proxy plugins/simplecloud-connection/ vor dem Stoppen an denselben Pfad im Template. Unter Templates findest du den vollständigen Ablauf.

Proxy neu starten und testen

Starte den Proxy nach Änderungen an der Registrierung oder an Spielerbefehlen neu. Betritt das Netzwerk, um das erste Ziel zu testen, und führe anschließend von einem anderen Backend /lobby aus. Für Fallbacks verwendet der Proxy dieselbe Verbindung.

Mit registration.enabled: true ersetzt Server Connection die Liste der registrierten Proxy-Server durch die SimpleCloud-Server. Trage jedes externe Backend unter registration.additional-servers ein oder setze die Registrierung auf false, wenn ein anderes Plugin die Liste verwaltet.

Konfiguration

config.yml

Die Hauptkonfigurationsdatei steuert die Serverregistrierung, Verbindungen, das Routing beim Netzwerkbeitritt und das Fallback-Verhalten.

version: 2

# ─────────────────────────────────────────────────────────────────────────────
# Server Registration
# Hält die registrierten Unterserver deines Proxys mit SimpleCloud synchron.
# ─────────────────────────────────────────────────────────────────────────────
registration:
    # Bei "false" werden keine SimpleCloud-Server auf dem Proxy registriert.
    enabled: true

    # Namensmuster für dynamisch gestartete Server auf dem Proxy.
    # Verfügbare Platzhalter: <group>, <numerical_id>, <id>, <name>
    server-name-pattern: '<group>-<numerical_id>'

    # Namensmuster für persistente Server.
    persistent-server-name-pattern: '<name>'

    # Servergruppen und persistente Server, die nicht auf dem Proxy registriert werden sollen.
    ignore-server-groups-and-persistent-servers: []

    # Externe Server (nicht über SimpleCloud), die manuell registriert werden sollen.
    additional-servers: []
    #   - name: 'build'
    #     address: '127.0.0.1'
    #     port: 25565

# ─────────────────────────────────────────────────────────────────────────────
# Subdomain Routing
# Leitet Spieler anhand des Hostnamens weiter, über den sie eine Verbindung herstellen.
# ─────────────────────────────────────────────────────────────────────────────
address:
    routes:
      - subdomain: 'play.example.com'
        target-connection: lobby

# ─────────────────────────────────────────────────────────────────────────────
# Connections
# Benannte Gruppen, die über einen Namensabgleich auf bestimmte Server verweisen.
# Diese werden bei network-join-targets, fallback und in der commands.yml genutzt.
# ─────────────────────────────────────────────────────────────────────────────
connections:
  - name: lobby
    server-name-matcher:
        # Operation für den Namensabgleich.
        # Verfügbar: STARTS_WITH, ENDS_WITH, CONTAINS, EQUALS, REGEX, PATTERN, GREATER_THAN
        operation: STARTS_WITH
        value: lobby
        # Bei "true" wird das Ergebnis des Abgleichs umgekehrt (invertiert).
        negate: false
    # Bedingungen, die erfüllt sein müssen, bevor ein Spieler diese Verbindung nutzen darf.
    # Details dazu findest du unten im Abschnitt "Verbindungsregeln".
    rules: []

# ─────────────────────────────────────────────────────────────────────────────
# Network Join Targets
# Bestimmt, wohin Spieler geschickt werden, wenn sie das Netzwerk betreten.
# ─────────────────────────────────────────────────────────────────────────────
network-join-targets:
    enabled: true
    target-connections:
      - name: lobby      # Muss mit einem oben definierten Verbindungsnamen übereinstimmen
        priority: 0      # Höhere Zahl = wird zuerst versucht.

# ─────────────────────────────────────────────────────────────────────────────
# Fallback
# Bestimmt, wohin Spieler geschickt werden, wenn ihr aktueller Server unerreichbar wird.
# ─────────────────────────────────────────────────────────────────────────────
fallback:
  enabled: true
  target-connections:
    - name: lobby
      priority: 0
      # Optional: Nutze dieses Fallback nur, wenn der Spieler von einem dieser Server kommt.
      from: []

Subdomain-Routen

Der Abschnitt address.routes wählt anhand des Hostnamens, mit dem ein Spieler dem Proxy beitritt, eine Verbindung aus. Jede Angabe unter subdomain muss der vollständige, exakte Hostname sein. Verwende zum Beispiel new.example.com und nicht nur new. Der Wert target-connection verweist auf einen Namen aus der Liste connections. Er verweist nicht direkt auf einen Server. Der server-name-matcher der Verbindung wählt anschließend einen verfügbaren Server aus.

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

  # Persistenter Server, der auf dem Proxy exakt als "smp-2026" registriert ist.
  - name: smp-2026
    server-name-matcher:
        operation: EQUALS
        value: smp-2026
        negate: false
    rules: []

Mit dieser Konfiguration werden Spieler über play.example.com auf einen verfügbaren Lobby-Server geleitet. Spieler über new.example.com werden auf den persistenten Server geleitet, der als smp-2026 registriert ist. Lass jeden verwendeten Hostnamen über einen A-, AAAA- oder CNAME-DNS-Eintrag auf den Proxy zeigen. Verwendet der Proxy nicht den Minecraft-Standardport, musst du zusätzlich einen passenden Minecraft-SRV-Eintrag konfigurieren.

Routing-Verhalten

Konfigurationsversion: Subdomain-Routing benötigt Version 2. Lass das Plugin eine bestehende Version-1-Datei migrieren, bevor du Routen hinzufügst, da diese bei der Migration nicht übernommen werden.
Exakter Abgleich: Gib den vollständigen Hostnamen an. Wildcard-Routen wie *.example.com werden nicht unterstützt.
Standardziel: Wenn keine Route passt, die Zielverbindung nicht existiert oder kein passender Server verfügbar ist, verwendet das Plugin anschließend die network-join-targets.
Verbindungsregeln: Subdomain-Routen werten Verbindungsregeln nicht aus. Eine Permission-Regel auf der Zielverbindung schränkt Spieler, die über diesen Hostnamen beitreten, nicht ein. Verwende priorisierte network-join-targets, wenn das Routing von einer Permission abhängen soll.

Abgleichsoperationen

Der server-name-matcher unterstützt folgende Operationen:

Operation	Beschreibung	Beispielwert
`STARTS_WITH`	Servername beginnt mit dem Wert	`lobby`
`ENDS_WITH`	Servername endet mit dem Wert	`-1`
`CONTAINS`	Servername enthält den Wert	`hub`
`EQUALS`	Exakte Übereinstimmung	`lobby-1`
`REGEX`	Voller Java-Regex-Abgleich	`lobby-\d+`
`PATTERN`	Abgleich mit einem Glob-Muster	`lobby-*`
`GREATER_THAN`	Numerischer Vergleich (Größer als)	`5`

Setze negate: true, um eine Operation umzukehren. So stimmen beispielsweise alle Server überein, die nicht mit lobby beginnen.

Verbindungsregeln

Verbindungen können Regeln enthalten, die ein Spieler erfüllen muss. Schlägt eine Regel fehl, wird die Verbindung übersprungen und die nächste Priorität geprüft. Es gibt zwei Regeltypen: Berechtigungsregel Prüft, ob ein Spieler eine bestimmte Permission besitzt.

rules:
  - type: PERMISSION
    name: server.join.vip        # Zu prüfende Permission
    value: 'true'                # Erwartetes Ergebnis (true oder false)
    bypass-permission: rank.admin # Optional: Überspringt diese Regel, wenn der Spieler diese Admin-Permission hat

Umgebungsvariablenregel Gleicht eine System-Umgebungsvariable über eine Filter-Operation mit einem Wert ab.

rules:
  - type: ENV
    name: SERVER_STATE           # Name der Umgebungsvariable
    value: maintenance           # Wert für den Vergleich
    operation: EQUALS            # Jede beliebige Filter-Operation (EQUALS, STARTS_WITH, etc.)
    negate: true                 # Bei "true" wird das Ergebnis umgekehrt
    bypass-permission: rank.admin # Optional: Überspringt diese Regel, wenn der Spieler diese Admin-Permission hat

Regeln werden der Reihe nach abgearbeitet. Wenn eine Regel fehlschlägt und keine bypass-permission greift, wird die komplette Verbindung übersprungen.

Prioritäten und Fallback-Auflösung

Sowohl network-join-targets als auch fallback unterstützen mehrere Zielverbindungen mit Prioritäten:

Zielverbindungen werden von der höchsten zur niedrigsten Priorität abgearbeitet
Haben mehrere Ziele die gleiche Priorität, wird eines davon zufällig ausgewählt
Hat ein Ziel keinen verfügbaren Server, wird automatisch die nächstniedrigere Priorität versucht
Die optionale from-Liste beschränkt einen Fallback auf Spieler, die von bestimmten Servern kommen

commands.yml

Konfiguriert die Navigationsbefehle für Spieler.

version: 2

commands:
  - name: lobby
    aliases:
      - hub
      - l
    permission: ''   # Leer lassen, damit jeder den Befehl nutzen darf
    messages:
        already-connected: '<color:#dc2626>Du bist bereits auf dieser Lobby!'
        no-target-connection-found: '<color:#dc2626>Es konnte kein Zielserver gefunden werden!</color>'
    target-connections:
      - name: lobby
        priority: 0
        # Optional: Erlaube dieses Ziel nur, wenn der Spieler aktuell auf einem dieser Server ist
        from: []

Befehle folgen derselben Logik wie network-join-targets und fallback. Änderungen an Verbindungsabgleichen, Regeln, Beitrittszielen, Fallbacks und Nachrichten kannst du mit diesem Befehl laden:

/connection reload

Starte den Proxy nach jeder Änderung an commands.yml neu. Der Reload liest die Datei zwar ein, bereits registrierte Proxy-Befehle behalten aber ihre bisherigen Einstellungen. Starte ebenfalls nach Änderungen an registration.additional-servers oder den Registrierungsmustern neu, damit der Proxy seine Serverliste neu aufbaut.

Berechtigungen

Berechtigung	Beschreibung
`simplecloud.connection.reload`	`/connection reload` verwenden
Wert aus `commands.yml`	Den jeweiligen Navigationsbefehl verwenden; ein leerer Wert erlaubt ihn allen Spielern

Fehlerbehebung

Spieler betreten den Proxy, erhalten aber keinen Server

Prüfe, ob network-join-targets.enabled auf true steht, die genannten Verbindungen existieren und jeder Matcher mindestens einen registrierten Server auswählt. Der Standard-Matcher erwartet Registrierungsnamen, die mit lobby beginnen.

Ein neuer Navigationsbefehl existiert nicht

Starte den Proxy nach jeder Änderung an commands.yml neu. /connection reload liest die Datei, aktualisiert oder registriert aber keine bereits laufenden Proxy-Befehle.

Ein externes Backend ist vom Proxy verschwunden

Trage es unter registration.additional-servers ein und starte den Proxy neu. Bei aktivierter Registrierung baut Server Connection die Liste der Proxy-Server beim Start neu auf.

Eine Subdomain-Route verwendet immer das normale Beitrittsziel

Verwende den vollständigen Hostnamen in address.routes, richte dessen DNS auf den Proxy und prüfe, ob target-connection eine vorhandene Verbindung mit einem verfügbaren Server bezeichnet. Wildcards und Verbindungsregeln gelten nicht für Subdomain-Routen.

Introduction

Setup

Configuration

Plugins

Unterstützte Software

Plugin installieren

Konfiguration

config.yml

Subdomain-Routen

Routing-Verhalten

Abgleichsoperationen

Verbindungsregeln

Prioritäten und Fallback-Auflösung

commands.yml

Berechtigungen

Fehlerbehebung

​Unterstützte Software

​Plugin installieren

​Konfiguration

​config.yml

​Subdomain-Routen

Routing-Verhalten

​Abgleichsoperationen

​Verbindungsregeln

​Prioritäten und Fallback-Auflösung

​commands.yml

​Berechtigungen

​Fehlerbehebung

Unterstützte Software

Plugin installieren

Konfiguration

config.yml

Subdomain-Routen

Abgleichsoperationen

Verbindungsregeln

Prioritäten und Fallback-Auflösung

commands.yml

Berechtigungen

Fehlerbehebung