Windows Games Explorer untuk Pengembang Game

Artikel
06/13/2023

Windows Vista meningkatkan pengalaman pengguna bermain game di Windows dengan menyertakan Games Explorer. Games Explorer diekspos di Menu Mulai Windows Vista sebagai folder Permainan dan menyediakan lokasi terpusat untuk mengakses permainan.

Dimulai dengan rilis DirectX SDK Maret 2009, skema file definisi game (GDF) baru digunakan untuk mendukung fitur di Windows 7, Penyedia Game dan umpan RSS, dan IGameExplorer2. IGameExplorer2 adalah antarmuka baru di Windows 7 yang menyederhanakan proses integrasi game dengan Games Explorer.

Artikel ini menguraikan proses mendaftarkan game dengan Games Explorer dan kontrol orang tua pada Windows Vista dan Windows 7 dengan menggunakan skema GDF baru.

Catatan

Game Explorer tidak tersedia di Windows 10, versi 1803, dan yang lebih baru.

Isi:

Prasyarat
Mengintegrasikan dengan Alat Penginstal
Proses Integrasi
Tugas Penjelajah Permainan
Mengintegrasikan ke dalam InstallScript
Mengintegrasikan ke dalam Paket MSI
Tips Penelusuran Kesalahan
Ringkasan

Prasyarat

Sebelum dapat mengintegrasikan game ke dalam Games Explorer, Anda harus membuat file definisi game (GDF). GDF adalah file XML yang berisi metadata yang menjelaskan permainan. Dalam rilis Maret 2009 dari DirectX SDK, bagian untuk penyedia game, umpan RSS, dan tugas permainan telah ditambahkan ke skema GDF. Untuk menggunakan instruksi dalam artikel ini, Anda harus menggunakan format GDF baru ini untuk membuat file GDF Anda.

Microsoft menyediakan alat untuk menulis GDF di DirectX SDK, Editor File Definisi Game, untuk mempermudah proses pembuatan ini. Alat ini juga membantu Anda membuat versi GDF yang dilokalkan.

Setelah GDF ditulis dan dilokalkan, GDF harus dienkapsulasi dalam bagian sumber daya dari file biner (baik yang dapat dieksekusi atau DLL), bersama dengan gambar mini dan ikon permainan. GDF berisi semua metadata yang terkait dengan game, termasuk peringkat game. Kontrol Orangtua Windows menggunakan peringkat permainan untuk memperbolehkan orang tua mengontrol akses ke permainan. File biner yang berisi GDF harus ditandatangani secara digital dengan sertifikat Authenticode yang valid; jika tidak, Games Explorer dan sistem kontrol orang tua mengabaikan peringkat permainan, karena informasi peringkat tidak dapat dipercaya tanpa sertifikasi. Untuk detail selengkapnya tentang penandatanganan kode dengan Authenticode, lihat Penandatanganan Authenticode untuk Pengembang Game.

Mengintegrasikan dengan Alat Penginstal

Untuk menyederhanakan integrasi Games Explorer, sampel GameUXInstallHelper menyediakan API umum yang dapat dipanggil pada Windows XP, Windows Vista, dan Windows 7. Ini dirancang untuk bekerja dengan skrip untuk InstallShield dan Wise Installation System, serta tindakan kustom MSI dan alat penginstalan kustom. Deteksi sistem operasi ditangani di dalam DLL sampel ini, sehingga pemanggil tidak perlu khawatir apakah klien menjalankan Windows XP, Windows Vista, atau Windows 7.

Fungsi yang diekspor oleh DLL ini adalah sebagai berikut:

GameExplorerInstallW: Mendaftarkan game dengan Games Explorer, diberikan jalur ke biner GDF, jalur lengkap ke folder tempat permainan diinstal, dan cakupan penginstalan.
GameExplorerInstallA: Mendaftarkan game dengan Games Explorer; Versi ANSI dari GameExplorerInstallW.
GameExplorerUninstallW: Menghapus game dari pendaftaran dengan Games Explorer, diberikan jalur ke biner GDF.
GameExplorerUninstallA: Menghapus permainan dari pendaftaran dengan Games Explorer; Versi ANSI dari GameExplorerUninstallW.
GameExplorerSetMSIProperties: Mengonfigurasi properti CustomActionData untuk tindakan penginstalan kustom yang ditangguhkan MSI. Penggunaan fungsi ini dijelaskan secara rinci nanti di artikel ini.
GameExplorerInstallUsingMSI: Menambahkan permainan ke Games Explorer; untuk digunakan selama penginstalan tindakan kustom MSI.
GameExplorerUninstallUsingMSI: Hapus permainan dari Games Explorer; untuk digunakan selama penginstalan tindakan kustom MSI.

Fungsi-fungsi ini dijelaskan lebih lanjut dalam header GameUXInstallHelper.h.

Proses Integrasi

Setelah GDF dan file terkait ditambahkan ke sumber daya biner, maka dimungkinkan untuk mengintegrasikan game dengan Games Explorer. Menggunakan GameUXInstallHelper akan menyederhanakan proses integrasi. Untuk mendaftarkan game dengan Games Explorer, panggil GameExplorerInstall dengan jalur ke biner GDF, jalur lengkap ke folder tempat permainan diinstal, dan cakupan penginstalan. Untuk menghapus pendaftaran game, panggil GameExplorerUninstall dengan jalur ke biner GDF.

Perhatikan bahwa proses penghapusan hanya menghapus satu instalasi unik. Jika permainan telah diinstal beberapa kali, proses ini harus diulang untuk setiap penginstalan unik.

Tugas Penjelajah Permainan

Tugas Games Explorer akan muncul di menu konteks item di Games Explorer. Tugas dibagi menjadi tugas putar dan tugas dukungan. Mainkan tugas meluncurkan permainan ke mode tertentu, sementara tugas dukungan melayani tujuan lain, termasuk menautkan ke situs web.

Di Windows Vista, tugas hanyalah pintasan yang terletak di folder tertentu. Tugas putar dan tugas dukungan disimpan dalam folder dengan nama PlayTasks dan SupportTasks yang sesuai. GameUXInstallHelper dapat membaca informasi tugas game dari file biner GDF dan membuat semua pintasan secara otomatis.

Di Windows 7, pintasan ke tugas tidak diperlukan, karena Games Explorer mendapatkan semua informasi tugas langsung dari file biner GDF.

Mengintegrasikan ke dalam InstallScript

Memanggil API Games Explorer dari InstallScript InstallShield menjadi mudah dengan menggunakan sampel GameUXInstallHelper. Langkah-langkah yang diperlukan untuk berintegrasi dengan InstallShield adalah sebagai berikut:

Buka proyek InstallScript di editor InstallShield.
Tambahkan GameUXInstallHelper.dll ke proyek yang akan diinstal ke direktori target.

Untuk menambahkan GameUXInstallHelper.dll ke proyek InstallScript:
1. Pada tab Perancang Penginstalan, klik Data Aplikasi di panel navigasi di sebelah kiri.
2. Klik File dan Folder dan telusuri folder komputer Sumber untuk menemukan GameUXInstallerHelper.dll di file komputer sumber.
  
  Lokasi default untuk GameUXInstallerHelper.dll adalah DirectX SDK root\Samples\C++\Misc\Bin\x86.
3. Di bawah Folder komputer tujuan, klik Folder Target Aplikasi.
4. Seret GameUXInstallerHelper.dll dari File komputer sumber ke file komputer Tujuan.
Di penjelajah InstallScript, klik file InstallScript (biasanya setup.rul) yang memanggil fungsi DLL.

Tempelkan InstallScript berikut ke dalam file:

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;

Mengintegrasikan ke dalam Paket MSI

Berikut ini adalah deskripsi tingkat tinggi dari langkah-langkah yang diperlukan untuk memanggil API Games Explorer menggunakan tindakan kustom MSI:

Tambahkan properti ke tabel Properti MSI yang disebut "RelativePathToGDF" yang berisi jalur relatif ke biner GDF.
Setelah tindakan CostFinalize, panggil fungsi GameUXInstallHelper DLL SetMSIGameExplorerProperties dalam tindakan kustom langsung untuk mengatur properti MSI yang sesuai untuk tindakan kustom lainnya.
Setelah penginstalan, picu tindakan kustom yang ditangguhkan setelah tindakan InstallFiles yang memanggil fungsi Dll GameUXInstallHelper AddToGameExplorerUsingMSI. Jika penginstalan adalah untuk semua pengguna, maka tindakan kustom harus mengatur bendera msidbCustomActionTypeNoImpersonate; jika tidak, tidak boleh mengatur bendera ini. Oleh karena itu, dua tindakan kustom yang hampir identik didefinisikan: GameUXAddAsAdmin dan GameUXAddAsCurUser.
Setelah penginstalan dihapus, picu tindakan kustom yang ditangguhkan sebelum tindakan RemoveFiles yang memanggil fungsi Dll GameUXInstallHelper RemoveFromGameExplorerUsingMSI. Jika penginstalan untuk semua pengguna, maka tindakan kustom harus mengatur bendera msidbCustomActionTypeNoImpersonate; jika tidak, tidak boleh mengatur bendera ini. Oleh karena itu, dua tindakan kustom yang hampir identik didefinisikan: GameUXRemoveAsAdmin dan GameUXRemoveAsCurUser.
Tentukan tindakan kustom putar kembali untuk menangani kasus di mana pengguna membatalkan penginstalan atau penghapusan setelah salah satu tindakan kustom ini telah terjadi. Ini menghasilkan 4 tindakan kustom tambahan: GameUXRollBackAddAsAdmin, GameUXRollBackAddAsCurUser, GameUXRollBackRemoveAsAdmin, dan GameUXRollBackRemoveAsCurUser.

Prosedur ini dijelaskan secara rinci dalam instruksi berikut, yang menjelaskan proses yang dapat dilakukan menggunakan editor MSI, seperti editor Orca yang ditemukan di Platform SDK. Beberapa editor MSI memiliki wizard yang menyederhanakan beberapa langkah konfigurasi ini.

Untuk mengonfigurasi paket MSI untuk integrasi dengan Games Explorer

Buka paket MSI di Orca.
Tambahkan baris yang diperlihatkan dalam tabel berikut ke tabel Biner dalam paket MSI.

Nama Data

GAMEUX jalur file ke DLL\GameUXInstallHelper.dll

Catatan

File ini akan disematkan dalam paket MSI, jadi Anda harus melakukan langkah ini setiap kali Anda mengkompilasi ulang GameUXInstallHelper.dll.

Nama	Data
GAMEUX	jalur file ke DLL\GameUXInstallHelper.dll

Tambahkan baris yang diperlihatkan dalam tabel berikut ke tabel CustomAction dalam paket MSI.

Perbuatan	Jenis	Sumber	Target
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

Tambahkan nilai yang ditampilkan untuk Tindakan, Kondisi, dan Urutan dalam tabel berikut ke tabel InstallExecuteSequence dalam paket MSI.

Perbuatan	Kondisi	Sequence	Catatan
GameUXSetMSIProperties		1015	Nomor urut menempatkan tindakan segera setelah CostFinalize.
GameUXAddAsAdmin	TIDAK Terinstal DAN ALLUSERS	4003	Tindakan kustom ini hanya akan terjadi selama penginstalan baru untuk semua pengguna. Nomor urutan menempatkan tindakan setelah InstallFiles dan setelah pemutaran kembali.
GameUXAddAsCurUser	TIDAK Terinstal DAN BUKAN ALLUSERS	4004	Tindakan kustom ini hanya akan terjadi selama penginstalan baru untuk pengguna saat ini saja. Nomor urutan menempatkan tindakan setelah InstallFiles dan setelah pemutaran kembali.
GameUXRollBackAddAsAdmin	TIDAK Terinstal DAN ALLUSERS	4001	Tindakan kustom ini hanya akan terjadi ketika penginstalan baru untuk semua pengguna dibatalkan. Nomor urutan menempatkan tindakan setelah InstallFiles dan sebelum tindakan Tambahkan kustom.
GameUXRollBackAddAsCurUser	TIDAK Terinstal DAN BUKAN ALLUSERS	4002	Tindakan kustom ini hanya akan terjadi ketika penginstalan baru untuk pengguna saat ini hanya dibatalkan. Nomor urutan menempatkan tindakan setelah InstallFiles dan sebelum tindakan Tambahkan kustom.
GameUXRemoveAsAdmin	REMOVE~="ALL" DAN ALLUSERS	3452	Tindakan kustom ini hanya akan terjadi selama penghapusan untuk semua pengguna. Nomor urutan menempatkan tindakan langsung sebelum RemoveFiles dan setelah pemutaran kembali.
GameUXRemoveAsCurUser	REMOVE~="ALL" DAN BUKAN ALLUSERS	3453	Tindakan kustom ini hanya akan terjadi selama penghapusan untuk pengguna saat ini. Nomor urutan menempatkan tindakan langsung sebelum RemoveFiles dan setelah pemutaran kembali.
GameUXRollBackRemoveAsAdmin	REMOVE~="ALL" DAN ALLUSERS	3450	Tindakan kustom ini hanya akan terjadi ketika penghapusan untuk semua pengguna dibatalkan. Nomor urutan menempatkan tindakan langsung sebelum RemoveFiles dan sebelum tindakan Hapus kustom.
GameUXRollBackRemoveAsCurUser	REMOVE~="ALL" DAN BUKAN ALLUSERS	3451	Tindakan kustom ini hanya akan terjadi ketika penghapusan untuk pengguna saat ini dibatalkan. Nomor urutan menempatkan tindakan langsung sebelum RemoveFiles dan sebelum tindakan Hapus kustom.

Tambahkan baris yang diperlihatkan dalam tabel berikut ke tabel Properti dalam paket MSI.

Properti Nilai

RelativePathToGDF jalur file relatif\nama file biner yang berisi GDF

Catatan

Lokasi yang ditentukan oleh jalur relatif terhadap lokasi yang ditentukan oleh jalur penginstalan. Misalnya, bin\GDF.dll.
Simpan paket MSI.

Properti	Nilai
RelativePathToGDF	jalur file relatif\nama file biner yang berisi GDF

Untuk informasi selengkapnya tentang paket MSI dan Penginstal Windows, lihat Penginstal Windows.

Tips Penelusuran Kesalahan

Berikut ini adalah beberapa tips untuk membantu men-debug masalah saat memanggil API Games Explorer:

Uji dengan kode sampel

Membangun solusi sampel GameUXInstallHelper akan membuat GameUXInstallHelper.dll dan GDFInstall.exe. GDFInstall.exe adalah aplikasi sampel yang menggunakan GameUXInstallHelper.dll. Menjalankan GDFInstall.exe akan meminta jika Anda ingin menginstal atau menghapus biner GDF dari penjelajah game. Anda dapat menguji file biner GDF Anda dengan meneruskannya sebagai baris perintah pertama arg ke GDFInstall.exe.

Jika Anda tidak memiliki biner GDF atau biner Anda gagal diinstal, coba gunakan sampel GDF di DirectX SDK. Sampel GDFExampleBinary ditemukan di DirectX SDK dan hanyalah DLL yang hanya berisi file GDF. Juga termasuk dalam sumbernya adalah proyek GDFMaker-nya. Anda dapat membangunnya dan mengujinya menggunakan GDFInstall.exe. Anda juga dapat membandingkan XML-nya dengan XML Anda untuk menentukan dengan tepat di mana masalahnya berada.

Pastikan permainan Anda dihapus dengan benar

Jika game sudah diinstal di Games Explorer, maka panggilan berikutnya ke IGameExplorer::AddGame akan mengembalikan E_FAIL jadi pastikan game Anda tidak diinstal sebelum pengujian. Ini juga berlaku jika Anda menginstal GDF hanya untuk pengguna saat ini dan kemudian mencoba menginstal GDF untuk semua pengguna. Anda harus terlebih dahulu menghapus game dari pengguna saat ini sebelum IGameExplorer::AddGame akan berhasil.

Jika Anda menjalankan enum GDFInstall.exe, aplikasi sampel akan memasuki mode berbeda yang akan menghitung semua game Games Explorer yang diinstal dan meminta Anda untuk menghapusnya. Anda juga dapat menelusuri dan mencari registri di HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\GameUX untuk memastikan bahwa game Anda tidak diinstal untuk pengguna lain pada sistem. Namun, jangan mengubah pengaturan registri ini untuk tujuan lain, karena tidak dijamin tetap kompatibel dalam versi sistem operasi di masa mendatang.

Pastikan untuk menandatangani menggunakan Authenticode

Jika Anda telah memberikan peringkat, tetapi tidak melihatnya di Games Explorer, pastikan Anda telah menggunakan Authenticode untuk menandatangani file executable atau DLL yang berisi peringkat. Penjelajah Permainan mengabaikan informasi peringkat dalam file yang tidak ditandatangani. Untuk informasi selengkapnya tentang Authenticode, lihat Penandatanganan Authenticode untuk Pengembang Game.

Pastikan kontrol orang tua tersedia

Pastikan Anda menguji kontrol orang tua pada edisi Windows Vista yang menyediakan kontrol orang tua: Home Basic, Home Premium, atau Ultimate. Windows Vista Business dan Windows Vista Enterprise tidak menyediakan kontrol orang tua namun jika Anda menguji pada Windows Vista Ultimate, dan komputer pengujian bergabung ke domain, Anda harus mengubah pengaturan kebijakan grup membuat kontrol orang tua terlihat. Untuk melakukan ini, lihat Memulai Games Explorer.

Verifikasi bahwa tugas berjenis benar

Jika Anda telah menentukan tugas dukungan yang tidak muncul di Games Explorer, verifikasi bahwa semua itu adalah tautan Web. Tugas pintasan lainnya harus dibuat sebagai tugas putar. Tugas dibahas sebelumnya dalam artikel ini di Tugas Games Explorer.

Memverifikasi data dalam biner GDF

GDFTrace.exe adalah alat yang ditemukan di DirectX SDK. Anda dapat menjalankan GDFTrace.exe pada biner GDF Anda dan itu akan menghasilkan semua metadata GDF yang terkandung dalam biner untuk setiap bahasa yang didukung untuk validasi cepat. Ini juga menampilkan peringatan tentang informasi yang hilang atau kedaluarsa.

Ringkasan

Games Explorer di Windows Vista menyediakan cara yang mudah dan dapat disesuaikan untuk menyajikan permainan Anda kepada pengguna Windows Vista, tetapi juga mengharuskan Anda untuk mendaftarkan permainan dengan sistem selama proses penginstalan. Sampel GameUXInstallHelper sangat menyederhanakan proses ini untuk pengembang.

Bagikan melalui