Gerenciador de Jogos do Windows para Desenvolvedores de Jogos

O Windows Vista melhora a experiência do usuário de jogos no Windows, incluindo o Gerenciador de Jogos. O Gerenciador de Jogos é exposto no Menu Iniciar do Windows Vista como a pasta Jogos e fornece um local central para acessar jogos.

A partir da versão de março de 2009 do SDK do DirectX, um novo esquema de arquivo de definição de jogo (GDF) é usado para dar suporte a recursos no Windows 7, provedor de jogos e feed RSS e IGameExplorer2. IGameExplorer2 é uma nova interface no Windows 7 que simplifica o processo de integração de um jogo com o Gerenciador de Jogos.

Este artigo descreve o processo de registro de um jogo com o Gerenciador de Jogos e controles parentais no Windows Vista e no Windows 7 usando o novo esquema GDF.

Nota

O Gerenciador de Jogos não está disponível no Windows 10, versão 1803 e posterior.

Conteúdo:

• pré-requisitos
• integração com um do Instalador
• do Processo de Integração do
• Tarefas do Gerenciador de Jogos
• integração ao InstallScript
• integração em um pacote MSI
• dicas de depuração
  • Teste com de código de exemplo
  • Verifique se o jogo foi removido corretamente
  • Certifique-se de assinar usando o Authenticode
  • Certifique-se de que os controles parentais estão disponíveis
  • Verificar se as tarefas são do tipo correto
  • Verificar os dados no binário GDF
• de Resumo do

Pré-requisitos

Antes de integrar um jogo ao Gerenciador de Jogos, você deve criar um GDF (arquivo de definição de jogo). Um GDF é um arquivo XML que contém metadados que descreve o jogo. Na versão de março de 2009 do SDK do DirectX, uma seção para provedor de jogos, RSS feed e tarefa de jogo foi adicionada ao esquema GDF. Para usar as instruções neste artigo, você deve usar esse novo formato GDF para criar seu arquivo GDF.

A Microsoft fornece uma ferramenta para criar GDFs no SDK do DirectX, Editor de Arquivos de Definição de Jogo, para facilitar esse processo de criação. Essa ferramenta também ajuda você a criar versões localizadas de um GDF.

Depois que um GDF tiver sido criado e localizado, ele deverá ser encapsulado em uma seção de recurso de um arquivo binário (um executável ou uma DLL), juntamente com a miniatura e o ícone do jogo. O GDF contém todos os metadados associados ao jogo, incluindo a classificação do jogo. Os Controles Parentais do Windows usam a classificação do jogo para permitir que os pais controlem o acesso ao jogo. O arquivo binário que contém o GDF deve ser assinado digitalmente com um certificado Authenticode válido; caso contrário, o Gerenciador de Jogos e o sistema de controle parental ignorarão a classificação do jogo, pois as informações de classificação não podem ser confiáveis sem certificação. Para obter mais detalhes sobre como assinar código com o Authenticode, consulte Autenticação de Autenticação para Desenvolvedores de Jogos.

Integração com um Instalador

Para simplificar a integração do Gerenciador de Jogos, o exemplo GameUXInstallHelper fornece uma API comum que pode ser chamada no Windows XP, Windows Vista e Windows 7. Ele foi projetado para trabalhar com scripts para InstallShield e Wise Installation System, bem como ações personalizadas msi e ferramentas de instalação personalizadas. A detecção do sistema operacional é tratada dentro desta DLL de exemplo, portanto, o chamador não precisa se preocupar se o cliente está executando o Windows XP, o Windows Vista ou o Windows 7.

As funções exportadas por essa DLL são as seguintes:

GameExplorerInstallW

Registra um jogo com o Gerenciador de Jogos, dado um caminho para o binário GDF, um caminho completo para a pasta em que o jogo está instalado e o escopo de instalação.

GameExplorerInstallA

Registra um jogo com o Gerenciador de Jogos; Versão ANSI do GameExplorerInstallW.

GameExplorerUninstallW

Remove um jogo do registro com o Gerenciador de Jogos, dado um caminho para o binário GDF.

GameExplorerUninstallA

Remove um jogo do registro com o Gerenciador de Jogos; Versão ANSI do GameExplorerUninstallW.

GameExplorerSetMSIProperties

Configura as propriedades CustomActionData para as ações de uma instalação personalizada adiada pela MSI. O uso dessa função é descrito em detalhes mais adiante neste artigo.

GameExplorerInstallUsingMSI

Adiciona um jogo ao Gerenciador de Jogos; para uso durante uma instalação de ação personalizada msi.

GameExplorerUninstallUsingMSI

Remover um jogo do Gerenciador de Jogos; para uso durante uma instalação de ação personalizada msi.

Essas funções são explicadas ainda mais no cabeçalho GameUXInstallHelper.h.

Processo de integração

Depois que o GDF e os arquivos relacionados tiverem sido adicionados a um recurso binário, é possível integrar o jogo ao Gerenciador de Jogos. Usar GameUXInstallHelper simplificará o processo de integração. Para registrar o jogo no Gerenciador de Jogos, chame o GameExplorerInstall com um caminho para o binário GDF, um caminho completo para a pasta em que o jogo está instalado e o escopo de instalação. Para remover o registro do jogo, chame GameExplorerUninstall com um caminho para o binário GDF.

Observe que o processo de remoção remove apenas uma instalação exclusiva. Se um jogo tiver sido instalado várias vezes, esse processo deverá ser repetido para cada instalação exclusiva.

Tarefas do Gerenciador de Jogos

As tarefas do Gerenciador de Jogos aparecerão no menu de contexto de um item no Gerenciador de Jogos. As tarefas são divididas em tarefas de reprodução e tarefas de suporte. As tarefas de reprodução iniciam um jogo em um modo específico, enquanto as tarefas de suporte atendem a qualquer outra finalidade, incluindo vincular a sites da Web.

No Windows Vista, as tarefas são simplesmente atalhos localizados em pastas específicas. Tarefas de reprodução e tarefas de suporte são armazenadas em pastas com os nomes correspondentes PlayTasks e SupportTasks. GameUXInstallHelper pode ler as informações da tarefa do jogo do arquivo binário GDF e criar todos os atalhos automaticamente.

No Windows 7, os atalhos para as tarefas não são necessários, pois o Gerenciador de Jogos obtém todas as informações da tarefa diretamente do arquivo binário GDF.

Integração ao InstallScript

A chamada de APIs do Gerenciador de Jogos do InstallShield's InstallScript facilita o uso do exemplo GameUXInstallHelper. As etapas necessárias para integrar ao InstallShield são as seguintes:

1. Abra um projeto InstallScript no editor InstallShield.

2. Adicione GameUXInstallHelper.dll ao projeto a ser instalado no diretório de destino.

   Para adicionar GameUXInstallHelper.dll a um projeto InstallScript:

   1. Na guia do Designer de Instalação, clique em de Dados do Aplicativo no painel de navegação à esquerda.

   2. Clique arquivos e pastas e navegue pastas do computador de origem para localizar GameUXInstallerHelper.dll nos arquivos do computador de origem .

      O local padrão para GameUXInstallerHelper.dll é Raiz do SDK do DirectX\Samples\C++\Misc\Bin\x86.

   3. Em pastas do computador de destino, clique em Pasta de Destino do Aplicativo.

   4. Arraste GameUXInstallerHelper.dll dos arquivos do computador de origem para arquivos do computador de destino.

3. No gerenciador InstallScript, clique no arquivo InstallScript (geralmente setup.rul) que chama a função DLL.

4. Cole o seguinte InstallScript no arquivo:

   typedef GUID
   begin
   LONG  Data1;
   SHORT Data2;
   SHORT Data3;
   CHAR  Data4(8);
   end;
   
   prototype LONG GameUXInstallHelper.GameExplorerInstallW(WSTRING, WSTRING, NUMBER);
   prototype LONG GameUXInstallHelper.GameExplorerUninstallW(WSTRING);
   
   function OnMoved()
   
   WSTRING gdfbin[256];
   WSTRING path[256];
   NUMBER scope;
   
   begin
   
   if !MAINTENANCE then
   
   UseDLL( TARGETDIR ^ "GameUXInstallHelper.dll" );
   UseDLL( WINSYSDIR ^ "OLE32.dll" );
   
   path = TARGETDIR;
   gdfbin = TARGETDIR ^ "bin\\ExampleGame.exe";  // TODO: Change this to point to binary containing the GDF
   
   if ALLUSERS == 1 then
   scope = 3;
   else
   scope = 2;
   endif;
   
   GameUXInstallHelper.GameExplorerInstallW( gdfbin, path, scope);
   
   UnUseDLL( TARGETDIR ^ "GameUXInstallHelper.dll" );
   UnUseDLL( WINSYSDIR ^ "OLE32.dll" );
   
   endif;
   
   end;
   
   function OnMoving()
   
   WSTRING gdfbin[256];
   
   begin
   
   if MAINTENANCE && UNINST != "" then
   
   UseDLL( TARGETDIR ^ "GameUXInstallHelper.dll" );
   UseDLL( WINSYSDIR ^ "OLE32.dll" );
   
   gdfbin = path ^ "bin\\ExampleGame.exe";  // TODO: Change this to point to binary containing the GDF
   
   GameUXInstallHelper.GameExplorerUninstallW(gdfbin);
   UnUseDLL( TARGETDIR ^ "GameUXInstallHelper.dll" );
   UnUseDLL( WINSYSDIR ^ "OLE32.dll" );
   
   endif;
   
   end;
   

Integrando-se a um pacote MSI

Veja a seguir uma descrição de alto nível das etapas necessárias para chamar as APIs do Gerenciador de Jogos usando ações personalizadas da MSI:

1. Adicione uma propriedade à tabela propriedade MSI chamada "RelativePathToGDF" que contém o caminho relativo para o binário GDF.
2. Após a ação CostFinalize, chame a função DLL GameUXInstallHelper SetMSIGameExplorerProperties em uma ação personalizada imediata para definir as propriedades msi apropriadas para as outras ações personalizadas.
3. Após a instalação, dispare uma ação personalizada adiada após a ação InstallFiles que chama a função DLL GameUXInstallHelper AddToGameExplorerUsingMSI. Se a instalação for para todos os usuários, a ação personalizada deverá definir o sinalizador msidbCustomActionTypeNoImpersonate; caso contrário, ele não deve definir esse sinalizador. Portanto, duas ações personalizadas quase idênticas são definidas: GameUXAddAsAdmin e GameUXAddAsCurUser.
4. Após a remoção da instalação, dispare uma ação personalizada adiada antes da ação RemoveFiles que chama a função DLL GameUXInstallHelper RemoveFromGameExplorerUsingMSI. Se a instalação for para todos os usuários, a ação personalizada deverá definir o sinalizador msidbCustomActionTypeNoImpersonate; caso contrário, ele não deve definir esse sinalizador. Portanto, duas ações personalizadas quase idênticas são definidas: GameUXRemoveAsAdmin e GameUXRemoveAsCurUser.
5. Defina ações personalizadas de reversão para lidar com o caso em que o usuário cancela a instalação ou remoção depois que uma dessas ações personalizadas já aconteceu. Isso resulta em mais 4 ações personalizadas: GameUXRollBackAddAsAdmin, GameUXRollBackAddAsCurUser, GameUXRollBackRemoveAsAdmin e GameUXRollBackRemoveAsCurUser.

Este procedimento é descrito em detalhes nas instruções a seguir, que descrevem um processo que pode ser feito usando um editor MSI, como o editor orca encontrado no SDK da Plataforma. Alguns editores msi têm assistentes que simplificam algumas dessas etapas de configuração.

Para configurar um pacote MSI para integração com o do Gerenciador de Jogos

1. Abra o pacote MSI em Orca.

2. Adicione a linha mostrada na tabela a seguir à tabela Binary no pacote MSI.

   Nome	Dados
   GAMEUX	caminho do arquivo para a\GameUXInstallHelper.dll de DLL

    

   Nota

   Esse arquivo será inserido no pacote MSI, portanto, você deve executar essa etapa sempre que recompilar GameUXInstallHelper.dll.

    

3. Adicione as linhas mostradas na tabela a seguir à tabela CustomAction no pacote MSI.

   Ação	Tipo	Fonte	Alvo
   GameUXSetMSIProperties	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue = 65	GAMEUX	SetMSIGameExplorerProperties
   GameUXAddAsAdmin	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate = 3137	GAMEUX	AddToGameExplorerUsingMSI
   GameUXAddAsCurUser	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeInScript = 1089	GAMEUX	AddToGameExplorerUsingMSI
   GameUXRollBackAddAsAdmin	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeRollback + msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate = 3393	GAMEUX	RemoveFromGameExplorerUsingMSI
   GameUXRollBackAddAsCurUser	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeRollback + msidbCustomActionTypeInScript = 1345	GAMEUX	RemoveFromGameExplorerUsingMSI
   GameUXRemoveAsAdmin	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate = 3137	GAMEUX	RemoveFromGameExplorerUsingMSI
   GameUXRemoveAsCurUser	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeInScript = 1089	GAMEUX	RemoveFromGameExplorerUsingMSI
   GameUXRollBackRemoveAsAdmin	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeRollback + msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate = 3393	GAMEUX	AddToGameExplorerUsingMSI
   GameUXRollBackRemoveAsCurUser	msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeRollback + msidbCustomActionTypeInScript = 1345	GAMEUX	AddToGameExplorerUsingMSI

    

4. Adicione os valores mostrados para Ação, Condição e Sequência na tabela a seguir à tabela InstallExecuteSequence no pacote MSI.

   Ação	Condição	Seqüenciar	Anotações
   GameUXSetMSIProperties		1015	O número de sequência coloca a ação logo após CostFinalize.
   GameUXAddAsAdmin	NÃO INSTALADO E ALLUSERS	4003	Essa ação personalizada só ocorrerá durante uma nova instalação para todos os usuários. O número de sequência coloca a ação após InstallFiles e após as reversões.
   GameUXAddAsCurUser	NÃO INSTALADO E NÃO ALLUSERS	4004	Essa ação personalizada só ocorrerá durante uma nova instalação somente para o usuário atual. O número de sequência coloca a ação após InstallFiles e após as reversões.
   GameUXRollBackAddAsAdmin	NÃO INSTALADO E ALLUSERS	4001	Essa ação personalizada só acontecerá quando uma nova instalação para todos os usuários for cancelada. O número de sequência coloca a ação após InstallFiles e antes da ação Adicionar personalizada.
   GameUXRollBackAddAsCurUser	NÃO INSTALADO E NÃO ALLUSERS	4002	Essa ação personalizada só ocorrerá quando uma nova instalação do usuário atual for cancelada. O número de sequência coloca a ação após InstallFiles e antes da ação Adicionar personalizada.
   GameUXRemoveAsAdmin	REMOVE~="ALL" E ALLUSERS	3452	Essa ação personalizada só ocorrerá durante a remoção para todos os usuários. O número de sequência coloca a ação diretamente antes de RemoveFiles e após as reversões.
   GameUXRemoveAsCurUser	REMOVE~="ALL" E NÃO ALLUSERS	3453	Essa ação personalizada só ocorrerá durante a remoção do usuário atual. O número de sequência coloca a ação diretamente antes de RemoveFiles e após as reversões.
   GameUXRollBackRemoveAsAdmin	REMOVE~="ALL" E ALLUSERS	3450	Essa ação personalizada só ocorrerá quando a remoção de todos os usuários for cancelada. O número de sequência coloca a ação diretamente antes de RemoveFiles e antes da ação Remover personalizada.
   GameUXRollBackRemoveAsCurUser	REMOVE~="ALL" E NÃO ALLUSERS	3451	Essa ação personalizada só ocorrerá quando a remoção do usuário atual for cancelada. O número de sequência coloca a ação diretamente antes de RemoveFiles e antes da ação Remover personalizada.

    

5. Adicione a linha mostrada na tabela a seguir à tabela Propriedade no pacote MSI.

   Propriedade	Valor
   RelativePathToGDF	caminho de arquivo relativo\name do arquivo binário que contém o GDF

    

   Nota

   O local especificado pelo caminho é relativo ao local especificado pelo caminho de instalação. Por exemplo, bin\GDF.dll.

    

6. Salve o pacote MSI.

Para obter informações mais detalhadas sobre pacotes MSI e Windows Installer, consulte Windows Installer.

Dicas de depuração

Veja a seguir algumas dicas para ajudar a depurar problemas ao chamar APIs do Gerenciador de Jogos:

Testar com o código de exemplo

A criação da solução de exemplo GameUXInstallHelper criará um GameUXInstallHelper.dll e um GDFInstall.exe. O GDFInstall.exe é um aplicativo de exemplo que usa GameUXInstallHelper.dll. Executar GDFInstall.exe solicitará se você quiser instalar ou remover um binário GDF do gerenciador de jogos. Você pode testar seu arquivo binário GDF passando-o como o primeiro arg de linha de comando para GDFInstall.exe.

Se você não tiver um binário GDF ou o seu não for instalado, tente usar o GDF de exemplo no SDK do DirectX. O exemplo GDFExampleBinary é encontrado no SDK do DirectX e é apenas uma DLL que contém apenas um arquivo GDF. Também está incluído na origem seu projeto GDFMaker. Você pode compilá-lo e testá-lo usando GDFInstall.exe. Você também pode comparar seu XML com o seu para identificar exatamente onde está o problema.

Verifique se o jogo foi removido corretamente

Se o jogo já estiver instalado no Gerenciador de Jogos, as chamadas subsequentes para IGameExplorer::AddGame retornarão E_FAIL portanto, verifique se o jogo não está instalado antes do teste. Isso também se aplica se você instalar o GDF somente para o usuário atual e tentar instalar o GDF para todos os usuários. Primeiro, você deve remover o jogo dos usuários atuais antes de IGameExplorer::AddGame terá êxito.

Se você executar GDFInstall.exe enumerar, o aplicativo de exemplo entrará em um modo diferente que enumera todos os jogos instalados do Gerenciador de Jogos e solicitará que você os remova. Você também pode procurar e pesquisar o registro no HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\GameUX para garantir que o jogo não esteja instalado para outro usuário no sistema. No entanto, não altere essas configurações do Registro para qualquer outra finalidade, pois elas não têm garantia de permanecerem compatíveis em versões futuras do sistema operacional.

Certifique-se de assinar usando o Authenticode

Se você forneceu uma classificação, mas não a está vendo no Gerenciador de Jogos, certifique-se de ter usado o Authenticode para assinar o arquivo executável ou DLL que contém a classificação. O Gerenciador de Jogos ignora as informações de classificação em arquivos não assinados. Para obter mais informações sobre o Authenticode, consulte Autenticação de Autenticação para Desenvolvedores de Jogos.

Verifique se os controles parentais estão disponíveis

Verifique se você está testando controles parentais em uma edição do Windows Vista que fornece controles parentais: Home Basic, Home Premium ou Ultimate. O Windows Vista Business e o Windows Vista Enterprise não fornecem controles parentais, no entanto, se você estiver testando no Windows Vista Ultimate e o computador de teste estiver ingressado em um domínio, você deverá alterar uma configuração de política de grupo para tornar os controles parentais visíveis. Para fazer isso, consulte Introdução aodo Gerenciador de Jogos.

Verifique se as tarefas são do tipo correto

Se você especificou tarefas de suporte que não aparecem no Gerenciador de Jogos, verifique se são todos links da Web. Quaisquer outras tarefas de atalho devem ser criadas como tarefas de reprodução. As tarefas são abordadas anteriormente neste artigo no tarefas do Gerenciador de Jogos do.

Verificar os dados no binário GDF

GDFTrace.exe é uma ferramenta encontrada no SDK do DirectX. Você pode executar GDFTrace.exe em seu binário GDF e ele produzirá todos os metadados do GDF contidos no binário para cada idioma com suporte para validação rápida. Ele também exibe quaisquer avisos sobre informações ausentes ou desatualizadas.

Resumo

O Gerenciador de Jogos no Windows Vista fornece uma maneira fácil e personalizável de apresentar seu jogo aos usuários do Windows Vista, mas também exige que você registre o jogo com o sistema durante o processo de instalação. O exemplo GameUXInstallHelper simplifica muito esse processo para desenvolvedores.