> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Guia essencial para implementar o PlayFab Game Saves com o GDK de outubro de 2025 (2510), incluindo os requisitos para novas implementações e orientações de migração

<Info>
  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.
</Info>

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

1. **Novo layout de pastas do GDK**: estrutura de diretórios do SDK centrada na plataforma
2. **Integração com o XGameRuntime**: runtime multiplataforma com requisitos de implantação específicos
3. **PlayFab Unified SDK**: arquitetura de SDK moderna para todos os componentes do PlayFab
4. **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.

<Note>
  **Novo no Game Saves?** Comece pela [Visão geral do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/overview) e pelo [Guia de início rápido](/pt-BR/services/playfab/player-progression/game-saves/quickstart) 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.
</Note>

## 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**:

```cmake theme={null}
# 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**:

```xml theme={null}
<!-- 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

1. **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

2. **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:

```cpp theme={null}
// 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...
```

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

#### 3. Implantação automatizada de DLLs

**Configuração do CMake**:

```cmake theme={null}
# 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**:

```xml theme={null}
<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** |

<Info>
  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.
</Info>

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

```xml theme={null}
<!-- 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:

```cmake theme={null}
# 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:

```cpp theme={null}
// 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:

```cpp theme={null}
// 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!
```

<Tip>
  Obtenha a ID do título e o ponto de extremidade da API no [PlayFab Game Manager](https://developer.playfab.com), nas configurações do seu título.
</Tip>

#### Sequência de limpeza adequada

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

```cpp theme={null}
// 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();
```

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

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

<Note>
  **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.
</Note>

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

<Info>
  **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](/pt-BR/services/playfab/player-progression/game-saves/steam-deck-implementation).
</Info>

### 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](/pt-BR/services/playfab/player-progression/game-saves/steam-deck-implementation) dedicado**

<Tip>
  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.
</Tip>

## 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](/pt-BR/services/playfab/player-progression/game-saves/steam-deck-implementation)
* [ ] **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

* [Visão geral do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/overview)
* [Início rápido do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/quickstart)
* [Guia de implementação no Steam Deck](/pt-BR/services/playfab/player-progression/game-saves/steam-deck-implementation)

### Referências de código de exemplo

* **Exemplo do Game Saves para Windows**: [PlayFabGameSaveSample-Windows](https://github.com/PlayFab/PlayFab-Samples/tree/master/Samples/All/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)


## Related topics

- [Guia de implementação do PlayFab Game Saves no Steam Deck](/pt-BR/services/playfab/player-progression/game-saves/steam-deck-implementation.md)
- [Modo offline do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/offline.md)
- [Estrutura de diretórios simplificada do GDK (cabeçalhos e bibliotecas)](/pt-BR/build/gdk-and-engines/guides/gdk-directory-structure.md)
- [Configuração do início rápido do SDK unificado do PlayFab](/pt-BR/services/playfab/sdks/unified-sdk/quickstart-setup.md)
- [Versão v0.2.0 do XBOX Godot Sample](/pt-BR/build/gdk-and-engines/godot-release-notes/godot-release-notes-0-2-0.md)