refactor(gdk)!: rename GDK* classes to Xbox* to avoid collisions with console-capable Godot forks (v0.3.0)

[James Lenell (jameslen-atg)]

refactor(gdk)!: rename GDK* classes to Xbox* (v0.3.0)

Warning

Breaking change. Every script-visible GDK* type is renamed to Xbox*. No deprecated aliases ship — this is a hard break.
The engine singleton is still named GDK. GDK.initialize() keeps working unchanged.

Migration guide: docs/gdk/migration-v0.3.md
Automated codemod: pwsh -File tools/migrate_gdk_to_xbox.ps1 -Path <your-project> -WhatIf

This revives the work from #143 (closed unmerged) on top of current main, and adds the release deliverables that were missing from it: a migration guide, a codemod, a CHANGELOG, and a version bump to 0.3.0.

Why this rename

This rename exists to let the addon enable console support inside compatible Godot forks. Console-capable forks supply the console platform layer and register their own types, and the GDK* prefix collided with names those forks already use. Godot registers extension classes in a single flat ClassDB namespace, so two providers exposing the same name cannot coexist in one project.

Moving this addon's script-visible types to the Xbox* prefix keeps them distinct, so the addon can be dropped into such a fork and light up console scenarios there rather than being blocked by a name conflict.

A single binary covers both PC and console. There is no separate console compilation, build preset, or conditional define — godot_gdk.gdextension declares only the windows.*.x86_64 libraries, and a console-capable fork loads those same binaries. One build of the addon, both targets.

Important

Godot itself is unchanged by this. The engine's console support comes from those forks, not from this repository. Within this repo the rename is a naming change only — no runtime behavior changed.

The one gotcha

The ClassDB class name and the engine singleton name are now different strings:

GDK.initialize()                 # unchanged — the singleton is still `GDK`
GDK.is_class("GDK")              # now false
GDK.is_class("Xbox")             # now true
Engine.has_singleton("GDK")      # unchanged — still true

Only type references move. Anything that reflects on the class name by string needs updating.

Usage — GDScript

# before
var users: GDKUsers = GDK.users
var achievements: GDKAchievements = GDK.achievements
var result: GDKResult = await achievements.update_achievement_async(user, "ach-1", 100)

# after
var users: XboxUsers = GDK.users
var achievements: XboxAchievements = GDK.achievements
var result: XboxResult = await achievements.update_achievement_async(user, "ach-1", 100)

Note that only the type annotations changed — the GDK.users / GDK.achievements accessors are untouched.

Signal payloads and is/as/extends positions move the same way:

# before
func _on_user_changed(user: GDKUser) -> void:
    if user is GDKUser:
        ...

# after
func _on_user_changed(user: XboxUser) -> void:
    if user is XboxUser:
        ...

Usage — C#

The C# binding is a matching Gdk → Xbox prefix swap, and the namespace moves GodotGdk → GodotXbox. The assembly name and csproj (GodotGdkCSharp) are unchanged, so existing <ProjectReference> entries still resolve.

// before
using GodotGdk;
GdkResult result = await Gdk.Users.AddDefaultUserAsync();
Gdk.Users.UserChanged += (GdkUser user, string change) => GD.Print(change);

// after
using GodotXbox;
XboxResult result = await Xbox.Users.AddDefaultUserAsync();
Xbox.Users.UserChanged += (XboxUser user, string change) => GD.Print(change);

Xbox is a static facade (Xbox.Users, Xbox.Achievements, …) — there is no .Instance.

Deliberately NOT renamed

These are product/plumbing names, not script-visible types, and stay as-is:

• the GDK engine singleton, and the addons/godot_gdk folder + godot_gdk.gdextension
• gdk/runtime/* and gdk/packaging/* Project Settings keys
• the gdk export feature tag, GDKPKG_* env vars, gdkpkg forwarders
• cmake/GDKDependencies.cmake, GDK_VERSION, gdk_edition.h
• GodotGdkCSharp assembly/csproj name
• all PlayFab* and GameInput* types (out of scope for this release)

Codemod

tools/migrate_gdk_to_xbox.ps1 rewrites an explicit list of 48 GDScript API names and 54 C# API names. It does not touch a consumer's own Gdk-prefixed identifiers by default (opt in with -RenameProjectGdkNames), and it never rewrites a bare GDK (that's the singleton).

pwsh -File tools/migrate_gdk_to_xbox.ps1 -Path C:\my-game -WhatIf   # preview
pwsh -File tools/migrate_gdk_to_xbox.ps1 -Path C:\my-game           # apply

It was validated by replaying it over main's pre-rename sample/ tree and diffing against this branch's hand-renamed version: 121 of 122 files came out byte-identical. The single remainder is a private method named OnGdkRuntimeError (Gdk infixed rather than prefixed), which is correctly out of scope for automation and is called out in the migration guide.

Also in this PR

• CHANGELOG.md — first changelog in the repo, seeded with v0.1.0 / v0.2.0 and this release
• addon versions bumped 0.1.0-dev/0.1.0 → 0.3.0 across all four plugin.cfg files; <Version>0.3.0</Version> added to both C# csproj files
• straggler doc fixes: GDKResult in docs/gdk/api-reference.md, GDKExportPlatform in docs/gdk/editor-tools.md
• migration guide linked from README.md and docs/README.md

Validation

All run locally against Godot 4.6.2-stable from this branch:

Gate	Result
tools/check_gd_scripts_headless.ps1	pass
tools/run_all_tests.ps1	474 tests, ~17k asserts, 0 failed (gdk 330 / playfab 84 / gameinput 60)
C++ doctest (gdk_unit_tests.exe)	pass
13 bootstrap mini-runners	pass
tools/run_csharp_tests.ps1	107 / 107
tools/package_addons.ps1 -Configuration Both -Reconfigure	pass (154 files, 15.44 MiB)
tools/export_samples.ps1	pass, all 4 tutorial tracks
dotnet build × 4 C# tutorial projects	pass
doc_classes ↔ ClassDB parity	47 documented / 48 registered — identical to main's baseline

Live coverage

Live tier was run, with writes enabled, against sandbox PlayFab title 10D176:

pwsh -File tools/run_all_tests.ps1 -Live -AllowLiveWrites `
  -PlayFabTitleId "10D176" -PlayFabCustomId "godot-gdk-ext-live-smoke" `
  -PlayFabMatchmakingQueue "godot_gdk_ext_live_smoke_queue"

Every stage passed except the PlayFab Multiplayer orchestrator (46 / 61 scenarios). These failures are not caused by this PR:

• tests/godot/mp_orchestrator/ is byte-identical to main on this branch (git diff public/main...HEAD -- tests/godot/mp_orchestrator is empty) and contains zero GDK* / Xbox* type references.
• All 15 failures are confined to PlayFab Lobby / Party / Match surfaces, which this rename does not touch.
• The orchestrator is known-flaky against live services. Two back-to-back runs produced 15 and 14 failures respectively, overlapping on 14.

Version matrix

Only Godot 4.6.2 is installed on this machine, so the 4.5.x (gut-4.5) and 4.7.x legs are deferred to the CI PR gates.

Migration for consumers

1. Read docs/gdk/migration-v0.3.md.
2. Run tools/migrate_gdk_to_xbox.ps1 -WhatIf, review, then apply.
3. Grep for any remaining is_class("GDK") / get_class() == "GDK" string comparisons — those must become "Xbox".

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of files (300). Try reducing the number of changed files and requesting a review from Copilot again.