This guide walks you through using the XBOX Godot Sample addons in your own Godot
project — what to copy, how to enable it, how to configure project settings,
and how to reach a signed-in user for both XBOX Live (godot_gdk) and
PlayFab (godot_playfab).
It also covers building the addon binaries from source, which is the current way to obtain them.
- Godot developers building a Windows game that needs to ship with Microsoft Store / Microsoft GDK identity, XBOX Live services, PlayFab backend features, GameInput, or MSIXVC packaging.
- Comfortable with Godot 4.x as an everyday tool: scenes, autoloads,
signals,
await, and the in-editor F1 documentation. - Have at least a sandbox Partner Center title (or plan to) — the XBOX-services side of the addons cannot meaningfully be exercised without a title id, SCID, and a sandbox.
You do not need prior Microsoft GDK or PlayFab experience to follow the tutorials. You do need a working Godot project, a Windows PC, and (for live tests) a sandbox-provisioned test account.
- Godot 4.x editor workflow (creating scenes, attaching scripts, using autoloads, reading the Output panel).
- GDScript basics:
func,varwith type hints,await,signal,match. The tutorial snippets are dense; you should be able to read one without looking up GDScript syntax. - One-shot async with
await Signal— this is how every long-running call in the addons resolves. The dedicated Async patterns page is the one-page primer the tutorials assume you've read.
Note
Check Compatibility for the supported Godot Engine and Microsoft GDK versions.
- Windows 10 (build 18362+) or Windows 11
- Godot 4.5+ (stable, Windows 64-bit)
- Microsoft GDK installed
(
winget install Microsoft.Gaming.GDK) - A built copy of each addon you want to use — built from source per Step 1 below
- For XBOX-services tutorials (T1+): a Partner Center title + SCID + sandbox test account
- For PlayFab tutorials (T1+): a PlayFab title id
- A scratch Godot project to copy the addons into (the tutorials build one from scratch — you do not need to clone this repo as a Godot project)
TL;DR
- Build the addon binaries from source (Step 1 below).
- Copy
addons/<addon>/into your project, including thebin/folder.- Enable the editor plugin in Project Settings → Plugins.
- Set the
gdk/runtime/*andplayfab/*project settings.- Subscribe to
GDK.users.user_changed(XBOX) and callPlayFab.users.sign_in_with_xuser_async(...)(PlayFab).
| Addon | Purpose |
|---|---|
addons/godot_gdk |
Microsoft GDK runtime + PC-supported XBOX services (users, achievements, presence, social, leaderboards, multiplayer activity, store, system, …). Installs an XboxBootstrap autoload. |
addons/godot_playfab |
PlayFab runtime, sign-in (XBOX-backed or custom id), Game Saves, leaderboards, Lobby + Matchmaking, Party, and REST service wrappers. Installs a PlayFabBootstrap autoload (auto-init is opt-in). |
addons/godot_gameinput |
GameInput controller integration (devices, polling, vibration, action-bridge into Godot's InputMap). Installs a GameInputBootstrap autoload. |
addons/godot_gdk_editortools |
GDScript-only editor plugin for PC MSIXVC packaging via makepkg.exe. Editor-only, no runtime. |
The four addons are independent — ship one, several, or all of them.
When something goes wrong while you follow the tutorials, the
Troubleshooting page collects the failures we see
most often (DLL load 126, SCID mismatch, sandbox mismatch, schema
errors in MicrosoftGame.config, etc.).
- Windows 10 (build 18362+) or Windows 11
- Godot 4.5+ (stable, Windows 64-bit)
- Microsoft GDK installed on
every machine that runs the game (the XBOX runtime DLLs the addons depend
on resolve from the Microsoft GDK install).
winget install Microsoft.Gaming.GDK.
- A title in Partner Center (Title ID, SCID, Sandbox ID at minimum)
- At least one XBOX test account provisioned in your sandbox
- Your dev PC switched into that sandbox
First time? You need an XBOX publisher account before you can register a Partner Center title. Start with the ID@XBOX program overview / application form and the Microsoft Game Stack publisher hub. Then follow Microsoft GDK — Get started, Configuring XBOX services (Title ID + SCID), and Setting up sandboxes for the Microsoft-side walkthrough that produces the IDs the rest of this guide refers to.
See Sample project setup and XBOX sandbox and test-account setup for the canonical addon-side walk-through.
- A PlayFab title (you'll need its title id)
- For the XBOX-backed
sign_in_with_xuser_asyncflow, the same XBOX prerequisites above - For
sign_in_with_custom_id_async, no XBOX setup is required
First time? You need a PlayFab title before you can fill in
playfab/runtime/title_id. Sign up at the PlayFab developer portal and follow PlayFab — Game Manager quickstart to create your account, studio, and first title. The Title ID lives in Game Manager under your title → Settings → API features. The PlayFab Learn hub is the entry point for everything else.
- Visual Studio 2022+ with the C++ Desktop workload
- CMake 3.29+ (required by the
CMakePresets.jsonschema version) - vcpkg in manifest mode. The build
reads
vcpkg.json+vcpkg-configuration.jsonat the repo root and resolves thems-gdk[playfab]andgameinputports for you, so you don't need a separate Microsoft GDK install just to compile the addons. Set theVCPKG_ROOTenvironment variable to your vcpkg clone (the CMake preset reads it via$env{VCPKG_ROOT}). You can also use the VCPKG component if it is installed with Visual Studio. The scriptpackage_addons.ps1will detect it and use it asVCPKG_ROOTautomatically.
Note: The vcpkg manifest only provides the build-time headers and import libs for Microsoft GDK + GameInput. You still need a full Microsoft GDK install on any machine where you intend to run
makepkg.exe,wdapp.exe, or the Game Config Editor (see Editor tools and Editor Tools plugin).
Note: The Debug build of the Microsoft GDK addon requires Visual Studio to be installed on the machine that runs the game, not just the machine that builds it. Use the Release build for distribution. See Troubleshooting for details.
You need a built copy of each addon you want to use. Build the drop-in layout from source: clone with submodules and run the package helper.
git clone --recurse-submodules https://github.com/microsoft/XBOX-Godot-Sample.git
cd XBOX-Godot-Sample
.\tools\package_addons.ps1The helper configures the addon-package CMake preset, builds Debug and
Release native addon DLLs by default, stages the drop-in addon files under
build\dist\godot-gdk-addons\addons\, and writes
build\dist\godot-gdk-addons-debug-release.zip. Copy the addon folders
you need from build\dist\godot-gdk-addons\addons\ into your Godot
project's addons/ folder (or extract the zip there).
The package build:
- Outputs each addon's DLLs and PDBs into
addons/<addon>/bin/ - Copies the runtime dependency DLLs (
libHttpClient.dll,Microsoft.XBOX.Services.C.Thunks.dllfor Release orMicrosoft.XBOX.Services.C.Thunks.Debug.dllfor Debug,PlayFabCore.dll,PlayFabServices.dll,PlayFabGameSave.dll,PlayFabMultiplayer.dll,Party.dll) into the samebin/folder so they ship side-by-side - Syncs the addon directories into every sample project under
sample/
If you only need one addon during development, use the targeted presets
(gdk-only, playfab-only, gameinput-only). See
Selective builds below for the exact commands.
For deeper notes on the build pipeline (CMake auto-detection of the Microsoft GDK install, selective builds, VS Code IntelliSense, ignored-artifact cleanup), jump to Building from source at the end of this guide.
For each addon you want, copy the entire addons/<addon>/ directory
into your project's addons/ folder. The shape that needs to land in
your project is:
your_project/
└── addons/
└── godot_gdk/
├── bin/ # native DLLs + runtime deps
│ ├── godot_gdk.windows.debug.x86_64.dll
│ ├── godot_gdk.windows.release.x86_64.dll
│ ├── libHttpClient.dll
│ ├── Microsoft.XBOX.Services.C.Thunks.Debug.dll
│ └── Microsoft.XBOX.Services.C.Thunks.dll
├── doc_classes/ # in-editor F1 documentation
├── editor/ # editor plugin scripts
├── runtime/ # XboxBootstrap autoload
├── godot_gdk.gdextension # extension manifest
└── plugin.cfg # editor plugin manifest
Repeat for godot_playfab/ and godot_gameinput/ if you want them. The
bin/ folder of each addon already contains every native runtime
dependency that addon needs — copy the directory recursively and you're
done.
Don't strip
bin/. Without the DLLs Godot logsGDExtension dynamic library not foundand the addon's singletons never register. 64-bit Windows is the only target the addons currently build for.
⚠️ Copy from the packaged output, not a raw dev build. Thebuild\dist\godot-gdk-addons\addons\layout produced bytools\package_addons.ps1is already consumer-ready. A raw in-treeaddons\<addon>\directory from acmake --builddev build also containssrc\,tests_support\, andCMakeLists.txt. Thetests_support\scripts extendGutTest(from the GUT testing framework, which your project won't have), so copying them in makes Godot throw parse errors likeCould not find base class "GutTest"on load. If you must copy from a dev build, excludesrc\,tests_support\, andCMakeLists.txt— keep onlybin\,runtime\,editor\,doc_classes\, the.gdextensionmanifest, andplugin.cfg.
Open your project in Godot once so it discovers the new plugin.cfg
files, then go to Project → Project Settings → Plugins and enable:
| Plugin name in the Plugins tab | What enabling it does |
|---|---|
GodotGDK |
Installs the XboxBootstrap autoload at res://addons/godot_gdk/runtime/gdk_bootstrap.gd. |
GodotPlayFab |
Installs the PlayFabBootstrap autoload at res://addons/godot_playfab/runtime/playfab_bootstrap.gd. The autoload only calls PlayFab.initialize() automatically when playfab/runtime/initialize_on_startup is true — sign-in stays in your code. |
Godot GameInput |
Installs the GameInputBootstrap autoload at res://addons/godot_gameinput/runtime/gameinput_bootstrap.gd. |
GDK Editor Tools |
(Optional, editor-only) registers MSIXVC packaging tooling under the editor's tools menu. |
Disabling a plugin removes its autoload again — there's no orphaned state.
The Plugins tab just writes an [editor_plugins] section to
project.godot. For headless setup, CI, onboarding scripts, or if you
prefer editing config directly, add the section yourself (list only the
addons you actually copied in):
[editor_plugins]
enabled=PackedStringArray("res://addons/godot_gdk/plugin.cfg", "res://addons/godot_playfab/plugin.cfg", "res://addons/godot_gameinput/plugin.cfg", "res://addons/godot_gdk_editortools/plugin.cfg")Without this section Godot opens with every plugin disabled and prints no error — the autoloads and the GDK editor menu simply never appear.
To confirm the addons resolve without parse or load errors — useful for agents and CI that can't visually check the editor — open the project once in headless mode and inspect the output:
godot --headless --path path\to\your_project --quit 2>&1 |
Select-String -Pattern "Parse Error", "GDExtension dynamic library not found"No matching lines means the addons loaded cleanly. (You can point
--path at any in-repo sample\tutorial_* project once its addon
binaries have been built and synced.) This is a quick load smoke test —
the repo's own GDScript validator
(tools\check_gd_scripts_headless.ps1) remains the authoritative parse
gate for contributors.
The bootstrap autoloads consume a handful of ProjectSettings entries.
You can edit them in Project → Project Settings → General (toggle
Advanced Settings) or write them straight into project.godot.
[gdk]
runtime/initialize_on_startup=true ; bootstrap calls GDK.initialize() at startup
runtime/auto_add_primary_user=true ; bootstrap calls add_default_user_async() after init
runtime/embed_dispatch=true ; pump async completions in _process (default)Leave embed_dispatch on unless you want to drive GDK.dispatch()
yourself for deterministic frame control.
[playfab]
title_id="" ; REQUIRED: your PlayFab title id
endpoint="" ; optional: blank derives https://<titleid>.playfabapi.com
runtime/initialize_on_startup=true ; bootstrap calls PlayFab.initialize() at startup (default false)
runtime/embed_dispatch=true ; pump async completions in _process (default)When initialize_on_startup is true, the PlayFabBootstrap autoload
calls PlayFab.initialize() during _ready — the same shape as the Microsoft GDK
bootstrap. Sign-in is still in your code because PlayFab needs a
per-player key (an XboxUser or a custom id).
Example override (the registered default for runtime/initialize_on_startup is false):
[game_input]
runtime/initialize_on_startup=true ; example override: bootstrap calls GameInput.initialize() at startup
runtime/auto_poll=true ; bootstrap calls GameInput.poll() in _process (default)
mapper/default_action_map="" ; optional path to a GameInputActionMap .tresSee GameInput addon for the action-bridge details.
This is the smallest thing that proves the addons are wired up correctly: an XBOX sign-in (godot_gdk) followed by a PlayFab sign-in that reuses the XBOX user (godot_playfab).
If you set gdk/runtime/initialize_on_startup and
gdk/runtime/auto_add_primary_user to true, the XboxBootstrap
autoload does this for you on _ready — your code just needs to react
to the result.
extends Node
## Drop this on a node in your first scene.
func _ready() -> void:
if not Engine.has_singleton("GDK"):
push_error("godot_gdk extension is not loaded — check addons/godot_gdk/bin/")
return
GDK.users.user_changed.connect(_on_user_changed)
# The bootstrap may already have signed someone in by the time _ready runs.
var user: XboxUser = GDK.users.get_primary_user()
if user != null:
_show_user(user)
func _on_user_changed(user: XboxUser, change_kind: String) -> void:
if change_kind == "added" and user == GDK.users.get_primary_user():
_show_user(user)
elif change_kind == "removed":
print("[GDK] user removed: %d" % user.local_id)
func _show_user(user: XboxUser) -> void:
print("[GDK] signed in as %s (XUID %s)" % [user.gamertag, user.xuid])If you want full control instead, leave the two gdk/runtime/* flags
off and call the lifecycle yourself:
func _ready() -> void:
var init_result: XboxResult = GDK.initialize()
if not init_result.ok:
push_warning("GDK.initialize failed: %s" % init_result.message)
return
var sign_in_result: XboxResult = await GDK.users.add_default_user_async()
if not sign_in_result.ok:
push_warning("Silent sign-in failed: %s" % sign_in_result.message)
return
var user: XboxUser = sign_in_result.data
print("[GDK] signed in as %s" % user.gamertag)
func _exit_tree() -> void:
if GDK.is_initialized():
GDK.shutdown()add_default_user_async() is the XBOX silent sign-in. If no user is
already signed into the XBOX app on the PC, it returns a non-ok result
(commonly no_default_user). Use add_user_with_ui_async() to put the
system sign-in UI on screen instead.
For the full method/signal table see
Microsoft GDK API reference → GDK.users.
Real XBOX Live sign-in needs Partner Center configuration, the right sandbox set on the PC, and a test account signed into the XBOX app — see Sample project setup and XBOX sandbox and test-account setup. Without those, sign-in will report a clear error and the rest of the game keeps running fine.
If you set playfab/runtime/initialize_on_startup to true, the
PlayFabBootstrap autoload calls PlayFab.initialize() for you. Sign-in
still goes through your code because PlayFab needs a per-player key —
either an XboxUser or a custom id.
extends Node
func _ready() -> void:
await _sign_in_to_playfab()
func _sign_in_to_playfab() -> void:
if not Engine.has_singleton("PlayFab"):
push_error("godot_playfab extension is not loaded")
return
if not Engine.has_singleton("GDK"):
push_error("godot_gdk extension is not loaded")
return
# Make sure GDK is up and we have an XBOX user.
if not GDK.is_initialized():
var init: XboxResult = GDK.initialize()
if not init.ok:
push_warning("GDK init failed: %s" % init.message); return
var xbox_user: XboxUser = GDK.users.get_primary_user()
if xbox_user == null or not xbox_user.signed_in:
var xbox_result: XboxResult = await GDK.users.add_default_user_async()
if not xbox_result.ok:
push_warning("XBOX sign-in failed: %s" % xbox_result.message); return
xbox_user = xbox_result.data
# Initialize PlayFab once. The PlayFabBootstrap autoload may have
# already done this when playfab/runtime/initialize_on_startup is true;
# the call here is a defensive fallback for projects that disable it.
if not PlayFab.is_initialized():
var pf_init: PlayFabResult = PlayFab.initialize()
if not pf_init.ok:
push_warning("PlayFab init failed: %s" % pf_init.message); return
# Sign the XBOX user into PlayFab.
var pf_result: PlayFabResult = await PlayFab.users.sign_in_with_xuser_async(xbox_user)
if not pf_result.ok:
push_warning("PlayFab sign-in failed: %s" % pf_result.message); return
var pf_user: PlayFabUser = pf_result.data
var key: Dictionary = pf_user.entity_key
print("[PlayFab] signed in: %s:%s" % [key.get("type", ""), key.get("id", "")])If you don't have an XBOX account yet (or are testing on a machine without Microsoft GDK Live setup), use the no-XBOX custom-ID path:
var pf_result: PlayFabResult = await PlayFab.users.sign_in_with_custom_id_async(
"your-title-defined-id", false) # false = don't auto-createsign_in_with_xuser_async returns invalid_xuser if you pass a null or
signed-out Microsoft GDK user, so always confirm xbox_user.signed_in first.
PlayFab Game Saves additionally require an XBOX-backed PlayFab session
(custom-id users will get xbox_user_required from PlayFab.game_saves
methods).
For the full PlayFab service surface see the PlayFab plugin overview.
Run your project. You should see, in order:
[GDK] Bootstrap: GDK.initialize() succeeded.
[GDK] Runtime initialized
[GDK] User added: <gamertag>
[GDK] signed in as <gamertag> (XUID <xuid>)
[PlayFab] signed in: title_player_account:<entity-id>
If sign-in fails before that point, the result.message you printed
tells you which step is broken — see
Troubleshooting → sign-in and the sandbox /
test-account guide.
| Symptom | Likely cause | Fix |
|---|---|---|
GDExtension dynamic library not found |
The bin/ folder didn't make it into the project copy |
Copy addons/<addon>/ recursively, including bin/ |
[GDK] Bootstrap: 'GDK' singleton not registered |
Extension failed to load (wrong Windows arch, missing Microsoft GDK install, missing libHttpClient.dll) |
Check that the addon copy preserved bin/ and that the Microsoft GDK is installed on the machine that runs the game |
Silent sign-in returns no_default_user |
No test account signed in to the XBOX app on the PC, or the PC sandbox doesn't match Partner Center | Set the sandbox with XblPCSandbox.exe and sign a test account into the XBOX app — see XBOX sandbox and test-account setup |
PlayFab.initialize() fails immediately |
playfab/runtime/title_id is empty |
Set playfab/runtime/title_id in Project Settings (or project.godot [playfab] runtime/title_id="...") |
sign_in_with_xuser_async returns invalid_xuser |
Passing a null / signed-out Microsoft GDK user | Verify xbox_user != null and xbox_user.signed_in before calling |
PlayFab.game_saves returns xbox_user_required |
The PlayFab session was created with a custom id | Use sign_in_with_xuser_async for any flow that touches Game Saves |
- Tutorials — task-oriented walkthroughs for sign-in, achievements, leaderboards, Game Saves, lobbies, and GameInput. Recommended next stop once you have signed in.
- Microsoft GDK API reference — full list of services
(
GDK.users,GDK.achievements,GDK.leaderboards,GDK.multiplayer_activity,GDK.store,GDK.system, …) - PlayFab plugin overview —
PlayFab.users,PlayFab.game_saves,PlayFab.leaderboards,PlayFab.multiplayer,PlayFab.party,PlayFab.events, and the REST service wrappers - GameInput addon — devices, polling, vibration,
and the action-bridge into Godot's
InputMap - Sample project setup — Partner Center configuration, sandboxes, test accounts
- Troubleshooting — common build, runtime, and test issues
Reference for contributors and anyone reproducing the addon binaries themselves.
git clone --recurse-submodules https://github.com/microsoft/XBOX-Godot-Sample.git
cd XBOX-Godot-SampleIf you've already cloned without submodules:
git submodule update --init --recursiveFor a packaged drop-in build (stages addons under build\dist\ and
produces an addons zip):
.\tools\package_addons.ps1For local development builds:
# Configure the debug build tree
cmake --preset default
cmake --build --preset debug
# Release needs its own configure and its own build tree
cmake --preset default-release
cmake --build --preset releaseDebug and Release are separate build trees. godot-cpp's
GODOTCPP_TARGETis a configure-time cache variable, sobuild/only ever produces correct Debug binaries andbuild/release/only ever produces correct Release binaries.cmake --build build --config Releasefails on purpose. See Release build linked the debug godot-cpp.
The build:
- Outputs addon DLLs to
addons/<addon>/bin/ - Copies built DLLs and runtime dependencies into each sample's
addons/<addon>/bin/ - Syncs addon metadata, editor scripts, GUT, and shared test support into the sample projects
# GDK addon only
cmake --preset gdk-only
cmake --build --preset debug-gdk
# PlayFab addon only
cmake --preset playfab-only
cmake --build --preset debug-playfab
# GameInput addon only
cmake --preset gameinput-only
cmake --build --preset debug-gameinputWhich preset should I use?
VCPKG_ROOTis set (or you're happy to set it) →cmake --preset default. Resolves the Microsoft GDK + GameInput from vcpkg; no machine-wide GDK install needed at build time.- No vcpkg, but the Microsoft GDK is installed on disk (auto-detected via
%GRDKLatest%/%GameDK%, pinned to a pre-approved edition with-DGDK_VERSION=<edition>, or set explicitly with-DGDK_INSTALL_DIR=<path>) →cmake --preset installed-gdk. No vcpkg checkout orVCPKG_ROOTrequired. - Neither → install vcpkg, set
VCPKG_ROOT, then usecmake --preset default.
By default, the build resolves the Microsoft GDK headers and import libs through
the ms-gdk[playfab] vcpkg port (default preset). This requires only
a vcpkg checkout — no machine-wide Microsoft GDK install is needed at build time.
If you already have a Microsoft GDK installed on disk (most developers
do, for makepkg.exe / wdapp.exe / Game Config Editor), the
installed-gdk preset consumes it directly and does not require vcpkg
at all — no VCPKG_ROOT, no vcpkg checkout, no port restore:
# Consume an installed Microsoft GDK. With no edition pinned, the oldest
# pre-approved edition that is installed is selected (the broadest-compatible
# baseline), auto-detected via %GRDKLatest% / %GameDK%.
cmake --preset installed-gdk
cmake --build --preset debug-installed-gdk
# Pin a specific pre-approved edition (must be in GDK_SUPPORTED_VERSIONS)
cmake --preset installed-gdk -DGDK_VERSION=251001
# Override edition selection entirely with an explicit path
cmake --preset installed-gdk -DGDK_INSTALL_DIR="C:/Program Files (x86)/Microsoft GDK/251001"Note: the
installed-gdkpreset is the only supported way to consume an installed Microsoft GDK. Setting-DGDK_DEPENDENCY_SOURCE=installedon thedefaultpreset does not work — the vcpkg toolchain processes manifest features (and restoresms-gdk[playfab]) before the Microsoft GDK source-selection logic runs. Theinstalled-gdkpreset sidesteps this by not loading the vcpkg toolchain at all.
Installed mode consumes the modern windows\ subdirectory layout of the
Microsoft GDK (<install>\windows\include, <install>\windows\lib\x64,
<install>\windows\bin\x64) that first shipped in the October 2025
Microsoft GDK. The addons build against any pre-approved edition
(see the version-selection table below); the C++ source is edition-gated on
grdk.h's _GRDK_EDITION, so October 2025 builds fall back to the older
XGameProtocol / XGameInvite activation APIs and skip the handful of PlayFab
fields added in April 2026. The legacy GRDK\ peer layout is not supported; use
the default preset (vcpkg) for older Microsoft GDK versions.
GameInput in installed mode — the installed Microsoft GDK ships GameInput v1
only, but the godot_gameinput addon targets v3. The installed-gdk
preset solves this by setting GAMEINPUT_SOURCE=nuget, which fetches
the Microsoft.GameInput NuGet package directly from nuget.org via
file(DOWNLOAD) (cached under build/installed-gdk/_deps/). No vcpkg
toolchain is involved; the first configure needs network access, and
subsequent configures reuse the cached extract. This is the same
upstream archive vcpkg's gameinput port wraps, so behavior is
identical at runtime. Target machines still need GameInputRedist.msi
installed (extracted to build/installed-gdk/_deps/gameinput-nuget-<version>/redist/).
Source-selection options:
GDK_DEPENDENCY_SOURCE |
Behavior |
|---|---|
vcpkg (default) |
Use the ms-gdk[playfab] vcpkg port. Set automatically by the default preset. Requires VCPKG_ROOT. |
installed |
Use a Microsoft GDK install on disk. Set automatically by the installed-gdk preset (which also drops the vcpkg toolchain — no VCPKG_ROOT required). Setting this alone on the default preset has no effect on the vcpkg restore. |
When GDK_DEPENDENCY_SOURCE=installed, the edition is selected from a
maintained, pre-approved allowlist:
| Option | Default | Behavior |
|---|---|---|
GDK_VERSION |
(empty) | 6-digit edition from the installed allowlist. Empty selects the oldest pre-approved edition that is installed. Ignored when GDK_INSTALL_DIR is set. |
GDK_SUPPORTED_VERSIONS |
See GDKDependencies.cmake |
Pre-approved editions the installed source may select. Maintainers extend this list as new editions are validated. |
GDK_ALLOW_UNAPPROVED |
OFF |
Escape hatch: allow GDK_VERSION to name an edition not in the allowlist (warns instead of failing). That edition is unvalidated — use at your own risk. |
GAMEINPUT_SOURCE |
Behavior |
|---|---|
vcpkg (default) |
Use the gameinput vcpkg port. Requires VCPKG_ROOT. |
nuget |
Fetch the Microsoft.GameInput NuGet package directly from nuget.org (no vcpkg required). Set automatically by the installed-gdk preset. The pinned version + SHA512 are tracked in cmake/GDKDependencies.cmake (override with -DGDK_GAMEINPUT_NUGET_VERSION=<version> -DGDK_GAMEINPUT_NUGET_SHA512=<hash>). |
GDK_VERSION only applies to GDK_DEPENDENCY_SOURCE=installed. On the
default (vcpkg) preset the Microsoft GDK edition is whatever the ms-gdk
port resolves to, governed by vcpkg's own versioning — the
default-registry.baseline in vcpkg-configuration.json. Everything
downstream follows the port automatically: the vcpkg-provided grdk.h carries
the matching _GRDK_EDITION, so the C++ edition gate (activation backend,
April-2026-only PlayFab fields) and the XSAPI import lib both flip to match the
selected edition with no extra flags.
To pin a specific edition on the vcpkg path, set a top-level overrides entry
in vcpkg.json to an ms-gdk version from the hosted
GDK matrix. CI injects the selected version
automatically.
Then reconfigure so vcpkg re-restores the port:
cmake --preset defaultThe ms-gdk port version uses the YYMM.N.<build> format and maps to the
6-digit GDK edition YYMM0N. The current hosted versions are listed in the
GDK matrix; an override must exist in the
registry's versions/m-/ms-gdk.json reachable from the baseline, or vcpkg
errors at configure time. An edition without a published port can still be
selected through the installed-GDK path.
Two coarser alternatives:
- Move the baseline — bump
default-registry.baselineinvcpkg-configuration.jsonto amicrosoft/vcpkgcommit whosems-gdkbaseline is the edition you want. Simpler, but it shifts every port. - Overlay port — supply a local
ports/ms-gdk/(viaoverlay-ports) for an edition that is not in the public registry (e.g.260400).
PlayFab Game Save on October 2025 ports. The
2510.xms-gdkports ship the PlayFab Game Save binaries (PlayFabGameSave.{lib,dll}) and headers, but their exported CMake config omits theXbox::PlayFabGameSavetarget (added in the April 20262604.xports). The build detects this and backfills the target from the installed vcpkg layout, sogodot_playfabconfigures and builds against every supported edition without extra flags — see_gdk_backfill_vcpkg_playfab_gamesaveincmake/GDKDependencies.cmake.
The build resolves its native dependencies via vcpkg manifest mode. CMake
reads vcpkg.json + vcpkg-configuration.json at the repo root and pulls
in the ms-gdk[playfab] and gameinput ports for you. There is no
machine-wide Microsoft GDK install required for compilation — set VCPKG_ROOT and
run the default preset.
If you ever need to point at a specific vcpkg toolchain file (for example, to share an installed cache between repos), override it on the CMake command line:
cmake --preset default -DCMAKE_TOOLCHAIN_FILE="C:/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake"Use the repo cleanup helper to preview or remove ignored local files such as
build\, addon/sample bin\, sample .godot\, local sample configs or Godot
editor copies under sample\, and generated packaging output.
# Preview what would be removed
.\tools\clean_repo.ps1
# Remove ignored local artifacts
.\tools\clean_repo.ps1 -ApplyThe script wraps git clean in ignored-files-only mode, so tracked repository
files stay intact.
The repository ships four tutorial sample projects:
sample/tutorial_gdk/(GDK only),sample/tutorial_playfab/(PlayFab only),sample/tutorial_integrated/(both), andsample/tutorial_gameinput/(standalone GameInput). Build the addons once (cmake --build build --preset debug) so each project's mirroredaddons/are populated, then open one in Godot. See the tutorials for the per-track walkthroughs.
sample/tutorial_netrumble/contains no project of its own. It documents XBOX Godot NetRumble, a full multiplayer game built on these addons and hosted in a separate repository.
Use the repo-wide orchestrator as the canonical local test command:
pwsh -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\tools\run_all_tests.ps1The orchestrator runs the GDScript parse gate, debug CMake build, C++
doctest executable, GUT host suites, bootstrap mini-runners, and the
aggregate summary. Results are written to
build\test-results\run-summary.json and .md. See
Sample and tests for the full pipeline,
the live switch, and troubleshooting links.
After building, VS Code IntelliSense should work automatically with the
included .vscode/c_cpp_properties.json. If you see red squiggles on
#include directives:
- Ensure you've built at least once — godot-cpp headers are generated
during the first build into
build/godot-cpp/gen/include/, and vcpkg stages the Microsoft GDK + GameInput headers intobuild/vcpkg_installed/. - Ensure
VCPKG_ROOTis set in your environment so the IntelliSense include paths resolve. If you point IntelliSense at a different vcpkg install than the build uses, update.vscode/c_cpp_properties.jsonto match. - Reload VS Code (
Ctrl+Shift+P→ "C/C++: Reset IntelliSense Database").
The config defines _GAMING_DESKTOP, which is required for XSAPI /
libHttpClient platform detection.
addons/godot_gdk/ # GDK addon: metadata, editor scripts, native sources
addons/godot_gameinput/ # GameInput addon: metadata, native sources
addons/godot_playfab/ # PlayFab addon: metadata, native sources
addons/godot_gdk_editortools/ # GDScript-only packaging tools (editor-only)
cmake/ # Shared CMake helpers
docs/ # Documentation
godot-cpp/ # godot-cpp submodule
sample/ # Tutorial sample projects:
# tutorial_gdk/ — GDK-only track
# tutorial_playfab/ — PlayFab-only track
# tutorial_integrated/ — GDK + PlayFab track
# tutorial_gameinput/ — standalone GameInput
# tutorial_netrumble/ — pointer to the external NetRumble game
tests/ # Baselines, C++ doctest sources, and Godot test hosts
godot/gdk/ # GDK and GDK packaging test host
godot/playfab/ # PlayFab test host
godot/gameinput/ # GameInput test host
third_party/Gut/ # GUT (bitwes/Gut) submodule — mirrored into test hosts
tools/ # CLI helper scripts
cmake --build build --preset debugThis rebuilds the DLL and syncs it, addon metadata, and generated test support into the sample projects.
Rebuild so the sample copy is refreshed:
cmake --build build --preset debug- Rebuild the addon or run the full orchestrator.
- Run
pwsh -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\tools\run_all_tests.ps1. - Open the relevant sample in the editor and verify the user-facing flow still loads.
- If XBOX Live or PlayFab live features changed, test with
-Liveagainst a sandbox title and test account.
Enable the repo-managed pre-commit hook to run headless GDScript validation before each commit:
git config core.hooksPath .githooks