Releases: microsoft/GDK
March 2023 GDK Public Release
March 2023 Microsoft Game Development Kit (GDK) release notes
Introduction
Welcome to the March 2023 Microsoft Game Development Kit release. You can use the GDK to develop games that can be certified and approved for release on Windows 11 PCs and Windows 10 PCs.
About this document
We have organized this document into the following sections.
- What's new
- Release notes:
- Documentation
What's new in the March 2023 Microsoft Game Development Kit
- The GDK is released in two types: Major (focused on features, three times a year) and Updates (focused on fixes, as often as needed).
- To view the full What's New section, see the online version of What's New.
March 2023 GDK update 5
Issue fixes
Xbox services
Fixed an issue where
XblCleanupAsyncwould never complete when called without any ongoing requests. [45364143]
GDK tools
Fixed an issue that caused the Microsoft Game Config editor to scale incorrectly when the PC was set to a non-English language. [45264919]
March 2023 GDK update 1
Notifications
Lighting
As of the March 2023 recovery, the GDK Lighting API only supports the following devices on console. Support for additional devices will be added in future recovery releases.
- Razer Turret for Xbox One (keyboard and mouse)
- Razer BlackWidow Tournament Edition Chroma V2
Issue fixes
Packaging
Fixed an issue where
makepkg packwould not create a package if the source files were read-only.
Xbox service
PlayFab Party titles that use peer-to-peer (P2P) for connectivity will now fall back to relayed connectivity if P2P connectivity is disrupted and unrecoverable.
March 2023 GDK
Breaking changes
If you're updating from a GDK version earlier than October 2022 GDK Update 2, check the release notes for previous releases for additional breaking changes that might affect you.
Notifications
Visual Studio
Side-by-side GDK uninstall issues
A bug in Visual Studio Installer version 17.4 can cause GDK components in Visual Studio 2019 and Visual Studio 2022 to work incorrectly after installing multiple GDK versions side-by-side on the same PC. The installer can also cause GDK uninstall failures.
This bug is fixed in Visual Studio Installer versions 17.4.6, 17.5.3 and 17.6.
Release notes
GDK Tools
Fixed a known issue where using the Visual Studio 2022 Debug Quick Resume option could result in a
failure to launch the titleerror message.
Input
Improved support for Japanese keyboard layouts in
GameInput.
Xbox services
Live Trace Analyzer (LTA)
Added checks to the LTA tool to detect if an Azure PlayFab title is using a known sample
titleid. The tool now returns a red failure that indicates that a sampletitleidis being used and must be configured to use a non-sampletitleidprior to being shipped to retail.
PlayFab
Added the PlayFab SDK Unreal Marketplace Plugin and GitHub Source to the ongoing official GDK compatibility matrix. Both releases were tested and are compatible with the March 2023 GDK and later.
Documentation
You can view the documentation online at Game Development Kit (GDK) documentation.
October 2022 GDK Update 2 Public Release
February 14, 2022
Placeholder while we test a new process and format for release notes
October 2022 GDK Update 1 Public Release
December 13, 2022
Placeholder while we test a new process and format for release notes
October 2022 GDK Public Release
November 3, 2022
Placeholder while we test a new process and format for release notes
June 2022 Update 4 Public Release
June 2022 Microsoft Game Development Kit (GDK) Update 4 release notes
Note: June 2022 Update 3 release has been temporarily removed to correct an error in a script that packaged the files. Will post as a standalone .zip as the 2206_June branch has already been updated to Update 4.
Introduction
- The public GDK release notes are a subset of information available to developers inside the Xbox developer program (e.g. ID@Xbox). The goal is to increase the amount of public information with every release, but some content remains specific and exclusive to developers with an active Microsoft Game Developer Kit w/ Xbox Extensions (GDKX) license agreement.
- GDK development samples are publicly available: https://github.com/microsoft/Xbox-GDK-Samples/!
- GDK public documentation available here: https://aka.ms/gamedevdocs
- For more information about the GDK and how to start developing games for Xbox consoles or Xbox Game Pass for PC on Windows 10/11, view the ReadMe.MD.
About this document
We have organized this document into the following sections.
- Release notes errata [topics added closer to or after the general availability (GA) date]
- What’s new
- Breaking changes
- Issues fixed in this release
- Known issues in this release
- Development environment setup
Release notes errata
Topics highlighted in this section were added closer to the general availability (GA) date.
What's new in the June 2022 Microsoft Game Development Kit
There is no "What's new" content for UPDATE releases.
- The GDK/GDKX are released in two types: Major (focused on features, three times a year) and Updates (focused on fixes, as often as needed by partners).
- To see the full What's New section, read the release notes for the corresponding mMajor rRelease.
Breaking changes
Note: For other breaking changes in this branch, please see the previous release notes.
Issues fixed in this release
Fixes: Networking
PlayFabMultiplayer - websocket memory leak in PFMultiplayerUninitialize
(Added October 3, 2022)
Fixed a bug in the PlayFabMultiplayer C++ Client SDK that caused websocket resources to leak memory when PFMultiplayerUninitialize() was called or when the library internally handled app
suspension on Xbox consoles.
Fixes: XSAPI
Connectivity issues on Fortnite (xboxone only) since GDK QFE2 Update
(Added October 3, 2022)
Fixed an issue where XblMultiplayerWriteSessionAsync's async callback doesn't return if it is waiting for an RTA connection ID and RTA can't reconnect after the network connection is lost.
Known issues in this release
Known issues: Development environment
Application platform | Multiprocess games are not currently supported on console
(Added June 9, 2022)
Multiprocess games in the GDKX on console are not currently supported. Do not use this feature in your games. We plan to revisit this area based on feedback and prioritization from our development partners. While it is possible to use CreateProcess to create multiple processes, the following are currently known issues.
- Graphics are only supported for a single process and device at any time.
- Audio is only supported for a single process at any time.
- Gaming Runtime Services (GRTS) and the various user APIs do not work across multiprocess games.
- Gamepad input does not work across multiprocess games.
Developer tools | .NET Core updates can block GDK/GDKX installation
(Added June 8, 2022)
.NET Core updates that are delivered through Microsoft Update can block GDK/GDKX installation. To resolve this issue, update your Visual Studio instance or uninstall the workloads that contain Microsoft.NET.Core.Component.SDK.2.1 through the Visual Studio Installer and then retry (un)installing the GDK/GDKX.
Known issues: Developer tools
Developer tools | PC projects that use Xbox services, XGameSave, XStore, and/or XUser must use <game configversion=”1”>
(Added June 10, 2022)
Developers can use the June 2022 GDK/GDKX to rapidly iterate on their PC games without registering them. As a result, we strongly recommend that you update to <game configversion=”1”> in MicrosoftGame.config. This requires setting MSAAppId and Title ID for titles that are using this version or later of the GDK/GDKX, that also use one or more of the following features.
- Xbox services
- XGameSave
- XStore
- XUser
For more information, see MicrosoftGame.config reference.
Without this MicrosoftGame.config setting, launching these titles by Visual Studio Run/F5 or double-clicking the .exe file causes the following missing package error.
E_GAMEUSER_NO_PACKAGE_IDENTITY
APIs in the previous areas can also fail with various error codes because of the missing package identity.
An alternate workaround (for remaining at <game configversion=”0”>) is to register and launch the build by using the wdapp command line-tool. This is shown in the following example.
c:\temp> wdapp register Gaming.Desktop.x64\Debug
The Ggame is registered as an Application,. iIf game-specific OS features are needed, run this as an Administrator to register it as a Game.
Registered 41336MicrosoftATG.InGameStoreXS_2021.6.10.0_x64__dspnxghe87tn0
1336MicrosoftATG.InGameStoreXS_dspnxghe87tn0!Game
Copied temporarily generated AppXManifest.xml file to C:\Users\user\AppData\Local\Temp\41336MicrosoftATG.InGameStoreXS_2021.6.10.0_x64__dspnxghe87tn0_AppXManifest.xml
The operation was completed successfully.
c:\temp> wdapp launch 41336MicrosoftATG.InGameStoreXS_dspnxghe87tn0!Game
The Application was launched successfully.
After the title has been launched, you can debug it by using the Attach to process feature of Visual Studio. If the title requires debugging as it is launching, you can add a DebugBreak() call to prompt to attach a debugger at the debug location. Depending on the configuration of your development PC, this might require you to add the following registry key.
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug – Aadd a DWORD named Auto with a value of 1.
- The wdapp register step makes the title appear in the Start menu, which has been changed to not be done as part of Visual Studio deploy/F5—the same behavior as generic Win32 projects.
This does not apply to console workflows and is also unnecessary for packaged builds to function correctly. This includes builds that were installed from the Xbox App or Microsoft Store.
(Known Issue – added June 15, 2022)
Developer tools | PC Game Pass titles might generate a pop-up error message (E_FAIL) when the user attempts to sign in to Xbox services
(Added June 9, 2022)
One of the newest features to improve the game launch experience for both developers and players is the PC Bootstrapper.
Bootstrapper has a dependency on GRTS. It is distributed automatically to all Windows 10 PCs and Windows 11 PCs.
If GRTS is out of date on your development PC, it can generate an error (E_FAIL) when the user attempts to sign in to the Xbox services.
To ensure that you have the latest version of SRTS on your development PC
- Verify your Windows 10 or Windows 11 developer environment is set to RETAIL mode and not in a developer sandbox.
- Close all other games and apps.
- Select the following link to go to the Microsoft Store page for GRTS (and then select More details to expand the Store page, if needed): https://www.microsoft.com/store/productId/9MWPM2CQNLHN.
- Ensure that the version of GRTS is current and does not prompt you for an update.
- To update all apps and components, go to the Library view in the Microsoft Store app.
Visual Studio life cycle updates
(Added June 9, 2022)
- Visual Studio 2017 (15.9) is now out of mainstream support. The June 2022 GDK/GDKX is the last release expected to support the Visual Studio 2017 IDE. Note that Platform Toolset v141 (the Visual Studio 2017 compiler) is supported through Visual Studio 2019 and Visual Studio 2022 with the appropriate components installed.
- Visual Studio 2019 (16.8) and earlier are out of mainstream support. Visual Studio 2019 (16.9) is in mainstream support through October 2022 and is supported by the June 2022 GDK/GDKX. Visual Studio 2019 (16.11) is in mainstream support until April 2029.
- Visual Studio 2022 (17.0) and Visual Studio 2022 (17.2) are supported through a Long-Term Servicing Channel.
Issue with XGameSaveFiles and player sign-out
(Added June 9, 2022)
If a game uses XGameSaveFiles and has any signed-in player sign out of that game, it will be closed. This issue will be fixed in a future update.
**Updated requirements for MSAAppId and...
June 2022 GDK Update 2 Public Release
June 2022 Microsoft Game Development Kit (GDK) Update 2 release notes
Introduction
- The public GDK release notes are a subset of information available to developers inside the Xbox developer program (e.g. ID@Xbox). The goal is to increase the amount of public information with every release, but some content remains specific and exclusive to developers with an active Microsoft Game Developer Kit w/ Xbox Extensions (GDKX) license agreement.
- GDK development samples are publicly available: https://github.com/microsoft/Xbox-GDK-Samples/!
- GDK public documentation available here: https://aka.ms/gamedevdocs
- For more information about the GDK and how to start developing games for Xbox consoles or Xbox Game Pass for PC on Windows 10/11, view the ReadMe.MD.
About this document
We have organized this document into the following sections.
- Release notes errata [topics added closer to or after the general availability (GA) date]
- What’s new
- Breaking changes
- Issues fixed in this release
- Known issues in this release
- Development environment setup
Release notes errata
Topics highlighted in this section were added closer to the general availability (GA) date.
- No errata submitted for this GDK update.
What's new in the June 2022 Microsoft Game Development Kit
There is no "What's new" content for UPDATE releases.
- The GDK/GDKX are released in two types: Major (focused on features, three times a year) and Updates (focused on fixes, as often as needed by partners).
Breaking changes
Direct3D 12 | DirectX header convergence across PC and Xbox
(Added June 7, 2022)
This section modifies the guidance that was provided in the What's New section of the same name (DirectX header convergence across PC and Xbox).
- Public D3D12 headers now look more alike between PC and Xbox. Any previously unsupported APIs between PC and Xbox are now explicitly noted as such in the debug layer.
- NOTE: Although some functionality is now included in the header (for example, D3D12_BARRIER_ACCESS), the driver does not yet support all the new additions.
- NOTE: If PC headers were previously being included in Xbox One and Xbox Series X|S toolchains to gain access to additional debug layer options that were not previously available in the console-specific headers, you might need to remove those includes (for example, d3dcommon.h from the Windows 10 SDK). Those defines now exist within the Xbox headers. If you do not do this, there might be duplicate guid\interface defines.
Uninstall the October 2021 Visual Studio 2022 .vsix files before installing the June 2022 GDK/GDKX
(Added June 9, 2022)
This note was included in the March 2022 GDK/GDKX, but it is important enough to highlight again for June 2022 and related updates.
If you manually installed the Visual Studio 2022 .vsix files that shipped alongside the October 2021 GDK/GDKX, uninstall those files before you install the June 2022 GDK/GDKX. If you do not do this, you will get debugging and deployment failures when you use Visual Studio 2022.
- Use the following command-line example to uninstall the October 2021 GDK/GDKX .vsix files. **NOTE: **This command might vary, depending on which edition of Visual Studio 2022 is installed and which .vsix files were initially installed.
- If the June 2022 GDK/GDKX was installed prior to uninstalling the October 2021 GDK/GDKX .vsix files, repair the June 2022 GDK/GDKX after uninstalling the October 2021 .vsix files to get back into a working state.
[Command-line example]:
vsixinstaller /skuName:Enterprise /skuVersion:17.1 /appIdName:VS /appIdInstallPath:"C:\Program Files\Microsoft Visual Studio\2022\Enterprise" /uninstall:Microsoft.Gaming.GDKX.PC.v143.211004 /uninstall:Microsoft.Gaming.GDKX.PC.v143.Templates /uninstall:Microsoft.Gaming.GDKX.PC /uninstall:Microsoft.Gaming.GDKX.Xbox.v143.211004 /uninstall:Microsoft.Gaming.GDKX.Xbox.v143.Templates /uninstall:Microsoft.Gaming.GDKX.Xbox
Issues fixed in this release
Fixes: Multiplayer and networking
Networking | XCurl automatically injects cookies when making HTTP requests
(Added July 15, 2022)
Fixed an issue in XCurl where cookies provided in server responses via Set-Cookie headers were automatically included on all future requests. Cookie headers are now not automatically set to align with LibCurl behavior.
PlayFab multiplayer | PFLobby header incorrectly documented the amMember special reserved key value
(Added July 15, 2022)
Fixed incorrect constant string values for PFLobbyMemberCountSearchKey and PFLobbyAmMemberSearchKey. This is one of three fixes that are included in the PFMultiplayer VPack update to version 1.1.5.
PlayFab multiplayer | LibHttpClient could cause PFMultiplayer to stall during PFMultiplayerUninitialize if the web socket is disconnected
(Added July 15, 2022)
Fixed an issue that could cause PFMultiplayerUninitialize to block indefinitely if a web socket was closed unexpectedly. This is one of three fixes that are included in the PFMultiplayer VPack update to version 1.1.5.
PlayFab Multiplayer | PubSub fails to reconnect if the underlying web socket failed, which could stall future operations that are relying on PubSub
(Added July 15, 2022)
Fixed an issue that caused PubSub notifications to become unusable and API operations to stall indefinitely after a web socket was disconnected unexpectedly. This is one of three fixes included in the PFMultiplayer VPack update to version 1.1.5.
Known issues in this release
Known issues: Development environment
Developer tools | .NET Core updates can block GDK/GDKX installation
(Added June 8, 2022)
.NET Core updates that are delivered through Microsoft Update can block GDK/GDKX installation. To resolve this issue, update your Visual Studio instance or uninstall the workloads that contain Microsoft.NET.Core.Component.SDK.2.1 through the Visual Studio Installer and then retry (un)installing the GDK/GDKX.
Known issues: Developer tools
Developer tools | PC projects that use Xbox services, XGameSave, XStore, and/or XUser must use <game configversion=”1”>
(Added June 10, 2022)
Developers can use the June 2022 GDK/GDKX to rapidly iterate on their PC games without registering them. As a result, we strongly recommend that you update to <game configversion=”1”> in MicrosoftGame.config. This requires setting MSAAppId and Title ID for titles that are using this version or later of the GDK/GDKX, that also use one or more of the following features.
- Xbox services
- XGameSave
- XStore
- XUser
For more information, see MicrosoftGame.config reference.
Without this MicrosoftGame.config setting, launching these titles by Visual Studio Run/F5 or double-clicking the .exe file causes the following missing package error.
E_GAMEUSER_NO_PACKAGE_IDENTITY
APIs in the previous areas can also fail with various error codes because of the missing package identity.
An alternate workaround (for remaining at <game configversion=”0”>) is to register and launch the build by using the wdapp command line-tool. This is shown in the following example.
c:\temp> wdapp register Gaming.Desktop.x64\Debug
Game registered as an Application, if game-specific OS features are needed, run as an Administrator to register as a Game.
Registered 41336MicrosoftATG.InGameStoreXS_2021.6.10.0_x64__dspnxghe87tn0
1336MicrosoftATG.InGameStoreXS_dspnxghe87tn0!Game
Copied temporarily generated AppXManifest.xml file to C:\Users\user\AppData\Local\Temp\41336MicrosoftATG.InGameStoreXS_2021.6.10.0_x64__dspnxghe87tn0_AppXManifest.xml
The operation was completed successfully.
c:\temp> wdapp launch 41336MicrosoftATG.InGameStoreXS_dspnxghe87tn0!Game
The Application was launched successfully.
After the title has been launched, you can debug it by using the Attach to process feature of Visual Studio. If the title requires debugging as it is launching, you can add a DebugBreak() call to prompt to attach a debugger at the debug location. Depending on the configuration of your development PC, this might require you to add the following registry key.
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug – add a DWORD named Auto with value of 1.
- The wdapp register step makes the title appear in the Start menu, which has been changed to not be done as part of Visual Studio deploy/F5—the same behavior as generic Win32 projects.
This does not apply to console workflows and is also unnecessary for packaged builds to function correctly. This includes builds that were installed from the Xbox App or Microsoft Store.
(Known Issue – added June 15, 2022)
Developer tools | PC Game Pass titles may generate pop-up error message (E_FAIL) when the user attempts to sign in to Xbox services
(Added June 9, 2022)
One of the newest features to improve the game launch experience for both developers and players is the PC Bootstrapper.
- Bootstrapper has a dependency on GRTS. It is distributed automa...
June 2022 GDK Update 1 Public Release
June 2022 Microsoft Game Development Kit (GDK) Update 1 public release notes
Introduction
- The public GDK release notes are a subset of information available to developers inside the Xbox developer program (e.g. ID@Xbox). The goal is to increase the amount of public information with every release, but some content remains specific and exclusive to developers with an active Microsoft Game Developer Kit w/ Xbox Extensions (GDKX) license agreement.
- GDK development samples are publicly available: https://github.com/microsoft/Xbox-GDK-Samples/!
- GDK public documentation available here: https://aka.ms/gamedevdocs
- For more information about the GDK and how to start developing games for Xbox consoles or Xbox Game Pass for PC on Windows 10/11, view the ReadMe.MD.
About this document
We have organized this document into the following sections.
- Release notes errata [if there are late changes and additions submitted the same week as GA]
- What’s new
- Breaking changes
- Issues fixed in this release
- Known issues in this release
- Development environment setup
Release notes errata
Topics highlighted in this section are added just before or just after the general availability (GA) release date.
No release notes errata submitted as of June 7, 2022.
What's new in the June 2022 Microsoft Game Development Kit
- There is no What's new content for Update releases.
- The GDK/GDKX are released in two types: Major (focused on features, three times a year) and Updates (focused on fixes, as often as they are needed by partners).
Breaking changes
Direct3D 12 | DirectX header convergence across PC and Xbox
(Added June 7, 2022)
This section modifies the guidance that was provided in the What's new section of the same name (DirectX header convergence across PC and Xbox).
- Public Direct3D 12 headers now look more alike between PC and Xbox. Any previously unsupported APIs between PC and Xbox are now explicitly noted as such in the debug layer.
- Note: Although some functionality is now included in the header (for example, D3D12_BARRIER_ACCESS), the driver does not yet support all the new additions.
- Note: If PC headers were previously being included in Xbox One and Xbox Series X|S toolchains to gain access to additional debug layer options that were not previously available in the console-specific headers, you might need to remove those includes (for example, d3dcommon.h from the Windows 10 SDK). Those defines now exist within the updated Xbox headers. If you do not do this, there might be duplicate guid\interface defines.
Uninstall the October 2021 Visual Studio 2022 .vsix files before installing the June 2022 GDK or GDKX
(Added June 9, 2022)
This note was included in the March 2022 GDK, but it is important enough to highlight again for June 2022
If you manually installed the Visual Studio 2022 .vsix files that shipped alongside the October 2021 GDKX, uninstall those files before you install the June 2022 GDKX. If you do not do this, you will get debugging and deployment failures when you use Visual Studio 2022.
- Use the following command-line example to uninstall the October 2021 GDKX .vsix files. **NOTE: **This command might vary, depending on which edition of Visual Studio 2022 is installed and which .vsix files were initially installed.
- If the June 2022 GDKX was installed prior to uninstalling the October 2021 GDKX .vsix files, repair the June 2022 GDKX after uninstalling the October 2021 .vsix files to get back into a working state.
Command-line example :
vsixinstaller /skuName:Enterprise /skuVersion:17.1 /appIdName:VS /appIdInstallPath:"C:\Program Files\Microsoft Visual Studio\2022\Enterprise" /uninstall:Microsoft.Gaming.GDKX.PC.v143.211004 /uninstall:Microsoft.Gaming.GDKX.PC.v143.Templates /uninstall:Microsoft.Gaming.GDKX.PC /uninstall:Microsoft.Gaming.GDKX.Xbox.v143.211004 /uninstall:Microsoft.Gaming.GDKX.Xbox.v143.Templates /uninstall:Microsoft.Gaming.GDKX.Xbox
Issues fixed in this release
Fixes: Developer tools
Developer tools | Fixed wdapp.exe launch failure
(Added July 7, 2022)
Fixed a bug when launching an .exe by using wdapp.exe launch and passing launch parameters .
Fixes: Input
GameInput | No callbacks fired by RegisterDeviceCallback method when passing in the GameInputAsyncEnumeration type.
(Added July 7, 2022)
IGameInputDispatcher::Dispatch now performs a minimal amount of work, even if a value of 0 is passed for the quotaInMicroseconds parameter.
Input | GameInput.lib for x86 returns error (E_NOTMIPL)
(Added July 7, 2022)
The x86 version of gameinput.lib was erroneously included in the June 2022 GDK . However, this file wasn’t intended for use and has been removed from the June 2022 GDK Update 1.
Fixes: Multiplayer and networking
Networking | Fixed a bug that caused XCurl to stop responding when suspending the title
(Added July 7, 2022)
Fixed a bug in XCurl that would cause it to stop responding if a request was starting at about the same time that the title started suspending.
Fixes: Performance tools - CPU and others
PIX (CPU) | Invalid data in component-placed API object resources
(Added July 7, 2022)
The data that was displayed in the Timing Capture Element Details view was incorrect for Direct3D resource objects. Data that did not apply to the selected resource was displayed. This has been fixed.
Fixes: System
Memory Manager | Minor inconsistencies in XMemVirtualQuery and XMemGetWorkingSetStatistics
(Added July 7, 2022)
Fixed minor inconsistencies in XMemVirtualQuery and XMemGetWorkingSetStatistics that might occur when the June 2022 Game OS is used with the August 2022 recovery on Xbox Series S consoles.
- This change aalso addresses an issue where XMEM_TOOL allocations that are used with XMEM_GPUOPT_BW_REQ may fail when the June 2022 Game OS is used with the August 2022 recovery on Xbox Series S consoles.
- This is an extremely rare combination because XMEM_GPUOPT_BW_REQ has no effect on Xbox Series S devices.
- Titles can also work around this by simply removing XMEM_GPUOPT_BW_REQ in this scenario.
Known issues in this release
Known issues: Developer tools
Developer tools | .NET Core updates can block GDK or GDKX installation
(Added June 8, 2022)
.NET Core updates that are delivered through Microsoft Update can block GDKX installation. To resolve this issue, update your Visual Studio instance or uninstall the workloads that contain Microsoft.NET.Core.Component.SDK.2.1 through the Visual Studio Installer and then retry (un)installing the GDKX.
Developer tools | PC projects that use Xbox services, XGameSave, XStore, and/or XUser must use <game configversion=”1”>
(Added June 10, 2022)
Developers can use the June 2022 GDK to rapidly iterate on their PC games without registering them. As a result, we strongly recommend that you update to <game configversion="1"> in Microsoftgame.config. This requires setting MSAAppId and Title ID for titles that are using this GDKX or later that use one or more of the following features.
- Xbox services
- XGameSave
- XStore
- XUser
For more information, see MicrosoftGame.config reference.
Without this MicrosoftGame.config setting, launching PC titles by using Visual Studio Run/F5 or double-clicking the .exe file causes the following missing package identity error.
E_GAMEUSER_NO_PACKAGE_IDENTITYAPIs in the previous areas can also fail with various error codes because of the missing package identity.
An alternate workaround (for remaining at <game configversion=”0”>) is to register and launch the build by using the wdapp command-line tool. This is shown in the following example.
c:\temp> wdapp register Gaming.Desktop.x64\Debug Game registered as an Application, if game-specific OS features are needed, run as an Administrator to register as a Game. Registered 41336MicrosoftATG.InGameStoreXS_2021.6.10.0_x64__dspnxghe87tn0 1336MicrosoftATG.InGameStoreXS_dspnxghe87tn0!Game Copied temporarily generated AppXManifest.xml file to C:\Users\user\AppData\Local\Temp\41336MicrosoftATG.InGameStoreXS_2021.6.10.0_x64__dspnxghe87tn0_AppXManifest.xml The operation was completed successfully. c:\temp> wdapp launch 41336MicrosoftATG.InGameStoreXS_dspnxghe87tn0!Game The Application was launched successfully.After the title has been launched, you can debug it by using the Attach to process feature of Visual Studio. If the title requires debugging as it is launching, you can add a DebugBreak() call to prompt you for attaching a debugger at the debug location. Depending on the configuration of your development PC, this might require you to add the following registry key.
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug – add a DWORD named Auto with value of 1.
- The wdapp register step makes the title appear in the Start menu, which has been changed to not be done as part of Visual Studio deploy/F5—the same behavior as generic Win32 projects.
This does not apply to conso...
March 2022 GDK Update 1 Public Release
March 2022 Microsoft Game Development Kit (GDK) Update 1 Public Release Notes
Introduction
- The public GDK release notes are a subset of information available to developers inside the Xbox developer program (e.g. ID@Xbox). The goal is to increase the amount of public information with every release, but some content remains specific and exclusive to developers with an active Microsoft Game Developer Kit w/ Xbox Extensions (GDKX) license agreement.
- GDK development samples are publicly available: https://github.com/microsoft/Xbox-GDK-Samples/!
- GDK public documentation available here: https://aka.ms/gamedevdocs
- For more information about the GDK and how to start developing games for Xbox consoles or Xbox Game Pass for PC on Windows 10/11, view the ReadMe.MD.
About this document
We have organized this document into the following sections.
- Release Notes Errata [late changes/additions submitted 1-7 days before GA]
- Breaking changes
- Issues fixed in this release
- Known issues in this release
- Development environment setup
Release Notes Errata
Topics highlighted in this section were added in close proximity to or after the general availability (GA) release date
- No errata identified yet.
Breaking changes
- No breaking changes identified yet.
Issues fixed in this release
Audio
Audio | Crash in MMDEVAPI.DLL
Fixed an access violation in mmdevapi.dll resulting in game crash because of accessing freed memory.
Developer tools
GDK Installer/Setup | VSIX packages orphaned by installer options in Visual Studio
Fixed an issue that caused GDK VSIX packages to be orphaned in Visual Studio on the PC when using Programs and Features | Change and choosing the Uninstall or Repair radio button.
Visual Studio | MGCCompile fails with updated IntelligentDelivery sample for Desktop when using Clang
Fixed a problem with the March 2022 GDK if you use a MGCCompile source filename other than “MicrosoftGame.config”, the Gaming.Desktop.x64 platform, and the ClangCl PlatformToolset together, which generated a build error:
1>C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Microsoft\VC\v170\Platforms\Gaming.Desktop.x64\220300\PlatformToolsets\ClangCL\Toolset.Edition.targets(83,7): error MSB3073: The command ""C:\Program Files (x86)\Microsoft GDK\bin\makepkg.exe" localize /d "C:\Direct3DGame1" /pd "C:\Direct3DGame1\Gaming.Desktop.x64\Debug" /gc """ exited with code 3.
Storage | WDApp and PC Bootstrapper compatibility
With the release of PC Bootstrapper, developers on PC need updated tools to get the correct behavior. By default, using wdapp install should not trigger the use of PC Bootstrapper. Developers wanting to trigger the PC bootstrapper with their dev packages should use wdapp install /bootstrapper.
Graphics: core platform
Direct3D12 | CopyTextureRegion copies both depth and stencil even if Subresource is 0 or 1
Fixed bug in CopyTextureRegion with depth stencil resources where only one of the two planes is specified via the subresource index.
Direct3D12 | Rendering artifacts following CopyTextureRegion from texture-compatible to non-texture-compatible depth
Fixed image corruption bug in CopyTextureRegion when copying between texture-compatible and non-texture-compatible depth stencil resources."
Graphics: shader compiler
HLSL | New file opened at every step during live compute shader debugging
HLSL code and HLSL variables are always available in the live debug session if shader PDBs are resolved.
ThreadID_X, ThreadID_Y and ThreadID_Z are always displayed when debugging a compute shader on-demand.
Fixed a bug that would sometimes open a new file on every single step.
Multiplayer and networking
Networking (HTTP) | Fix for hang in XCurl
Fixes an issue in XCurl where if you try to abort an xcurl write operation (CURLOPT_WRITEFUNCTION or CURLOPT_HEADERFUNCTION), curl_easy_perform will hang indefinitely and requests managed by multi handles will never complete via calls to curl_multi_perform.
XSAPI | Real Time Activity (RTA) shared URI subscription issue
Fixed a bug where multiple Real Time Activity subscriptions that are using the same URI would all be removed if one of them unsubscribes.
XSAPI | Groups/GroupsCount value is empty when retrieved by using XblMultiplayerSessionMembers
Fixed a bug where XblMultiplayerSessionMember's Groups and GroupCount fields were not correctly deserialized.
XSAPI | LHC Websocket handle not closed on Status_Request_Error
Fixed an issue where a websocket handle would not be closed under certain circumstances, causing a timeout on suspension.
XSAPI | Crashes in curl_multi_cleanup
Fixed a crash in XSAPI and libHttpClient when cleaning up web requests handled via libHttpClient's CURL implementation
XSAPI | Duplicate sequence numbers in multiplayer activity (MPA) APIs
Fixed an issue that caused multiple Multiplayer Activity requests sent within the same second to be ignored.
XSAPI | XblTraceAnalyzer.exe fails when reading .saz files
Fixed a failure in XblTraceAnalyzer.exe when parsing .saz files if the files weren't written in timestamp order.
XSAPI | Xbox app downloads fail after switching to new sandbox (xblpcsandbox.exe) until Reboot
Fixed an issue that prevented xbox app downloads after switching sandboxes.
XSAPI | XblPresenceAddTitlePresenceChangedHandler returning unknown
Fixed a issue causing XblPresenceAddTitlePresenceChangedHandler events to show XblPresenceTitleState::Unknown instead of the correct title state.
Known issues in this release
Development tools
Packaging and Installs | Deprecation of Mod and Package Virtualization elements in MicrosoftGame.config
As of the March 2022 GDK, MicrosoftGame.config has been updated to schema version 1 (Game configVersion="1") for new titles.
- As part of these new schema requirements, the ModFolder, EnableWritesToPackageRoot, DisableFilesystemWriteVirtualization, and DisableRegistryWriteVirtualization elements are now deprecated.
- Their functionality is now enabled by default because of updates to how packages are installed on PC (Flat File Install).
Packaging and Installs | Updates to the MicrosoftGame.config Editor to handle new schema and element requirements
The MicrosoftGame.config Editor now properly manages rules around schema version 1 updates (Game configVersion="1"), including enforcing MSAAppId and TitleId to be present if either is specified or if AdvancedUserModel is set to false and automatically removing deprecated elements (the ModFolder, EnableWritesToPackageRoot, DisableFilesystemWriteVirtualization, and DisableRegistryWriteVirtualization elements)
Visual Studio | Visual Studio life cycle updates
- Visual Studio 2017 (15.9) is now out of mainstream support. The June 2022 GDK/GDKX is the last release expected to support the Visual Studio 2017 IDE. Note that PlatformToolset v141 (the Visual Studio 2017 compiler) is supported through Visual Studio 2019 and Visual Studio 2022 with the appropriate components installed.
- Visual Studio 2019 (16.8) and earlier are out of mainstream support. Visual Studio 2019 (16.9) is in mainstream support through October 2022 and is supported by the June 2022 GDKX. Visual Studio 2019 (16.11) is in mainstream support until April 2029.
- Visual Studio 2022 (17.0) and Visual Studio 2022 (17.2) are supported through a Long-Term Servicing Channel.
Visual Studio | Shader Model property in Visual Studio must be set according to the platform
New shaders that are added to gaming projects through the Visual Studio Add New Project command are explicitly set to version 4.0. It isn’t a valid version for either the Gaming.Desktop.x64 platform or the Gaming.Xbox.XboxOne.x64 platform.
To specify the correct version, select Properties for the shader file. Enter the version number that corresponds to the Windows platform or the Xbox platform under HLSL Compiler > Shader Model.
- Gaming.Desktop.x64: 5.1
- Gaming.Xbox.XboxOne.x64: 6.0
- Note: You can also enter these version numbers at the project level, and then select the value "" for individual shader files.
Subval | Submission Validator /ValidationLanguage
Version 10.0.22000.4310 of SubVal.dll does not output Japanese strings when the /ValidationLanguage flag is set by using the 2206 version of MakePkg. This will be fixed with an updated version of SubVal.dll that will be available in June 2022.
Packaging and Installs | Updated requirements for MSAAppId and TitleId
As of the March 2022 ...
June 2022 GDK Public Release
June 2022 Microsoft Game Development Kit (GDK) public release notes
Introduction
- The public GDK release notes are a subset of information available to developers inside the Xbox developer program (e.g. ID@Xbox). The goal is to increase the amount of public information with every release, but some content remains specific and exclusive to developers with an active Microsoft Game Developer Kit w/ Xbox Extensions (GDKX) license agreement.
- GDK development samples are publicly available: https://github.com/microsoft/Xbox-GDK-Samples/!
- GDK public documentation available here: https://aka.ms/gamedevdocs
- For more information about the GDK and how to start developing games for Xbox consoles or Xbox Game Pass for PC on Windows 10/11, view the ReadMe.MD.
About this document
We have organized this document into the following sections.
- Release Notes Errata [late changes/additions submitted 1-7 days before GA]
- What’s new
- Breaking changes
- Issues fixed in this release
- Known issues in this release
- Development environment setup
Release Notes Errata
Topics highlighted in this section were added in close proximity to or after the general availability (GA) release date
(Breaking Change - Added 2022.06.07)
Direct3D 12 | DirectX header convergence across PC and Xbox
This article modifies the guidance provided in the What's New article of the same name "DirectX header convergence across PC and Xbox".
- Public D3D12 headers will look more similar between PC and Xbox. Any previously unsupported APIs between Xbox and PC are now explicitly noted as such in the debug layer.
- Note: Although some functionality is now included in the header (e.g. D3D12_BARRIER_ACCESS), the driver does not yet support all of the new additions.
- Note: If PC headers were previously being included in Xbox One and Xbox Series X|S toolchains to gain access to additional debug layer options that were not previously available in the console-specific headers, you may need to remove those includes (d3dcommon.h from the Windows Kit for instance), since those defines now exist within the headers update headers. Failure to do so may result in duplicate guid\interface defines.
(Known Issue – Added 2022.06.08)
Input | Minimum value required for manual title control of GameInput work queue (CreateDispatcher)
IGameInputDispatcher::Dispatch will not complete any work, when passing a value of 0 for the quotaInMicroseconds parameter per the API documentation. To work around this, pass a value of at least 100 us. This regression will be fixed in an upcoming QFE release.
([Known Issue] – Added [2022.06.10])
Developer Tools | PC projects that utilize Xbox Live, XStore and/or XUser must use <game configversion=”1”>
The June 2022 GDK allows developers to rapidly iterate on their games on PC without requiring registration of their game, therefore for titles using this GDK or newer that use one or more of the following features:
- Xbox Live
- XGameSave
- XStore
- XUser
It is strongly recommended to update to <game configversion="1"> in the Microsoftgame.config, which will require setting a Title ID and MSAAppId. Please see MicrosoftGame.config reference for more information.
Without this MicrosoftGame.config setting, launching these titles by Visual Studio Run/F5 or double-clicking on the exe will result the following error:
E_GAMEUSER_NO_PACKAGE_IDENTITY
APIs in the areas listed above can also fail with various error codes due to the missing package identity.
An alternate workaround (for remaining at <game configversion=”0”>) is to register and launch the build using the
wdappcommand line tool, as in the following example:
c:\temp> wdapp register Gaming.Desktop.x64\Debug
Game registered as an Application, if game specific OS features are needed, run as an Administrator to register as a Game.
Registered 41336MicrosoftATG.InGameStoreXS_2021.6.10.0_x64__dspnxghe87tn0
1336MicrosoftATG.InGameStoreXS_dspnxghe87tn0!Game
Copied temporary generated AppXManifest.xml file to C:\Users\user\AppData\Local\Temp\41336MicrosoftATG.InGameStoreXS_2021.6.10.0_x64__dspnxghe87tn0_AppXManifest.xml
The operation completed successfully.
c:\temp> wdapp launch 41336MicrosoftATG.InGameStoreXS_dspnxghe87tn0!Game
Application launched successfully.
Once launched, the title can be debugged by using the “Attach to process” feature of Visual Studio. If the title requires debugging as it is launching, a DebugBreak() call can be added to prompt for a debugger to be attached at that location. Please note that depending on the configuration of the PC, this may require adding the following registry key:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug – add a DWORD named Auto with value of 1.
- Note the
wdapp registerstep is the operation that will make the title show up in the Start menu, which has been changed to not be done as part of Visual Studio deploy/F5—the same behaviour as generic win32 projects.This does not apply to console workflows, and is also not necessary for correct functioning of packaged builds, including builds installed from the Xbox App/Microsoft Store.
([Known Issue] – Added [2022.06.15])
[Development Tools] | [PC Game Pass titles may generate pop-up error message (E_FAIL) when attempting to sign in]
One of the newest features to improve the game launch experience for both developers and players, is the PC Bootstrapper.
Bootstrapper has a dependency on the Gaming RunTime Service (GRTS) that is distributed automatically to all Windows 10/11 PCs.
If GRTS is out of date on the development PC, it can generate an error (E_FAIL) when attempting to sign in.
To make sure you have the latest version of Gaming Services on your PC:
- Verify your Windows 10/11 developer environment is set to RETAIL mode and not in a developer sandbox.
- Close all other games and apps.
- Use this link to go to the Microsoft Store page for Microsoft Gaming Services (and select “More details” to expand the Store page if needed): https://www.microsoft.com/store/productId/9MWPM2CQNLHN
- Ensure it is current and does not tell you it needs updating.
- Also, go to the Library view in the Microsoft Store app to update all apps and components.
What's new in the June 2022 Microsoft Game Development Kit
The Microsoft Game Development Kit (GDK) is a complete set of tools, APIs, extensions, and programming models that can be used across current and future Microsoft Gaming platforms and initiatives. Microsoft Game Development Kit (GDK) design and features are driven by your feedback about how you like to develop games. For a complete introduction, see Welcome to the Microsoft Game Development Kit.
In addition to many bug fixes, this release includes the following new features.
Table of Contents
Graphics
System
Networking
Developer tools
Documentation
Samples
Graphics
DirectX header convergence across PC and Xbox
Public D3D12 headers will look more similar between PC and Xbox. Any previously unsupported APIs between Xbox and PC are now explicitly noted as such in the debug layer.
[!] Note: Although some functionality is now included in the header (e.g. D3D12_BARRIER_ACCESS), the driver does not yet support all of the new additions.
System
GRTS handle tracking
The June 2022 Microsoft Game Development Kit (GDK) introduces a way for developers to troubleshoot bugs involving incorrect handle
usage. Most of the GRTS APIs utilize handles which correspond to the lifetime of internal objects in
the platform implementation. Games often encounter problems caused by accidentally providing
invalid (NULL, previously freed, etc.) handles into these APIs leading to title crashes. Developers
may also inadvertently leak handles leading to excessive resource usage. Using the new
XSystemHandleTrack function can be used to help diagnose and fix these
issues.
DLC now supports age-restrictions
Prior to the June 2022 Microsoft Game Development Kit (GDK), age-restrictions were only getting enforced against the base package. Starting with the June 2022 Microsoft Game Development Kit (GDK), these same restrictions are enforced when mounting new DLC. Using the new XPackageMountWithUiAsync function, the platform will automatically check the restrictions on the DLC and compare that to the family settings on the console and the ages of who is signed in. If necessary, this new API will pop a dialog to collect parental consent. The platform takes care of all age-restriction requirements and enforcement. Titles that want to see what content might b...
October 2021 GDK Update 5 Public Release
(2022.05.12 @ 0411PDT - The VS2022 support files for this release have been added as attached binaries).
GDK development samples are now publicly available: https://github.com/microsoft/Xbox-GDK-Samples/!
GDK public documentation available here: https://aka.ms/gamedevdocs
2022.05.12 Release Notes
- As of the above date, the The March 2022 release is technically the latest (major) release.
- Only use the October 2021 GDK Update 5 if you are intentionally staying on the October branch vs. using the latest branch.
- For more information about the GDK and how to start developing games for Xbox consoles or Xbox Game Pass for PC on Windows 10/11, view the ReadMe.MD.
Resolved Issues
Common Components Between Windows 10/11 & Xbox Consoles
Developer Tools | [Visual Studio] Fixed an issue that caused GDK VSIX packages to be orphaned in Visual Studio on the PC when using the Change and choosing the Uninstall or Repair option button in Programs and Features.
Networking | [XSAPI] Fixed an issue where a web socket handle didn't close under certain circumstances, causing a time out on suspension.
Networking | [XSAPI] Fixed an issue that caused multiple Multiplayer Activity requests that were sent within the same second to be ignored.
Xbox (available in GDKX also known as the GDK w/ Xbox Extensions)
[6] Fix(es) in this release: Platform (memory manager): [1], Developer Tools (XBOM): [1], Graphics (PIX, DX12): [3], Audio: [1]
Note: Changes proprietary to Xbox console hardware, graphics, memory management, storage, and security features are only documented in the GDKX release notes published to the private/NDA-only Xbox Developer Forums. See ReadMe for more details about the GDKX.
Known Issues (PC Development / Common)
Issue #18 | [Developer Tools] Visual Studio 2019 Lifecycle update
Issue #17 | [Developer Tools] GDK Visual Studio 2022 Preview Support - See issue for resolution / use the attached VS2022 Support Assets.
Workarounds Available
Issue #14 | [Developer Tools] MicrosoftGame.config files added by using the item template in the GDK might not set the Item Type property correctly
Issue #13 | [Developer Tools] MicrosoftGame.config files added by using the item template in the GDK might have the file extension changed
Issue #12 | [Developer Tools] Newly added MicrosoftGame.config files don’t appear in Xbox Gaming Project Control
Issue #10 | [Developer Tools] Using version 20348 of the Windows10 SDK and version 22000 of the Windows 11 SDK with the GDK
Issue #8 | [Developer Tools] Gaming Services may be removed or fail to install during GDK installation
Issue #7 | [Developer Tools] .NET Core 2.1 updates delivered through Microsoft Update can block GDK installation