Wie man Epic Online Services Unreal Blueprint Login-Fehler und Achievement-Fehler behebt

Sie kompilieren einen Shipping-Build Ihres Unreal Engine-Spiels, starten es aus dem Epic Games Launcher und klicken auf Ihren benutzerdefinierten Login-Button. Nichts passiert oder der Game-Client friert ein, und Ihre Logs füllen sich mit kryptischen Fehlermeldungen zur Authentifizierung. Noch schlimmer: Ihr Node zum Freischalten von Achievements wird ausgeführt, ohne sichtbare Fehler zu werfen, aber das Spielerprofil im Epic Games Store Overlay bleibt komplett leer. Diese Fehler treten bei der Integration von Storefront-APIs extrem häufig auf. Glücklicherweise lassen sie sich beheben, indem Sie Ihren asynchronen Execution-Flow korrigieren und verstehen, wie das Subsystem User-Identitäten mappt.

EOS-Authentifizierungs-Pipeline verstehen: EAID vs. PUID

Die Integration von Epic Online Services (EOS) über das Online Subsystem (OSS) der Unreal Engine erfordert den Umgang mit einem zweistufigen Identity-System. Die Epic Account ID (EAID) wird vom Auth Interface verwaltet. Sie validiert, wer der User auf Storefront-Ebene ist, und ermöglicht Features wie das Social-Overlay, Freundeslisten und Bibliotheksprüfungen im Epic Games Store.

Im Gegensatz dazu wird die Product User ID (PUID) vom Connect Interface verwaltet. Die PUID ist ein spielspezifischer Identifier, der den User mit Backend-Game-Services verknüpft. Zu diesen Services gehören Matchmaking, Stats, Cloud-Saves und Achievements.

Warum EAID- und PUID-Mismatches Achievements verhindern

Ein häufiges Fehlerbild tritt auf, wenn Entwickler sich erfolgreich über das Auth Interface authentifizieren (wodurch eine EAID generiert wird), aber das Subsystem den Login beim Connect Interface nicht erfolgreich abschließt. Da Achievements vom Connect Interface über PUIDs verwaltet werden, schlägt das Schreiben von Achievement-Fortschritten ohne aufgelöste PUID mit einem EOS_InvalidUser-Fehler fehl.

Bei Spielen, die ohne Storefront-Wrapper starten, loggen sich User normalerweise mit Anmeldedaten ein, die mit einer zentralen User-Tabelle abgeglichen werden. In einem modernen Storefront-Ökosystem wie dem Epic Games Store ist die Identität föderiert. Wenn Ihr Spiel startet, erhält es ein kryptografisches Ticket vom Launcher. Das Spiel leitet dieses Ticket dann an die Authentifizierungsserver der Storefront weiter. Das SDK gibt eine Epic Account ID zurück, die als eine Art Reisepass des Users für alle Spiele auf der Plattform dient.

Um jedoch den Datenschutz und die Cross-Play-Sicherheit zu gewährleisten, erlaubt Epic spielspezifischen Features wie Achievements nicht, die Epic Account ID direkt auszulesen. Stattdessen muss das Spiel das Connect Interface initialisieren, das einen zweiten Austausch durchführt, um eine Product User ID abzurufen. Diese Trennung stellt sicher, dass bei einem Hack Ihres Spiels die globalen Epic Account-Anmeldedaten der Spieler nicht gefährdet werden. Ohne die PUID befindet sich Ihr Spiel praktisch in einem nicht authentifizierten Gast-Status, was den Zugriff auf EGS-Features blockiert. Wenn Ihrer Credentials-Konfiguration oder Client-Policy im Epic Developer Portal die erforderlichen Berechtigungen fehlen, schlägt diese Verknüpfung fehl. Das Identity Interface meldet einen erfolgreichen Login, da der Epic-Account gültig ist, aber die Game-Services-Ebene kann keine Achievement-Daten schreiben, weil nie eine PUID verknüpft wurde.

Die Anatomie einer fehlerhaften Blueprint-Login-Sequenz

Viele Entwickler stoßen auf Login-Probleme, weil sie ihre Blueprint-Execution-Pins linear verketten. Das direkte Ziehen des Execution-Pins von einem Login-Node in einen Query Achievements- oder Write Achievement Progress-Node wird immer fehlschlagen.

Authentifizierungsanfragen müssen an das Epic-Backend gesendet werden und sind daher asynchron. Die Engine führt den Blueprint-Graph bereits im nächsten Frame weiter aus, lange bevor die Epic-Server die User-Credentials zurückgeben. Zu diesem Zeitpunkt ist die Unique Net ID des Spielers noch null.

Der „Missing Node“-Fehler: Race Conditions bei der asynchronen Ausführung

Wenn Sie Achievement-Nodes unmittelbar nach dem Login-Node aufrufen, wirft das Subsystem einen Silent-Error, da der gecachte User-Status leer ist. Der korrekte Workflow erfordert das Binden von Custom Events an die asynchronen Delegates des Subsystems.

Zudem übersehen Entwickler oft den entscheidenden Schritt, Achievements zu cachen, bevor sie darauf schreiben. Sie können den Fortschritt eines Achievements nicht ändern, ohne zuvor das aktuelle Schema vom Server abzufragen. Der Aufruf von Write Achievements ohne vorherigen Query Achievements-Aufruf führt zu einem Silent-Failure oder einem EOS_InvalidUser-Fehler in Ihrem Console-Log, da die lokale gecachte Achievement-Map die Größe 0 hat.

Der korrekte asynchrone Blueprint-Flow

Um dies zu beheben, müssen Sie den Login-Trigger vom Achievement-Update trennen. Rufen Sie zuerst den Login-Node auf und geben Sie die korrekten Authentifizierungs-Credentials an.

Binden Sie zweitens ein Event an das On Login Complete-Delegate des Identity Interfaces. Sobald dieses Event ausgelöst wird und einen Erfolgsstatus zurückgibt, rufen Sie die Unique Net ID des Users ab.

Übergeben Sie drittens diese ID an den Query Achievements-Node. Binden Sie schließlich ein Event an das On Query Achievements Complete-Delegate und rufen Sie Write Achievement Progress nur innerhalb dieses Callbacks auf.

Implementierung eines robusten EOS Login- & Achievement-Controllers in C++

Um diese asynchronen Operationen sauber zu verarbeiten, wird dringend empfohlen, den Authentifizierungs-Loop in C++ zu implementieren. Dies bietet direkten Zugriff auf das IOnlineSubsystem und seine Interfaces.

Nachfolgend finden Sie eine vollständige, produktionsbereite C++-Implementierung eines Login- und Achievement-Handlers:

#include "OnlineSubsystem.h"
#include "Interfaces/OnlineIdentityInterface.h"
#include "Interfaces/OnlineAchievementsInterface.h"
#include "OnlineSubsystemUtils.h"

void UEOSLoginHandler::LoginToEpicGames(APlayerController* PlayerController)

{
    if (!PlayerController) return;

    IOnlineSubsystem* Subsystem = IOnlineSubsystem::Get(TEXT("EOS"));
    if (!Subsystem)
    {
        UE_LOG(LogTemp, Warning, TEXT("EOS Subsystem not found. Make sure the plugin is enabled."));
        return;
    }

    IOnlineIdentityPtr Identity = Subsystem->GetIdentityInterface();
    if (Identity.IsValid())
    {
        FOnlineAccountCredentials Credentials;
        Credentials.Type = TEXT("ExchangeCode");
        Credentials.Id = TEXT("");
        Credentials.Token = TEXT(""); // The launcher passes this via command line arguments

        Identity->AddOnLoginCompleteDelegate_Handle(0, FOnLoginCompleteDelegate::CreateUObject(this, &UEOSLoginHandler::OnLoginComplete));
        Identity->Login(0, Credentials);
    }
}

void UEOSLoginHandler::OnLoginComplete(int32 LocalUserNum, bool bWasSuccessful, const FUniqueNetId& UserId, const FString& Error)
{
    if (!bWasSuccessful)
    { 
        UE_LOG(LogTemp, Error, TEXT("Epic Online Services Login Failed. Error: %s"), *Error);
        return;
    }

    UE_LOG(LogTemp, Log, TEXT("EOS Login Successful. ID resolved: %s"), *UserId.ToString());

    IOnlineSubsystem* Subsystem = IOnlineSubsystem::Get(TEXT("EOS"));
    IOnlineAchievementsPtr Achievements = Subsystem->GetAchievementsInterface();
    if (Achievements.IsValid())
    { 
        Achievements->QueryAchievements(UserId, FOnQueryAchievementsCompleteDelegate::CreateUObject(this, &UEOSLoginHandler::OnQueryAchievementsComplete));
    }
}

void UEOSLoginHandler::OnQueryAchievementsComplete(const FUniqueNetId& PlayerId, bool bWasSuccessful)
{
    if (!bWasSuccessful)
    {
        UE_LOG(LogTemp, Warning, TEXT("Failed to query achievements from Epic Developer Portal."));
        return;
    }

    UE_LOG(LogTemp, Log, TEXT("Achievements queried successfully. Now writing progress."));

    IOnlineSubsystem* Subsystem = IOnlineSubsystem::Get(TEXT("EOS"));
    IOnlineAchievementsPtr Achievements = Subsystem->GetAchievementsInterface();
    if (Achievements.IsValid())
    {
        FOnlineAchievementsWriteRef WriteObject = MakeShared<FOnlineAchievementsWrite>();
        WriteObject->SetFloatStat(TEXT("ACH_FIRST_BLOOD"), 100.0f);

        Achievements->WriteAchievements(PlayerId, WriteObject, FOnAchievementsWrittenDelegate::CreateUObject(this, &UEOSLoginHandler::OnAchievementsWritten));
    }
}

void UEOSLoginHandler::OnAchievementsWritten(const FUniqueNetId& PlayerId, bool bWasSuccessful)
{
    if (bWasSuccessful)
    {
        UE_LOG(LogTemp, Log, TEXT("Achievement successfully unlocked on Epic Games Store!"));
    }
    else
    {
        UE_LOG(LogTemp, Error, TEXT("Failed to write achievement progress. Check sandbox mappings."));
    }
}

Dieser Controller nutzt sequentielle Callbacks. Er stellt sicher, dass auf das Achievement Interface erst zugegriffen wird, wenn das Identity Interface sowohl die Epic Account ID als auch die Product User ID erfolgreich aufgelöst hat.

Konfiguration Ihrer DefaultEngine.ini-Datei für EOS

Blueprint-Login-Nodes können nicht initialisiert werden, wenn die Konfigurationen in Ihrer Config/DefaultEngine.ini-Datei fehlerhaft sind. Das Online Subsystem EOS-Plugin benötigt spezifische Parameter, um sich an Ihren Game-Client zu binden.

Verwenden Sie das folgende Konfigurations-Template, um sicherzustellen, dass Ihr Subsystem ordnungsgemäß initialisiert wird:

[OnlineSubsystem]
DefaultPlatformService=EOS

[OnlineSubsystemEOS]
bEnabled=true
bUseEpicConnect=true
ProductId=your_product_id_here
SandboxId=your_sandbox_id_here
DeploymentId=your_deployment_id_here
ClientId=your_client_id_here
ClientSecret=your_client_secret_here

[OnlineSubsystemEOS.Auth]
bUseEpicAccount=true

Die Konfiguration Ihrer DefaultEngine.ini-Datei fungiert als Brücke zwischen Ihren kompilierten Game-Binaries und dem Epic Developer Portal. Die Parameter unter [OnlineSubsystemEOS] müssen exakt mit Ihren Produkteinstellungen übereinstimmen.

Eine häufige Ursache für Verwirrung ist der Unterschied zwischen Client Credentials und Sandbox-IDs. Die Client-ID und das Client-Secret stellen die Anmeldedaten Ihres Game-Clients dar, mit denen er mit dem EOS-Backend kommunizieren kann. Die Sandbox-ID repräsentiert die spezifische Umgebung (wie Development, Staging oder Live), auf die Ihr Client zugreift.

Wenn Ihr Game-Client versucht, sich mit einer Sandbox-ID zu authentifizieren, die nicht mit der Client-Credentials-Policy übereinstimmt, wird die Authentifizierungsanfrage abgelehnt. Zudem muss das Flag bUseEpicConnect auf true gesetzt werden, damit das Online Subsystem das EAID-zu-PUID-Mapping automatisch im Hintergrund übernimmt.

Behebung von Overlay-Focus-Mismatches und Plattform-Integration

Das EOS-Plugin von Unreal stützt sich stark auf das Epic Games Overlay, um Benachrichtigungen anzuzeigen, Freundeseinladungen zu verarbeiten und OAuth-Web-Authentifizierungen durchzuführen. Wenn Ihr Game-Client einen Login mit dem Credential-Typ AccountPortal auslöst, öffnet das Betriebssystem ein Browserfenster oder blendet das Overlay ein.

Diese Weiterleitung verschiebt den Fokus weg vom Spielfenster. Wenn Ihre Input-Modi nicht darauf ausgelegt sind, den Fokusverlust abzufangen, kann das Spiel einfrieren oder hängende Tastatureingaben registrieren.

Die Behebung von Input-Problemen, die durch Overlays verursacht werden, ist ein altbekanntes Problem für PC-Entwickler. Beispielsweise kann die Overlay-Injektion mit Raw-Input-Treibern kollidieren und dazu führen, dass Tastatur- und Maus-States einfrieren. Um zu verhindern, dass diese Bugs das Spielerlebnis ruinieren, können Sie sich unsere Analyse ansehen: The Marathon Input Issues Fix: Architecting PC Games to Survive Overlay Conflicts.

Darüber hinaus werden Initialisierungsfehler beim Testen oft durch falsch konfigurierte Socket-Verbindungen oder Timeout-Schwellenwerte in Ihrer lokalen Konfiguration verursacht. Wenn Sie Treiber-Timeouts beim Session-Startup untersuchen, lesen Sie unseren Leitfaden unter Uefn Session Launch Timeout Nightmares: Diagnosing Unreal Engine Network Drivers.

Vereinfachung von Cross-Platform-Storefront-Backends

Die manuelle Konfiguration von Storefront-Subsystemen, das Schreiben von C++-Delegate-Chains und der Umgang mit plattformspezifischen Overlay-Fokus-Problemen ist extrem zeitaufwendig. Dies für mehrere Storefronts wie Steam, EGS und Konsolen zu tun, vervielfacht Ihren Entwicklungsaufwand.

Dies selbst zu entwickeln erfordert das Aufsetzen von Load Balancern, Database Sharding und SSL-Zertifikatsmanagement — locker 4-6 Wochen Arbeit.

Mit horizOn erhalten Sie ein vereinheitlichtes Cross-Platform-Backend, das diese Storefront-APIs abstrahiert. Anstatt sich mit Dual-Identity-Tokens (EAID/PUID), Epic-Sandboxes oder Steamworks-Initialisierungscode herumzuschlagen, nutzen Sie eine einzige API, die User-Profile, Achievements, Matchmaking und Leaderboards verwaltet.

horizOn fungiert als Brücke und synchronisiert Achievements und Spielerfortschritte automatisch mit der Storefront, über die der User das Spiel gestartet hat. So können Sie sich auf den Game-Loop konzentrieren, statt Storefront-Boilerplate zu schreiben. Das bedeutet, dass Ihre Spieler Achievements freischalten, auf Cloud-Saves zugreifen und nach Matches suchen können, unabhängig davon, welche Plattform oder welchen Launcher sie verwenden – ohne dass Sie eine einzige Zeile storefront-spezifischen SDK-Code schreiben müssen.

Moderne Best Practices für Epic Online Services-Integrationen

1. Asynchrone Nodes niemals direkt verketten: Warten Sie immer darauf, dass die Delegates OnLoginComplete und OnQueryAchievementsComplete ausgelöst werden, bevor Sie nachgelagerte Operationen wie das Schreiben von Stats oder Achievements ausführen.

2. Verbose Logging während der Entwicklung aktivieren: Fügen Sie die folgenden Zeilen zu Ihrer DefaultEngine.ini unter [Core.Log] hinzu, um versteckte EOS-Warnungen zu verfolgen:

   [Core.Log]
   LogOnline=VeryVerbose
   LogOnlineGame=VeryVerbose
   LogEOSSDK=VeryVerbose
   

3. Achievements im Dev Portal auf EOS mappen: Stellen Sie sicher, dass unter dem Epic Games Store (EGS) erstellte Achievements explizit Ihrem Epic Online Services (EOS)-Backend zugeordnet sind. Wenn sie nicht verknüpft sind, erkennt das EOS SDK die Achievement-ID nicht.

4. ExchangeCode in Shipping-Builds verwenden: Während der lokalen Entwicklung ist der Login-Typ Developer mit einem Dev Auth Tool praktisch, aber Sie müssen den Credentials-Typ in Shipping-Builds, die über den Epic Games Launcher gestartet werden, auf ExchangeCode umstellen. Die Verwendung des vom Launcher bereitgestellten Auth-Typs ExchangeCode überspringt die OAuth-Weiterleitung im Webbrowser, wodurch die Dauer der Login-Sequenz von 8–12 Sekunden manueller Benutzerinteraktion auf einen automatischen Handshake unter 500 ms verkürzt wird.

Storefront-Integrationen optimieren

Die Behebung von Epic Online Services Login- und Achievement-Fehlern in der Unreal Engine läuft darauf hinaus, die asynchrone Pipeline zu verstehen und Konfigurationsprofile perfekt aufeinander abzustimmen. Durch die saubere Verwaltung des Übergangs zwischen Identity- und Game-Service-Interfaces können Entwickler Silent-Errors eliminieren und ein nahtloses Spielerlebnis bieten.

Bereit, Ihr Multiplayer-Backend zu skalieren? Testen Sie horizOn kostenlos oder werfen Sie einen Blick in die API-Dokumentation.

---

Quelle: Epic Games Store (Online Services AND Achievements)