O que é o MicrosoftGame.config?
Cada jogo distribuído por meio da Microsoft Store deve incluir um manifesto que declare, no mínimo, a identidade do título, o nome do editor e um conjunto de elementos visuais do shell específicos do título (cadeias de caracteres, ícones e imagens) usados para exibir o nome e a representação gráfica do jogo na Microsoft Store e no shell (para console) e no menu Iniciar, na barra de tarefas e em outros locais do Shell do Windows (para PC). Além disso, um jogo pode implementar recursos opcionais, como conteúdo para download (DLC), que dependem de valores de configuração também armazenados no manifesto do jogo. O nome do arquivo de manifesto é MicrosoftGame.config.Por que criar um novo esquema de manifesto?
Cada pacote na Microsoft Store contém um manifesto chamado AppXManifest.xml. Seu esquema evoluiu ao longo de muitos anos para acomodar uma ampla variedade de recursos e cenários de aplicativos. Com o MicrosoftGame.config, os desenvolvedores de jogos interagem com um esquema de manifesto centrado em jogos mais simples, que é mais acessível, menos propenso a erros e mais produtivo. Quando o desenvolvedor empacota ou registra um jogo, as ferramentas validam o conteúdo do MicrosoftGame.config e geram um AppXManifest.xml bem formado em nome do desenvolvedor do jogo. OAppXManifest gerado é incluído no pacote resultante.
A partir do Microsoft Game Development Kit (GDK) de março de 2022, o Game configVersion foi atualizado de 0 para 1 para novos títulos criados com este Microsoft Game Development Kit (GDK) e versões futuras. Títulos existentes podem optar por essa atualização de versão para aproveitar essas melhorias. Para obter mais informações, consulte Referência do MicrosoftGame.config (exemplo de MicrosoftGame.config e esquema).
Documentação disponível
No arquivo de documentação offline do Microsoft Game Development Kit (GDK) (GDK.chm), você pode encontrar a documentação sobre o MicrosoftGame.config nos locais mostrados na tabela a seguir.Criação do MicrosoftGame.config
Ao criar um novo projeto para a plataforma Gaming.Desktop.x64, Gaming.Xbox.XboxOne.x64 ou Gaming.Xbox.Scarlett.x64, um MicrosoftGameConfig.mgc é associado ao seu projeto no Visual Studio. Ele tem valores padrão que permitem o desenvolvimento inicial no PC e no XBOX sem a necessidade de configuração adicional até que você comece a usar recursos do Gaming Runtime, da Microsoft Store e da identidade do título. Quando o projeto é compilado, o MicrosoftGameConfig.mgc é renomeado para MicrosoftGame.config ao ser copiado para o diretório de saída do projeto. Um exemplo desse MicrosoftGameConfig.mgc padrão, para XBOX, é mostrado a seguir.Se você adicionar manualmente um arquivo Microsoftgame.config ao seu projeto, certifique-se de alterar as propriedades do arquivo para o tipo de arquivo
copy.Adicionando manualmente um arquivo MicrosoftGame.config
Um ou mais arquivos MicrosoftGame.config também podem ser adicionados manualmente ao seu projeto. A adição manual de um arquivo pode ser feita de duas maneiras:- Definindo as propriedades apropriadas em um arquivo existente para que o Visual Studio o reconheça como um arquivo MicrosoftGame.config.
- Usando um Modelo de Item fornecido com o sistema de projetos C++ do Microsoft Game Development Kit (GDK).
- Defina sua configuração para a plataforma “Gaming.Xbox.XboxOne.x64”, “Gaming.Xbox.Scarlett.x64” ou “Gaming.Desktop.x64”.
- Adicione o arquivo MicrosoftGame.config do seu jogo como um arquivo no seu projeto do Visual Studio.
- Nas propriedades do arquivo MicrosoftGame.config, defina Tipo de Item como Microsoft Game Config, conforme mostrado a seguir.
- Clique com o botão direito do mouse em um projeto e selecione Adicionar->Novo Item.
- O modelo MicrosoftGameConfig.mgc pode ser encontrado no nó Visual C++->Gaming->Microsoft Game Development Kit->Edition da árvore, conforme mostrado a seguir.
Propriedade de projeto do Visual Studio para o MicrosoftGame.config
Sempre que um arquivo MicrosoftGameConfig.mgc é adicionado a um projeto, seja automaticamente quando o projeto é criado ou manualmente, uma propriedade (MGCCompile) é adicionada ao seu projeto do Visual Studio. A propriedade MGCCompile é usada pelo sistema de projetos para automatizar o seguinte:
- Geração de um arquivo .pri se você tiver recursos de cadeia de caracteres localizados
- Renomeação do arquivo MicrosoftGameConfig.mgc para MicrosoftGame.config, se necessário
- Cópia do seu MicrosoftGame.config para a pasta de saída
- Registro do seu MicrosoftGame.config após o build
- Inicialização do seu jogo com identidade no depurador
Gerenciando vários arquivos MicrosoftGameConfig.mgc no Visual Studio e no MSBuild
Um projeto do Visual Studio do Microsoft Game Development Kit (GDK) pode ter vários arquivos MicrosoftGameConfig.mgc associados a ele. É comum usar arquivos MicrosoftGameConfig.mgc diferentes para configurações de build diferentes ou para builds de XBOX e PC, por exemplo. Se você usava anteriormente uma lógica de build personalizada para gerenciar vários arquivos MicrosoftGameConfig.mgc, esse cenário agora tem suporte direto do sistema de projetos. Um arquivo MicrosoftGameConfig.mgc pode ser atribuído a configurações de build individuais de duas maneiras. Primeiro, a janela de ferramentas XBOX Gaming Project Control inclui suporte para gerenciar vários arquivos MicrosoftGameConfig.mgc (tópico sob NDA), conforme mostrado a seguir.
DefaultApplyTo da propriedade MGCCompile para especificar um arquivo MicrosoftGameConfig.mgc padrão. Esse arquivo padrão será usado para todas as configurações, a menos que seja substituído explicitamente. Use o elemento ApplyTo da propriedade MGCCompile para atribuir um arquivo de configuração a uma configuração de build específica.
O trecho a seguir de um arquivo de projeto especifica MicrosoftGameConfig_dev.mgc como o arquivo de configuração padrão. MicrosoftGameConfig_dev.mgc será usado para todas as configurações de build, exceto Release, para a qual uma substituição (MicrosoftGameConfig_release.mgc) foi especificada.
Suporte ao IntelliSense para o MicrosoftGame.config
A modificação de um MicrosoftGame.config no Visual Studio agora oferece suporte aos recursos do IntelliSense. Isso permite obter informações adicionais, conforme mostrado nas duas capturas de tela a seguir. Nomes de elementos válidos são listados automaticamente quando um elemento está sendo criado.
Requisitos de plataforma para o MicrosoftGame.config
Ao criar um arquivo MicrosoftGame.config para o seu título, você precisará criar um para cada plataforma do Microsoft Game Development Kit (GDK) (Gaming.Xbox.XboxOne.x64, Gaming.Xbox.Scarlett.x64 e Gaming.Desktop.x64). Isso é necessário para garantir que os valores de elementos armazenados no MicrosoftGame.config tenham um mapeamento um para um com a plataforma para a qual seu executável é compilado. Isso é especificado principalmente pelo atributoTargetDeviceFamily no elemento Executable do arquivo MicrosoftGame.config. Para obter mais informações, consulte a seção Detalhes adicionais de elementos no tópico de referência.
Ao ser iniciado, seu título se comporta de maneira diferente com base nos requisitos de plataforma, no dispositivo em que o título está sendo iniciado e no tipo de executável, conforme mostrado na tabela a seguir.
No cenário em que um título de XBOX Series X|S é iniciado em um Dev Kit do XBOX Series X sem um MicrosoftGame.config, ele reutilizará o estado existente da VM do Microsoft Game Development Kit (GDK), se aplicável. Por exemplo, se um título do Microsoft Game Development Kit (GDK) com compatibilidade com versões anteriores (XBOX One no XBOX Series X|S) tiver sido iniciado antes da tentativa de iniciar um título nativo de XBOX Series X|S, ele será executado usando essa mesma VM de compatibilidade com versões anteriores do Microsoft Game Development Kit (GDK). Recomendamos usar um MicrosoftGame.config com TargetDeviceFamily configurado para indicar a intenção adequada caso você se depare com esse cenário. Títulos ERA são executados em um estado de VM separado e, portanto, não influenciam o comportamento da VM do Microsoft Game Development Kit (GDK) nesse cenário.
Criando e editando um MicrosoftGame.config fora do Visual Studio
Conforme observado acima, o Visual Studio oferece várias maneiras de criar e gerenciar o arquivo MicrosoftGame.config do seu título. Além da criação e edição no Visual Studio, há uma ferramenta autônoma que permite criar e editar o MicrosoftGame.config diretamente. O Editor do MicrosoftGame.config é uma ferramenta de interface do usuário que facilita a criação e a edição de arquivos .config. Esse editor também inclui integrações com as informações do seu título no Partner Center para baixar e sincronizar automaticamente informações, como TitleId, MSAAppId e StoreId, por meio de um Assistente de Associação à Store. Seus comentários são bem-vindos, então use a ferramenta de sugestões no editor para nos informar sua opinião.Iniciando um jogo sem o MicrosoftGame.config
No Microsoft Game Development Kit (GDK), você pode iniciar um jogo de PC ou de XBOX sem ter um MicrosoftGame.config presente. Isso é permitido para o desenvolvimento inicial antes da criação de um MicrosoftGame.config e tem como objetivo oferecer flexibilidade para quando você quiser aderir a recursos do Gaming Runtime, da Microsoft Store e da identidade do título. Para lançar um título com o Microsoft Game Development Kit (GDK), um MicrosoftGame.config é necessário para criar o pacote do título antes do envio para a Microsoft Store. É recomendável adotar e configurar o MicrosoftGame.config do seu título assim que você começar a desenvolver recursos que exijam o Gaming Runtime, XBOX services, a Microsoft Store ou a identidade do título. Jogos de PC que não têm um MicrosoftGame.config podem ser compilados e iniciados clicando duas vezes no executável compilado. Eles serão executados sem integração com os recursos do Gaming Runtime. Para dar suporte a recursos do Gaming Runtime, identidade do título, empacotamento MSIXVC e à capacidade de enviar para a Microsoft Store, um MicrosoftGame.config é necessário. Jogos de XBOX que não têm um MicrosoftGame.config poderão usar as ferramentas do GDK para implantar builds de arquivos soltos, iniciar, depurar e usar um subconjunto da funcionalidade do Microsoft Game Development Kit (GDK) prontamente. Para dar suporte a todos os recursos do Microsoft Game Development Kit (GDK), identidade do título, empacotamento XVC e à capacidade de enviar para a Microsoft Store, um MicrosoftGame.config é necessário. Para iniciar seu título no XBOX sem um MicrosoftGame.config, você pode:- Usar o launch do xbapp.exe (tópico sob NDA).
- Usar a funcionalidade de implantação/inicialização do XBOX Manager.
- Iniciar o título no Developer Home (Dev Home) no seu XBOX.
Iniciando um jogo Win32
Um jogo Win32 para PC que não usa o Gaming Runtime nem serviços de jogos em nuvem pode ser iniciado e/ou depurado como qualquer outro executável do Windows. Basta clicar no executável do jogo com o mouse ou executá-lo diretamente em uma janela de prompt de comando, e o processo do jogo será criado. Os serviços de jogos realizam trabalho em nome de um jogo. Para usar o Gaming Runtime ou serviços de jogos em nuvem, um jogo deve fornecer dados contextuais. Por exemplo, um jogo pode passar ao XBOX services um identificador exclusivo chamado identidade do título, o que permite ao serviço identificar qual jogo está concedendo conquistas aos jogadores. Informações contextuais como a identidade do título podem ser armazenadas de forma persistente no Repositório de Aplicativos do Windows por meio de um processo chamado registro. É também por meio do registro que um jogo especifica quais cadeias de caracteres e logotipos o Shell do Windows deve usar para representar o jogo na lista de aplicativos do menu Iniciar. Por meio de uma ação chamada inicialização de aplicativo (app-launch), um processo de jogo é criado e o jogo recebe acesso às suas informações contextuais persistentes do repositório de aplicativos. Se você não iniciar o jogo por app-launch, um processo será criado para executá-lo, mas seu contexto não estará disponível. Isso impede que o jogo use corretamente o Gaming Runtime e os serviços de jogos em nuvem. Você pode iniciar seu jogo por app-launch de qualquer uma das seguintes maneiras.- Menu Iniciar (lista de aplicativos, bloco do aplicativo)
- Pesquisa na barra de tarefas (lista de resultados da pesquisa/painel de detalhes)
- Launch do wdapp.exe
- Windows Device Portal (WDP): Installed Apps > Start
Depurando um jogo Win32
No Microsoft Game Development Kit (GDK), jogos Win32 para PC passam pelos caminhos de registro e app-launch ao selecionar F5 para compilar e executar. Isso eleva esse fluxo de trabalho ao mesmo padrão existente no XBOX. Com relação ao Debug Installed App Package no PC Win32, o Debug Installed App Package no Visual Studio não adiciona seu jogo à lista de pacotes que podem ser depurados se o manifesto do jogo se chamar MicrosoftGame.config. O Debug Installed App Package só reconhece seu jogo como um pacote se um arquivo chamado AppXManifest.xml estiver presente na pasta com seu executável. Para contornar isso, você pode criar umAppXManifest simples que contenha valores válidos para o seu jogo e salvá-lo manualmente na pasta com seu executável e o MicrosoftGame.config.