The new GDK Extension allows you to publish games on the Microsoft Store and make use of Xbox Live functionality for implementing features such as save games, player stats, rich presence, achievements and in-app purchases via add-ons. The GDK extension is available for download on GitHub for free.
The GitHub repository also contains the source for the GDK extension and steps on building it, if you would like to make modifications and build your own version of the extension. A demo project is also provided within the same repository.
Note: Packages exported with the GDK extension are published via the Partner Center onto the Microsoft Store, so make sure to read its guide as well.
Requirements
The GDK Extension only supports x64 Windows builds, so make sure to enable the x64 Windows Runtime in Game Options -> Windows -> General.
Hit "Apply" or "OK", and your project is now ready for use with the GDK Extension!
A small note about the Partner Center: Under Xbox services -> Xbox Settings -> Device families for your game, "Windows 10 PC" needs to be enabled so you are able to publish your game on Windows using the GDK extension.
Getting the Extension
The extension is used with the Windows target provided with GameMaker Studio 2. You first need to download it from the Releases page on GitHub:
Once the ZIP file is extracted, you will see the following files alongside a readme text file:
- GDK Extension.yymps: This is the actual extension file and can be dragged into the GMS2 IDE to import it into your project.
You can also use the Tools -> Import Local Package option to import this file. - post_package_step.bat & post_run_step.bat: These files need to be placed in your GMS2 project's root folder (the same place where the .yyp is stored)
Tip: You can quickly open your project directory by right-clicking anywhere in the Asset Browser and selecting "Open in Explorer" (or "Open in Finder" on Mac).
Importing the Extension
The extension contains several files inside its "Included Files" (/datafiles) directory, including template logos required for the submission to the Partner Center, a template config file for you to fill, and a PDF file with documentation for the extension.
It also contains the extension asset itself (GDKExtension) with the GDK DLL.
Click on "Add All" and then "Import".
Configuration
Exporting with the GDK extension requires you to set up a MicrosoftGame.Config file (an XML file) and place it in the Included Files of your project.
The extension itself comes with a template config file for you to fill, and you also have the option of looking at the demo project and copying the config from there. Do note that you will need to replace the values for most of the XML tags in order to publish a functional game to the Microsoft Store.
You can also use Microsoft's Config tool to generate this file and then place it in your Included Files.
Visuals
The config file allows you to supply logos for your game under the ShellVisuals tag, such as StoreLogo, Square150x150Logo, and more (as can be seen in the screenshot above). These files must be present in your Included Files directory as well, and templates for these are also provided with the extension:
Optional Manifest
This is an optional step that you can complete while setting up your extension.
If you wish to use Event-based functions for your stats and achievements (as opposed to title-managed functions) you must set up a manifest file containing information on your stats and leaderboards. More information about these functions is included in the extension's documentation.
Note: You will only be able to retrieve the Manifest for your stats if your Stats configuration system is set to use Event-Based Stats.
This is found under Xbox services -> Xbox Settings -> Data Platform Setting on your game's page on the Partner Center.
Here's how you can include this Manifest file in your project:
- Open your game on the Partner Center.
- Go under Xbox services and select Gameplay settings.
- Open the Player stats drop-down menu and select Stat rules.
- Click on Download published events manifest next to the New event button.
- Place the downloaded file in the Included Files of your project. Your project is now ready to use event-based functions!
If you publish any new changes on the Gameplay settings section of your game, you must download the manifest file again and add it to your project, replacing the older version of the manifest.
Extension Usage with GML
The following three functions must be used in your game for the GDK extension to be functional:
- gdk_init(scid): This must be called before any other GDK function. It is recommended to use a persistent "controller"/"manager" object and to call this function in its Create or Game Start event.
The SCID can be found on your game's page on the Partner Center, under Game setup -> Identity details -> Show details -> Xbox IDs -> Xbox Service Configuration ID.
- gdk_update(): This must be called every frame that the GDK extension is used. This can be placed in the Step event of your persistent manager object.
- gdk_quit(): This must be called when the game ends (it is recommended to place this in the Clean Up event of your persistent manager object). No GDK functions must be called after calling this function.
More information about these functions is included in the extension's PDF documentation (which can be found in its Included Files).
GDK Extension Modules
Let's have a brief look at the different modules present in the GDK extension, which allow you to make use of various Xbox Live functionality.
Detailed information about these modules can be found in the extension's documentation.
- Base Module: The base module allows you to get information about the users logged in on the system, the user currently controlling the game and allows you to show the account picker so the player can select the account they wish to play with.
- Storage Module: The storage module allows you to save and load game data using buffers, and to attach saves to user accounts.
- Xbox Live Module: The Xbox Live module allows you to work with various social features such as stats, leaderboards, achievements and rich presence. You can choose to either use event-based functions (which require the optional manifest mentioned earlier in this blog) or title-managed functions (which are recommended for achievements).
- In-App Purchases Module: The IAP module allows you to work with various kinds of add-ons, such as consumables, durables, subscriptions and DLCs.
Exporting with the GDK Extension
You can use the regular Windows target to export your game while the GDK Extension is simply present in your project. This will export a ZIP file with a package folder containing the files you need to upload your game to the Microsoft Store, mainly the .msixcv file and the .ekb file.
Summary
You can now use the GDK extension to publish your games to the Microsoft Store and make use of various Xbox Live social features to increase player engagement!
Download it on GitHub, and after importing it into your project, make sure to read the documentation file provided with the Included Files. Also read about the Microsoft Partner Center on the Helpdesk.
Happy GameMaking!
