Integrar o GDK a um mecanismo C/C++ personalizado

Use este tópico se você estiver preparando seu jogo para publicação na Microsoft Store no PC e seu jogo usar um mecanismo baseado em C/C++ que não tenha suporte interno ao GDK.

Criar um produto no Partner Center
Integrar o GDK a jogos C/C++
Testar os XBOX services no seu jogo
Publicação

Criar um produto no Partner Center

Antes de publicar um jogo na Microsoft Store, você precisa criar seu produto habilitado para XBOX services no Partner Center. Para obter mais informações sobre o Partner Center, consulte Configurar um aplicativo ou jogo no Partner Center, para Parceiros Gerenciados.

Integrar o GDK a jogos C/C++

Para integrar o GDK a um jogo C/C++, o jogo precisa de 4 itens:

Os cabeçalhos do GDK e da XBOX Services API (XSAPI) que descrevem as assinaturas de API e as estruturas de dados.
As bibliotecas de importação que informam ao vinculador como resolver referências externas às funções exportadas do GDK.
As bibliotecas estáticas do XSAPI ou as bibliotecas de importação que informam ao vinculador como resolver referências externas às funções exportadas da DLL do XSAPI.
- O XSAPI está disponível nas formas estática e dinâmica. Consulte a tabela abaixo para obter mais informações e escolha entre a forma estática ou dinâmica.
As bibliotecas de vínculo dinâmico que de fato contêm a implementação de runtime das funções do GDK e do XSAPI (se você usar a versão dinâmica do XSAPI).

Para que os jogos se integrem às experiências essenciais do ecossistema XBOX, eles precisam interagir com dois componentes: Gaming Runtime Services (GRTS) e XSAPI. Estes são os arquivos necessários para um jogo não gerenciado:

Componente	GRTS (somente dinâmico)	XSAPI (dinâmico)	XSAPI (estático)
Cabeçalhos	Cabeçalhos do GRTS: XUser, XGameSave, XGameUI etc. (do GDK)	Cabeçalhos do XSAPI: profile_c.h, achievements_c.h etc. (do GDK)	Cabeçalhos do XSAPI: profile_c.h, achievements_c.h etc. (do GDK)
Biblioteca de importação	xgameruntime.lib (do GDK)	Microsoft.Xbox.Services.GDK.C.Thunks.lib (do GDK)	Microsoft.Xbox.Services.142.GDK.C.lib (do GDK)
Biblioteca de vínculo dinâmico	xgameruntime.dll e algumas outras dlls (instaladas em system32 pelo GRTS)	Microsoft.Xbox.Services.GDK.C.Thunks.dll (do GDK, precisa ser incluída no pacote do jogo)	Não é necessária

Para jogos que usam uma arquitetura baseada em plug-ins com funcionalidades distribuídas em várias DLLs, recomendamos e oferecemos suporte à integração do XSAPI a elas por meio da Thunks.dll. Essa abordagem funciona de forma confiável nas plataformas PC e XBOX.Quando você vincula o XSAPI estaticamente a várias DLLs, cada DLL mantém sua própria cópia do estado global. Como resultado, chamar XblInitialize em uma DLL não inicializa o XSAPI nas outras. Compartilhar identificadores do XSAPI entre DLLs com instâncias estáticas separadas pode causar falhas ou comportamento imprevisível.A Thunks.dll resolve isso fornecendo uma única instância compartilhada do XSAPI e de seu estado. Isso evita a duplicação e garante um comportamento consistente em todas as DLLs.Embora seja tecnicamente possível vincular o XSAPI estaticamente a uma DLL e exportar os símbolos, essa abordagem é mais complexa e propensa a erros. Usar a Thunks.dll é mais simples, mais seguro e totalmente compatível.

Adicionar os requisitos do Gaming Runtime Services e do XSAPI ao seu projeto

As etapas a seguir descrevem as alterações que você precisa fazer no seu projeto para garantir que ele tenha todos os requisitos para usar o Gaming Runtime Services e o XSAPI.

Verifique se o destino é x64. No Visual Studio, vá para Build->Configuration Manager e defina Active solution platform como x64.
Adicione os seguintes caminhos de inclusão: C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\GameKit\Include C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Include C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Include Em que GDK version number será um diretório nomeado com o ano, o mês e o número da subversão da versão. Por exemplo, para o GDK de junho de 2022, o nome do diretório seria 220600. Para o Microsoft GDK (junho de 2024) ou anterior, use C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Include e C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Include No Visual Studio, você adicionaria esses caminhos na página de propriedades do projeto em Configuration Properties->VC++ Directories->Include Directories.
Adicione os seguintes caminhos de biblioteca para as bibliotecas de importação: C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\GameKit\Lib\amd64 C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\Release C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Lib\x64 Em que GDK version number será um diretório nomeado com o ano, o mês e o número da subversão da versão. Por exemplo, para o GDK de junho de 2022, o nome do diretório seria 220600. Para o Microsoft GDK (junho de 2024) ou anterior, use C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Release e C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Lib No Visual Studio, você adicionaria esses caminhos na página de propriedades do projeto em Configuration Properties->VC++ Directories->Library Directories.
Adicione as seguintes bibliotecas à lista de bibliotecas vinculadas ao seu projeto: C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\GameKit\Lib\amd64\xgameruntime.lib C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\Release\Microsoft.Xbox.Services.GDK.C.Thunks.lib (or Microsoft.Xbox.Services.142.GDK.C.lib, if statically linking) C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Lib\x64\libHttpClient.GDK.lib Em que GDK version number será um diretório nomeado com o ano, o mês e o número da subversão da versão. Por exemplo, para o GDK de junho de 2022, o nome do diretório seria 220600. Para o Microsoft GDK (junho de 2024) ou anterior, use C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\Release\Microsoft.Xbox.Services.GDK.C.Thunks.lib (ou Microsoft.Xbox.Services.142.GDK.C.lib, se a vinculação for estática) e C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\DesignTime\CommonConfiguration\Neutral\Lib\libHttpClient.GDK.lib No Visual Studio, você adicionaria as bibliotecas na página de propriedades do projeto em Configuration Properties->Linker->Input->Additional Dependencies.
Defina _GAMING_DESKTOP e WINAPI_FAMILY=WINAPI_FAMILY_DESKTOP_APP. No Visual Studio, você adicionaria a seguinte linha na página de propriedades do projeto em C/C++->Command Line->Additional Options: /D "_GAMING_DESKTOP" /D "WINAPI_FAMILY=WINAPI_FAMILY_DESKTOP_APP"

Crie um arquivo MicrosoftGame.config e verifique se ele é copiado para o mesmo destino que o .exe durante os builds. Observação: se o seu mecanismo oferecer suporte a qualquer tipo de funcionalidade de execução no editor que use um .exe diferente durante a execução, copie o MicrosoftGame.config também para o mesmo diretório desse .exe. Se o MicrosoftGame.config não estiver presente no mesmo diretório do .exe, os XBOX services não funcionarão ao usar a funcionalidade de execução no editor. Para iniciar o desenvolvimento, você pode usar uma configuração com valores padrão, como no exemplo a seguir. Os valores de Identity Name, Executable Name e Executable Alias seriam todos substituídos pelo nome do seu executável.

<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">
<Identity Name="Direct3DGame1_test"
            Publisher="CN=Publisher"
            Version="1.0.0.0"/>
<ExecutableList>
    <Executable Name="Direct3DGame1_test.exe"
                Id="Game"
                Alias="Direct3DGame1_test.exe"/>
</ExecutableList>
<ShellVisuals DefaultDisplayName="Direct3DGame1_test"
                PublisherDisplayName="PublisherName"
                Square480x480Logo="LargeLogo.png"
                Square150x150Logo="GraphicsLogo.png"
                Square44x44Logo="SmallLogo.png"
                Description="Direct3DGame1_test"
                ForegroundText="light"
                BackgroundColor="#000040"
                SplashScreenImage="SplashScreen.png"
                StoreLogo="StoreLogo.png"/>
</Game>

Verifique se cópias de Microsoft.Xbox.Services.GDK.C.Thunks.dll (se vinculada dinamicamente), XCurl.dll e libHttpClient.GDK.dll são copiadas para o mesmo destino que o .exe durante os builds. Observação: se o seu mecanismo oferecer suporte a qualquer tipo de funcionalidade de execução no editor que use um .exe diferente durante a execução, verifique se esse .exe também faz referência a essas .dlls. Se as .dlls não forem referenciadas pelo .exe, os XBOX services não funcionarão ao usar a funcionalidade de execução no editor. Se você vincular o XSAPI dinamicamente, a Microsoft.Xbox.Services.GDK.C.Thunks.dll pode ser encontrada na instalação do GDK no seguinte diretório: C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\Lib\x64\[Debug|Release] A XCurl.dll pode ser encontrada na instalação do GDK no seguinte diretório: C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.XCurl.API\Redist\x64 A libHttpClient.GDK.dll pode ser encontrada na instalação do GDK no seguinte diretório: C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Redist\x64 Em que GDK version number será um diretório nomeado com o ano, o mês e o número da subversão da versão. Por exemplo, para o GDK de junho de 2022, o nome do diretório seria 220600. Para o Microsoft GDK (junho de 2024) ou anterior, use C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.Services.API.C\DesignTime\CommonConfiguration\Neutral\Lib\[Debug|Release], C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.XCurl.API\Redist\CommonConfiguration\neutral e C:\Program Files (x86)\Microsoft GDK\[GDK version number]\GRDK\ExtensionLibraries\Xbox.LibHttpClient\Redist\CommonConfiguration\neutral

Como alternativa, se você estiver integrando o GDK a um projeto de área de trabalho existente do Visual Studio, poderá seguir as etapas deste tópico para converter seu projeto em um projeto do GDK: Adicionar o Microsoft Game Development Kit a um projeto de área de trabalho existente.

Atualizar o MicrosoftGame.config

O arquivo MicrosoftGame.config criado na etapa anterior tem valores padrão que permitem o desenvolvimento inicial no PC e no XBOX sem configuração adicional. Você precisa atualizar esses valores somente quando começar a usar recursos do Gaming Runtime, da Microsoft Store e da identidade do título. Para usar a funcionalidade dos XBOX services, atualize o MicrosoftGame.config do seu projeto com os detalhes de identidade do seu projeto no Partner Center.

Acesse o painel do Partner Center.
Selecione seu jogo na lista de produtos.
Selecione a guia Game setup e, em seguida, selecione Identity details.
Selecione Show Details para expandir a seção Identity details.
Use os seguintes valores da tabela na seção Identity details e copie esses valores do Partner Center para o elemento e o campo correspondentes no MicrosoftGame.config.

Nome no Partner Center	MicrosoftGame.config
XBOX Title ID	TitleId
Package/Identity/Name	Identity->Name
Package/Identity/Publisher	Identity->Publisher
XBOX services -> XBOX Settings -> MSAAppId	MSAAppId

Por exemplo, os seguintes detalhes de identidade no Partner Center fariam seu MicrosoftGame.config ficar parecido com o exemplo abaixo:

Nome no Partner Center	Valor de exemplo
XBOX Title ID	64353034
Package/Identity/Name	41336MicrosoftATG.Achievements2017Redux
Package/Identity/Publisher	CN=A4954634-DF4B-47C7-AB70-D3215D246AF1
XBOX services -> XBOX Settings -> MSAAppId	0000000000000000

<?xml version="1.0" encoding="utf-8"?>
<Game configVersion="1">

  <Identity Name='41336MicrosoftATG.Achievements2017Redux' Version="1.1.0.0" Publisher='CN=A4954634-DF4B-47C7-AB70-D3215D246AF1' />


  <TitleId>64353034</TitleId>
  <MSAAppId>0000000000000000</MSAAppId>

  <ExecutableList>
    <Executable Name="Achievements2017_desktop.exe"
                TargetDeviceFamily="PC"
                Id="Game"/>
  </ExecutableList>

  <ShellVisuals DefaultDisplayName="Achievements2017 Desktop Sample"
                PublisherDisplayName="Xbox Advanced Technology Group"
                StoreLogo="Assets\StoreLogo.png"
                Square150x150Logo="Assets\Logo.png"
                Square44x44Logo="Assets\SmallLogo.png"
                Square480x480Logo="Assets\LargeLogo.png"
                Description="Achievements2017"
                ForegroundText="dark"
                BackgroundColor="#000000"
                SplashScreenImage="Assets\SplashScreen.png"/>
</Game>

Consulte a Visão geral do MicrosoftGame.config para obter informações adicionais sobre os valores no MicrosoftGame.config.

Inicializar o runtime do jogo e o XSAPI

As etapas a seguir mostram como inicializar o Gaming Runtime Services e o XSAPI no seu jogo.

Inclua o cabeçalho XGameRuntime e o cabeçalho services-c do XSAPI.
#include <XGameRuntime.h> #include <xsapi-c/services_c.h>

Chame XGameRuntimeInitialize para inicializar o runtime do GDK.

// Initialize the GameRuntime
HRESULT hr = XGameRuntimeInitialize();
if (FAILED(hr))
{
    if (hr == E_GAMERUNTIME_DLL_NOT_FOUND || hr == E_GAMERUNTIME_VERSION_MISMATCH)
    {
        (void)MessageBoxW(nullptr, L"Game Runtime is not installed on this system or needs updating.", g_szAppName, MB_ICONERROR | MB_OK);
    }
    return 1;
}

Chame XblInitialize para inicializar o XSAPI.

 XblInitArgs xblArgs = {};
 //xblArgs.queue = queue; // Uncomment this line if you've chosen to create your own XTaskQueue. Otherwise, by default, this line is not needed.
 xblArgs.scid = "00000000-0000-0000-0000-000000000000"; // Add your scid from your Partner Center project here;
 HRESULT hr = XblInitialize(&xblArgs);
 if (FAILED(hr))
 {
     // Handle failure
 }

Desinicializar o runtime do jogo

O Gaming Runtime Services precisa ser desinicializado antes que seu jogo seja encerrado. O XSAPI não precisa ser limpo explicitamente antes do encerramento. Desinicialize o runtime do GDK chamando XGameRuntimeUninitialize.

 // Uninitialize the Gaming Runtime after
 // all other activity has been completed.
 XGameRuntimeUninitialize();

Consulte Introdução às APIs dos XBOX services para obter uma visão geral detalhada do uso do XSAPI no seu jogo.
Consulte Recursos do Game Development Kit (GDK) para obter visões gerais sobre a implementação de recursos do GDK.

Testar os XBOX services no seu jogo

Para testar a funcionalidade dos XBOX services no seu jogo, como conquistas, você precisa usar uma área restrita e contas de teste com acesso a essa área restrita.

Criar uma conta de teste

Para testar qualquer recurso dos XBOX services no seu jogo, crie contas de teste que tenham acesso à sua área restrita de desenvolvimento. Para obter informações sobre como criar contas de teste, consulte Criar contas de teste.

Alternar sua área restrita

Depois de criar uma conta de teste, use-a para acessar sua área restrita seguindo estas etapas.

Para encontrar o ID da sua área restrita, acesse o Partner Center.
Selecione XBOX services e, em seguida, selecione Gameplay Settings.
O ID da sua área restrita está na primeira guia e tem um nome como “ABCDEF.0”.
Abra o menu Iniciar.
Digite Microsoft GDK Command Prompts e pressione Enter no teclado.
Abra o primeiro prompt de comando.
No prompt de comando, digite XblPCSandbox.exe [ID da sua área restrita].
Depois que o prompt de comando iniciar vários aplicativos, entre no aplicativo XBOX com sua conta de teste.

Se você conseguir entrar com êxito, terá criado uma conta de teste e mudado para sua área restrita para começar os testes. Para obter mais informações sobre áreas restritas, consulte Visão geral das áreas restritas dos XBOX services.

Publicação

Para estar pronto para publicar seu jogo, você precisa:

Ter concluído a integração do seu jogo com o GDK
Ter criado um pacote do jogo seguindo as etapas em Introdução ao empacotamento de títulos para PC usando as ferramentas de empacotamento MSIXVC

Depois de concluir esses dois requisitos, você estará pronto para publicar. Para enviar seu jogo, acesse o Partner Center e siga as instruções na interface do usuário.

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

Criar um produto no Partner Center

Integrar o GDK a jogos C/C++

Adicionar os requisitos do Gaming Runtime Services e do XSAPI ao seu projeto

Atualizar o MicrosoftGame.config

Inicializar o runtime do jogo e o XSAPI

Desinicializar o runtime do jogo

Testar os XBOX services no seu jogo

Criar uma conta de teste

Alternar sua área restrita

Publicação

​Criar um produto no Partner Center

​Integrar o GDK a jogos C/C++

​Adicionar os requisitos do Gaming Runtime Services e do XSAPI ao seu projeto

​Atualizar o MicrosoftGame.config

​Inicializar o runtime do jogo e o XSAPI

​Desinicializar o runtime do jogo

​Testar os XBOX services no seu jogo

​Criar uma conta de teste

​Alternar sua área restrita

​Publicação

Criar um produto no Partner Center

Integrar o GDK a jogos C/C++

Adicionar os requisitos do Gaming Runtime Services e do XSAPI ao seu projeto

Atualizar o MicrosoftGame.config

Inicializar o runtime do jogo e o XSAPI

Desinicializar o runtime do jogo

Testar os XBOX services no seu jogo

Criar uma conta de teste

Alternar sua área restrita

Publicação