Floodgate - Bedrock gracze na serwerze Java

Co to jest Floodgate

Floodgate to darmowy plugin open-source tworzony przez zespół GeyserMC. Jego jedynym zadaniem jest obsługa uwierzytelniania graczy Bedrock Edition na serwerach Java działających w trybie online (online-mode=true). Bez Floodgate gracze Bedrock próbujący dołączyć przez Geyser spotykaliby się z błędem autoryzacji - serwer Java wymagałby od nich konta Mojang/Microsoft z licencją Java, której ci gracze po prostu nie mają.

Floodgate rozwiązuje ten problem elegancko: przechwytuje połączenie gracza Bedrock jeszcze zanim dotrze ono do systemu autoryzacji Java i podmienia je na tymczasową tożsamość zweryfikowaną przez Xbox Live. Gracz jest legalny z punktu widzenia Microsoftu (ma konto Xbox), ale nie potrzebuje oddzielnego konta Java Edition.

Plugin jest rozwijany aktywnie od 2020 roku i jest integralną częścią ekosystemu GeyserMC. Pobierzesz go razem z Geyserem ze strony GeyserMC. Kod źródłowy dostępny jest na GitHub.

Więcej o samym protokole crossplay przeczytasz na stronie GeyserMC w naszej wiki.

Jak działa z GeyserMC

Żeby zrozumieć rolę Floodgate, trzeba najpierw wiedzieć, jak działa GeyserMC. Geyser to most protokołowy - tłumaczy pakiety Bedrock Edition na pakiety Java Edition (i odwrotnie) w czasie rzeczywistym. Dzięki temu klient Bedrock "myśli", że gra na serwerze Bedrock, a serwer Java "myśli", że ma do czynienia z klientem Java.

Problem pojawia się na etapie logowania. Standardowy serwer Java z włączonym online-mode weryfikuje każdego gracza przez serwery Mojang/Microsoft. Gracz Bedrock nie ma konta Java - ma konto Xbox. Te dwa systemy nie rozmawiają ze sobą bez pośrednika.

Tutaj wchodzi Floodgate. Pełni rolę właśnie tego pośrednika:

1. Gracz Bedrock łączy się z Geyserem (który może działać jako osobny proxy lub jako plugin na tym samym serwerze)
2. Geyser weryfikuje tożsamość gracza przez Xbox Live / serwery Microsoft Bedrock
3. Floodgate odbiera te dane i generuje tymczasowy, szyfrowany token dla tego gracza
4. Token jest wstrzykiwany do strumienia danych logowania zanim serwer Java wykona swoją weryfikację online
5. Floodgate na serwerze Java rozszyfrowuje token i zezwala graczowi wejść, omijając standardową weryfikację Mojang

Cały proces jest bezpieczny - używa kryptografii klucza publicznego. Klucz prywatny jest generowany lokalnie przy instalacji Floodgate i nigdy nie opuszcza twojego serwera.

Instalacja

Instalacja Floodgate jest prosta, ale wymaga zachowania kilku kolejności kroków:

1. Pobierz plik floodgate-spigot.jar (lub floodgate-velocity.jar / floodgate-bungee.jar) ze strony GeyserMC. Wersje build są dostępne jako "stable" (zalecane) i "development".
2. Wrzuć plik do folderu plugins/ swojego serwera Java.
3. Uruchom serwer raz, żeby Floodgate wygenerował swój folder konfiguracyjny i - co ważne - klucz szyfrujący (key.pem).
4. Teraz skonfiguruj GeyserMC tak, żeby wskazywał na folder Floodgate. W pliku plugins/Geyser-Spigot/config.yml ustaw:

floodgate-key-file: "plugins/floodgate/key.pem"

Jeśli Geyser i Floodgate działają na tym samym serwerze (tryb plugin), GeyserMC automatycznie wykryje Floodgate i załaduje klucz sam. Ręczna konfiguracja ścieżki potrzebna jest tylko przy konfiguracji proxy (BungeeCord/Velocity), gdzie Geyser i serwery backendowe są oddzielnymi procesami.

Po prawidłowej instalacji w konsoli powinny pojawić się logi podobne do:

[Floodgate] Enabling Floodgate
[Floodgate] Loading key from plugins/floodgate/key.pem
[Floodgate] Successfully enabled Floodgate

Zwróć uwagę: plik key.pem jest krytyczny. Jeśli go zgubisz lub zostanie nadpisany, wszyscy gracze Bedrock z powiązanymi kontami (Global Linking) stracą swoje powiązania. Warto go regularnie backupować.

Konfiguracja

Plik konfiguracyjny Floodgate to plugins/floodgate/config.yml. Oto najważniejsze opcje:

# Prefix dodawany przed nazwą gracza Bedrock
# Domyślnie kropka (.) - zapobiega kolizjom nazw z graczami Java
username-prefix: "."

# Czy zezwalać na dołączanie graczy Bedrock bez powiązanego konta Java?
# true = gracze Bedrock mogą grać bez linkowania (domyślnie)
# false = wymagane powiązanie konta przez Global Linking
disconnect:
  wrong-username: "Your Bedrock username is not valid for this server!"

# Integracja z systemem skórek
# Pobiera skórkę gracza Bedrock i wyświetla ją na serwerze Java
send-floodgate-data: true

# Opcje dla konfiguracji proxy (BungeeCord/Velocity)
metrics:
  enabled: true
  uuid: "..."

Większość adminów nie zmienia zbyt wiele poza prefixem. Kluczowa decyzja to właśnie prefix - więcej o nim w następnej sekcji.

Prefix graczy Bedrock

Jednym z powodów istnienia prefixu jest techniczny problem z nazwami użytkowników. Minecraft Java i Bedrock używają różnych reguł dla nicków. Na Bedrock gracze mogą mieć spacje w nazwie lub zaczynać od cyfry - co jest niemożliwe na Java. Prefix rozwiązuje ten problem i dodatkowo sygnalizuje innym graczom, że dany nick pochodzi z Bedrock.

Domyślny prefix to kropka (.), co daje nazwy w stylu .SteveXbox. Inne popularne wybory:

Pamiętaj, że prefix wchodzi w skład nazwy gracza z punktu widzenia serwera. Jeśli gracz Bedrock ma nick "Steve" i prefix to ".", to na serwerze istnieje jako ".Steve". Jeśli jednocześnie gracz Java też ma nick "Steve", nie będzie konfliktu - to dwie różne nazwy. Dlatego nie ustawiaj pustego prefixu na serwerach, gdzie grają zarówno gracze Java jak i Bedrock - ryzykujesz kolizję nicków.

Jeśli masz na serwerze EssentialsX, gracze Bedrock mogą mieć swoje domy i konta ekonomii pod prefixową nazwą. Działa to transparentnie - nie musisz nic specjalnie konfigurować.

Łączenie kont (Global Linking)

Global Linking to jedna z najbardziej przydatnych funkcji ekosystemu GeyserMC/Floodgate. Pozwala graczowi Bedrock powiązać swoje konto Xbox z istniejącym kontem Java. Po powiązaniu, kiedy gracz Bedrock dołącza przez Floodgate, serwer widzi go jako gracza Java z jego prawdziwą nazwą - bez prefixu, z jego progressem, uprawnieniami i skórką.

Powiązanie konta odbywa się przez stronę link.geysermc.org. Gracz:

1. Wchodzi na stronę i loguje się kontem Xbox (Bedrock)
2. Następnie loguje się kontem Microsoft powiązanym z Java Edition
3. Strona tworzy powiązanie w globalnej bazie danych GeyserMC
4. Od tej chwili kiedy gracz Bedrock dołącza do dowolnego serwera z Floodgate, automatycznie widoczny jest pod swoją nazwą Java

Global Linking działa globalnie - raz powiązane konto działa na wszystkich serwerach używających Floodgate z włączonym global linking. Nie trzeba tego robić osobno na każdym serwerze.

Jeśli wolisz lokalne powiązania (tylko na swoim serwerze), możesz wyłączyć global linking w konfiguracji i zamiast tego użyć Floodgate API do zaimplementowania własnego systemu. Jednak dla większości serwerów global linking to najwygodniejsze rozwiązanie - gracze linkują raz i gotowe.

Administratorzy mogą też ręcznie zarządzać powiązaniami przez komendy konsoli serwera, co przydaje się gdy gracz ma problemy z samodzielnym linkowaniem.

Formularz Custom Forms

Bedrock Edition ma wbudowany system formularzy UI (modalnych okienek) niedostępny w Java Edition. Floodgate wystawia API, dzięki któremu pluginy Java mogą wysyłać te formularze do graczy Bedrock.

Dostępne są trzy typy formularzy:

• SimpleForm - lista przycisków z opcjonalnym obrazkiem. Idealny do menu nawigacyjnych, wyboru trybu gry, warpu itp.
• ModalForm - dwa przyciski z pytaniem. Prosty dialog tak/nie, np. potwierdzenie zakupu lub akceptacja regulaminu.
• CustomForm - pełen formularz z dowolnymi komponentami: pola tekstowe, suwaki, przełączniki, listy rozwijane. Przydatny do rejestracji, konfiguracji profilu, zgłoszeń.

Formularze są dostępne przez Floodgate API w Javie. Przykładowe użycie w pluginie:

// Sprawdź czy gracz to Bedrock
FloodgateApi api = FloodgateApi.getInstance();
if (api.isFloodgatePlayer(player.getUniqueId())) {
    FloodgatePlayer floodgatePlayer = api.getPlayer(player.getUniqueId());

    // Zbuduj formularz
    SimpleForm form = SimpleForm.builder()
        .title("Wybierz tryb gry")
        .button("Survival")
        .button("Creative")
        .button("Spectator")
        .responseHandler((responseForm, exception) -> {
            if (exception != null) return; // gracz zamknął formularz
            int clicked = responseForm.getClickedButtonId();
            // obsłuż wybór...
        })
        .build();

    floodgatePlayer.sendForm(form);
}

Większość adminów nie implementuje własnych formularzy - to funkcja dla deweloperów pluginów. Ale warto wiedzieć, że ta możliwość istnieje, szczególnie jeśli tworzysz serwer mocno nastawiony na graczy mobilnych lub konsolowych.

Uprawnienia

Floodgate sam w sobie ma minimalny zestaw uprawnień. Kluczowe to:

Bardziej skomplikowane zarządzanie uprawnieniami pojawia się, gdy chcesz traktować graczy Bedrock inaczej niż graczy Java - np. dać im inną rangę lub ograniczyć dostęp do niektórych funkcji. W takim przypadku musisz w pluginie uprawnień (np. LuckPerms) stworzyć logikę opartą na prefixie nazwy gracza lub skorzystać z Floodgate API, które pozwala sprawdzić czy dany UUID należy do gracza Bedrock.

Przykładowe sprawdzenie w LuckPerms przez kontekst: Floodgate integruje się z LuckPerms i dodaje kontekst floodgate:isfloodgate=true, który możesz wykorzystać do nadawania rang wyłącznie graczom Bedrock.

Floodgate na BungeeCord / Velocity

Jeśli prowadzisz sieć serwerów (hub + gameservery) za BungeeCord lub Velocity, konfiguracja Floodgate jest trochę bardziej złożona, ale daje największe możliwości. W takiej topologii Floodgate instalujesz w dwóch miejscach:

1. Na proxy (BungeeCord/Velocity) - instalujesz floodgate-bungee.jar lub floodgate-velocity.jar. To tutaj generowany jest klucz key.pem i odbywa się uwierzytelnianie Bedrock.
2. Na każdym serwerze backendowym - instalujesz floodgate-spigot.jar i konfigurujesz go tak, żeby używał klucza z proxy (wskazujesz ścieżkę do key.pem z proxy lub kopiujesz plik).

# Na backendowych serwerach, w plugins/floodgate/config.yml:
# Wskazuje proxy jako źródło danych Floodgate
player-link:
  enabled: true
  use-global-linking: true

Ważna zasada: ten sam plik key.pem musi być na proxy i na wszystkich backendach. Jeśli klucze się nie zgadzają, serwery backendowe odrzucą graczy Bedrock. Po wygenerowaniu klucza na proxy - skopiuj go na wszystkie backend serwery i wstaw do folderu plugins/floodgate/.

Przy konfiguracji proxy Geyser może działać jako:

• Plugin na samym BungeeCord/Velocity (najprostsze, jeden punkt wejścia)
• Osobny standalone proxy przed BungeeCord (bardziej zaawansowane, lepsze dla dużego ruchu)

Jeśli prowadzisz serwer crossplay na poważnie, topologia proxy jest zdecydowanie zalecanym rozwiązaniem - pozwala Geyserowi działać niezależnie od restart backendowych serwerów.

Porady

• Zawsze backupuj key.pem - to plik krytyczny. Jego utrata oznacza konieczność ponownego linkowania kont przez wszystkich graczy. Wrzuć go do sejfu razem z backupem worlda.
• Nie ustawiaj pustego prefixu na serwerach mixed Java+Bedrock. Kolizja nazw spowoduje błędy w pluginach uprawnień i ekonomii.
• Zaktualizuj whitelist i bany - jeśli masz whitelist lub bany oparte na nazwach graczy, pamiętaj że gracze Bedrock mają prefixowane nazwy. Blokowanie ".SteveXbox" to co innego niż blokowanie "SteveXbox".
• Floodgate + ViaVersion - jeśli używasz ViaVersion do obsługi wielu wersji Javy, Floodgate działa z nim bez problemów. Instaluj Floodgate przed ViaVersion.
• Sprawdź port w firewallu - gracze Bedrock podłączają się na porcie UDP 19132 (domyślny Geyser/Bedrock), nie TCP 25565. Upewnij się że firewall przepuszcza UDP na tym porcie.
• Debug przez logi - Floodgate loguje szczegółowe informacje o każdym połączeniu Bedrock. Jeśli gracz nie może się połączyć, pierwsze miejsce do sprawdzenia to logs/latest.log na poziomie DEBUG.

Kompatybilność

Floodgate jest kompatybilny z szerokim zakresem platform serwerowych:

Floodgate nie działa na Forge w standardowej konfiguracji - ekosystem Forge ma osobne rozwiązania crossplay. Nie działa też na CraftBukkit (brak aktywnego wsparcia dla tak starej platformy).

Jeśli chodzi o wersje Minecrafta, Floodgate obsługuje wersje Bedrock odpowiadające aktualnym wersjom obsługiwanym przez GeyserMC. Zespół GeyserMC regularnie aktualizuje oba pluginy po każdej aktualizacji Minecrafta, zazwyczaj w ciągu kilku dni od wydania. Sprawdź aktualnie obsługiwane wersje na stronie pobierania.

Popularne pluginy kompatybilne z Floodgate bez żadnej dodatkowej konfiguracji:

• EssentialsX - komendy, ekonomia, domy działają normalnie dla graczy Bedrock
• LuckPerms - konteksty Floodgate pozwalają na osobne uprawnienia dla Bedrock
• WorldGuard - ochrona regionów działa dla graczy Bedrock
• Citizens / NPC - gracze Bedrock widzą NPC i mogą z nimi wchodzić w interakcję
• CoreProtect - logi bloków dla graczy Bedrock działają prawidłowo z prefixowaną nazwą

Gotowy na crossplay? Zacznij od przewodnika po GeyserMC, a następnie wróć tutaj po konfigurację Floodgate. Razem te dwa pluginy dają kompletne rozwiązanie crossplay dla twojego serwera. Jeśli szukasz inspiracji jak promować serwer wśród graczy Bedrock, sprawdź też nasze zestawienie popularnych pluginów serwerowych.