Welcome to the documentation for the XBOX Godot Sample repository — a collection of Godot 4.x GDExtension addons for Windows gaming integrations around the Microsoft public GDK.
docs/
├── README.md — this index
├── getting-started.md — onboarding (repo build + first sign-in)
├── addon-getting-started.md — drop-in addons quickstart
├── async-patterns.md — one-page async-system primer
├── troubleshooting.md — common build, runtime, and test issues
├── tutorials/ — task-oriented walkthroughs
├── gdk/ — godot_gdk addon
├── playfab/ — godot_playfab addon
│ └── async-system.md — PlayFab completion/dispatch contract
├── gameinput/ — godot_gameinput addon
├── editortools/ — godot_gdk_editortools addon
└── platform/ — XBOX Sandbox + test-account setup
- Getting Started — adding the addons to your
project, configuring project settings, getting to user sign-in (XBOX
- PlayFab), and building from source
- Addons getting started — short quickstart for dropping the addons into an existing Godot project (enable, set PlayFab title id, create game config, switch sandbox, sign in)
- Tutorials — task-oriented walkthroughs for sign-in, achievements, leaderboards, Game Saves, lobbies, Multiplayer Activity, PlayFab Party, the integration tech demo capstone, plus a standalone GameInput track
- Async patterns — one-page primer on the
_asyncnaming convention,await-on-coroutine, Result objects, and service-level runtime errors - PlayFab async system — PlayFab-specific fire-once completion signals, dispatch ownership, and shutdown/cancellation behavior
- Test Pipeline — repo-wide orchestrator, GUT hosts, C++ doctest, live switch, and test baselines
Current committed sample hosts:
sample/tutorial_gdk/— GDK-only tutorial track (sign-in, achievements, title storage & stats, Multiplayer Activity)sample/tutorial_playfab/— PlayFab-only tutorial track (sign-in, leaderboards, lobby, Party)sample/tutorial_integrated/— integrated GDK + PlayFab track (XBOX→PlayFab sign-in, integration tech demo)sample/tutorial_gameinput/— standalone GameInput demo
sample/tutorial_netrumble/is a pointer rather than a committed host: it documents XBOX Godot NetRumble, a full multiplayer game built on these addons that lives in a separate repository.The tutorials walk through each surface, and the test hosts under
tests/godot/exercise the addons end-to-end.
- Migrating to v0.3.0 — the
GDK*→Xbox*type rename, the old → new table, and the codemod - Sample Project Setup — Partner Center configuration, sandbox setup, test accounts, and the config flow
- GDScript API Reference — public API
surface for
GDK,GDK.system,GDK.users,GDK.game_ui,GDK.accessibility,GDK.achievements,GDK.package,GDK.stats,GDK.leaderboards,GDK.privacy,GDK.presence,GDK.social,GDK.profile,GDK.string_verify,GDK.title_storage,GDK.error_reporting,GDK.multiplayer_activity,GDK.capture,GDK.launcher,GDK.networking, andGDK.store
- Plugin Overview — implementation status and document map
- Build and Loading — addon layout, build flow, and how Godot loads the extension
- Native Runtime — runtime structure, services, and request flow
- Async System — shared queue, pending-signal helpers, XAsync bridge, and cancellation
- Editor Tools — editor plugin, setup panel, and export platform
- Sample and Tests — sample architecture, coverage hosts, and the repo-wide test pipeline
- GameInput Addon — devices, polling, vibration, action bridge, project settings, sample integration, and testing
- GameInput Manual Tests — hardware checklist for things headless tests can't cover (real controllers, rumble, hot-plug)
- PlayFab Plugin Overview — runtime
configuration, public surface (
PlayFab,PlayFab.users,PlayFab.game_saves,PlayFab.leaderboards, and the client-safe service wrappers underPlayFab.accounts,PlayFab.catalog,PlayFab.cloud_script,PlayFab.entity_data,PlayFab.experimentation,PlayFab.friends,PlayFab.groups,PlayFab.inventory,PlayFab.localization,PlayFab.player_data,PlayFab.statistics,PlayFab.title_data), sample usage, and testing - PlayFab title prerequisites —
PlayFab title configuration required before any PlayFab tutorial or
sample runs (Title ID, per-tutorial Game Manager fixtures including
the statistic + leaderboard pair backing T3, the Lobby and Party
feature switches, and the
configure_playfab_test_title.ps1helper)
- Editor Tools Plugin — headless runner and CLI reference for PC packaging verbs
- Editor
GDKmenu — Create/Edit MicrosoftGame.config, sandbox switching, Package Manager, and documentation shortcuts
- XBOX Sandbox and Test Accounts — switching the PC into a Partner Center sandbox, signing in the XBOX app with a test account, and the error-code lookup table
- Troubleshooting — common build, runtime, and test issues
- Issue triage (
/triage) — maintainer-triggered AI first-pass evaluation of an issue against the code, rollout, and pilot checklist - GDK release watch — weekly watcher for new
microsoft/GDKreleases that files a tracking issue and posts an AI advisory assessment on it as an implementation brief for a human or coding agent - PR-local live validation — checks a pull request out at its exact head commit on a GDK-capable machine, runs the full live-write suite on every supported Godot version, and comments the result