Explorador de Jogos do Windows para Programadores de Jogos

O Windows Vista melhora a experiência do usuário com jogos no Windows ao incluir o Explorador de Jogos. O Explorador de Jogos é exposto no Menu Iniciar do Windows Vista como a pasta Jogos e fornece uma localização central para aceder aos 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 oferecer suporte a recursos no Windows 7, Game Provider e RSS feed e IGameExplorer2. IGameExplorer2 é uma nova interface no Windows 7 que simplifica o processo de integração de um jogo com o Games Explorer.

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

Observação

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

Índice:

Pré-requisitos

Antes de integrar um jogo no Explorador de Jogos, tem de criar um ficheiro de definição de jogo (GDF). Um GDF é um arquivo XML que contém metadados que descrevem 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, Game Definition File Editor, para facilitar esse processo de criação. Essa ferramenta também ajuda a criar versões localizadas de um GDF.

Uma vez que um GDF tenha sido criado e localizado, ele deve ser encapsulado dentro de uma seção de recursos de um arquivo binário (executável ou 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 Controlos Parentais do Windows utilizam 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 Explorador de Jogos e o sistema de controlo parental ignoram a classificação do jogo, porque as informações de classificação não podem ser fidedignas sem certificação. Para obter mais detalhes sobre como assinar código com o Authenticode, consulte Authenticode Signing for Game Developers.

Integração com um instalador

Para simplificar a integração do Games Explorer, 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 deteçã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, Windows Vista ou Windows 7.

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

GameExplorerInstallW

Registra um jogo com o Games Explorer, dado um caminho para o binário GDF, um caminho completo para a pasta onde o jogo está instalado e o escopo da instalação.

GameExplorerInstallA

Regista um jogo com o Explorador de Jogos; ANSI versão do GameExplorerInstallW.

GameExplorerUninstallW

Remove um jogo do registo no Explorador de Jogos, dado um caminho para o binário GDF.

GameExplorerUninstallA

Remove um jogo do registo no Explorador de Jogos; ANSI versão do GameExplorerUninstallW.

GameExplorerSetMSIProperties

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

GameExplorerInstallUsingMSI

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

GameExplorerUninstallUsingMSI

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

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

Processo de Integração

Uma vez que o GDF e arquivos relacionados foram adicionados a um recurso binário, é possível integrar o jogo com o Games Explorer. Usar GameUXInstallHelper simplificará o processo de integração. Para registrar o jogo no Games Explorer, chame o GameExplorerInstall com um caminho para o binário GDF, um caminho completo para a pasta onde o jogo está instalado e o escopo da instalação. Para remover o registro do jogo, chame GameExplorerUninstall com um caminho para o binário GDF.

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

Tarefas do Explorador de Jogos

As tarefas do Explorador de Jogos aparecerão no menu de contexto de um item no Explorador de Jogos. As tarefas são divididas em tarefas lúdicas e tarefas de apoio. As tarefas de jogo iniciam um jogo num modo específico, enquanto as tarefas de suporte servem qualquer outro propósito, incluindo a ligação a Web sites.

No Windows Vista, as tarefas são simplesmente atalhos localizados em pastas específicas. As tarefas de jogo e as 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 a partir 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, porque o Explorador de Jogos obtém todas as informações da tarefa diretamente do arquivo binário GDF.

Integração no InstallScript

Chamar APIs do Games Explorer a partir do InstallScript do InstallShield é facilitado usando o exemplo GameUXInstallHelper. As etapas necessárias para integrar com o InstallShield são as seguintes:

  1. Abra um projeto InstallScript no editor do 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 Designer de Instalação, clique em Dados do Aplicativo no painel de navegação à esquerda.

    2. Clique em Arquivos e Pastas e navegue nas pastas do computador 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 explorador 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;

Integração em um pacote MSI

A seguir está uma descrição de alto nível das etapas necessárias para chamar as APIs do Games Explorer usando ações personalizadas MSI:

  1. Adicione uma propriedade à tabela MSI Property chamada "RelativePathToGDF" contendo 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, acione 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, não deve definir este sinalizador. Portanto, duas ações personalizadas quase idênticas são definidas: GameUXAddAsAdmin e GameUXAddAsCurUser.
  4. Após a remoção da instalação, acione uma ação personalizada adiada antes da ação RemoveFiles que chama a função DLL GameUXInstallHelper RemoveFromGameExplorerUsingMSI. Se a instalação foi para todos os usuários, a ação personalizada deve definir o sinalizador msidbCustomActionTypeNoImpersonate; caso contrário, não deve definir este 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 após uma dessas ações personalizadas já ter acontecido. Isso resulta em 4 ações personalizadas adicionais: 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 Platform SDK. Alguns editores MSI têm assistentes que simplificam algumas dessas etapas de configuração.

Para configurar um pacote MSI para integração com o Games Explorer

  1. Abra o pacote MSI no Orca.

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

    Designação Dados
    GAMEUX caminho do arquivo para a\GameUXInstallHelper.dll DLL

     

    Observação

    Este arquivo será incorporado no pacote MSI, então você deve fazer esta etapa toda vez que recompilar GameUXInstallHelper.dll.

     

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

    Ação Tipo Fonte Público-alvo
    GameUXSetMSIProperties msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue = 65 GAMEUX SetMSIGameExplorerProperties
    GameUXAddAsAdmin msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeInScript + msidbCustomActionTypeNoImpersonate = 3137 GAMEUX AddToGameExplorerUsandoMSI
    GameUXAddAsCurUser msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeInScript = 1089 GAMEUX AddToGameExplorerUsandoMSI
    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 AddToGameExplorerUsandoMSI
    GameUXRollBackRemoveAsCurUser msidbCustomActionTypeDll + msidbCustomActionTypeBinaryData + msidbCustomActionTypeContinue + msidbCustomActionTypeRollback + msidbCustomActionTypeInScript = 1345 GAMEUX AddToGameExplorerUsandoMSI

     

  4. Adicione os valores mostrados para Action, Condition e Sequence na tabela a seguir à tabela InstallExecuteSequence no pacote MSI.

    Ação Condição Sequência Observaçõ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ó acontecerá 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 NEM TODOS OS UTILIZADORES 4004 Essa ação personalizada só acontecerá durante uma nova instalação apenas 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 NEM TODOS OS UTILIZADORES 4002 Essa ação personalizada só acontecerá quando uma nova instalação para o 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 Esta ação personalizada só acontecerá 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~="TODOS" E NÃO TODOSOS USUÁRIOS 3453 Esta ação personalizada só acontecerá durante a remoção para o 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 Esta ação personalizada só acontecerá quando a remoção para 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 personalizada Remover.
    GameUXRollBackRemoveAsCurUser REMOVE~="TODOS" E NÃO TODOSOS USUÁRIOS 3451 Essa ação personalizada só acontecerá quando a remoção para o usuário atual for cancelada. O número de sequência coloca a ação diretamente antes de RemoveFiles e antes da ação personalizada Remover.

     

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

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

     

    Observação

    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 o Windows Installer, consulte Windows Installer.

Dicas de depuração

A seguir estão algumas dicas para ajudar a depurar problemas ao chamar APIs do Games Explorer:

Teste com 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 perguntará se você deseja instalar ou remover um binário GDF do explorador de jogos. Você pode testar seu arquivo binário GDF passando-o como a primeira linha de comando arg para GDFInstall.exe.

Se você não tiver um binário GDF ou se o seu não conseguir instalar, 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 fonte o seu projeto GDFMaker. Você pode criá-lo e testá-lo usando GDFInstall.exe. Você também pode comparar seu XML com o seu para identificar exatamente onde está o problema.

Certifique-se de que o jogo foi removido corretamente

Se o jogo já estiver instalado no Explorador de Jogos, as chamadas subsequentes para IGameExplorer::AddGame retornarão E_FAIL portanto, certifique-se de que seu jogo não esteja instalado antes do teste. Isso também se aplica se você instalar o GDF apenas para o usuário atual e, em seguida, tentar instalar o GDF para todos os usuários. Você deve primeiro remover o jogo dos usuários atuais antes que IGameExplorer::AddGame seja bem-sucedido.

Se você executar GDFInstall.exe enum, o aplicativo de exemplo entrará em um modo diferente que enumerará todos os jogos do Games Explorer instalados e solicitará que você os remova. Você também pode navegar e pesquisar o registro em HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\GameUX para se certificar de que seu jogo não está instalado para outro usuário no sistema. No entanto, não altere essas configurações do Registro para qualquer outra finalidade, pois não é garantido que elas permaneçam compatíveis em versões futuras do sistema operacional.

Certifique-se de assinar usando o Authenticode

Se tiver fornecido uma classificação, mas não a estiver a ver no Explorador de Jogos, certifique-se de que utilizou o Authenticode para assinar o ficheiro executável ou DLL que contém a classificação. O Explorador de Jogos ignora as informações de classificação em ficheiros não assinados. Para obter mais informações sobre o Authenticode, consulte Authenticode Signing for Game Developers.

Certifique-se de que os controlos parentais estão disponíveis

Certifique-se de que está a testar os controlos parentais numa edição do Windows Vista que fornece controlos 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 associado a um domínio, você deverá alterar uma configuração de diretiva de grupo para tornar os controles parentais visíveis. Para fazer isso, consulte Introdução ao Explorador 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 em Tarefas do Explorador de Jogos.

Verifique os dados em 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 GDF contidos no binário para cada idioma suportado para validação rápida. Ele também exibe avisos sobre informações ausentes ou desatualizadas.

Resumo

O Explorador de Jogos no Windows Vista fornece uma forma fácil e personalizável de apresentar o seu jogo aos utilizadores do Windows Vista, mas também requer que registe o jogo no sistema durante o processo de instalação. O exemplo GameUXInstallHelper simplifica muito esse processo para os desenvolvedores.

 

 

  • Last updated on