Explorador de juegos de Windows para desarrolladores de juegos
Windows Vista mejora la experiencia del usuario al jugar en Windows mediante la inclusión del Explorador de juegos. El Explorador de juegos se expone en el menú inicio de Windows Vista y en la carpeta Juegos y proporciona una ubicación central para acceder a los juegos.
A partir de la versión de marzo de 2009 del SDK de DirectX, se usa un nuevo esquema de archivo de definición de juego (GDF) para admitir características en Windows 7, Proveedor de juegos y Fuente RSS, e IGameExplorer2. IGameExplorer2 es una nueva interfaz en Windows 7 que simplifica el proceso de integración de un juego con el Explorador de juegos.
En este artículo se describe el proceso de registrar un juego con el Explorador de juegos y los controles parentales en Windows Vista y Windows 7 mediante el nuevo esquema GDF.
Nota:
El Explorador de juegos no está disponible en Windows 10, versión 1803 y posteriores.
Contenido:
- Requisitos previos
- Integración con un instalador
- Proceso de integración
- Tareas del Explorador de juegos
- Integración en InstallScript
- Integración en un paquete MSI
- Sugerencias de depuración
- Resumen
Requisitos previos
Para poder integrar un juego en el Explorador de juegos, debe crear un archivo de definición de juego (GDF). Un GDF es un archivo XML que contiene metadatos que describen el juego. En la versión de marzo de 2009 del SDK de DirectX, se ha agregado una sección para el proveedor de juegos, la fuente RSS y la tarea de juego al esquema de GDF. Para usar las instrucciones de este artículo, debe usar este nuevo formato GDF para crear el archivo GDF.
Microsoft proporciona una herramienta para crear GDF en el SDK de DirectX, el editor de archivos de definición de juegos, para facilitar este proceso de creación. Esta herramienta también le ayuda a crear versiones localizadas de un GDF.
Una vez que se ha creado y localizado un GDF, debe encapsularse dentro de una sección de recursos de un archivo binario (ya sea un archivo ejecutable o DLL), junto con la miniatura y el icono del juego. El GDF contiene todos los metadatos asociados al juego, incluida la clasificación del juego. Los controles parentales de Windows usan la clasificación del juego para permitir que los padres controlen el acceso al juego. El archivo binario que contiene el GDF debe estar firmado digitalmente con un certificado Authenticode válido; de lo contrario, el Explorador de juegos y el sistema de control parental ignoran la clasificación del juego, ya que la información de clasificación no puede ser de confianza sin certificación. Para obtener más información sobre la firma de código con Authenticode, consulte Firma de Authenticode para desarrolladores de juegos.
Integración con un instalador
Para simplificar la integración del Explorador de juegos, el ejemplo GameUXInstallHelper proporciona una API común a la que se puede llamar en Windows XP, Windows Vista y Windows 7. Está diseñado para funcionar con scripts para InstallShield y Wise Installation System, así como con acciones personalizadas MSI y herramientas de instalación personalizadas. La detección del sistema operativo se controla dentro de este archivo DLL de ejemplo, por lo que el autor de la llamada no tiene que preocuparse de si el cliente ejecuta Windows XP, Windows Vista o Windows 7.
Las funciones exportadas por este archivo DLL son las siguientes:
-
GameExplorerInstallW
-
Registra un juego con el Explorador de juegos, dada una ruta de acceso al archivo binario de GDF, una ruta de acceso completa a la carpeta donde está instalado el juego y el ámbito de instalación.
-
GameExplorerInstallA
-
Registra un juego con el Explorador de juegos; versión ANSI de GameExplorerInstallW.
-
GameExplorerUninstallW
-
Quita un juego del registro con el Explorador de juegos, dada una ruta de acceso al archivo binario de GDF.
-
GameExplorerUninstallA
-
Quita un juego del registro con el Explorador de juegos; versión ANSI de GameExplorerUninstallW.
-
GameExplorerSetMSIProperties
-
Configura las propiedades CustomActionData para las acciones de una instalación personalizada diferida de MSI. El uso de esta función se describe en detalle más adelante en este artículo.
-
GameExplorerInstallUsingMSI
-
Agrega un juego al Explorador de juegos; para su uso durante una instalación de acción personalizada de MSI.
-
GameExplorerUninstallUsingMSI
-
Quita un juego del Explorador de juegos; para su uso durante una instalación de acción personalizada de MSI.
Estas funciones se explican aún más en el encabezado GameUXInstallHelper.h.
Proceso de integración
Cuando se han agregado los archivos GDF y relacionados a un recurso binario, es posible integrar el juego con el Explorador de juegos. El uso de GameUXInstallHelper simplificará el proceso de integración. Para registrar el juego con el Explorador de juegos, llame a GameExplorerInstall con una ruta de acceso al archivo binario de GDF, una ruta de acceso completa a la carpeta donde está instalado el juego y el ámbito de instalación. Para quitar el registro del juego, llame a GameExplorerUninstall con una ruta de acceso al binario de GDF.
Tenga en cuenta que el proceso de eliminación solo quita una instalación única. Si se ha instalado un juego varias veces, este proceso debe repetirse para cada instalación única.
Tareas del Explorador de juegos
Las tareas del Explorador de juegos aparecerán en el menú contextual de un elemento en el Explorador de juegos. Las tareas se dividen en tareas de juego y tareas de soporte. Las tareas de juego inician un juego en un modo determinado, mientras que las tareas de soporte sirven para cualquier otro propósito, incluida la vinculación a sitios web.
En Windows Vista, las tareas son simplemente accesos directos que se encuentran en carpetas específicas. Las tareas de juego y las tareas de soporte se almacenan en carpetas con los nombres correspondientes PlayTasks y SupportTasks. GameUXInstallHelper puede leer la información de tareas del juego desde el archivo binario GDF y crear todos los accesos directos automáticamente.
En Windows 7, los accesos directos a las tareas no son necesarios, ya que el Explorador de juegos obtiene toda la información de tareas directamente desde el archivo binario de GDF.
Integración en InstallScript
Llamar a las API del Explorador de juegos desde InstallShield de InstallScript se facilita mediante el ejemplo GameUXInstallHelper. Los pasos necesarios para integrar con InstallShield son los siguientes:
Abra un proyecto de InstallScript en el editor de InstallShield.
Agregue GameUXInstallHelper.dll al proyecto que se va a instalar en el directorio de destino.
Para agregar GameUXInstallHelper.dll a un proyecto de InstallScript:
En la pestaña Diseñador de instalación, haga clic en Datos de aplicación en el panel de navegación de la izquierda.
Haga clic en Archivos y carpetas y busque las Carpetas del equipo de origen para buscar GameUXInstallerHelper.dll en los Archivos del equipo de origen.
La ubicación predeterminada de GameUXInstallerHelper.dll es el SDK de DirectX root\Samples\C++\Misc\Bin\x86.
En Carpetas del equipo de destino, haga clic en Carpeta de destino de la aplicación.
Arrastre GameUXInstallerHelper.dll desde los Archivos del equipo de origen a los Archivos del equipo de destino.
En el explorador de InstallScript, haga clic en el archivo InstallScript (normalmente setup.rul) que llama a la función DLL.
Pegue el código InstallScript siguiente en el archivo:
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;
Integración en un paquete MSI
A continuación se muestra una descripción general de los pasos necesarios para llamar a las API del Explorador de juegos mediante acciones personalizadas de MSI:
- Agregue una propiedad a la tabla Property de MSI denominada "RelativePathToGDF" que contiene la ruta de acceso relativa al archivo binario de GDF.
- Después de la acción CostFinalize, llame a la función DLL de GameUXInstallHelper SetMSIGameExplorerProperties en una acción personalizada inmediata para establecer las propiedades MSI adecuadas para las demás acciones personalizadas.
- Tras la instalación, desencadene una acción personalizada diferida después de la acción InstallFiles que llama a la función DLL de GameUXInstallHelper AddToGameExplorerUsingMSI. Si la instalación es para todos los usuarios, la acción personalizada debe establecer la marca msidbCustomActionTypeNoImpersonate; de lo contrario, no debe establecer esta marca. Por lo tanto, se definen dos acciones personalizadas casi idénticas: GameUXAddAsAdmin y GameUXAddAsCurUser.
- Tras la eliminación de la instalación, desencadene una acción personalizada diferida antes de la acción RemoveFiles que llama a la función DLL de GameUXInstallHelper RemoveFromGameExplorerUsingMSI. Si la instalación era para todos los usuarios, la acción personalizada debe establecer la marca msidbCustomActionTypeNoImpersonate; de lo contrario, no debe establecer esta marca. Por lo tanto, se definen dos acciones personalizadas casi idénticas: GameUXRemoveAsAdmin y GameUXRemoveAsCurUser.
- Defina acciones personalizadas de reversión para lidiar con el caso en el que el usuario cancela la instalación o la eliminación después de que ya se haya producido una de estas acciones personalizadas. Esto da como resultado 4 acciones personalizadas adicionales: GameUXRollBackAddAsAdmin, GameUXRollBackAddAsCurUser, GameUXRollBackRemoveAsAdmin y GameUXRollBackRemoveAsCurUser.
Este procedimiento se describe en detalle en las instrucciones siguientes, que describen un proceso que se puede realizar mediante un editor MSI, como el editor Orca que se encuentra en el SDK de la plataforma. Algunos editores MSI tienen asistentes que simplifican algunos de estos pasos de configuración.
Para configurar un paquete MSI para la integración con el Explorador de juegos
Abra el paquete MSI en Orca.
Agregue la fila que se muestra en la tabla siguiente a la tabla Binary del paquete MSI.
Nombre Data GAMEUX ruta de acceso al archivo DLL\GameUXInstallHelper.dll Nota:
Este archivo se incrustará en el paquete MSI, por lo que debe realizar este paso cada vez que vuelva a compilar GameUXInstallHelper.dll.
Agregue las filas que se muestran en la tabla siguiente a la tabla CustomAction del paquete MSI.
Acción Tipo Source Destino 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 Agregue los valores que se muestran para Action, Condition y Sequence en la tabla siguiente a la tabla InstallExecuteSequence en el paquete MSI.
Acción Condición Secuencia Notas GameUXSetMSIProperties 1015 El número de secuencia coloca la acción poco después de CostFinalize. GameUXAddAsAdmin NOT Installed AND ALLUSERS 4003 Esta acción personalizada solo se realizará durante una instalación nueva para todos los usuarios. El número de secuencia coloca la acción después de InstallFiles y después de las reversiones. GameUXAddAsCurUser NOT Installed AND NOT ALLUSERS 4004 Esta acción personalizada solo se realizará durante una instalación nueva para el usuario actual. El número de secuencia coloca la acción después de InstallFiles y después de las reversiones. GameUXRollBackAddAsAdmin NOT Installed AND ALLUSERS 4001 Esta acción personalizada solo se producirá cuando se cancele una instalación nueva para todos los usuarios. El número de secuencia coloca la acción después de InstallFiles y antes de la acción Add personalizada. GameUXRollBackAddAsCurUser NOT Installed AND NOT ALLUSERS 4002 Esta acción personalizada solo se producirá cuando se cancele una instalación nueva para el usuario actual. El número de secuencia coloca la acción después de InstallFiles y antes de la acción Add personalizada. GameUXRemoveAsAdmin REMOVE~="ALL" AND ALLUSERS 3452 Esta acción personalizada solo se realizará durante la eliminación de todos los usuarios. El número de secuencia coloca la acción directamente antes de RemoveFiles y después de las reversiones. GameUXRemoveAsCurUser REMOVE~="ALL" AND NOT ALLUSERS 3453 Esta acción personalizada solo se producirá durante la eliminación del usuario actual. El número de secuencia coloca la acción directamente antes de RemoveFiles y después de las reversiones. GameUXRollBackRemoveAsAdmin REMOVE~="ALL" AND ALLUSERS 3450 Esta acción personalizada solo se producirá cuando se cancele la eliminación de todos los usuarios. El número de secuencia coloca la acción directamente antes de RemoveFiles y antes de la acción Remove personalizada. GameUXRollBackRemoveAsCurUser REMOVE~="ALL" AND NOT ALLUSERS 3451 Esta acción personalizada solo se producirá cuando se cancele la eliminación del usuario actual. El número de secuencia coloca la acción directamente antes de RemoveFiles y antes de la acción Remove personalizada. Agregue la fila que se muestra en la tabla siguiente a la tabla Property del paquete MSI.
Propiedad Valor RelativePathToGDF ruta de acceso del archivo relativo\nombre del archivo binario que contiene el GDF Nota:
La ubicación especificada por la ruta de acceso es relativa a la ubicación especificada por la ruta de instalación. Por ejemplo, bin\GDF.dll.
Guarde el paquete MSI.
Para obtener información más detallada sobre los paquetes MSI y Windows Installer, consulte Windows Installer.
Sugerencias de depuración
A continuación se muestran algunas sugerencias para ayudar a depurar problemas al llamar a las API del Explorador de juegos:
Prueba con código de ejemplo
La compilación de la solución de ejemplo GameUXInstallHelper creará GameUXInstallHelper.dll y GDFInstall.exe. GDFInstall.exe es una aplicación de ejemplo que usa GameUXInstallHelper.dll. Al ejecutar GDFInstall.exe se le pedirá si desea instalar o quitar un archivo binario GDF del explorador de juegos. Para probar el archivo binario GDF, puede pasarlo como el primer argumento de línea de comandos a GDFInstall.exe.
Si no tiene un archivo binario GDF o el suyo no se puede instalar, intente usar el GDF de ejemplo en el SDK de DirectX. El ejemplo GDFExampleBinary se encuentra en el SDK de DirectX y es solo un archivo DLL que contiene únicamente un archivo GDF. También se incluye en el origen su proyecto de GDFMaker. Puede compilarlo y probarlo mediante GDFInstall.exe. También puede comparar su XML con el suyo para identificar exactamente dónde está el problema.
Comprobación de que el juego se quitó correctamente
Si el juego ya está instalado en el Explorador de juegos, las llamadas posteriores a IGameExplorer::AddGame devolverán E_FAIL así que asegúrese de que el juego no esté instalado antes de las pruebas. Esto también se aplica si instala el GDF solo para el usuario actual y, a continuación, intenta instalar el GDF para todos los usuarios. Primero debe quitar el juego de los usuarios actuales antes de que IGameExplorer::AddGame se realice correctamente.
Si ejecuta la enumeración GDFInstall.exe, la aplicación de ejemplo entrará en un modo diferente que enumerará todos los juegos del Explorador de juegos instalados y le pedirá que los quite. También puede examinar y buscar el registro en HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\GameUX para asegurarse de que el juego no esté instalado para otro usuario en el sistema. Sin embargo, no modifique esta configuración del Registro para ningún otro propósito, ya que no se garantiza que sigan siendo compatibles en versiones futuras del sistema operativo.
Comprobación de firmar con Authenticode
Si ha proporcionado una clasificación, pero no la ve en el Explorador de juegos, asegúrese de que ha usado Authenticode para firmar el archivo ejecutable o DLL que contiene la clasificación. El Explorador de juegos omite la información de clasificaciones en archivos sin firmar. Para obtener más información sobre Authenticode, consulte Firma de Authenticode para desarrolladores de juegos.
Comprobación de que los controles parentales están disponibles
Asegúrese de que está probando controles parentales en una edición de Windows Vista que proporciona controles parentales: Home Basic, Home Premium o Ultimate. Windows Vista Business y Windows Vista Enterprise no proporcionan controles parentales, pero si está probando en Windows Vista Ultimate y el equipo de prueba está unido a un dominio, debe cambiar una configuración de directiva de grupo para que los controles parentales sean visibles. Para ello, consulte Introducción al Explorador de juegos.
Comprobación de que las tareas son del tipo correcto
Si ha especificado tareas de soporte que no aparecen en el Explorador de juegos, compruebe que todas son vínculos web. Cualquier otra tarea de método abreviado debe crearse como tareas de juego. Las tareas se tratan anteriormente en este artículo en Tareas del Explorador de juegos.
Comprobación de los datos en el archivo binario de GDF
GDFTrace.exe es una herramienta que se encuentra en el SDK de DirectX. Puede ejecutar GDFTrace.exe en el archivo binario de GDF y generará todos los metadatos de GDF contenidos en el binario para cada idioma compatible para una validación rápida. También muestra las advertencias sobre la falta o la información obsoleta.
Resumen
El Explorador de juegos en Windows Vista proporciona una manera fácil y personalizable de presentar un juego a los usuarios de Windows Vista, pero también requiere que registre el juego con el sistema durante el proceso de instalación. El ejemplo GameUXInstallHelper simplifica considerablemente este proceso para los desarrolladores.