Dlaczego uruchamianie sesji kończy się timeoutem: Rozwiązanie błędu handshake w UEFN 'Failed to Connect to Beacon'

Każdy deweloper gier multiplayer zna to uczucie bezradności, gdy uruchamia sesję playtestową tylko po to, by patrzeć na zawieszony pasek postępu, który ostatecznie zwraca generyczny błąd matchmakingu. W Unreal Editor for Fortnite (UEFN) ta frustracja często objawia się konkretnym, blokującym błędem w logach: "Failed to connect to beacon. Your backend is: Fortnite Your Build is: ++Fortnite+Release-41.00-CL-54618515 Region: BR BuildIdOverride is: 53972989". Ten błąd blokuje twórcom dostęp do serwerów testowych na wiele godzin, zatrzymując lokalne cykle iteracji i zaburzając harmonogramy prac deweloperskich.

Ta utrata połączenia rzadko wynika z prostego braku dostępu do Internetu. Zamiast tego wskazuje na problem z początkowym protokołem handshake UDP, którego Unreal Engine używa do koordynacji sesji graczy przed załadowaniem assetów gry. Aby wyeliminować ten problem ze stabilnością, deweloperzy muszą zrozumieć, jak działają online beacons w Unreal Engine pod maską, w jaki sposób infrastruktura matchmakingu Epic Games wchodzi w interakcję z lokalnymi klientami oraz jak skonfigurować sieć lokalną, aby uniknąć gubienia pakietów (packet loss).

Jak działają beacons w Unreal Engine pod maską

Lekki handshake UDP vs. pełny Game Travel

W przeciwieństwie do standardowych połączeń gameplayowych, które ładują cały poziom (UWorld) i serializują wszystkie replikowane aktory (replicated actors) poprzez główny net driver, online beacons ustanawiają lekki kanał kontrolny UDP przy użyciu AOnlineBeaconHost i AOnlineBeaconClient. Ta architektura odpytuje o dostępność slotów na serwerze, obsługuje żądania rezerwacji i wymienia niestandardowe dane telemetryczne, zużywając minimalną przepustowość. W UEFN beacon matchmakingowy jest wdrażany w celu weryfikacji zgodności wersji klienta przed rozpoczęciem ładowania mapy. Ustanawiając oddzielny kanał socketu, silnik unika narzutu związanego ze spawnowaniem pełnego player controllera i przechodzeniem (traveling) do docelowego poziomu, jeśli serwer jest pełny lub działa na niekompatybilnym buildzie.

Cykl życia matchmakingu w UEFN

Kiedy klikasz przycisk Launch Session w UEFN, edytor negocjuje z serwerami matchmakingowymi Epic, aby zlokalizować lub uruchomić (spin up) instancję Dedicated Server z aktualnym buildem Twojego projektu. Matchmaking backend zwraca connection string zawierający adres IP, dynamiczny port oraz unikalny kryptograficzny token sesji. Klient UEFN na Twoim lokalnym komputerze inicjuje beacon client w celu wykonania handshake'u ze zdalną instancją. Jeśli handshake się powiedzie, klient otrzymuje zgodę na travel i rozpoczyna pobieranie skookowanych (cooked) assetów mapy. Kiedy pojawia się błąd sieciowy, taki jak failed to connect to beacon uefn, handshake kończy się niepowodzeniem na tym wstępnym etapie kontrolnym, co uniemożliwia klientowi rozpoczęcie pełnej sekwencji travel.

Jeśli uruchamianie Twojej sesji nie powiedzie się i pozostaje zawieszone na ekranie ładowania przez kilka minut przed wystąpieniem błędu, możesz również doświadczać problemów opisanych w UEFN session launch timeout nightmares, które często są powiązane ze źle skonfigurowanymi sterownikami sieciowymi (network drivers) lub wirtualnymi kartami sieciowymi (virtual network adapters).

Dlaczego sesje UEFN zgłaszają "Failed to Connect to Beacon"

1. Packet Loss i problemy z routingiem regionalnym

Backend Epic dynamicznie przekierowuje sesje playtestowe UEFN do regionalnych instancji chmurowych (takich jak North America East, Europe czy Brazil). Jeśli routing Twojego lokalnego dostawcy internetu (ISP) wykazuje packet loss przekraczający 2% lub jeśli opóźnienie (latency) wzrośnie powyżej 180 ms podczas handshake'u, pakiety UDP zawierające żądanie beacon zostaną odrzucone. Beacon client ma rygorystyczny connection timeout (zazwyczaj 15,0 sekund). Jeśli pakiet zawierający potwierdzenie handshake'u z serwera nie dotrze w tym oknie czasowym, klient przerywa połączenie, co prowadzi do komunikatu o błędzie "failed to connect".

Aby potwierdzić routing packet loss, deweloperzy mogą uruchomić traceroute lub pathping do usług Epic. Na przykład wykonanie pathping qnet.epicgames.com w wierszu poleceń przetestuje pingiem każdy hop sieciowy 100 razy w okresie 250 sekund. Jeśli zauważysz, że dany hop wykazuje ponad 1% packet loss na brzegu sieci Twojego ISP, połączenie beacon nie powiedzie się podczas uruchamiania sesji, ponieważ handshaki UDP są niezwykle delikatne w porównaniu do TCP.

Kiedy edytor UEFN wysyła żądanie połączenia, wysyła serię pakietów UDP. Protokół niezawodnego kanału (reliable channel) Unreal Engine oczekuje pakietu potwierdzenia (ACK) dla każdego wysłanego pakietu kontrolnego. Jeśli Twój lokalny ISP kieruje ruch przez przeciążone kable oceaniczne lub błędnie skonfigurowane węzły, te pakiety UDP są po cichu odrzucane bez żadnych komunikatów o błędach ICMP. Edytor pozostaje w stanie oczekiwania do momentu wygaśnięcia wewnętrznego licznika connection timeout, zgłaszając błąd matchmakingu, ponieważ wymagane handshaki nigdy się nie zakończyły.

2. Niezgodności wersji i rozbieżności Build ID

Podczas głównych aktualizacji silnika Fortnite (np. przejścia na Release-41.00), serwery backendowe Epic i lokalne instalacje UEFN mogą przejściowo stracić synchronizację. Parametr BuildIdOverride (np. 53972989) reprezentuje konkretny identyfikator kompilacji assetów projektu. Jeśli serwer matchmakingowy spróbuje powiązać sesję Twojego edytora z instancją hosta działającą na innym build ID lub wersji CL (Changelist), beacon host aktywnie odrzuci połączenie. Klient rejestruje to odrzucenie jako błąd połączenia, ponieważ socket hosta odmawia ukończenia handshake'u z niezgodnym klientem.

3. Port Exhaustion UDP i blokady lokalnego firewallu

Beacony Unreal Engine komunikują się przez dynamiczne porty UDP. Podczas gdy standardowe gry domyślnie korzystają z portu 7777, sesje UEFN rutynowo alokują porty w zakresie dynamicznym/ephemeral (między 10000 a 65535), aby obsługiwać współbieżne instancje serwerów. Jeśli Twój lokalny router korzysta z restrykcyjnego symetrycznego NAT (symmetric NAT), lub jeśli Windows Firewall jest skonfigurowany tak, aby odrzucać niepożądane wychodzące pakiety UDP na niestandardowych portach, handshaki beaconów zostaną po cichu zablokowane. Socket klienta pozostanie w stanie Connecting aż do momentu timeoutu, zgłaszając błąd matchmakingu.

W lokalnych sesjach testowych UEFN uruchamia lokalną instancję klienta Fortnite, która musi powiązać się (bind) z lokalnym portem loopback, jednocześnie komunikując się ze zdalnymi serwerami matchmakingowymi Epic. Jeśli masz uruchomionych wiele instancji edytora lub jeśli zawieszone procesy w tle nadal blokują lokalne porty, napotkasz problem port exhaustion. Gdy lokalny sterownik sieciowy (network driver) nie może przydzielić socketu w zakresie portów ephemeral, klient nie jest w stanie nawet zainicjować połączenia wychodzącego, co prowadzi do cichego błędu, zanim jakiekolwiek pakiety opuszczą Twoją kartę sieciową (NIC).

W skrajnych przypadkach wyczerpanie zasobów po stronie serwera może całkowicie uniemożliwić odpowiedź beacon hosta, co prowadzi do zerwania socketu (socket drop). Jeśli Twój Dedicated Server jest całkowicie zawieszony z powodu niezoptymalizowanego kodu gameplayowego, zapoznaj się z artykułem ultimate UEFN server crash fix protocol, aby ustabilizować ticki po stronie serwera.

Deep Dive: Analiza kodu połączenia beacon

Aby zrozumieć, jak silnik zarządza tymi stanami, przyjrzyjmy się typowej implementacji AOnlineBeaconClient w Unreal Engine. Ta klasa C++ kontroluje inicjalizację socketu, handshake połączenia oraz obsługę timeoutów.

// Source: CustomBeaconClient.h
#pragma once

#include "CoreMinimal.h"
#include "OnlineBeaconClient.h"
#include "CustomBeaconClient.generated.h"

UCLASS()
class MYMULTIPLAYERGAME_API ACustomBeaconClient : public AOnlineBeaconClient
{
    GENERATED_BODY()

public:
    ACustomBeaconClient();

    // Initiates the connection to the host beacon
    bool ConnectToSessionHost(const FString& ConnectURL, float TimeoutSeconds);

    // Override connection failure handlers
    virtual void OnFailure() override;
    virtual void OnConnectionTimeout() override;

protected:
    // Handle completed handshake response from the server host
    virtual void OnBeaconHandshakeComplete();
};

// Source: CustomBeaconClient.cpp
#include "CustomBeaconClient.h"
#include "OnlineSubsystemUtils.h"

ACustomBeaconClient::ACustomBeaconClient()
{
    // Default fallback timeout in seconds
    ConnectionTimeout = 15.0f;
}

bool ACustomBeaconClient::ConnectToSessionHost(const FString& ConnectURL, float TimeoutSeconds)
{
    ConnectionTimeout = TimeoutSeconds;
    
    FURL URL(nullptr, *ConnectURL, TRAVEL_Absolute);
    if (URL.Valid)
    {
        UE_LOG(LogNet, Log, TEXT("Initiating beacon handshake to URL: %s with timeout: %.2f seconds"), *ConnectURL, ConnectionTimeout);
        return ConnectToHost(URL);
    }
    
    UE_LOG(LogNet, Warning, TEXT("Failed to parse connection URL for beacon client: %s"), *ConnectURL);
    return false;
}

void ACustomBeaconClient::OnFailure()
{
    UE_LOG(LogNet, Error, TEXT("Beacon handshake failed. Internal network state: %s"), *GetConnectionStateString());
    Super::OnFailure();
}

void ACustomBeaconClient::OnConnectionTimeout()
{
    UE_LOG(LogNet, Error, TEXT("Beacon connection timed out after %.2f seconds. Diagnostic: UDP packets blocked or server unresponsive."), ConnectionTimeout);
    Super::OnConnectionTimeout();
}

Dostosowanie konfiguracji sieciowej w DefaultEngine.ini

Choć twórcy UEFN nie mogą modyfikować kodu C++ backendu Epic, deweloperzy pracujący nad niestandardowymi projektami w Unreal Engine mogą konfigurować progi beaconów bezpośrednio w plikach konfiguracycznych swojego projektu. Dostosowanie tych wartości pozwala klientom o wolniejszych połączeniach sieciowych na pomyślne negocjowanie handshake'ów:

[/Script/OnlineSubsystemUtils.OnlineBeaconClient]
ConnectionTimeout=25.0
BeaconConnectionInitialTimeout=10.0

[/Script/OnlineSubsystemUtils.OnlineBeaconHost]
BeaconPort=15000
MaxConcurrentConnections=256

Zwiększenie ConnectionTimeout z 15.0 do 25.0 sekund zapewnia kluczowy bufor dla graczy na połączeniach o wysokim opóźnieniu (takich jak internet satelitarny lub długodystansowy routing regionalny), zapobiegając przedwczesnemu zamykaniu socketów.

Przewodnik krok po kroku: Jak naprawić błąd "Failed to Connect to Beacon"

Jeśli regularnie tracisz dostęp do sesji UEFN z powodu tego błędu, wykonaj poniższe kroki rozwiązywania problemów, aby zweryfikować i naprawić swój stos sieciowy (network stack):

Krok 1: Skonfiguruj reguły wychodzące UDP w firewallu

Windows Firewall może blokować ruch wychodzący na portach UDP ephemeral, jeśli uprawnienia pliku wykonywalnego UEFN zostaną uszkodzone podczas aktualizacji. Uruchom poniższy skrypt PowerShell jako Administrator, aby automatycznie utworzyć wymagane reguły:

# Define the target executable path for UEFN
$UefnPath = "C:\Program Files\Epic Games\Fortnite\Engine\Binaries\Win64\UnrealEditor.exe"

# Configure Outbound Allow Rule for UDP traffic
New-NetFirewallRule -DisplayName "Allow UEFN Outbound UDP" `
    -Direction Outbound `
    -Program $UefnPath `
    -Protocol UDP `
    -Action Allow `
    -Enabled True

# Configure Inbound Allow Rule for UDP traffic
New-NetFirewallRule -DisplayName "Allow UEFN Inbound UDP" `
    -Direction Inbound `
    -Program $UefnPath `
    -Protocol UDP `
    -Action Allow `
    -Enabled True

Krok 2: Opróżnij cache DNS i zresetuj stos TCP/IP

Uszkodzony cache DNS lub błędnie skonfigurowane katalogi Winsock mogą zakłócić routing pakietów UDP do węzłów matchmakingowych Epic.

1. Otwórz PowerShell lub Wiersz polecenia (Command Prompt) jako administrator.
2. Wykonaj kolejno następujące polecenia:

   ipconfig /flushdns
   netsh int ip reset
   netsh winsock reset
   

3. Uruchom ponownie komputer, aby zastosować zresetowaną konfigurację i zreiniocjować karty sieciowe (network adapters).

Krok 3: Wyczyść cache Epic Games Launcher i UEFN

Niezgodności w lokalnym cache mogą skutkować tym, że launcher będzie wysyłał przestarzałe dane uwierzytelniające lub niezgodne Build ID podczas negocjacji sesji.

1. Zamknij całkowicie Epic Games Launcher i UEFN.
2. Naciśnij Win + R, wpisz %localappdata% i naciśnij Enter.
3. Znajdź folder EpicGamesLauncher i przejdź do Saved. Usuń folder webcache.
4. Znajdź folder UnrealEditorFortnite i przejdź do Saved. Usuń katalogi Crashes, Logs oraz StagedBuilds, aby wymusić ponowne zbudowanie konfiguracji builda.

Krok 4: Zreautoryzuj się i wymuś synchronizację builda

Jeśli UEFN zachowa stary token uwierzytelniający, beacon host Epic odrzuci próby połączenia.

1. Otwórz Epic Games Launcher, kliknij ikonę swojego profilu i wyloguj się ze swojego konta.
2. Uruchom ponownie launcher, zaloguj się ponownie i przejdź do swojej Biblioteki.
3. Kliknij three kropki obok Unreal Editor for Fortnite, wybierz Zarządzaj (Manage), a następnie kliknij Zweryfikuj (Verify).
4. Czasami regionalne węzły matchmakingu stają się tymczasowo przeciążone lub zdesynchronizowane podczas wdrażania aktualizacji (rolling updates). W UEFN przejdź do ustawień i tymczasowo zmień swój region matchmakingu z 'Auto' na konkretny sąsiedni region (np. zmieniając z Brazylii na US-East). Wymusi to na backendzie alokację kontenera serwera w innej regionalnej podsieci, pozwoli ominąć przeciążenie lokalnego routingu i zreicjować handshake beaconu na czystym węźle hosta.
5. Uruchom UEFN, open swój projekt i spróbuj rozpocząć sesję. Ten proces wymusi na edytorze synchronizację lokalnych metadanych builda z działającym backendem matchmakingu.

Ograniczanie wąskich gardeł matchmakingu z horizOn

Konfiguracja, utrzymanie i skalowanie Dedicated Server Beacons to jedne z najbardziej skomplikowanych aspektów inżynierii multiplayer. Budowa własnego backendu do koordynacji matchmakingu, uruchamiania instancji serwerów on-demand i zarządzania regionalnym routingiem wymaga wdrożenia Load Balancerów, shardingu baz danych oraz zarządzania certyfikatami SSL – co dla doświadczonego backend engineer oznacza łatwo 4-6 tygodni pracy nad samą infrastrukturą.

Dzięki integracji z horizOn te skomplikowane usługi backendowe otrzymujesz skonfigurowane out of the box. Menedżer serwerów gier (game server manager) dostarczany przez platformę automatycznie obsługuje regionalne aprowizowanie kontenerów (container provisioning), monitoruje stan serwerów (server health) i zapewnia, że klienci mogą bezpiecznie przeprowadzić handshake z host beaconami bez doświadczania cichych strat pakietów UDP (silent UDP drops) czy błędów niezgodności wersji. Z horizOn możesz skupić się na pisaniu gameplay logic i projektowaniu wciągających światów, pozostawiając zawiłości niskopoziomowego routingu sesji dedykowanej, przetestowanej w boju platformie serwerowej.

Sprawdzone w boju dobre praktyki dla połączeń sesyjnych w Unreal Engine

1. Zaimplementuj dynamiczne ponowne próby beacon timeout: Nie polegaj na pojedynczej próbie połączenia. Wdróż pętlę retries po stronie klienta, która spróbuje nawiązać połączenie ponownie 3 razy z wykładniczym opóźnieniem (exponential backoff, np. 2.0s, 4.0s i 8.0s) przed wyrzuceniem błędu widocznego dla użytkownika.
2. Odłącz wirtualne karty sieciowe: Wyłącz nieużywane wirtualne karty sieciowe (takie jak te utworzone przez Docker, Hamachi czy stare instalacje VPN) w ustawieniach połączeń sieciowych systemu Windows. Adaptery te mogą zmieniać kolejność bindowania socketów klienta, kierując pakiety UDP Unreal Engine w martwe punkty.
3. Monitoruj żywotność pakietów wychodzących poprzez MTU: Jeśli Maximum Transmission Unit (MTU) Twojego routera jest skonfigurowany na zbyt niską wartość, duże pakiety handshake zawierające tokeny sesji ulegną fragmentacji. Jeśli jakikolwiek fragment zostanie utracony, cały pakiet przepadnie. Upewnij się, że MTU routera jest ustawione na standardowe 1500 bajtów, aby pomieścić duże ładunki sieciowe (network payloads).
4. Loguj stany handshake'u sieciowego: Zawsze loguj szczegółowe stany AOnlineBeaconClient::GetConnectionStateString() podczas dewelopmentu. Daje to natychmiastowy dowód diagnostyczny, czy błąd wystąpił podczas rozwiązywania DNS, bindowania socketu, czy właściwego handshake'u pakietów.
5. Używaj filtrów UDP w Wireshark podczas handshake'ów: Podczas lokalnego debugowania błędów połączeń uruchom przechwytywanie pakietów za pomocą Wiresharka z filtrem udp.port == 7777 || udp.port == 15000 lub szerszym zakresem odpowiadającym zakresowi dynamicznemu Unreal Engine. Szukaj wychodzących pakietów kontrolnych będących odpowiednikami SYN, które nie otrzymują żadnej odpowiedzi przychodzącej. Jeśli widzisz ruch wychodzący, ale zero pakietów przychodzących, firewall na routerze klienta lub w kontenerze hosta w chmurze odrzuca ruch handshake.

Podsumowanie

Rozwiązywanie problemów z połączeniem w UEFN wymaga metodycznego podejścia do konfiguracji sieciowej. Zapewniając odpowiednie uprawnienia dla reguł wychodzących w firewallu, czyszcząc uszkodzone cache sieciowe oraz weryfikując synchronizację wersji, możesz trwale wyeliminować frustrującą pętlę błędów failed to connect to beacon uefn.

Chcesz skalować swój multiplayer backend i uniknąć problemów z konfiguracją sieci? Wypróbuj horizOn za darmo lub zapoznaj się z API docs, aby zobaczyć, jak proste może być dedykowane hostowanie sesji.

---

Źródło: "Failed to connect to beacon" upon launching session