Come risolvere i problemi di Save Roaming di Xbox in Unreal Engine nelle build GDK e Windows Store

L'incubo del Save Roaming con GDK

Configurate il pacchetto delle vostre build GDK per Xbox Series X e Windows Store, verificate che gli achievements si stiano sincronizzando, vedete l'icona di caricamento del cloud sync ruotare all'avvio, e poi assistete con orrore al fatto che i file di salvataggio dei giocatori rimangono completamente isolati su ciascuna piattaforma. Tutto sembra corretto dal punto di vista dell'utente: il sign-in va a buon fine, le notifiche si attivano e entrambe le build mostrano che i file di salvataggio persistono localmente tra i vari avvii del gioco. Eppure, i progressi su Xbox non effettuano mai il roaming verso la build PC, e viceversa.

Gestire le discrepanze dei dati di salvataggio è frustrante quanto fare troubleshooting dei multiplayer desyncs durante il gameplay live; entrambi i problemi derivano da un mismatch delle autorità di stato (state authorities). Nel caso di Xbox Play Anywhere (XPA), questo problema è raramente un fallimento a livello di console. Si tratta quasi sempre di una race condition nel modo in cui Unreal Engine mappa i suoi indici utente astratti basati su numeri interi ai sistemi di identità specifici del GDK di Microsoft. Vediamo perché succede e come risolverlo sia in C++ che in Blueprint.

L'anatomia di GDK Connected Storage

Per capire perché il save roaming fallisce, dobbiamo prima comprendere come il GDK di Microsoft gestisce i file di salvataggio degli utenti sotto il cofano. A differenza di Steam o di backend di gioco personalizzati, che in genere trattano i file di salvataggio come file raw caricati su un server remoto, the Microsoft Game Development Kit (GDK) utilizza il Connected Storage (l'API XGameSave). In questa architettura, i salvataggi non sono semplici percorsi di file raw, ma sistemi di container strutturati. Questi container contengono singoli blob di file di salvataggio che vengono sincronizzati in modo sicuro con i server Xbox Live.

Affinché il cloud save roaming funzioni tra la console Xbox e le build Windows Store (PC), il GDK si affida a una matrice di corrispondenza molto rigida. Le due build devono condividere esattamente gli stessi Title ID, Service Configuration ID (SCID) e Sandbox (come RETAIL o XDKS.1). Inoltre, il giocatore deve aver effettuato l'accesso allo stesso Microsoft Account (MSA) su entrambi i dispositivi. Infine, i nomi dei container generati dal vostro sistema di salvataggio devono corrispondere carattere per carattere; altrimenti, il sistema di sincronizzazione cloud li tratterà come set di dati indipendenti.

Inoltre, Connected Storage alloca un massimo di 256 megabyte di storage per utente, per titolo, con un limite per singolo container di 16 megabyte. Se il vostro sistema di salvataggio supera questi limiti rigidi, l'API fallisce silenziosamente o restituisce codici di errore che il sistema di salvataggio predefinito di Unreal Engine non fa risalire (bubble up) in superficie. È fondamentale progettare i vostri sistemi di salvataggio tenendo conto di questi vincoli, assicurandosi che le dimensioni dei file rimangano ridotte e strutturate.

La causa principale: la race condition del login asincrono

Il motivo più comune per il fallimento del save roaming del GDK nei progetti Unreal Engine è una sottile race condition nel modo in cui il gioco determina chi sta salvando. Su una console Xbox Series X, il sistema operativo è strutturato attorno ai profili controller attivi. All'avvio del gioco, un utente è già selezionato a livello di sistema operativo (OS). La console assegna automaticamente un XUserHandle al contesto di esecuzione del gioco, e Unreal Engine mappa questo profilo attivo su UserIndex 0 quasi immediatamente.

Su PC Windows, il flusso è completamente diverso. Il gioco si avvia immediatamente, senza richiedere un profilo attivo. Il flusso di login dell'app Xbox o del Windows Store viene eseguito in modo asincrono in background. Se il codice di gioco chiama LoadGameFromSlot o DoesSaveGameExist subito all'avvio (ad esempio, in una chiamata a GameInstance::Init o nel BeginPlay del menu principale), l'Online Subsystem del GDK non ha ancora completato il sign-in dell'utente.

Quando l'ISaveGameSystem di Unreal Engine (nello specifico l'implementazione GDK, FGameSaveSystemGDK) viene chiamato con UserIndex = 0 prima che un utente abbia effettuato il sign-in, viene utilizzato come fallback un utente guest locale. Il GDK mappa quindi questa sessione sullo storage offline locale del PC, aggirando il container sincronizzato in cloud. Una volta che il sign-in asincrono viene finalmente completato pochi secondi dopo, il gioco è già in esecuzione con i dati locali. Se il giocatore effettua un nuovo salvataggio, l'engine potrebbe scriverlo nel profilo guest locale o tentare di scrivere nel container MSA appena risolto, creando uno sdoppiamento di stato (state split) in cui il profilo cloud sulla console e il profilo locale su PC contengono file completamente diversi.

Come Unreal Engine mappa UserIndex a XUserHandle

Il sistema di salvataggio di Unreal Engine è stato progettato molto prima dei moderni sistemi di identità delle piattaforme. Utilizza un semplice intero (UserIndex) per differenziare i giocatori in co-op locale. Nell'implementazione GDK, l'engine cerca di risolvere questo intero in un XUserHandle chiamando helper interni del subsystem GDK. Se l'indice del giocatore si mappa su un handle non valido o non inizializzato, l'operazione di salvataggio esegue silenziosamente il fallback su una directory locale.

Per evitare questo, dovete assicurarvi di fare due cose. Primo, non dovete toccare il sistema di salvataggio finché l'interfaccia di identità dell'Online Subsystem non segnala che il giocatore ha effettuato completamente il login. Secondo, dovete risolvere il corretto UserIndex specifico della piattaforma associato alla FUniqueNetId dell'utente connesso, invece di presumere che il controller del giocatore locale sia sempre all'indice 0. Implementiamo un sistema che garantisca questo flusso di lavoro.

Guida all'implementazione: risolvere la race condition

Passo 1: La classe GDK Save Utility

Create una classe personalizzata UGDKSaveHelper che eredita da UBlueprintFunctionLibrary. Questa classe conterrà la logica per ottenere l'indice utente corretto e verificare che l'utente abbia effettuato il login. Ecco il file header (GDKSaveHelper.h):

#pragma once

#include "CoreMinimal.h"
#include "Kismet/BlueprintFunctionLibrary.h"
#include "Interfaces/OnlineIdentityInterface.h"
#include "GDKSaveHelper.generated.h"

UCLASS()
class HORIZON_API UGDKSaveHelper : public UBlueprintFunctionLibrary
{
    GENERATED_BODY()

public:
    UFUNCTION(BlueprintCallable, Category = "GDK Save System")
    static int32 GetGDKUserIndex(const APlayerController* PlayerController);

    UFUNCTION(BlueprintPure, Category = "GDK Save System")
    static bool IsPlayerLoggedInGDK(const APlayerController* PlayerController);
};

Ed ecco il file di implementazione (GDKSaveHelper.cpp), che utilizza l'online subsystem per mappare in modo sicuro il network ID del giocatore locale al suo indice utente specifico della piattaforma:

#include "GDKSaveHelper.h"
#include "GameFramework/PlayerController.h"
#include "OnlineSubsystem.h"
#include "OnlineSubsystemUtils.h"

int32 UGDKSaveHelper::GetGDKUserIndex(const APlayerController* PlayerController)
{
    if (!PlayerController)
    {
        UE_LOG(LogTemp, Warning, TEXT("GetGDKUserIndex: PlayerController is null."));
        return -1;
    }

    IOnlineSubsystem* OnlineSub = IOnlineSubsystem::Get();
    if (!OnlineSub)
    {
        UE_LOG(LogTemp, Warning, TEXT("GetGDKUserIndex: OnlineSubsystem is null."));
        return -1;
    }

    IOnlineIdentityPtr IdentityInterface = OnlineSub->GetIdentityInterface();
    if (!IdentityInterface.IsValid())
    {
        UE_LOG(LogTemp, Warning, TEXT("GetGDKUserIndex: IdentityInterface is invalid."));
        return -1;
    }

    ULocalPlayer* LocalPlayer = PlayerController->GetLocalPlayer();
    if (!LocalPlayer)
    {
        UE_LOG(LogTemp, Warning, TEXT("GetGDKUserIndex: LocalPlayer is null."));
        return -1;
    }

    FUniqueNetIdRepl UniqueId = LocalPlayer->GetPreferredUniqueNetId();
    if (!UniqueId.IsValid() || !UniqueId.GetUniqueNetId()->IsValid())
    {
        UE_LOG(LogTemp, Warning, TEXT("GetGDKUserIndex: Unique ID is not valid yet."));
        return -1;
    }

    int32 PlatformUserIndex = IdentityInterface->GetPlatformUserIndexFromUniqueNetId(*UniqueId.GetUniqueNetId());
    
    if (PlatformUserIndex == PLATFORMUSERID_NONE)
    {
        UE_LOG(LogTemp, Warning, TEXT("GetGDKUserIndex: PlatformUserIndex mapped to PLATFORMUSERID_NONE."));
        return -1;
    }

    UE_LOG(LogTemp, Log, TEXT("GetGDKUserIndex: Successfully resolved UserIndex to %d"), PlatformUserIndex);
    return PlatformUserIndex;
}

bool UGDKSaveHelper::IsPlayerLoggedInGDK(const APlayerController* PlayerController)
{
    if (!PlayerController)
    {
        return false;
    }

    IOnlineSubsystem* OnlineSub = IOnlineSubsystem::Get();
    if (OnlineSub)
    {
        IOnlineIdentityPtr IdentityInterface = OnlineSub->GetIdentityInterface();
        if (IdentityInterface.IsValid())
        {
            ULocalPlayer* LocalPlayer = PlayerController->GetLocalPlayer();
            if (LocalPlayer)
            {
                FUniqueNetIdRepl UniqueId = LocalPlayer->GetPreferredUniqueNetId();
                if (UniqueId.IsValid() && UniqueId.GetUniqueNetId()->IsValid())
                { 
                    ELoginStatus::Type LoginStatus = IdentityInterface->GetLoginStatus(*UniqueId.GetUniqueNetId());
                    return LoginStatus == ELoginStatus::LoggedIn;
                }
            }
        }
    }
    return false;
}

Passo 2: Modificare la logica di salvataggio e caricamento

Nei vostri Blueprint o nella gestione dello stato di gioco in C++, dovete fare il wrap delle chiamate di caricamento. Invece di chiamare LoadGameFromSlot subito all'avvio, implementate un controllo che attenda il sign-in. Effettuate il bind all'evento On Login Complete dall'Online Identity subsystem. Una volta attivato l'evento, verificate se l'utente ha completato il login, richiedete l'indice risolto e passatelo direttamente ai nodi di salvataggio del gioco.

Se il sign-in fallisce o il giocatore lo annulla, dovete gestire il gioco in uno stato di 'ospite' (guest). Avvisate il giocatore che i suoi progressi non saranno salvati nel cloud e rimarranno locali sulla macchina corrente. In questo modo si garantisce che il giocatore sia sempre consapevole dello stato dei suoi salvataggi, evitando perdite impreviste di progressi quando si cambia dispositivo.

Passo 3: Allineare i file di configurazione

Anche se il vostro codice risolve l'indice utente corretto, il save roaming fallirà se i file di configurazione nei pacchetti Xbox GDK e PC GDK non corrispondono. Aprite il vostro DefaultEngine.ini e assicuratevi che le impostazioni dell'online subsystem del GDK siano corrette. Il Title ID e il Service Configuration ID (SCID) devono corrispondere esattamente alla registrazione nel Partner Center di Microsoft.

[OnlineSubsystemGDK]
bEnabled=true
TitleId=1234ABCD
ServiceConfigId=12345678-1234-abcd-1234-1234567890ab
bEnableConfigService=true

[OnlineSubsystem]
DefaultPlatformService=GDK

Nel vostro MicrosoftGame.config (che impacchetta la vostra applicazione), verificate che l'Identity e il Title ID corrispondano esattamente ai valori all'interno della dashboard del vostro Partner Center:

<GameConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Identity Name="YourPublisher.YourGameName"
            Publisher="CN=12345678-1234-abcd-1234-1234567890ab"
            Version="1.0.0.0"/>
  
  <TitleId>1234ABCD</TitleId>
  <MSAAppId>0000000012345678</MSAAppId>
  
  <DevelopmentServer>RETAIL</DevelopmentServer>
</GameConfig>

Tenete presente che quando eseguite test in una sandbox (ad esempio XDKS.1), i vostri account di test devono essere aggiunti alla sandbox ed effettuare correttamente il sign-in all'interno dell'app Xbox su PC. Se l'app Xbox è connessa con un account diverso rispetto a Windows Store, l'API del GDK di Windows non riuscirà ad inizializzare il provider XGameSave di Microsoft, portando a directory locali non corrispondenti. Potete verificarlo controllando la cartella locale AppData per vedere dove vengono scritti i file di salvataggio.

Alternativa: Salvataggi in cloud senza lock-in della piattaforma tramite horizOn

Configurare le API Connected Storage del GDK di Microsoft, gestire i fallback guest offline e mantenere sandbox identiche tra ambienti PC e console può richiedere settimane di setup e debugging. E anche una volta funzionante, sarete vincolati all'ecosistema Microsoft. Questi salvataggi non effettueranno il roaming verso Steam, Epic Games Store, PlayStation o Nintendo Switch.

Invece di scrivere wrapper specifici per la piattaforma o ricorrere a configurazioni in tempo reale complesse come descritto in un tutorial sui WebSocket per Unreal Engine per backend in tempo reale, potete delegare completamente l'architettura del vostro stato di salvataggio a un servizio di backend agnostico rispetto alla piattaforma come horizOn. Utilizzando horizOn, la gestione dello stato di salvataggio è disaccoppiata dalle API specifiche della piattaforma. Potete autenticare i giocatori utilizzando la loro identità di piattaforma (come Steam, Epic o Xbox Live) e salvare i loro dati in un database cloud unificato.

Questo aggira completamente i problemi di mismatch della sandbox di Xbox, consentendo un vero e proprio cross-platform save roaming tra Steam, Xbox e PlayStation. Ecco un esempio concettuale di quanto sia semplice salvare i progressi del giocatore a livello globale utilizzando le API REST del servizio in C++ per Unreal Engine:

#include "HttpModule.h"
#include "Interfaces/IHttpRequest.h"
#include "Interfaces/IHttpResponse.h"
#include "Dom/JsonObject.h"
#include "Serialization/JsonWriter.h"
#include "Serialization/JsonSerializer.h"

void SaveToHorizonCloud(const FString& PlayerToken, const FString& SaveDataJson)
{
    TSharedRef<IHttpRequest, ESPMode::ThreadSafe> Request = FHttpModule::Get().CreateRequest();
    Request->SetURL(TEXT("https://api.horizon.pm/v1/save-state"));
    Request->SetVerb(TEXT("POST"));
    Request->SetHeader(TEXT("Content-Type"), TEXT("application/json"));
    Request->SetHeader(TEXT("Authorization"), FString::Printf(TEXT("Bearer %s"), *PlayerToken));
    
    TSharedPtr<FJsonObject> Payload = MakeShareable(new FJsonObject());
    Payload->SetStringField(TEXT("slot_name"), TEXT("SaveSlot1"));
    Payload->SetStringField(TEXT("data"), SaveDataJson);
    
    FString OutputString;
    TSharedRef<TJsonWriter<>> Writer = TJsonWriterFactory<>::Create(&OutputString);
    FJsonSerializer::Serialize(Payload.ToSharedRef(), Writer);
    
    Request->SetContentAsString(OutputString);
    Request->OnProcessRequestComplete().BindLambda([](FHttpRequestPtr Req, FHttpResponsePtr Res, bool bWasSuccessful)
    {
        if (bWasSuccessful && Res->GetResponseCode() == 200)
        {
            UE_LOG(LogTemp, Log, TEXT("Save state synchronized successfully."));
        }
        else
        {
            UE_LOG(LogTemp, Error, TEXT("Failed to sync save state to cloud."));
        }
    });
    
    Request->ProcessRequest();
}

Costruire da soli un sistema robusto di salvataggio in cloud richiede la configurazione di database globali, la gestione di token di sessione sicuri e la gestione dei conflitti di sincronizzazione offline, richiedendo facilmente dalle 4 alle 6 settimane di tempo di sviluppo dedicato. Con horizOn, questi servizi di backend sono già preconfigurati, permettendovi di pubblicare il vostro gioco invece di costruire infrastrutture di database. Semplifica la pipeline trasformandola da un grattacapo di configurazione multi-piattaforma a una singola chiamata API.

Best practice per l'architettura dei salvataggi cross-platform

Sia che decidiate di addentrarvi nella configurazione del Connected Storage del GDK di Microsoft o di astrarla con un servizio di backend, dovreste attenervi a queste best practice fondamentali:

1. Non salvare mai su Tick o Frame-End: Connected Storage limita le operazioni di scrittura per prevenire il deterioramento del disco e il throttling della sincronizzazione cloud. Eseguite salvataggi batch in trigger point specifici (checkpoint, transizioni di livello, uscita dai menu).
2. Implementate risolutori di conflitti di salvataggio (Save Conflict Resolvers): Se un salvataggio su PC ha un timestamp delle 14:00 e un salvataggio su Xbox ha un timestamp delle 14:05, non sovrascrivete ciecamente il salvataggio più vecchio. Presentate un prompt dell'interfaccia utente (UI) che mostra i tempi di gioco, i progressi del livello e i metadati, lasciando che sia il giocatore a scegliere lo stato attivo.
3. Validate l'integrità del file di salvataggio: Prima della scrittura, serializzate i dati di salvataggio e generate un hash MD5 o SHA-256. Salvate questo hash all'interno di un blocco di metadati separato per verificare che i download dei file non si siano corrotti durante il transito in cloud.
4. Gestite i sign-out in modo corretto: Nel GDK, i giocatori possono effettuare il sign-out tramite la dashboard di Xbox mentre il gioco è in esecuzione. Registratevi al delegate OnLoginStatusChanged e mettete immediatamente in pausa il gioco se l'utente attivo cambia.

Se siete pronti a implementare un sistema di salvataggio cloud scalabile e agnostico rispetto alla piattaforma senza i grattacapo di configurazione del GDK, potete iniziare oggi stesso. Scoprite di più provando horizOn gratuitamente o consultando la documentazione dell'API.

---

Fonte: Xbox/GDK XPA cross platform save roaming not working