Implementação do Game Saves com o GDK de outubro de 2025

Este guia aborda a implementação do PlayFab Game Saves com o GDK de outubro de 2025 (versão 2510). Seja você novo no Game Saves ou esteja migrando de uma implementação anterior, este documento fornece os requisitos essenciais e as instruções de configuração, com atenção especial ao suporte ao Steam Deck.

Visão geral dos requisitos de implementação

Ao implementar o PlayFab Game Saves com o GDK de outubro de 2025, você precisa entender quatro componentes principais:

Novo layout de pastas do GDK: estrutura de diretórios do SDK centrada na plataforma
Integração com o XGameRuntime: runtime multiplataforma com requisitos de implantação específicos
PlayFab Unified SDK: arquitetura de SDK moderna para todos os componentes do PlayFab
Outros componentes do Unified SDK: componentes atualizados do Party e do Multiplayer (se usados)

Os três primeiros componentes são obrigatórios para todas as implementações do Game Saves com o GDK de outubro de 2025 e posteriores, incluindo o suporte ao Steam Deck. O quarto componente só se aplica se o seu jogo usar os recursos do PlayFab Party ou do Multiplayer.

Novo no Game Saves? Comece pela Visão geral do Game Saves e pelo Guia de início rápido para entender os conceitos básicos e, em seguida, volte aqui para obter os detalhes de implementação específicos do GDK de outubro de 2025.

1. Layout de pastas do GDK e configuração de caminhos

Estrutura atual do GDK

O GDK de outubro de 2025 usa uma estrutura de diretórios plana e centrada na plataforma. Entender esse layout é essencial para configurar seu sistema de build corretamente. Layout do GDK de outubro de 2025:

\Microsoft GDK\251000\windows\include
\Microsoft GDK\251000\xbox\lib\x64
\Microsoft GDK\251000\xbox\bin\x64

Migrando de um GDK anterior? A estrutura de pastas anterior ($(GDK)\GRDK\ and $(GDK)\GXDK\) foi substituída. Atualize seus scripts de build adequadamente.

Configurando seu sistema de build

Configuração de caminhos necessária

Configure seu sistema de build para usar os caminhos específicos de plataforma corretos:

Exemplo de configuração do sistema de build

Configuração do CMake:

# Configure GDK paths for your target platform
if(CMAKE_SYSTEM_NAME STREQUAL "Windows")
    set(GDK_INCLUDE_DIR "${GDK_PATH}/windows/include")
    set(GDK_LIB_DIR "${GDK_PATH}/windows/lib/x64")
elseif(XBOX)
    set(GDK_INCLUDE_DIR "${GDK_PATH}/xbox/include")
    set(GDK_LIB_DIR "${GDK_PATH}/xbox/lib/x64")
endif()

Configuração do MSBuild:

<!-- Set include paths for Game Saves development -->
<IncludePath>$(GDK)\windows\include;$(IncludePath)</IncludePath>
<LibraryPath>$(GDK)\windows\lib\x64;$(LibraryPath)</LibraryPath>

Detalhes do suporte a plataformas

XBOX: usa pastas xbox para todas as gerações recentes de consoles XBOX
Windows: todas as plataformas Windows (PC, Steam PC, Steam Deck-Proton) usam a pasta windows
Steam Deck: apesar de executar o SteamOS, usa a pasta windows para compatibilidade com a emulação do Proton

Etapas de implementação

Configure seu sistema de build
- Configure os caminhos de inclusão e de biblioteca usando a nova estrutura do GDK
- Adicione lógica de detecção de plataforma se for direcionar para várias plataformas
- Teste a compilação em todas as plataformas de destino
Valide a integração do Game Saves
- Verifique se todas as bibliotecas necessárias são vinculadas corretamente
- Teste a funcionalidade nas suas plataformas de destino
- Verifique a conectividade com o serviço PlayFab

2. Integração com o XGameRuntime

Entendendo o XGameRuntime

O XGameRuntime fornece a base para os serviços do XBOX Live e para a funcionalidade do Game Saves em todas as plataformas. Veja o que você precisa saber:

Componentes principais

xgameruntime.lib (biblioteca de importação)

É vinculada ao projeto do seu jogo no momento da compilação
Localiza e carrega a DLL de runtime automaticamente
Trata a descoberta de serviços (local vs. sistema)

xgameruntime.dll (biblioteca de runtime)

Implementa a funcionalidade do XBOX Live e do Game Saves
Local: {GDK}\windows\bin\xgameruntime.dll
Essencial para builds da Steam: deve ser implantada com o seu jogo

Requisitos de implementação

1. Integração básica

Todas as implementações do Game Saves exigem a inicialização do XGameRuntime:

// Initialize XGameRuntime - required for all Game Saves implementations
HRESULT hr = XGameRuntimeInitialize();
if (FAILED(hr)) {
    // Handle initialization failure
    return hr;
}

2. Requisitos da plataforma Steam

Essencial para builds da Steam: Ao criar o build para a Steam, você deve incluir xgameruntime.dll no diretório do jogo. Sem essa DLL, ao executar no Steam Deck:

A autenticação do XBOX Live falhará
A funcionalidade do Game Saves ficará indisponível

Estrutura de implantação:

YourGame/
├── YourGame.exe
├── xgameruntime.dll          // Required for Steam/Steam Deck
├── Steam_api64.dll
└── Other game files...

Os builds da Microsoft Store carregam automaticamente o XGameRuntime do sistema e não exigem a implantação da DLL.

3. Implantação automatizada de DLLs

Configuração do CMake:

# Automatically copy XGameRuntime DLL for Steam builds
if(STEAM_BUILD)
    add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
        COMMAND ${CMAKE_COMMAND} -E copy_if_different
        "${GDK_PATH}/windows/bin/xgameruntime.dll"
        $<TARGET_FILE_DIR:${PROJECT_NAME}>)
endif()

Configuração do MSBuild:

<Target Name="CopySteamRuntimeDll" AfterTargets="Build" Condition="'$(SteamBuild)'=='true'">
  <Copy SourceFiles="$(GDK)\windows\bin\xgameruntime.dll" 
        DestinationFolder="$(OutDir)" />
</Target>

Comportamento do runtime específico da plataforma

Plataforma	Origem da DLL	Modo de runtime	Suporte ao Game Saves	Comportamento de sincronização
Microsoft Store	DLL do sistema	GRTS	Suporte total	Fora do processo, continua após o desligamento
Steam PC	DLL do sistema	GRTS	Suporte total	Fora do processo, continua após o desligamento
Steam Deck	DLL local	Serviços locais	Suporte durante o tempo de vida do jogo	Somente no processo, para no desligamento

O suporte ao Steam Deck exige especificamente a implantação da DLL local. O sistema não pode recorrer aos serviços do sistema como em outras plataformas. Além disso, o mecanismo de sincronização é executado no processo, o que significa que os jogos devem garantir que os dados salvos críticos sejam sincronizados antes do desligamento.

3. Integração com o PlayFab Unified SDK

O que é o PlayFab Unified SDK?

O PlayFab Unified SDK é um SDK moderno e coeso que reúne todos os componentes do PlayFab em uma única arquitetura. O Game Saves agora faz parte desse sistema unificado, oferecendo: Benefícios para o desenvolvimento com o Game Saves:

Gerenciamento de memória unificado em todos os componentes do PlayFab
Padrões consistentes de operações assíncronas
Rastreamento e diagnóstico integrados
Carregamento modular de componentes (inclua apenas o que você precisa)

Novo no PlayFab? O Unified SDK simplifica a integração, fornecendo um padrão de API único e consistente em todos os serviços do PlayFab. Se você estiver implementando o Game Saves ou qualquer outro serviço do PlayFab pela primeira vez, vai querer começar com essa arquitetura moderna.

Componentes do SDK necessários

As implementações do Game Saves precisam destes componentes do Unified SDK: Componentes essenciais:

libHttpClient: comunicação HTTP/WebSocket multiplataforma
PlayFab Core: autenticação, gerenciamento de entidades e configuração
PlayFab GameSave: funcionalidade específica do Game Saves

Componentes opcionais:

PlayFab Services: serviços compartilhados para LiveOps, gerenciamento de contas e outros sistemas de progressão (recomendado se você usar outros serviços do PlayFab)

Requisitos de bibliotecas e DLLs

Bibliotecas necessárias para vinculação

Link these .lib files in your project:
- libHttpClient.lib
- PlayFabCore.lib 
- PlayFabServices.lib (optional, but recommended for additional PlayFab features)
- PlayFabGameSave.lib
- xgameruntime.lib

DLLs necessárias para implantação

Deploy these .dll files with Steam builds:
- libHttpClient.dll
- PlayFabCore.dll
- PlayFabServices.dll (optional, but recommended)
- PlayFabGameSave.dll
- xgameruntime.dll

Configuração do sistema de build

Configuração do MSBuild

Configure seu projeto do Visual Studio para vincular o Unified SDK:

<!-- Link all required Unified SDK libraries -->
<AdditionalDependencies>
  libHttpClient.lib;
  PlayFabCore.lib;
  PlayFabServices.lib;
  PlayFabGameSave.lib;
  xgameruntime.lib;
  %(AdditionalDependencies)
</AdditionalDependencies>

<!-- Automatically deploy DLLs for Steam builds -->
<Target Name="CopyUnifiedSDKDlls" AfterTargets="Build" Condition="'$(SteamBuild)'=='true'">
  <ItemGroup>
    <UnifiedSDKDlls Include="$(GDK)\windows\bin\libHttpClient.dll" />
    <UnifiedSDKDlls Include="$(GDK)\windows\bin\PlayFabCore.dll" />
    <UnifiedSDKDlls Include="$(GDK)\windows\bin\PlayFabServices.dll" />
    <UnifiedSDKDlls Include="$(GDK)\windows\bin\PlayFabGameSave.dll" />
    <UnifiedSDKDlls Include="$(GDK)\windows\bin\xgameruntime.dll" />
  </ItemGroup>
  </ItemGroup>
  <Copy SourceFiles="@(UnifiedSDKDlls)" DestinationFolder="$(OutDir)" />
</Target>

Migrando de um GDK anterior? Substitua caminhos antigos como $(GDK)\GRDK\...\include pela nova estrutura mostrada acima.

Configuração do CMake

Para projetos baseados em CMake, configure as dependências e a implantação:

# Link all required Unified SDK libraries
target_link_libraries(${PROJECT_NAME} PRIVATE
    libHttpClient
    PlayFabCore
    PlayFabServices
    PlayFabGameSave
    xgameruntime
)

# Automatically deploy DLLs for Steam builds
if(STEAM_BUILD)
    set(UNIFIED_SDK_DLLS
        "${GDK_PATH}/windows/bin/libHttpClient.dll"
        "${GDK_PATH}/windows/bin/PlayFabCore.dll"
        "${GDK_PATH}/windows/bin/PlayFabServices.dll"
        "${GDK_PATH}/windows/bin/PlayFabGameSave.dll"
        "${GDK_PATH}/windows/bin/xgameruntime.dll"
    )
    
    foreach(DLL ${UNIFIED_SDK_DLLS})
        add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
            COMMAND ${CMAKE_COMMAND} -E copy_if_different
            ${DLL} $<TARGET_FILE_DIR:${PROJECT_NAME}>)
    endforeach()
endif()

Implementação do código

Cabeçalhos necessários

Inclua os cabeçalhos necessários do Unified SDK no seu projeto:

// Essential headers for Game Saves implementation
#include <playfab/core/PFCore.h>
#include <playfab/services/PFServices.h>
#include <playfab/gamesave/PFGameSave.h>
#include <XGameRuntimeInit.h>

Sequência de inicialização

Siga esta ordem de inicialização para configurar corretamente o Game Saves:

// 1. Initialize XGameRuntime (foundation for Xbox Live services)
HRESULT hr = XGameRuntimeInitialize();
if (FAILED(hr)) {
    // Handle initialization failure
    return hr;
}

// 2. Initialize PlayFab Core (authentication and entity management)
hr = PFInitialize(nullptr);
if (FAILED(hr)) {
    // Handle PlayFab Core initialization failure
    return hr;
}

// 3. Initialize PlayFab Services (optional - only if using other PlayFab services)
hr = PFServicesInitialize(nullptr);
if (FAILED(hr)) {
    // Handle PlayFab Services initialization failure
    return hr;
}

// 4. Create service configuration (connects to your PlayFab title)
PFServiceConfigHandle serviceConfigHandle{ nullptr };
hr = PFServiceConfigCreateHandle(
    "https://YOUR_TITLE_ID.playfabapi.com",    // Replace with your endpoint
    "YOUR_TITLE_ID",                           // Replace with your Title ID
    &serviceConfigHandle);
if (FAILED(hr)) {
    // Handle service config creation failure
    return hr;
}

// 5. Initialize Game Saves with your service configuration
hr = PFGameSaveFilesInitialize(serviceConfigHandle);
if (FAILED(hr)) {
    // Handle Game Saves initialization failure
    return hr;
}

// Game Saves is now ready for use!

Obtenha a ID do título e o ponto de extremidade da API no PlayFab Game Manager, nas configurações do seu título.

Sequência de limpeza adequada

Ao desligar o aplicativo, limpe os recursos na ordem inversa:

// Clean up Game Saves
PFGameSaveFilesUninitialize();

// Close service configuration
PFServiceConfigCloseHandle(serviceConfigHandle);
serviceConfigHandle = nullptr;

// Async cleanup for PlayFab Services (only if initialized)
XAsyncBlock async{};
HRESULT hr = PFServicesUninitializeAsync(&async);
hr = XAsyncGetStatus(&async, true);  // Wait for completion

// Async cleanup for PlayFab Core
hr = PFUninitializeAsync(&async);
hr = XAsyncGetStatus(&async, true);  // Wait for completion

// Clean up XGameRuntime
XGameRuntimeUninitialize();

Sempre use o padrão de limpeza assíncrona para o PlayFab Services e o Core para garantir a liberação adequada dos recursos.

4. Outros componentes do PlayFab Unified SDK

Alterações nas APIs do Party e do Multiplayer

Embora não sejam diretamente necessárias para a funcionalidade do Game Saves, o GDK de outubro de 2025 também inclui versões atualizadas dos componentes PlayFab Party e PlayFab Multiplayer como parte do Unified SDK. Esses componentes têm novas APIs que se integram melhor ao sistema de autenticação unificado.

Principais alterações em relação aos SDKs autônomos

Integração da autenticação:

Padrão legado: anteriormente, os títulos que usavam os SDKs autônomos do Party/Multiplayer precisavam gerenciar manualmente EntityID e EntityToken a partir dos resultados do login no PlayFab e passá-los às APIs do Party/Multiplayer
Padrão do Unified SDK: o Party e o Multiplayer agora aceitam PFEntityHandle diretamente, eliminando o gerenciamento manual de tokens

Novas APIs disponíveis:

Party: novas APIs que aceitam PFEntityHandle para a autenticação de usuários
Multiplayer: novas APIs que aceitam PFEntityHandle para operações de lobby e matchmaking

Benefícios da migração (se você usar o Party/Multiplayer):

Fluxo de autenticação simplificado com atualização automática de tokens
Padrões consistentes de tratamento de erros em todos os componentes do PlayFab
Gerenciamento de memória e padrões de operações assíncronas unificados

Componentes do Party e do Multiplayer: se o seu jogo usar o PlayFab Party ou o Multiplayer, considere migrar para as novas APIs unificadas que aceitam PFEntityHandle diretamente, para uma integração melhor. No entanto, isso não é necessário para a funcionalidade do Game Saves; você pode ignorar a seção 4 com segurança se usar apenas o Game Saves.

5. Implementação no Steam Deck

O suporte ao Steam Deck no PlayFab Game Saves exige uma implementação adicional significativa além dos builds padrão para PC, incluindo fluxos de autenticação personalizados, retornos de chamada de interface do usuário abrangentes e estratégias de sincronização cuidadosas.

Complexidade da implementação no Steam Deck: a integração com o Steam Deck envolve fluxos de autenticação personalizados, implementação de retornos de chamada de interface do usuário e diferenças críticas no comportamento de sincronização. Devido à complexidade e à extensão dos requisitos de implementação, a implementação no Steam Deck está em seu próprio guia dedicado.

Principais considerações sobre o Steam Deck

Diferença crítica no comportamento de sincronização:

Windows PC: o Game Saves é executado fora do processo e pode continuar sincronizando após o desligamento do jogo
Steam Deck: o Game Saves é executado somente no processo e para de sincronizar quando o jogo é desligado

Requisitos de implementação:

Todas as DLLs do Unified SDK devem ser implantadas com o seu build da Steam
Fluxo de autenticação XUser personalizado com retornos de chamada de interface do usuário
Configuração do Registro para testes em áreas restritas que não sejam de varejo
Padrões de sincronização frequentes para evitar perda de dados

Recomendações universais de sincronização (benéficas para todas as plataformas): Embora esses padrões sejam obrigatórios para o Steam Deck, eles são altamente recomendados para todas as plataformas, especialmente dispositivos portáteis, em que desligamentos repentinos são comuns:

Sincronize os dados salvos com frequência (após cada nível, checkpoint ou progresso significativo)
Sempre sincronize antes de exibir as confirmações de “sair do jogo”
Considere a sincronização em segundo plano durante as transições de jogabilidade
Implemente indicadores de progresso da sincronização para garantir a conclusão antes do desligamento

Implementação completa no Steam Deck

Para obter detalhes abrangentes da implementação no Steam Deck, incluindo:

Configuração detalhada do fluxo de autenticação
Implementação completa dos retornos de chamada de interface do usuário
Sequência de inicialização passo a passo
Guia de solução de problemas
Referências de código de exemplo

Consulte o Guia de implementação no Steam Deck dedicado

Comece pelos requisitos deste documento e, em seguida, passe para o guia do Steam Deck para obter os detalhes de implementação específicos da plataforma.

6. Lista de verificação da implementação

Introdução (novas implementações)

Configure o GDK de outubro de 2025 e verifique a instalação
Configure o sistema de build com os caminhos corretos do GDK e as referências de bibliotecas
Adicione as bibliotecas do Unified SDK à configuração de vinculação do seu projeto
Inclua os cabeçalhos necessários no seu código-fonte
Implemente a sequência de inicialização seguindo o padrão do Unified SDK
Configure a implantação de DLLs para os builds da Steam (4 DLLs obrigatórias, 1 opcional)
Teste a funcionalidade básica nas suas plataformas de destino

Migração (implementações existentes)

Atualize os caminhos do sistema de build da estrutura antiga do GDK para o novo layout
Substitua as bibliotecas autônomas pelos componentes do Unified SDK
Atualize as inclusões de cabeçalhos para usar os novos cabeçalhos do Unified SDK
Modifique a sequência de inicialização para usar as novas APIs do Unified SDK
Atualize a sequência de limpeza com o padrão adequado de limpeza assíncrona
Adicione DLLs extras à implantação da Steam (1 DLL → 4-5 DLLs)
Verifique se a funcionalidade permanece intacta após a migração

Configuração do sistema de build

Caminhos de inclusão: defina como $(GDK)\windows\include (ou o equivalente da plataforma)
Caminhos de biblioteca: defina como $(GDK)\windows\lib\x64 (ou o equivalente da plataforma)
Bibliotecas de vinculação: adicione os arquivos .lib necessários às dependências do vinculador (4 obrigatórias, 1 opcional)
Implantação de DLLs: configure a cópia automática para os builds da Steam
Detecção de plataforma: adicione lógica se for criar builds para várias plataformas

Tarefas de implementação do código

Cabeçalhos: inclua todos os cabeçalhos necessários do Unified SDK
Inicialização: implemente a sequência de inicialização adequada de 5 etapas
Tratamento de erros: adicione a verificação de erros apropriada para cada etapa de inicialização
Limpeza: implemente a limpeza em ordem inversa com padrões assíncronos
Configuração: substitua os valores codificados pela sua ID de título e pelo seu ponto de extremidade do PlayFab

Requisitos de teste

Windows PC: verifique a funcionalidade do Game Saves
Steam Deck: conclua a implementação usando o Guia de implementação no Steam Deck
Microsoft Store: confirme que não há regressão na funcionalidade
Multiplataforma: teste a sincronização de salvamentos entre todas as plataformas (PC, Steam Deck, XBOX)

7. Recursos e suporte

Links da documentação

Referências de código de exemplo

Exemplo do Game Saves para Windows: PlayFabGameSaveSample-Windows
- GameSaveIntegration.cpp/.h: integração principal do Game Saves
- SteamIntegration.cpp/.h: implementação específica do Steam Deck (consulte o guia do Steam Deck)
- GameSaveIntegrationUI.cpp/.h: implementações dos retornos de chamada de interface do usuário (consulte o guia do Steam Deck)

Última modificação em 8 de outubro de 2026

⌘I

​Visão geral dos requisitos de implementação

​1. Layout de pastas do GDK e configuração de caminhos

​Estrutura atual do GDK

​Configurando seu sistema de build

​Configuração de caminhos necessária

​Exemplo de configuração do sistema de build

​Detalhes do suporte a plataformas

​Etapas de implementação

​2. Integração com o XGameRuntime

​Entendendo o XGameRuntime

​Componentes principais

​Requisitos de implementação

​1. Integração básica

​2. Requisitos da plataforma Steam

​3. Implantação automatizada de DLLs

​Comportamento do runtime específico da plataforma

​3. Integração com o PlayFab Unified SDK

​O que é o PlayFab Unified SDK?

​Componentes do SDK necessários

​Requisitos de bibliotecas e DLLs

​Bibliotecas necessárias para vinculação

​DLLs necessárias para implantação

​Configuração do sistema de build

​Configuração do MSBuild

​Configuração do CMake

​Implementação do código

​Cabeçalhos necessários

​Sequência de inicialização

​Sequência de limpeza adequada

​4. Outros componentes do PlayFab Unified SDK

​Alterações nas APIs do Party e do Multiplayer

​Principais alterações em relação aos SDKs autônomos

​5. Implementação no Steam Deck

​Principais considerações sobre o Steam Deck

​Implementação completa no Steam Deck

​6. Lista de verificação da implementação

​Introdução (novas implementações)

​Migração (implementações existentes)

​Configuração do sistema de build

​Tarefas de implementação do código

​Requisitos de teste

​7. Recursos e suporte

​Links da documentação

​Referências de código de exemplo

Visão geral dos requisitos de implementação

1. Layout de pastas do GDK e configuração de caminhos

Estrutura atual do GDK

Configurando seu sistema de build

Configuração de caminhos necessária

Exemplo de configuração do sistema de build

Detalhes do suporte a plataformas

Etapas de implementação

2. Integração com o XGameRuntime

Entendendo o XGameRuntime

Componentes principais

Requisitos de implementação

1. Integração básica

2. Requisitos da plataforma Steam

3. Implantação automatizada de DLLs

Comportamento do runtime específico da plataforma

3. Integração com o PlayFab Unified SDK

O que é o PlayFab Unified SDK?

Componentes do SDK necessários

Requisitos de bibliotecas e DLLs

Bibliotecas necessárias para vinculação

DLLs necessárias para implantação

Configuração do sistema de build

Configuração do MSBuild

Configuração do CMake

Implementação do código

Cabeçalhos necessários

Sequência de inicialização

Sequência de limpeza adequada

4. Outros componentes do PlayFab Unified SDK

Alterações nas APIs do Party e do Multiplayer

Principais alterações em relação aos SDKs autônomos

5. Implementação no Steam Deck

Principais considerações sobre o Steam Deck

Implementação completa no Steam Deck

6. Lista de verificação da implementação

Introdução (novas implementações)

Migração (implementações existentes)

Configuração do sistema de build

Tarefas de implementação do código

Requisitos de teste

7. Recursos e suporte

Links da documentação

Referências de código de exemplo