Cara Mengatasi Masalah Xbox Save Roaming Unreal Engine pada Build GDK dan Windows Store

Nightmare GDK Save Roaming

Anda melakukan packaging build GDK untuk Xbox Series X dan Windows Store, memastikan pencapaian (achievement) tersinkronisasi, melihat ikon cloud sync berputar saat booting, dan kemudian terkejut melihat file save pemain Anda tetap terisolasi sepenuhnya di masing-masing platform. Semua terlihat benar dari perspektif pengguna: proses sign-in berhasil, notifikasi muncul, dan kedua build menunjukkan file save tetap tersimpan secara lokal saat game dijalankan ulang. Namun, progres di Xbox tidak pernah melakukan roaming ke build PC, begitu pula sebaliknya.

Menangani diskrepansi data save sama frustrasinya dengan melakukan troubleshooting multiplayer desyncs selama gameplay berlangsung; kedua masalah ini berakar dari ketidakcocokan otoritas state (state authority mismatch). Dalam kasus Xbox Play Anywhere (XPA), masalah ini jarang disebabkan oleh kegagalan di level konsol. Masalah ini hampir selalu berupa race condition tentang bagaimana Unreal Engine memetakan indeks user berbasis integer yang abstrak ke sistem identitas spesifik GDK milik Microsoft. Mari kita pelajari mengapa hal ini terjadi dan bagaimana cara memperbaikinya di C++ maupun Blueprint.

Anatomi dari GDK Connected Storage

Untuk memahami mengapa save roaming gagal, pertama-tama kita harus memahami bagaimana GDK Microsoft menangani file save user di balik layar. Berbeda dengan Steam atau backend game kustom yang biasanya memperlakukan file save sebagai file mentah yang diunggah ke server jarak jauh, Microsoft Game Development Kit (GDK) menggunakan Connected Storage (API XGameSave). Di bawah arsitektur ini, save bukan berupa path file mentah melainkan sistem container yang terstruktur. Container ini menampung blob file save individu yang disinkronkan secara aman dengan server Xbox Live.

Agar cloud save roaming dapat berfungsi antara konsol Xbox dan build Windows Store (PC), GDK mengandalkan matriks pencocokan yang ketat. Kedua build harus memiliki Title ID, Service Configuration ID (SCID), dan Sandbox (seperti RETAIL atau XDKS.1) yang sama persis. Selain itu, pemain harus sign-in ke Microsoft Account (MSA) yang sama di kedua perangkat. Terakhir, nama container yang dihasilkan oleh save system Anda harus cocok karakter-demi-karakter; jika tidak, sistem sinkronisasi cloud akan menganggapnya sebagai kumpulan data yang terpisah.

Selain itu, Connected Storage mengalokasikan maksimum 256 megabyte penyimpanan per user, per title, dengan batas container individu sebesar 16 megabyte. Jika save system Anda melebihi batas keras (hard limit) ini, API akan mengalami kegagalan secara diam-diam (silently fail) atau mengembalikan kode error yang tidak dimunculkan (bubble up) ke permukaan oleh default save system milik Unreal Engine. Sangat penting untuk merancang save system Anda dengan mempertimbangkan batasan-batasan ini, guna memastikan ukuran file tetap kecil dan terstruktur.

Penyebab Utama: Race Condition pada Asynchronous Login

Alasan paling umum untuk kegagalan GDK save roaming dalam proyek Unreal Engine adalah adanya race condition yang halus tentang bagaimana game menentukan siapa yang melakukan penyimpanan. Pada konsol Xbox Series X, sistem operasi dibangun di sekitar profil controller yang aktif. Saat game melakukan booting, user sudah terpilih di level OS. Konsol secara otomatis menetapkan XUserHandle ke konteks eksekusi game, dan Unreal Engine memetakan profil aktif ini ke UserIndex 0 hampir seketika.

Di Windows PC, alurnya sangat berbeda. Game langsung melakukan booting tanpa meminta profil aktif terlebih dahulu. Alur login Xbox App atau Windows Store berjalan secara asinkron di latar belakang (background). Jika kode game Anda memanggil LoadGameFromSlot atau DoesSaveGameExist segera setelah booting (misalnya, pada panggilan GameInstance::Init atau BeginPlay di main menu Anda), Online Subsystem GDK belum menyelesaikan proses sign-in user.

Ketika ISaveGameSystem milik Unreal Engine (khususnya implementasi GDK, FGameSaveSystemGDK) dipanggil dengan UserIndex = 0 sebelum user melakukan sign-in, sistem akan beralih (fall back) ke local guest user. GDK kemudian memetakan sesi ini ke penyimpanan offline lokal di PC, melewati (bypassing) container yang tersinkronisasi dengan cloud. Begitu proses asynchronous sign-in akhirnya selesai beberapa detik kemudian, game sudah berjalan menggunakan data lokal. Jika pemain menulis data save baru, engine mungkin akan menulisnya ke profil guest lokal atau mencoba menulis ke container MSA yang baru teridentifikasi, menciptakan state split di mana profil cloud pada konsol dan profil lokal pada PC memiliki file yang sepenuhnya berbeda.

Bagaimana Unreal Engine Memetakan UserIndex ke XUserHandle

Save system Unreal Engine dirancang jauh sebelum adanya sistem identitas platform modern. Sistem ini menggunakan integer sederhana (UserIndex) untuk membedakan antar pemain dalam local co-op. Pada implementasi GDK, engine mencoba me-resolve integer ini menjadi XUserHandle dengan memanggil helper internal subsystem GDK. Jika indeks pemain dipetakan ke handle yang tidak valid atau belum diinisialisasi, operasi save akan secara diam-diam beralih (fall back) ke direktori lokal.

Untuk mencegah hal ini, Anda harus memastikan dua hal. Pertama, Anda tidak boleh menyentuh save system sampai antarmuka identitas Online Subsystem melaporkan bahwa pemain telah sepenuhnya login. Kedua, Anda harus me-resolve UserIndex spesifik platform yang benar yang terkait dengan FUniqueNetId user yang telah login, alih-alih mengasumsikan bahwa player controller lokal selalu menggunakan indeks 0. Mari kita implementasikan sistem yang menjamin alur kerja ini.

Panduan Implementasi: Menyelesaikan Masalah Race Condition

Langkah 1: GDK Save Utility Class

Buat class kustom UGDKSaveHelper yang mewarisi UBlueprintFunctionLibrary. Class ini akan berisi logika untuk mendapatkan indeks user yang benar dan memastikan user telah login. Berikut adalah 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);
};

Dan berikut adalah file implementasi (GDKSaveHelper.cpp) yang menggunakan online subsystem untuk memetakan network ID pemain lokal dengan aman ke indeks user spesifik platform mereka:

#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;
}

Langkah 2: Memodifikasi Logika Save dan Load Anda

Dalam manajemen game state Blueprint atau C++ Anda, Anda harus membungkus (wrap) panggilan load Anda. Alih-alih memanggil LoadGameFromSlot segera saat startup, implementasikan pemeriksaan yang menunggu proses sign-in. Lakukan binding ke event On Login Complete dari Online Identity subsystem. Setelah event tersebut dipicu, periksa apakah user telah sepenuhnya login, dapatkan indeks hasil resolve mereka, dan teruskan langsung ke node save game.

Jika sign-in gagal atau pemain membatalkannya, Anda harus menangani game dalam state 'guest'. Berikan peringatan kepada pemain bahwa progres mereka tidak akan disimpan ke cloud dan akan tetap berada secara lokal di mesin saat ini. Ini memastikan bahwa pemain selalu mengetahui status penyimpanan mereka, mencegah hilangnya progres yang tidak terduga saat berpindah perangkat.

Langkah 3: Menyelaraskan File Konfigurasi

Bahkan jika kode Anda berhasil me-resolve indeks user yang benar, save roaming akan gagal jika file konfigurasi pada paket Xbox GDK dan PC GDK tidak cocok. Buka file DefaultEngine.ini Anda dan pastikan pengaturan GDK online subsystem sudah benar. Title ID dan Service Configuration ID (SCID) harus cocok persis dengan registrasi Microsoft Partner Center Anda.

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

[OnlineSubsystem]
DefaultPlatformService=GDK

Dalam file MicrosoftGame.config Anda (yang memaketkan aplikasi Anda), verifikasi bahwa Identity dan Title ID cocok persis dengan nilai di dalam dashboard Partner Center Anda:

<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>

Perlu diingat bahwa saat melakukan pengujian dalam sandbox (misalnya XDKS.1), akun pengujian Anda harus ditambahkan ke sandbox dan harus sign-in dengan benar di dalam Xbox App di PC. Jika Xbox App terhubung dengan akun yang berbeda dari Windows Store, API Windows GDK akan gagal menginisialisasi provider XGameSave, yang menyebabkan direktori lokal tidak cocok. Anda dapat memverifikasi ini dengan memeriksa folder AppData lokal untuk melihat di mana file save ditulis.

Alternatif: Cloud Save Tanpa Platform Lock-In via horizOn

Mengonfigurasi API GDK Connected Storage milik Microsoft, menangani fallback guest secara offline, dan mempertahankan sandbox yang identik di lingkungan PC dan konsol dapat memakan waktu berminggu-minggu untuk setup dan debugging. Bahkan setelah berhasil, Anda akan terkunci dalam ekosistem Microsoft (platform lock-in). Data save ini tidak akan bisa melakukan roaming ke Steam, Epic Games Store, Playstation, atau Nintendo Switch.

Alih-alih menulis wrapper spesifik platform, atau menggunakan setup real-time yang kompleks seperti yang dijelaskan dalam Unreal Engine WebSockets tutorial untuk backend real-time, Anda dapat mendelegasikan seluruh arsitektur save state Anda ke backend service yang platform-agnostic seperti horizOn. Dengan menggunakan horizOn, manajemen save state didecoupling dari API spesifik platform. Anda mengautentikasi pemain menggunakan identitas platform mereka (seperti Steam, Epic, atau Xbox Live) dan menyimpan data mereka ke database cloud terpadu.

Langkah ini menghindari masalah ketidakcocokan sandbox Xbox sepenuhnya, memungkinkan cross-platform save roaming yang sesungguhnya antara Steam, Xbox, dan PlayStation. Berikut adalah contoh konseptual betapa sederhananya menyimpan progres pemain secara global menggunakan REST API layanan tersebut dalam C++ 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();
}

Membangun sendiri sistem cloud save yang andal memerlukan setup database global, manajemen session token yang aman, serta penanganan konflik sinkronisasi offline—yang dapat memakan waktu 4 hingga 6 minggu kerja engineering khusus. Dengan horizOn, backend service ini sudah dikonfigurasi sebelumnya, sehingga Anda dapat segera merilis game alih-alih sibuk membangun infrastruktur database. Ini menyederhanakan pipeline Anda dari masalah konfigurasi multi-platform yang membingungkan menjadi satu panggilan API saja.

Best Practice untuk Arsitektur Cross-Platform Save

Baik Anda memilih untuk bersusah payah mengonfigurasi Connected Storage GDK Microsoft atau mengabstraksikannya dengan backend service, Anda harus mematuhi beberapa best practice inti berikut:

1. Never Save on Tick or Frame-End: Connected Storage membatasi operasi penulisan untuk mencegah degradasi disk dan pembatasan (throttling) sinkronisasi cloud. Lakukan batch save pada trigger point tertentu (checkpoint, transisi level, menu exit).
2. Implement Save Conflict Resolvers: Jika sebuah save di PC memiliki timestamp pukul 14.00 dan save di Xbox memiliki timestamp pukul 14.05, jangan langsung menimpa data save yang lebih lama secara membabi buta. Tampilkan prompt UI yang menunjukkan waktu bermain, progres level, dan metadata, lalu biarkan pemain memilih state aktif mereka.
3. Validate Save File Integrity: Sebelum menulis data, lakukan serialisasi data save Anda dan buat hash MD5 atau SHA-256. Simpan hash ini di dalam blok metadata terpisah untuk memverifikasi bahwa file yang diunduh tidak rusak selama proses pengiriman melalui cloud.
4. Gracefully Handle Sign-Outs: Di dalam GDK, pemain dapat sign-out melalui dashboard Xbox saat game sedang berjalan. Daftarkan delegate OnLoginStatusChanged dan segera lakukan pause pada game jika user aktif berubah.

Jika Anda siap untuk mengimplementasikan sistem cloud save yang scalable dan platform-agnostic tanpa pusing memikirkan konfigurasi GDK, Anda dapat memulainya hari ini. Pelajari lebih lanjut dengan mencoba horizOn secara gratis atau meninjau API docs.

---

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