Skip to content

Latest commit

 

History

History
150 lines (126 loc) · 7.08 KB

README.md

File metadata and controls

150 lines (126 loc) · 7.08 KB

XBOX Godot Sample Documentation

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.

Folder structure

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

  • 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 _async naming 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

Sample projects

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.

Godot Microsoft GDK addon (godot_gdk)

User guides

  • 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, and GDK.store

Architecture

  • 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 (godot_gameinput)

  • 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 addon (godot_playfab)

  • PlayFab Plugin Overview — runtime configuration, public surface (PlayFab, PlayFab.users, PlayFab.game_saves, PlayFab.leaderboards, and the client-safe service wrappers under PlayFab.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.ps1 helper)

Editor Tools addon (godot_gdk_editortools)

  • Editor Tools Plugin — headless runner and CLI reference for PC packaging verbs
  • Editor GDK menu — Create/Edit MicrosoftGame.config, sandbox switching, Package Manager, and documentation shortcuts

Platform setup

  • 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

Repository automation

  • 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/GDK releases 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