Dlaczego połączenie WebSocket w Unreal Engine C++ nie powiodło się (i jak to naprawić)

Podpinasz delegaty, podajesz URL ws://localhost:8080 i wywołujesz Connect(). Zamiast udanego handshake'a, Unreal Engine wyrzuca frustrująco ogólny błąd Connection failed. Sprawdzasz logi serwera — nic. Wklejasz ten sam URL do Postmana i łączy się natychmiast.

Każdy deweloper gier Multiplayer uderzył w tę ścianę. Gdy występuje błąd unreal engine c++ websocket connection failed, domyślne logowanie silnika nie daje prawie żadnego kontekstu. Podstawowa implementacja (LibWebSockets) domyślnie tłumi błędy sieciowe.

Niezależnie od tego, czy budujesz system matchmakingu, czat, czy próbujesz zastąpić HTTP polling backendem czasu rzeczywistego, niedziałające połączenie WebSocket całkowicie wstrzymuje postęp.

Oto dokładny proces techniczny debugowania i zabezpieczania połączeń WebSocket C++ w Unreal Engine 5.

Krok 1: Wymuszenie ładowania modułu WebSockets

Najczęstszym powodem natychmiastowego niepowodzenia połączenia jest brakujący lub niezaładowany moduł.

Dodanie "WebSockets" do PublicDependencyModuleNames w Build.cs jest wymagane, ale nie zawsze wystarczające. W zależności od tego, gdzie inicjalizujesz połączenie (np. Subsystem lub GameInstance), moduł może nie być w pamięci podczas wywołania FWebSocketsModule::Get().CreateWebSocket().

Aby to naprawić, załaduj moduł jawnie przed pierwszym połąceniem:

if (!FModuleManager::Get().IsModuleLoaded("WebSockets"))
{
    FModuleManager::Get().LoadModuleChecked("WebSockets");
}

Krok 2: Pułapka rozwiązywania localhost przez IPv6

Jeśli kod działa w Postmanie, ale nie w Unreal Engine, sprawdź URL. Przeglądarki i Postman automatycznie przełączają się między IPv6 (::1) a IPv4 (127.0.0.1) dla localhost. Stack sieciowy Unreal Engine jest bardziej rygorystyczny. Jeśli Twój lokalny serwer Node.js lub Go nasłuchuje tylko na IPv4, silnik może próbować rozwiązać localhost jako IPv6 i odrzucić połączenie.

Rozwiązanie: Nigdy nie używaj localhost w developmentcie lokalnym. Zawsze wpisuj dokładny adres IP.

Zmień: ws://localhost:8080/ws na ws://127.0.0.1:8080/ws

Krok 3: Odmaskowanie błędów LibWebSockets

Unreal Engine używa LibWebSockets (LWS). Aby zobaczyć błędy TLS handshake lub timeouty, włącz verbose logging w DefaultEngine.ini:

[Core.Log]
LogWebSockets=Verbose
LogHttp=Verbose

Krok 4: Naprawa błędów certyfikatów WSS (Secure WebSocket)

Połączenie działające na ws://, ale nie na wss://, to zazwyczaj problem z walidacją certyfikatu SSL/TLS. W packaged builds bundle certyfikatów nie jest dołączany domyślnie. LWS odrzuci połączenie, aby zapobiec atakom man-in-the-middle.

Sprawdź ustawienie Verify Peer w Project Settings -> Engine -> Network.

Implementacja WebSocket C++ odporna na błędy

Aby uniknąć cichych błędów, potrzebujesz architektury obsługującej czyszczenie delegatów i exponential backoff dla reintencji. Poleganie na pojedynczym Connect() sprawia, że systemy Multiplayer są niestabilne i prowadzi do desynchronizacji i błędnych stanów świata.

(Kod pozostaje bez zmian)

Najlepsze praktyki

1. Exponential Backoff: Nigdy nie ponawiaj połączenia natychmiast, aby nie wykonać ataku DDoS na własny Backend.
2. Czyszczenie delegatów: Używaj RemoveAll(this), aby uniknąć memory leaks i crashy.
3. Ping/Pong Keep-Alives: Load balancery zabijają bezczynne połączenia TCP. Wysyłaj ping JSON co 30-60 sekund.
4. Rozmiar bufora: LWS ma ograniczone bufory. Przy dużych JSON-ach (np. 5MB) połączenie może zostać zerwane.

Skalowanie Backend Multiplayer

Naprawienie błędu unreal engine c++ websocket connection failed to dopiero początek. Skalowanie wymaga load balancerów z obsługą WebSocketów i shardingu bazy danych.

Dzięki horizOn te usługi są prekonfigurowane. To zarządzany BaaS dla deweloperów gier. Obsługuj matchmaking i synchronizację czasu rzeczywistego przez jedno API.

Następne kroki

Zastosuj poprawkę IPv4 127.0.0.1 i włącz LogWebSockets verbose. Gotowy na skalowanie? Wypróbuj horizOn za darmo.