This document describes the current public GDScript API surface of the
godot_gdk addon. It is built from the actual bound methods and signals in
the native implementation.
For architecture details, see Native Runtime and Async System.
GDK is the only engine singleton registered by the addon. All services are
accessed as namespaces under this root.
| Method | Returns | Description |
|---|---|---|
initialize(config := null) |
XboxResult |
Start the Microsoft GDK runtime. See Initialization config. Re-initializing returns already_initialized; guard repeated startup with GDK.is_initialized(). |
shutdown() |
void |
Clean up the runtime |
is_available() |
bool |
Whether this build was compiled with _GAMING_DESKTOP support |
is_initialized() |
bool |
Whether the runtime has been initialized |
dispatch() |
int |
Pump async completions and manager state manually when gdk/runtime/embed_dispatch is disabled or when deterministic control is needed |
get_users() |
XboxUsers |
Access the users service |
get_game_ui() |
XboxGameUI |
Access the system UI service |
get_accessibility() |
XboxAccessibility |
Access the accessibility service |
get_achievements() |
XboxAchievements |
Access the achievements service |
get_package() |
XboxPackage |
Access package metadata and DLC content-loading helpers |
get_stats() |
XboxStats |
Access the XBOX Services statistics service |
get_leaderboards() |
XboxLeaderboards |
Access the XBOX Services leaderboard service |
get_privacy() |
XboxPrivacy |
Access the XBOX Services privacy service |
get_presence() |
XboxPresence |
Access the presence service |
get_social() |
XboxSocial |
Access the social graph service |
get_store() |
XboxStore |
Access the XStore commerce service |
get_profile() |
XboxProfile |
Access the XBOX Services profile service |
get_string_verify() |
XboxStringVerify |
Access the XBOX Services string verification service |
get_title_storage() |
XboxTitleStorage |
Access the XBOX Services Title Storage service |
get_error_reporting() |
XboxErrorReporting |
Access the Microsoft GDK XError callback/options service |
get_launcher() |
XboxLauncher |
Access the launcher service for URI/store/settings flows |
get_multiplayer_activity() |
XboxMultiplayerActivity |
Access the multiplayer activity service |
get_capture() |
XboxCapture |
Access the capture metadata and capture-state service |
get_system() |
XboxSystem |
Access title/runtime metadata and environment facts |
get_display() |
XboxDisplay |
Access HDR mode probing and display timeout deferrals |
get_activation() |
XboxActivation |
Access game activation events (protocol/file/invite launches) |
get_networking() |
XboxNetworking |
Access XNetworking.h port, connectivity, NSAL, and TCP buffer surfaces |
| Signal | Description |
|---|---|
initialized() |
Runtime initialized successfully |
shutdown_completed() |
Runtime shutdown complete |
runtime_error(result: XboxResult) |
An XError callback reported a runtime-wide error. Reserved for the global X-error bridge — caller-driven failures are returned as the per-call XboxResult and per-service unsolicited errors are emitted on GDK.<service>.runtime_error (e.g. GDK.social.runtime_error, GDK.achievements.runtime_error). |
func _ready():
GDK.initialize()
func _exit_tree():
GDK.shutdown()By default the addon pumps completions automatically each process frame through
gdk/runtime/embed_dispatch.
If you disable that setting, call dispatch() manually:
func _process(_delta):
GDK.dispatch()When config is a Dictionary, the XBOX services bootstrap accepts the first
matching SCID override it finds in this order:
config["scid"]config["service_configuration_id"]config["XBOX_live/scid"]config["xbox_live"]["scid"]
If no override is supplied, the addon derives the default SCID from
XGameGetXboxTitleId() as the current-title SCID. Calling initialize() again
while the runtime is still active returns XboxResult.code == "already_initialized",
so repeated startup paths should guard with GDK.is_initialized().
if not GDK.is_initialized():
var init_result: XboxResult = GDK.initialize({
"xbox_live": {
"scid": "00000000-0000-0000-0000-00001234ABCD"
}
})
if not init_result.ok:
push_error(init_result.code)Before wiring service calls, gather your title-owned stat names, leaderboard identifiers, presence string IDs, Store IDs, DLC pack paths, sandbox IDs, and peer test-account XUIDs from the checklist in Sample setup.
GDK.system is a RefCounted service object returned by GDK.get_system().
| Method | Returns | Description |
|---|---|---|
get_title_id() |
XboxResult |
Read the current XBOX title ID (data is int) |
get_title_id_hex() |
XboxResult |
Read the current XBOX title ID as uppercase 0x-prefixed hex (data is String) |
get_sandbox_id() |
XboxResult |
Read the current sandbox ID (data is String) |
get_service_configuration_id() |
XboxResult |
Read the current SCID from the shared XBOX services scaffold (data is String) |
is_xbox_services_initialized() |
bool |
Check whether the shared XBOX services scaffold is initialized |
is_feature_available(name) |
bool |
Check whether an optional GDK runtime feature is available (XGameRuntimeIsFeatureAvailable). name is a case-insensitive feature id such as "XAccessibility", "XGameUI", "XGameSave", or "XGameStreaming". Unknown names push a warning and return false. |
is_handheld() |
bool |
Whether Windows identifies the device as a gaming handheld. Does not require GDK.initialize(). |
var title_result: XboxResult = GDK.system.get_title_id()
if title_result.ok:
print("Title ID:", title_result.data)
var sandbox_result: XboxResult = GDK.system.get_sandbox_id()
if sandbox_result.ok:
print("Sandbox:", sandbox_result.data)GDK.users is a RefCounted service object returned by GDK.get_users().
| Method | Returns | Description |
|---|---|---|
add_default_user_async() |
Signal |
Silent XBOX sign-in for a non-guest user |
add_user_with_ui_async(allow_guests := false) |
Signal |
Interactive XBOX sign-in. Requires the advanced user model; under the simplified (PC-default) user model the native call returns a failed XboxResult (E_INVALIDARG), so PC titles should use the silent add_default_user_async(). By default resolves the launching default user with the system sign-in UI; pass allow_guests = true to open the guest-capable account picker. It does not replace the session primary user. When the platform reports cancellation, the result resolves with a failed XboxResult whose code is cancelled. |
add_user_by_id_with_ui_async(xuid) |
Signal |
Re-establish one specific account by decimal XUID, showing UI only if that account needs attention. Use this on resume instead of a blind account picker. |
get_primary_user() |
XboxUser |
Current primary user (or null) |
get_users() |
Array |
All local users |
get_max_users() |
XboxResult |
Maximum simultaneous local users on this platform; data is an int |
is_sign_out_available() |
bool |
Whether this platform supports title-initiated sign-out. Check before sign_out_async(). |
sign_out_async(user) |
Signal |
Sign user out. On success the user is already removed from get_users() and user_changed has fired once with removed. Fails with sign_out_not_available when is_sign_out_available() is false. |
acquire_sign_out_deferral() |
XboxResult |
Acquire an XboxUserSignOutDeferral (in data) to delay a pending sign-out while flushing per-user state |
find_user_by_xuid(xuid) |
XboxResult |
Non-prompting lookup of a signed-in user by decimal XUID; data is an XboxUser |
find_user_by_local_id(local_id) |
XboxResult |
Non-prompting lookup by local user ID; data is an XboxUser |
find_user_for_device(device_id) |
XboxResult |
The user currently paired with device_id; data is an XboxUser |
find_controller_for_user_with_ui_async(user) |
Signal |
Open the system controller-selection dialog for user. Success data contains device_id and has_device. Required by XR-112 when a user has no assigned controller. |
get_device_associations() |
Array |
Current user/device pairings as {device_id, user_local_id} dictionaries |
get_devices_for_user(user) |
PackedStringArray |
Device IDs currently paired with user |
get_default_audio_endpoint(user, kind := XboxUsers.AUDIO_ENDPOINT_KIND_COMMUNICATION_RENDER) |
XboxResult |
The user's default communication audio endpoint; success data contains kind and endpoint_id |
check_privilege_async(user, privilege) |
Signal |
Check user privilege |
resolve_privilege_with_ui_async(user, privilege) |
Signal |
Resolve privilege with UI |
resolve_issue_with_ui_async(user, url) |
Signal |
Resolve account issue with UI |
get_gamer_picture_async(user, size) |
Signal |
Fetch user's profile picture |
get_token_and_signature_async(user, method, url, headers, body, force_refresh) |
Signal |
Get XBOX Live auth token |
Device IDs are the 64-character lowercase hex encoding of the platform's
APP_LOCAL_DEVICE_ID. The same string is used by get_device_associations(),
get_devices_for_user(), find_user_for_device(),
find_controller_for_user_with_ui_async(), and the
device_association_changed signal.
| Signal | Description |
|---|---|
user_changed(user: XboxUser, change_kind: String) |
The single user lifecycle/state event. change_kind is added, removed, signed_in_again, gamertag, gamer_picture, or privileges; for removed, user identifies the removed user and is no longer present in get_users() |
device_association_changed(device_id: String, old_user_local_id: int, new_user_local_id: int) |
The platform re-paired a device (typically a controller) with a different user. Also fires once per existing pairing at startup. A local ID of 0 means "no user"; resolve non-zero IDs with find_user_by_local_id(). |
default_audio_endpoint_changed(user_local_id: int, kind: int, endpoint_id: String) |
A user's default communication audio endpoint changed. endpoint_id is empty when the endpoint was removed. |
XR-112 requires titles to establish an active user and a controller for that user on first activation, and to re-validate both when resuming from suspend or constrained mode. The service exposes everything that requires, but deliberately does not act on the title's behalf — XR-112 permits several valid reactions (resume the player, remove the player, show the picker) and the right one is game-design dependent.
func _establish_user_and_controller() -> void:
var result: XboxResult = await GDK.users.add_default_user_async()
if not result.ok:
# No default user: the advanced user model can fall back to the picker.
result = await GDK.users.add_user_with_ui_async(true)
if not result.ok:
_warn_progress_will_not_be_saved()
return
var user: XboxUser = result.data
_show_gamertag(user.gamertag) # XR-112: show who is playing before profile actions
# XR-112: the user must have a controller before gameplay input is accepted.
if GDK.users.get_devices_for_user(user).is_empty():
await GDK.users.find_controller_for_user_with_ui_async(user)
func _on_resumed(previous_xuid: String) -> void:
var found: XboxResult = GDK.users.find_user_by_xuid(previous_xuid)
if not found.ok:
# The expected player signed out while suspended: re-establish or drop them.
found = await GDK.users.add_user_by_id_with_ui_async(previous_xuid)
if not found.ok:
_remove_player()
return
var user: XboxUser = found.data
if GDK.users.get_devices_for_user(user).is_empty():
await GDK.users.find_controller_for_user_with_ui_async(user)check_privilege_async() passes the raw integer you supply directly to
XUserCheckPrivilege(), and resolve_privilege_with_ui_async() forwards it to
XUserResolvePrivilegeWithUiAsync(). The addon does not bind named privilege
constants.
Successful check_privilege_async() payloads use these keys:
| Key | Type | Meaning |
|---|---|---|
privilege |
int |
Echo of the requested privilege id |
has_privilege |
bool |
Whether the user currently has the privilege |
deny_reason |
String |
none, purchase_required, restricted, banned, or unknown |
deny_reason_value |
int |
Raw native XUserPrivilegeDenyReason integer |
needs_user_issue_resolution |
bool |
true when the check returned user_issue_resolution_required |
Successful resolve_privilege_with_ui_async() payloads currently echo only
privilege.
func _ready():
GDK.users.user_changed.connect(_on_user_changed)
var result = await GDK.users.add_default_user_async()
if result.ok:
print("Signed in: ", result.data.gamertag)
func _on_user_changed(user: XboxUser, change_kind: String):
print("User %s: %s" % [change_kind, user.gamertag])GDK.game_ui is a RefCounted service object returned by GDK.get_game_ui().
| Method | Returns | Description |
|---|---|---|
show_message_dialog_async(title, message, first_button, second_button, third_button, default_button, cancel_button) |
Signal |
Show a system message dialog; success data includes selected_button and selected_button_index |
set_notification_position_hint(position) |
XboxResult |
Set the notification position hint (bottom_center, bottom_left, bottom_right, top_center, top_left, top_right) |
show_player_profile_card_async(requesting_user, target_xuid) |
Signal |
Show the profile card UI for a target XUID |
show_player_picker_async(requesting_user, prompt, selectable_xuids, preselected_xuids, min_selection_count, max_selection_count) |
Signal |
Show player picker UI; success data includes selected_xuids and selection_count |
resolve_privilege_with_ui_async(user, privilege) |
Signal |
Forward to users-service privilege remediation UI flow |
show_achievements_async(requesting_user) |
Signal |
Show the system achievements UI for the current title |
show_error_dialog_async(error_code, context) |
Signal |
Show the system error dialog for an HRESULT error_code with optional context text |
show_send_game_invite_async(requesting_user, session_configuration_id, session_template_name, session_id, invitation_text, custom_activation_context) |
Signal |
Show the system send-game-invite UI for a multiplayer session |
show_text_entry_async(title_text, description_text, default_text, input_scope, max_text_length) |
Signal |
Show the virtual-keyboard text entry UI; success data includes text |
show_virtual_keyboard() |
XboxResult |
Best-effort request to show the Windows gamepad keyboard for the focused Godot text control; success data is whether Windows accepted the request. Does not require GDK.initialize(). |
hide_virtual_keyboard() |
XboxResult |
Best-effort request to dismiss the Windows virtual keyboard; success data is whether Windows accepted the request. Does not require GDK.initialize(). |
show_text_entry_async() and show_virtual_keyboard() serve different input
models. The former opens the GDK system text-entry UI and returns a complete
string. The latter leaves the focused LineEdit or TextEdit in place and
asks Windows to route virtual-keyboard input to it. Windows can validly decline
the best-effort request when the game is not foreground or a hardware keyboard
is available.
| Signal | Description |
|---|---|
virtual_keyboard_showing |
Fires before Windows shows the current view's primary input pane. Does not require GDK.initialize(). |
virtual_keyboard_hiding |
Fires before Windows hides the current view's primary input pane. Does not require GDK.initialize(). |
These signals map to CoreInputView.PrimaryViewShowing and
PrimaryViewHiding, available on Windows 10 version 2004 and later. They
describe the start of a pane transition; they do not guarantee that Windows
will complete it or that a prior best-effort show/hide request was accepted.
default_button and cancel_button accept first/0, second/1, or
third/2. Validation failures return invalid_title, invalid_message,
invalid_button_label, invalid_default_button, invalid_cancel_button, or
invalid_button_layout.
Script-visible wrapper around a local XBOX user.
| Property | Type | Description |
|---|---|---|
local_id |
int |
Local user ID |
xuid |
String |
XBOX User ID |
gamertag |
String |
Display name (the Classic gamertag component) |
modern_gamertag |
String |
Modern gamertag component, without the numeric suffix. Empty when the platform or account does not expose it. |
modern_gamertag_suffix |
String |
Numeric suffix of the modern gamertag (for example #1234). Empty when unused. |
unique_modern_gamertag |
String |
Modern gamertag combined with its suffix — the preferred display string. Empty when unavailable. |
age_group |
XboxUser.AgeGroup |
Age group enum |
sign_in_state |
XboxUser.SignInState |
Sign-in state enum |
guest |
bool |
Whether the user is a guest |
signed_in |
bool |
Whether the user is signed in |
store_user |
bool |
Whether the user is a store user |
| Method | Returns | Description |
|---|---|---|
get_age_group_name() |
String |
Age group as human-readable string |
get_sign_in_state_name() |
String |
Sign-in state as human-readable string |
is_valid() |
bool |
Whether this wrapper still holds a live native user handle |
is_same_user(other) |
bool |
Whether other refers to the same underlying account, even if it is a different wrapper instance |
duplicate_user() |
XboxUser |
An independently owned copy of this user, or null on failure. Use when a user must outlive the service cache. |
RefCounted handle returned in XboxResult.data by
GDK.users.acquire_sign_out_deferral(). While it is held, the platform delays a
pending sign-out so the title can flush per-user state. Release it as soon as
that work completes — the handle is also released automatically when the object
is freed.
| Method | Returns | Description |
|---|---|---|
is_valid() |
bool |
Whether the deferral is still held |
release() |
void |
Release the deferral. Safe to call more than once, and safe after GDK.shutdown(). |
var deferral_result: XboxResult = GDK.users.acquire_sign_out_deferral()
if deferral_result.ok:
var deferral: XboxUserSignOutDeferral = deferral_result.data
await _flush_save_data()
deferral.release()GDK.accessibility is a RefCounted service object returned by GDK.get_accessibility().
| Method | Returns | Description |
|---|---|---|
query_closed_caption_properties() |
XboxResult |
Query closed-caption properties from XClosedCaptionGetProperties; on success result.data is XboxClosedCaptionProperties |
set_closed_caption_enabled(enabled) |
XboxResult |
Set caption-enabled state using XClosedCaptionSetEnabled |
query_high_contrast_mode() |
XboxResult |
Query current high-contrast mode from XHighContrastGetMode; on success result.data includes mode and mode_name |
get_high_contrast_mode_name(mode) |
String |
Convert XboxAccessibility.HighContrastMode to snake_case name |
- These wrappers are scoped to concrete PC-supported APIs documented under
XAccessibility.h. - Speech-to-text overlay APIs are intentionally excluded from this first deterministic accessibility surface.
Script-visible wrapper around the native XClosedCaptionProperties payload.
| Property | Type | Description |
|---|---|---|
background_color |
Color |
Caption background color |
font_color |
Color |
Caption font color |
window_color |
Color |
Caption window color |
font_edge_attribute |
XboxClosedCaptionProperties.FontEdgeAttribute |
Caption edge style |
font_style |
XboxClosedCaptionProperties.FontStyle |
Caption font style |
font_scale |
float |
Caption font scale |
enabled |
bool |
Whether captions are enabled |
GDK.achievements is a RefCounted service object returned by
GDK.get_achievements(). It uses the Achievements Manager pattern
with direct-await completion signals.
| Method | Returns | Description |
|---|---|---|
query_player_achievements_async(user) |
Signal |
Query achievements for a user |
update_achievement_async(user, achievement_id, percent_complete) |
Signal |
Update achievement progress |
get_cached_achievements(user) |
Array |
Get cached achievement list |
get_achievements_by_state(user, progress_state) |
XboxResult |
Filter the cached achievements by progress state ("Achieved", "NotStarted", "InProgress", "Unknown"; case-insensitive). data.achievements is an Array of XboxAchievement. Returns achievements_not_loaded until query_player_achievements_async() has warmed the cache for user. |
| Signal | Description |
|---|---|
achievement_unlocked(user: XboxUser, achievement_id: String) |
An achievement was unlocked |
achievements_updated(user: XboxUser) |
Achievement cache was updated |
runtime_error(result: XboxResult) |
An unsolicited achievement-service error occurred (background failure with no per-call response). Caller-driven errors are returned as the per-call XboxResult from each method. |
# Query achievements
var result = await GDK.achievements.query_player_achievements_async(user)
if result.ok:
for achievement in GDK.achievements.get_cached_achievements(user):
print(achievement.name, ": ", achievement.progress_percent, "%")
# Update progress (25% increments)
await GDK.achievements.update_achievement_async(user, "1", 25)Script-visible wrapper around a cached achievement.
| Property | Type | Description |
|---|---|---|
id |
String |
Achievement identifier |
name |
String |
Localized display name |
service_configuration_id |
String |
Service config ID |
progress_state |
String |
Progress state |
progress_percent |
int |
Computed progress (0–100) |
unlocked |
bool |
Whether fully unlocked |
secret |
bool |
Whether hidden until unlocked |
locked_description |
String |
Description shown when locked |
unlocked_description |
String |
Description shown when unlocked |
| Method | Returns | Description |
|---|---|---|
is_unlocked() |
bool |
Whether the achievement is fully unlocked |
is_secret() |
bool |
Whether the achievement is hidden until unlocked |
GDK.package is a RefCounted service object returned by GDK.get_package().
| Method | Returns | Description |
|---|---|---|
enumerate_packages(package_kind := XboxPackage.PACKAGE_KIND_CONTENT, scope := XboxPackage.ENUMERATION_SCOPE_THIS_AND_RELATED) |
XboxResult |
Enumerate installed packages; data is an Array of package dictionaries |
find_package_by_identifier(package_identifier, package_kind := XboxPackage.PACKAGE_KIND_CONTENT, scope := XboxPackage.ENUMERATION_SCOPE_THIS_AND_RELATED) |
XboxResult |
Find one installed package by package identifier |
get_current_process_package_identifier() |
XboxResult |
Resolve package identity for the current process |
mount_package_async(package_identifier) |
Signal |
Mount package content and return XboxPackageMount in XboxResult.data |
load_resource_pack_async(package_identifier, pack_relative_path, replace_files := false, offset := 0) |
Signal |
Mount package content and load package-relative .pck/.zip into res:// |
get_loaded_resource_packs() |
Array |
Return service-owned XboxPackageResourcePack metadata for loaded packs |
get_install_progress(package_identifier) |
XboxResult |
Snapshot install progress for a package identifier |
mount_package_async()is the loose-file path; callers are responsible for closing the returned mount.load_resource_pack_async()is the Godot-native DLC path; mounts for loaded resource packs stay service-owned untilGDK.shutdown().- If shutdown cancels an in-flight package mount/resource-pack load, the completion signal resolves with
XboxResult.code == "cancelled".
enumerate_packages() and find_package_by_identifier() return dictionaries
with these keys:
| Key | Type | Meaning |
|---|---|---|
package_identifier |
String |
Runtime package identifier for follow-up mount/load calls |
store_id |
String |
Store product ID reported by the package metadata |
display_name |
String |
Package display name |
description |
String |
Package description |
publisher |
String |
Package publisher string |
title_id |
String |
Title ID string reported by the package metadata |
installing |
bool |
Whether the package is still installing |
age_restricted |
bool |
Whether the package is age restricted |
kind |
int |
Raw native package-kind value |
kind_name |
String |
game or content |
index |
int |
Package index within the current enumeration result |
count |
int |
Total package count reported for the enumeration result |
The package dictionary tells you which content package to mount. The
pack_relative_path is still title-owned: it must point to a .pck or .zip
inside that mounted package, and the runtime rejects empty paths, absolute
paths, ./.., and other extensions.
var packages_result: XboxResult = GDK.package.enumerate_packages()
if packages_result.ok and not packages_result.data.is_empty():
var package_info: Dictionary = packages_result.data[0]
var load_result: XboxResult = await GDK.package.load_resource_pack_async(
package_info["package_identifier"],
"content/dlc/episode1.pck")
if load_result.ok:
var pack_info: Dictionary = load_result.data
print(pack_info["resource_pack"].pack_path)See Sample setup for the title-owned values you need to supply for DLC/package flows.
GDK.stats is a RefCounted service object returned by GDK.get_stats().
It wraps XBOX Services user statistics reads, title-managed statistic updates,
real-time statistic tracking, and a per-user in-memory cache.
| Method | Returns | Description |
|---|---|---|
query_user_stats_async(user, stat_names := PackedStringArray()) |
Signal |
Query named stats for one local user; success data is a Dictionary keyed by stat name |
query_users_stats_async(user, xuids, stat_names := PackedStringArray()) |
Signal |
Query named stats for multiple target XUIDs using the local user as caller context; success data is keyed by XUID |
get_single_stat_async(user, stat_name) |
Signal |
Read a single named stat for the signed-in user; success data is a Dictionary keyed by stat name (one entry) |
set_stat_integer(user, stat_name, value) |
XboxResult |
Stage an integer title-managed statistic for the user |
set_stat_number(user, stat_name, value) |
XboxResult |
Stage a numeric title-managed statistic for the user |
flush_stats_async(user) |
Signal |
Submit staged title-managed statistics for the user (merge semantics) |
write_stats_async(user, stats) |
Signal |
Replace-all write: the stats Dictionary (name → number) becomes the user's complete title-managed stat document. Non-numeric values are rejected with invalid_stat_value. Live-write surface |
delete_stats_async(user, stat_names) |
Signal |
Delete the named title-managed stats for the user. Live-write surface |
track_stats(user, stat_names) |
XboxResult |
Start tracking real-time changes for named stats |
stop_tracking_stats(user, stat_names := PackedStringArray()) |
XboxResult |
Stop tracking named stats, or all tracked stats for the user when empty |
get_cached_stats(user) |
Dictionary |
Return cached stats for the user keyed by stat name |
| Signal | Description |
|---|---|
stats_updated(user: XboxUser, stats: Dictionary) |
Cached stats changed for a user |
stat_changed(user: XboxUser, stat_name: String, value: Variant) |
A tracked statistic changed |
stats_flushed(user: XboxUser, result: XboxResult) |
Staged statistics finished flushing |
Stat dictionaries are keyed by statistic name. Each value contains name,
type, value, and service_configuration_id. Native statistic values are
returned as strings because XBOX Services user-stat query results expose values
as string payloads.
var query_result = await GDK.stats.query_user_stats_async(user, ["score"])
if query_result.ok:
print(query_result.data["score"]["value"])
GDK.stats.set_stat_number(user, "score", 123.0)
var flush_result = await GDK.stats.flush_stats_async(user)
if flush_result.ok:
print("Stats flushed")GDK.leaderboards is a RefCounted service object returned by
GDK.get_leaderboards(). It wraps read-only XBOX Services leaderboard queries
backed by title-managed statistics.
| Method | Returns | Description |
|---|---|---|
get_leaderboard_async(user, stat_name, max_items := 25) |
Signal |
Query the global leaderboard for a stat |
get_leaderboard_around_user_async(user, stat_name, max_items := 25) |
Signal |
Query the global leaderboard around the local user's XUID |
get_social_leaderboard_async(user, stat_name, max_items := 25) |
Signal |
Query the followed-people social leaderboard for a stat |
get_next_page_async(leaderboard) |
Signal |
Fetch the next page for a returned XboxLeaderboard |
get_cached_leaderboard(stat_name) |
XboxLeaderboard |
Return the cached leaderboard for a stat, or null |
| Signal | Description |
|---|---|
leaderboard_updated(stat_name: String, leaderboard: XboxLeaderboard) |
A leaderboard query or next-page request updated the cache |
| Property | Type | Description |
|---|---|---|
stat_name |
String |
Statistic backing the leaderboard |
query_type |
String |
global, around_user, or social |
total_row_count |
int |
Total rows reported by XBOX Services |
has_next |
bool |
Whether another page can be fetched |
columns |
Array[XboxLeaderboardColumn] |
Column metadata |
rows |
Array[XboxLeaderboardRow] |
Row data |
XboxLeaderboardRow.column_values contains the JSON-encoded column values
returned by XBOX Services.
var result = await GDK.leaderboards.get_leaderboard_async(user, "score", 25)
if result.ok:
var leaderboard: XboxLeaderboard = result.data
for row in leaderboard.rows:
print("%s: %s" % [row.unique_modern_gamertag, row.column_values])
if leaderboard.has_next:
await GDK.leaderboards.get_next_page_async(leaderboard)GDK.privacy is a RefCounted service object returned by
GDK.get_privacy(). It wraps XBOX Services privacy permission checks plus
avoid-list and mute-list reads.
| Method | Returns | Description |
|---|---|---|
check_permission_async(user, permission, target_xuid) |
Signal |
Check whether user has a permission with the target XUID |
check_permission_for_anonymous_user_async(user, permission, anonymous_user_type) |
Signal |
Check whether user has a permission with an anonymous user type |
batch_check_permission_async(user, permission, target_xuids) |
Signal |
Check one permission against multiple target XUIDs |
get_avoid_list_async(user) |
Signal |
Query the avoid list for user; success data is a PackedStringArray of XUID strings |
get_mute_list_async(user) |
Signal |
Query the mute list for user; success data is a PackedStringArray of XUID strings |
Permission check results are dictionaries with allowed, target_xuid,
target_user_type, permission, and reasons. Each deny reason contains
reason, restricted_privilege, and restricted_privacy_setting.
Supported permission strings are normalized case-insensitively and include
communicate_using_text, communicate_using_video,
communicate_using_voice, view_target_profile,
view_target_game_history, view_target_video_history,
view_target_music_history, view_target_exercise_info,
view_target_presence, view_target_video_status,
view_target_music_status, play_multiplayer,
view_target_user_created_content, broadcast_with_twitch,
write_comment, share_item, and
share_target_content_to_external_networks.
Anonymous user type values are cross_network_user and
cross_network_friend. Invalid permission inputs return
XboxResult.code == "invalid_permission"; invalid anonymous-user inputs return
XboxResult.code == "invalid_anonymous_user_type".
var permission_result = await GDK.privacy.check_permission_async(
user,
"communicate_using_voice",
"2814639012345678")
if permission_result.ok and permission_result.data["allowed"]:
print("Voice chat is allowed")
var mute_list_result = await GDK.privacy.get_mute_list_async(user)
if mute_list_result.ok:
print("Muted users: ", mute_list_result.data)GDK.presence is a RefCounted service object returned by GDK.get_presence().
| Method | Returns | Description |
|---|---|---|
set_presence_async(user, state, rich_presence) |
Signal |
Set rich presence for a local user |
clear_presence_async(user) |
Signal |
Clear presence for a local user |
get_presence_async(xuids) |
Signal |
Query presence records for a list of XUIDs |
get_presence_for_social_group_async(user, social_group) |
Signal |
Query presence records for a named social group |
track_presence(user, xuids, title_ids := PackedInt64Array()) |
XboxResult |
Track device/title presence changes for XUIDs and optional title IDs |
stop_tracking_presence(user, xuids := PackedStringArray(), title_ids := PackedInt64Array()) |
XboxResult |
Stop tracking specific XUIDs/title IDs, or all tracked values when arrays are empty |
get_cached_presence(xuid) |
XboxPresenceRecord |
Get a cached presence record by XUID |
Notes:
stateis the configured rich-presence string ID for the title's SCID in Partner Center. It is not arbitrary display text.get_presence_async(xuids)uses the signed-in primary user as its XBOX services caller context, soGDK.users.get_primary_user()must be non-null.get_presence_for_social_group_async(user, social_group)uses the supplied local user as its XBOX Services caller context.
| Signal | Description |
|---|---|
presence_changed(xuid: String, presence: XboxPresenceRecord) |
A cached presence record was updated |
local_presence_set(user: XboxUser) |
Local user presence was set successfully |
device_presence_changed(xuid: String) |
A tracked user's device presence changed |
title_presence_changed(xuid: String, title_id: int) |
A tracked user's title presence changed |
# Set presence
await GDK.presence.set_presence_async(user, "InGame")
# Query presence for a list of XUIDs
var result = await GDK.presence.get_presence_async(["1234567890123456"])
if result.ok:
var record: XboxPresenceRecord = GDK.presence.get_cached_presence("1234567890123456")
if record != null:
print("%s is %s" % [record.xuid, record.get_user_state_name()])
for title in record.title_records:
var title_name = str(title.get("title_name", ""))
var rich_presence = str(title.get("rich_presence_string", ""))
print("%s: %s" % [title_name, rich_presence])Script-visible wrapper around a cached XBOX presence record.
| Property | Type | Description |
|---|---|---|
xuid |
String |
XBOX User ID |
user_state |
XboxPresenceRecord.UserState |
USER_STATE_UNKNOWN, USER_STATE_ONLINE, USER_STATE_AWAY, or USER_STATE_OFFLINE |
title_records |
Array[Dictionary] |
Title/device presence records translated from XBOX Services |
| Method | Returns | Description |
|---|---|---|
is_online() |
bool |
true when user_state is USER_STATE_ONLINE |
get_user_state_name() |
String |
Human-readable state string: unknown, online, away, or offline |
title_records dictionaries can include title_id, title_name,
title_active, rich_presence_string, device_type, device_type_name,
and broadcast fields when XBOX Services reports them.
GDK.social is a RefCounted service object returned by GDK.get_social().
| Method | Returns | Description |
|---|---|---|
start_social_graph(user) |
XboxResult |
Start tracking the social graph for a user |
stop_social_graph(user) |
void |
Stop tracking the social graph for a user |
get_friends_async(user) |
Signal |
Query the default friends group |
create_social_group(user, filter) |
XboxResult |
Create a filtered social group. On success result.data is the XboxSocialGroup; on failure result.ok is false and runtime_error is also emitted on GDK.social. |
create_social_group_from_xuids(user, xuids) |
XboxResult |
Create a social group from explicit XUIDs. On success result.data is the XboxSocialGroup; on failure result.ok is false and runtime_error is also emitted on GDK.social. |
update_social_user_group(group, xuids) |
XboxResult |
Replace the tracked-user list of a list-based XboxSocialGroup (one created via create_social_group_from_xuids). result.data.count is the new tracked-user count. Filter-based groups cannot be updated this way. |
set_rich_presence_polling(user, enabled) |
XboxResult |
Enable or disable Social Manager rich-presence polling for user. result.data.enabled echoes the requested state; the user's social graph is started if needed. |
destroy_social_group(group) |
void |
Destroy a social group |
get_group_users(group) |
XboxResult |
Get the XboxSocialUser list for a group. result.data is always an Array (possibly empty); result.ok is false when the underlying lookup fails. |
submit_reputation_feedback_async(user, target_xuid, feedback_type, reason := "", evidence_id := "") |
Signal |
Submit one reputation feedback item |
submit_batch_reputation_feedback_async(user, feedback_items) |
Signal |
Submit multiple reputation feedback items |
Batch reputation feedback items are dictionaries with target_xuid and
feedback_type, plus optional reason and evidence_id. Supported
feedback_type values are:
fair_play_kills_teammatesfair_play_cheaterfair_play_tamperingfair_play_quitterfair_play_kickedcommunications_inappropriate_videocommunications_abusive_voiceinappropriate_user_generated_contentpositive_skilled_playerpositive_helpful_playerpositive_high_quality_user_generated_contentcomms_phishingcomms_picture_messagecomms_spamcomms_text_messagecomms_voice_messagefair_play_console_ban_requestfair_play_idlerfair_play_user_ban_requestuser_content_gamerpicuser_content_personal_infofair_play_unsportingfair_play_leaderboard_cheater
Validation failures return invalid_feedback_type for unknown feedback types,
invalid_feedback_items for empty batch arrays, invalid_feedback_item when a
batch item is not a dictionary or is missing target_xuid/feedback_type, and
invalid_xuid for malformed XUID strings.
| Signal | Description |
|---|---|
social_graph_changed(user: XboxUser) |
The social graph loaded or changed for a user |
social_group_updated(group: XboxSocialGroup) |
A social group's membership was updated |
social_user_changed(xuid: String, social_user: XboxSocialUser) |
A tracked user's social/presence data changed |
runtime_error(result: XboxResult) |
An unsolicited social-service error occurred (background failure with no per-call response). Caller-driven errors from the public create_social_group* and get_group_users methods are also mirrored here in addition to being returned. |
GDK.social.social_graph_changed.connect(_on_graph_changed)
var result = GDK.social.start_social_graph(user)
if result.ok:
var friends_result = await GDK.social.get_friends_async(user)
if friends_result.ok:
var users_result = GDK.social.get_group_users(friends_result.data)
if users_result.ok:
for friend in users_result.data:
print(friend.gamertag)Script-visible wrapper around a tracked social user.
| Property | Type | Description |
|---|---|---|
xuid |
String |
XBOX User ID |
favorite |
bool |
Whether the user is a favorite of the local user |
friend |
bool |
Whether the user is a friend of the local user |
display_name |
String |
Display name |
real_name |
String |
Real name (if available) |
display_picture_url |
String |
Raw display-picture URL |
gamerscore |
String |
Gamerscore string |
gamertag |
String |
Classic gamertag |
presence |
XboxPresenceRecord |
Current Social Manager presence snapshot |
title_history |
Dictionary |
Title-history fields reported by Social Manager |
preferred_color |
Dictionary |
Preferred color fields reported by Social Manager |
| Method | Returns | Description |
|---|---|---|
is_following_user() |
bool |
Whether the local user follows this user |
is_followed_by_caller() |
bool |
Whether this user is followed by the caller |
uses_avatar() |
bool |
Whether the display picture uses an avatar |
get_modern_gamertag() |
String |
Modern gamertag |
get_modern_gamertag_suffix() |
String |
Modern gamertag suffix |
get_unique_modern_gamertag() |
String |
Modern gamertag including suffix |
Use presence.user_state and presence.title_records for online state,
current-title, and rich-presence details; those are not direct XboxSocialUser
properties.
Script-visible wrapper around a Social Manager group.
| Property | Type | Description |
|---|---|---|
presence_filter |
XboxSocialFilter.PresenceFilter |
Presence filter used to create this group |
relationship_filter |
XboxSocialFilter.RelationshipFilter |
Relationship filter used to create this group |
Namespace for social filter enums.
PresenceFilter
| GDScript constant | Enum value | Description |
|---|---|---|
PRESENCE_FILTER_UNKNOWN |
UNKNOWN |
Unknown |
PRESENCE_FILTER_TITLE_ONLINE |
TITLE_ONLINE |
Users online in the current title |
PRESENCE_FILTER_TITLE_OFFLINE |
TITLE_OFFLINE |
Users offline in the current title |
PRESENCE_FILTER_TITLE_ONLINE_OUTSIDE_TITLE |
TITLE_ONLINE_OUTSIDE_TITLE |
Users online but outside the current title |
PRESENCE_FILTER_ALL_ONLINE |
ALL_ONLINE |
All online users |
PRESENCE_FILTER_ALL_OFFLINE |
ALL_OFFLINE |
All offline users |
PRESENCE_FILTER_ALL_TITLE |
ALL_TITLE |
All users associated with the current title |
PRESENCE_FILTER_ALL |
ALL |
All users regardless of presence or title |
RelationshipFilter
| GDScript constant | Enum value | Description |
|---|---|---|
RELATIONSHIP_FILTER_UNKNOWN |
UNKNOWN |
Unknown |
RELATIONSHIP_FILTER_FRIENDS |
FRIENDS |
Friends only |
RELATIONSHIP_FILTER_FAVORITE |
FAVORITE |
Favorite friends only |
GDK.store is a RefCounted service object returned by GDK.get_store().
It wraps PC-supported XStore commerce APIs and caches the latest
license-acquire result per Store product ID. All operations require a
signed-in XboxUser and an initialized GDK runtime.
| Method | Returns | Description |
|---|---|---|
query_license_status_async(user, store_id) |
Signal |
Query whether user can acquire a license for store_id. Completion XboxResult.data is an XboxStoreLicenseStatus on success. |
refresh_entitlements_async(user, store_id) |
Signal |
Refresh entitlements for store_id by re-querying license-acquire status. |
show_purchase_ui_async(user, store_id) |
Signal |
Show the system purchase UI for store_id. |
show_product_page_ui_async(user, store_id) |
Signal |
Show the system product page UI for store_id. |
show_associated_products_ui_async(user, store_id, product_kinds) |
Signal |
Show the associated-products UI. product_kinds is a comma-separated filter (consumable, durable, game, pass, unmanaged_consumable); empty includes all kinds. |
show_rate_and_review_ui_async(user) |
Signal |
Show the rate-and-review UI; success data includes was_updated. |
show_redeem_token_ui_async(user, token, allowed_store_ids, disallow_csv_redemption) |
Signal |
Show the token-redemption UI for token. allowed_store_ids optionally restricts redeemable products. |
show_gifting_ui_async(user, store_id, name, extended_json) |
Signal |
Show the gifting UI for store_id with optional gifting metadata. |
get_cached_license_status(store_id) |
XboxStoreLicenseStatus |
Returns the cached license status for store_id, or null when no cached value exists. |
check_cached_license_status(store_id) |
XboxResult |
Synchronous cache-only check; returns license_status_not_cached when no cached status exists. |
var result = await GDK.store.query_license_status_async(user, "9NBLGGH4R315")
if result.ok:
var status: XboxStoreLicenseStatus = result.data
print(status.store_id, status.licensable_sku, status.status)Typed wrapper around an XStore license-acquire result.
| Property | Type | Description |
|---|---|---|
store_id |
String |
Store product ID used for the query |
licensable_sku |
String |
SKU value returned by XStore |
status |
int |
Raw XStoreCanAcquireLicenseResult.status value returned by XStoreCanAcquireLicenseForStoreIdResult() |
The addon stores status unchanged from the native XStoreCanAcquireLicenseResult
payload; interpret the integer with the matching Microsoft GDK SDK enum/reference for
your installed SDK version.
GDK.profile is a RefCounted service object returned by GDK.get_profile().
| Method | Returns | Description |
|---|---|---|
get_profile_async(user, xuid) |
Signal |
Query one XBOX profile |
get_profiles_async(user, xuids) |
Signal |
Query XBOX profiles for a list of XUID strings |
get_profiles_for_social_group_async(user, social_group) |
Signal |
Query XBOX profiles for a social group such as People or Favorites |
On success, get_profile_async() returns an XboxResult whose data is a
XboxUserProfile. Batch and social-group queries return an Array of
XboxUserProfile objects.
var result = await GDK.profile.get_profile_async(user, target_xuid)
if result.ok:
var profile: XboxUserProfile = result.data
print(profile.unique_modern_gamertag)Script-visible wrapper around an XBOX Services profile record.
| Property | Type | Description |
|---|---|---|
xuid |
String |
XBOX User ID |
app_display_name |
String |
Application display name |
app_display_picture_resize_uri |
String |
Application display picture resize URI |
game_display_name |
String |
Game display name |
game_display_picture_resize_uri |
String |
Game display picture resize URI |
gamerscore |
String |
Gamer score string |
gamertag |
String |
Classic gamertag |
modern_gamertag |
String |
Modern gamertag |
modern_gamertag_suffix |
String |
Modern gamertag suffix, if present |
unique_modern_gamertag |
String |
Unique modern gamertag and suffix |
GDK.string_verify is a RefCounted service object returned by
GDK.get_string_verify().
| Method | Returns | Description |
|---|---|---|
verify_string_async(user, text) |
Signal |
Verify one string for XBOX Live acceptability |
verify_strings_async(user, strings) |
Signal |
Verify multiple strings for XBOX Live acceptability |
On success, verify_string_async() returns an XboxResult whose data is a
dictionary with:
| Key | Type | Description |
|---|---|---|
result_code |
String |
success, offensive, too_long, or unknown_error |
acceptable |
bool |
Whether the service accepted the string |
first_offending_substring |
String |
First offending substring when available |
verify_strings_async() returns an Array of the same dictionaries.
var result = await GDK.string_verify.verify_string_async(user, player_name)
if result.ok and not result.data.acceptable:
push_warning("Rejected text: %s" % result.data.result_code)GDK.title_storage is a RefCounted service object returned by
GDK.get_title_storage(). This wraps XBOX Services Title Storage from
title_storage_c.h; it is unrelated to PlayFab Game Saves or Microsoft GDK
XGameSaveFiles.
| Method | Returns | Description |
|---|---|---|
get_quota_async(user, storage_type) |
Signal |
Query quota for trusted_platform, global, or universal storage |
list_blob_metadata_async(user, storage_type, blob_path := "", skip_items := 0, max_items := 25) |
Signal |
List blob metadata and return a paged result |
get_next_blob_metadata_async(result) |
Signal |
Fetch the next metadata page |
download_blob_async(user, storage_type, blob_path) |
Signal |
Download a blob by first querying its metadata |
upload_blob_async(user, storage_type, blob_path, data, display_name := "", e_tag := "", match_condition := "not_used") |
Signal |
Upload bytes using binary blob metadata |
delete_blob_async(user, storage_type, blob_path, e_tag := "", match_condition := "not_used") |
Signal |
Delete a binary blob; match_condition supports not_used and if_match |
Quota results return a dictionary with storage_type, used_bytes, and
quota_bytes. Download results return a dictionary with metadata and data.
Upload results return an XboxTitleStorageBlobMetadata.
var list_result = await GDK.title_storage.list_blob_metadata_async(
user, "universal", "saves", 0, 25)
if list_result.ok:
var page: XboxTitleStorageBlobMetadataResult = list_result.data
for metadata: XboxTitleStorageBlobMetadata in page.items:
print(metadata.blob_path, " -> ", metadata.length)Script-visible wrapper around Title Storage blob metadata.
| Property | Type | Description |
|---|---|---|
blob_path |
String |
Blob path |
blob_type |
String |
binary, json, config, or unknown |
storage_type |
String |
trusted_platform, global, universal, or unknown |
display_name |
String |
Friendly display name |
e_tag |
String |
Service ETag |
client_timestamp |
int |
Client timestamp |
length |
int |
Blob length in bytes |
service_configuration_id |
String |
SCID |
xuid |
String |
Owning XUID when present |
Paged Title Storage metadata result. Keep the object alive while requesting additional pages.
| Property | Type | Description |
|---|---|---|
items |
Array |
XboxTitleStorageBlobMetadata items |
has_next |
bool |
Whether another page can be fetched |
storage_type |
String |
Storage type for the query |
blob_path |
String |
Blob path prefix for the query |
GDK.error_reporting is a RefCounted service object returned by
GDK.get_error_reporting().
This service wraps the public Microsoft GDK XError callback/options APIs
(XErrorSetCallback, XErrorSetOptions). It does not submit reports to
external endpoints.
| Method | Returns | Description |
|---|---|---|
configure_options(debugger_present_options := XboxErrorReporting.ERROR_OPTIONS_NONE, debugger_not_present_options := XboxErrorReporting.ERROR_OPTIONS_NONE) |
XboxResult |
Configure XError behavior using XboxErrorReporting.ErrorOptions enum flags (bitwise OR supported) |
set_callback_enabled(enabled) |
XboxResult |
Enable/disable forwarding from XError callback into Godot signals |
is_callback_enabled() |
bool |
Whether callback forwarding is currently enabled |
| Value | Description |
|---|---|
ERROR_OPTIONS_NONE (0) |
No special error behavior options |
ERROR_OPTIONS_OUTPUT_DEBUG_STRING_ON_ERROR (1) |
Request OutputDebugString behavior when an error occurs |
ERROR_OPTIONS_DEBUG_BREAK_ON_ERROR (2) |
Request debug-break behavior when an error occurs |
ERROR_OPTIONS_FAIL_FAST_ON_ERROR (4) |
Request fail-fast behavior when an error occurs |
| Signal | Description |
|---|---|
error_reported(result: XboxResult) |
Emitted when XError callback reports an error; also mirrored through GDK.runtime_error(result) |
Privacy note: if your title attaches metadata to downstream telemetry based on callback events, your title owns privacy/compliance review for that metadata.
GDK.multiplayer_activity is a RefCounted service object returned by
GDK.get_multiplayer_activity().
| Method | Returns | Description |
|---|---|---|
set_activity_async(user, connection_string, join_restriction, max_players, current_players, group_id, allow_cross_platform_join) |
Signal |
Set the current multiplayer activity for a user |
get_activities_async(user, xuids) |
Signal |
Fetch activities for a list of XUIDs |
get_cached_activity(xuid) |
XboxMultiplayerActivityInfo |
Get a cached activity by XUID (or null) |
delete_activity_async(user) |
Signal |
Delete the current user's activity |
send_invites_async(user, xuids, allow_cross_platform_join, connection_string) |
Signal |
Send invites to the given XUIDs |
show_invite_ui_async(user) |
Signal |
Show the system invite UI |
update_recent_players(user, xuids, encounter_type) |
XboxResult |
Record recent-player encounters |
flush_recent_players_async(user) |
Signal |
Flush pending recent-player records |
accept_pending_invite(invite_uri) |
XboxResult |
Parse and accept a pending invite URI |
| Signal | Description |
|---|---|
activities_updated(xuids: PackedStringArray) |
One or more activities were updated in the cache |
pending_invite_received(invite: Dictionary) |
A pending invite was received at startup |
invite_accepted(invite: Dictionary) |
The user accepted a multiplayer invite |
Invite dictionaries match GDK.activation and include raw_uri, activation_type, scheme, action, and decoded query fields such as sender_xuid.
send_invites_async() resolves its connection string in this order:
- Use the explicit
connection_stringargument when it is non-empty. - Otherwise reuse the cached local activity connection string set by
set_activity_async(). - If neither path yields a non-empty value, the call fails with
XboxResult.code == "missing_connection_string".
var mpa = GDK.multiplayer_activity
# Set your activity first so empty-string invites can reuse the cached
# connection string for this local user.
var set_result: XboxResult = await mpa.set_activity_async(
user,
"myserver://connect?session=abc",
"followed",
4,
1)
if set_result.ok:
await mpa.send_invites_async(user, PackedStringArray([other_xuid]))
# You can also pass an explicit connection string without caching one first.
await mpa.send_invites_async(
user,
PackedStringArray([other_xuid]),
true,
"myserver://connect?session=override")
# Fetch another player's activity
var result = await mpa.get_activities_async(user, [other_xuid])
if result.ok:
var info = mpa.get_cached_activity(other_xuid)
print(info.get_connection_string())
# React to accepted invites
mpa.invite_accepted.connect(func(invite):
get_tree().change_scene_to_file("res://multiplayer.tscn")
# use invite["connection_string"] to connect
)Script-visible wrapper around a cached multiplayer activity snapshot.
| Method | Returns | Description |
|---|---|---|
get_xuid() |
String |
XUID of the player this activity belongs to |
get_connection_string() |
String |
Connection string for joining the session |
get_join_restriction() |
String |
Join restriction ("public", "followed", "invite_only") |
get_max_players() |
int |
Maximum players in the session |
get_current_players() |
int |
Current player count |
get_group_id() |
String |
Optional group identifier |
get_platform() |
String |
Platform the activity was set from |
GDK.capture is a RefCounted service object returned by GDK.get_capture().
| Method | Returns | Description |
|---|---|---|
enable_capture() |
XboxResult |
Re-enable Game Bar capture for this title after a previous disable_capture() call |
disable_capture() |
XboxResult |
Disable Game Bar capture for this title |
record_diagnostic_clip_async(duration: float) |
Signal |
Record a diagnostic video clip of the given duration in seconds and return a deferred completion signal. Requires Game Bar. |
take_diagnostic_screenshot_async(path_hint: String) |
Signal |
Take a diagnostic screenshot and return a deferred completion signal. Requires Game Bar. |
create_metadata(reserved_bytes := 0) |
XboxCaptureMetaData |
Create a script-side metadata write context, or null if the runtime is not initialized. reserved_bytes is retained for compatibility and ignored. |
All wrapped APIs are available in _GAMING_DESKTOP builds via XAppCapture.h / xgameruntime.lib.
| Native function | Microsoft GDK |
|---|---|
XAppCaptureEnableRecord |
YES |
XAppCaptureDisableRecord |
YES |
XAppCaptureRecordDiagnosticClip |
YES (Game Bar) |
XAppCaptureTakeDiagnosticScreenshot |
YES (Game Bar) |
XAppCaptureMetadataAddStringEvent |
YES |
XAppCaptureMetadataAddDoubleEvent |
YES |
XAppCaptureMetadataAddInt32Event |
YES |
XAppCaptureMetadataStartStringState |
YES |
XAppCaptureMetadataStartDoubleState |
YES |
XAppCaptureMetadataStartInt32State |
YES |
XAppCaptureMetadataStopAllStates |
YES |
XAppCaptureMetadataRemainingStorageBytesAvailable |
YES |
Excluded (console-only): XAppCaptureOpenLocalStorageFiles, XAppCaptureCloseLocalStorageFilesHandle, XAppCaptureDiagnosticClipLocalId result extraction.
# Annotate capture with metadata
var meta = GDK.capture.create_metadata()
if meta:
meta.start_string_state("zone", "lobby")
meta.add_int32_event("score", 9001)
# ... gameplay ...
meta.stop_all_states()
meta.close()
# Record a short clip (requires Game Bar active)
var result = await GDK.capture.record_diagnostic_clip_async(10.0)
if result.ok:
print("Clip recorded")Script-side write context for the process-wide XAppCaptureMetadata* APIs. Created by GDK.capture.create_metadata().
| Method | Returns | Description |
|---|---|---|
is_valid() |
bool |
Whether the script-side metadata context is open |
close() |
void |
Close the script-side context early (also closed automatically on free) |
stop_all_states() |
XboxResult |
Stop all active persistent metadata states |
get_remaining_storage_bytes() |
int |
Bytes remaining in the local metadata buffer (-1 on error) |
add_string_event(name, value, priority := 0) |
XboxResult |
Write a one-shot string event |
add_double_event(name, value, priority := 0) |
XboxResult |
Write a one-shot double event |
add_int32_event(name, value, priority := 0) |
XboxResult |
Write a one-shot int32 event |
start_string_state(name, value, priority := 0) |
XboxResult |
Begin a persistent string state |
start_double_state(name, value, priority := 0) |
XboxResult |
Begin a persistent double state |
start_int32_state(name, value, priority := 0) |
XboxResult |
Begin a persistent int32 state |
Priority enum
| Value | Description |
|---|---|
PRIORITY_GAMEPLAY (0) |
Standard gameplay-level priority (XAppCaptureMetadataPriority::Informational) |
PRIORITY_IMPORTANT (1) |
Higher-importance priority (XAppCaptureMetadataPriority::Important) |
GDK.launcher is a RefCounted service object returned by GDK.get_launcher().
It wraps PC-supported XLaunchUri flows.
| Method | Returns | Description |
|---|---|---|
launch_uri(uri, user := null) |
XboxResult |
Launch an absolute URI with XLaunchUri |
- Blank or malformed URIs return
invalid_uri. unsupported_launcher_destinationis returned for blocked destinations such asfile:,javascript:,data:, andabout:URIs, and forms-*URIs other thanms-settings:andms-windows-store:.- Unsigned/invalid optional users return
invalid_user.
Launcher success paths depend on host OS URI handlers and package context and are not deterministic for CI. Use a manual smoke pass on a Microsoft GDK machine:
var result = GDK.launcher.launch_uri("ms-settings:privacy-microphone")
print(result.ok, result.code, result.message)Normalized result payload returned by all async operations.
| Field | Type | Description |
|---|---|---|
ok |
bool |
Whether the operation succeeded |
hresult |
int |
Native HRESULT code |
code |
String |
Error code string |
message |
String |
Human-readable error message |
data |
Variant |
Operation payload (e.g., XboxUser, Dictionary, Image) |
GDK.display is a RefCounted service object returned by GDK.get_display(). It
wraps the Microsoft GDK XDisplay.h family: HDR mode probe/enable and idle display
timeout deferrals.
| Method | Returns | Description |
|---|---|---|
try_enable_hdr_mode(preference := HDR_MODE_PREFERENCE_PREFER_HDR) |
XboxResult |
Probe and best-effort enable HDR via XDisplayTryEnableHdrMode |
acquire_timeout_deferral() |
XboxResult |
Acquire an XboxDisplayTimeoutDeferral that suppresses idle display blanking |
| Constant | Value | Description |
|---|---|---|
HDR_MODE_UNKNOWN (0) |
Mode could not be determined | |
HDR_MODE_ENABLED (1) |
Display reports HDR enabled | |
HDR_MODE_DISABLED (2) |
Display reports HDR disabled | |
HDR_MODE_PREFERENCE_PREFER_HDR (0) |
Prefer HDR even if it lowers refresh rate | |
HDR_MODE_PREFERENCE_PREFER_REFRESH_RATE (1) |
Prefer high refresh rate over HDR |
try_enable_hdr_mode success payload (XboxResult.data) is a Dictionary:
| Key | Type | Description |
|---|---|---|
mode |
int |
One of the HDR_MODE_* constants above |
info |
Dictionary |
Present when mode == HDR_MODE_ENABLED. Contains min_tone_map_luminance, max_tone_map_luminance, and max_full_frame_tone_map_luminance (all float). |
acquire_timeout_deferral success payload is an XboxDisplayTimeoutDeferral
ref-counted handle wrapper. Call release() (or drop all references) to release
the deferral and re-enable system idle behavior.
- All methods return
not_initializedwhen called beforeGDK.initialize(). try_enable_hdr_modereturnsinvalid_preferencefor unknown preference values.- Native failures surface as
hdr_mode_failed/acquire_timeout_deferral_failedwith the underlying HRESULT formatted intomessage.
Ref-counted wrapper around an XDisplayTimeoutDeferralHandle.
| Method | Returns | Description |
|---|---|---|
is_valid() |
bool |
true while the underlying handle is open |
release() |
void |
Closes the handle (idempotent); also runs in the destructor |
Construction is internal — instances are produced by
GDK.display.acquire_timeout_deferral().
GDK.activation is a RefCounted service object returned by
GDK.get_activation(). It wraps XGameActivation.h on April 2026+ GDK editions,
and transparently falls back to XGameProtocol.h + XGameInvite.h on October
2025 editions (the backend is selected at compile time via grdk.h's
_GRDK_EDITION). Subscribe to the typed signals to
react to protocol launches, file launches, pending invites, and accepted
invites. GDK.activation owns the single native activation registration;
GDK.multiplayer_activity receives invite events through the same internal
fan-out so both services see the same parsed invite dictionary.
| Method | Returns | Description |
|---|---|---|
accept_pending_invite(invite_uri) |
XboxResult |
Accept a pending invite URI (XGameActivationAcceptPendingInvite, or XGameInviteAcceptPendingInvite on October 2025 editions) |
| Signal | Arguments | Description |
|---|---|---|
protocol_activated |
uri: String |
The title was launched via a protocol URI |
file_activated |
file: String |
The title was launched with a file association |
pending_invite_received |
invite: Dictionary |
A multiplayer invite is pending; pass invite.raw_uri to accept_pending_invite |
invite_accepted |
invite: Dictionary |
An invite was accepted (typically by the system) |
activated |
info: Dictionary |
Catch-all event; info.type is one of ACTIVATION_TYPE_* and includes uri/file/invite_uri matching the typed signal. Invite events also include info.invite. |
| Constant | Value | Description |
|---|---|---|
ACTIVATION_TYPE_PROTOCOL (0) |
Protocol activation | |
ACTIVATION_TYPE_FILE (1) |
File activation | |
ACTIVATION_TYPE_PENDING_GAME_INVITE (2) |
Pending game invite | |
ACTIVATION_TYPE_ACCEPTED_GAME_INVITE (3) |
Accepted game invite |
accept_pending_invitereturnsnot_initializedbeforeGDK.initialize().- Empty or whitespace-only URIs return
invalid_invite_uri. - Native failures surface as
accept_pending_invite_failedwith the underlying HRESULT formatted intomessage. - If activation registration fails on this host (e.g., a partially registered
package), the synchronous
accept_pending_inviteAPI still works; the signal-driven flow simply emits no events. Apush_warningis logged once.
GDK.speech is a RefCounted service object returned by GDK.get_speech(). It
wraps XSpeechSynthesizer.h to turn text or SSML into PCM/WAV audio bytes on the
local device with no network call, which makes it usable for accessibility
narration, prompts, and announcer lines. The service lazily creates a single
native synthesizer the first time a voice is selected or speech is synthesized,
and releases it on GDK.shutdown().
| Method | Returns | Description |
|---|---|---|
get_installed_voices() |
Array |
Installed voices as dictionaries with id, display_name, language, gender ("male"/"female"), and description. Empty before GDK.initialize() |
set_default_voice() |
XboxResult |
Select the platform default voice for subsequent synthesis |
set_custom_voice(voice_id) |
XboxResult |
Select a voice by id; rejects an empty id with invalid_voice_id |
synthesize_text(text) |
XboxResult |
Synthesize plain text; data.audio_wav is a PackedByteArray of RIFF/WAV bytes and data.byte_count is its length |
synthesize_ssml(ssml) |
XboxResult |
Synthesize an SSML document; same payload shape as synthesize_text |
synthesize_to_stream(text) |
AudioStreamWAV |
Convenience helper returning a ready-to-play stream, or null on failure |
- Calls before
GDK.initialize()returnnot_initialized. - Empty
text/ssmlreturnsinvalid_input; an emptyvoice_idreturnsinvalid_voice_id. - If the synthesizer cannot be created on this host, calls return
speech_synthesizer_unavailable.
# Enumerate voices and pick one
var voices: Array = GDK.speech.get_installed_voices()
if voices.size() > 0:
GDK.speech.set_custom_voice(voices[0]["id"])
# Synthesize to raw WAV bytes
var result: XboxResult = GDK.speech.synthesize_text("Welcome to the game.")
if result.ok:
var wav_bytes: PackedByteArray = result.data["audio_wav"]
# ...persist or hand off the WAV bytes...
# Or play immediately through a Godot AudioStreamPlayer
var stream := GDK.speech.synthesize_to_stream("Welcome to the game.")
if stream != null:
$AudioStreamPlayer.stream = stream
$AudioStreamPlayer.play()GDK.events is a RefCounted service object returned by GDK.get_events().
It writes GDK-native in-game telemetry through XGameEventWrite. Events are
batched and uploaded asynchronously by the runtime. This is complementary to
PlayFab analytics (godot_playfab); titles may use either or both.
| Method | Returns | Description |
|---|---|---|
write_event(user, event_name, dimensions, measurements) |
XboxResult |
Write a telemetry event for user. dimensions/measurements are Dictionary payloads serialized to JSON. Success data includes event_name and play_session_id. |
set_play_session_id(play_session_id) |
void |
Set the play-session GUID used to group events. Pass "" to regenerate a fresh GUID. |
get_play_session_id() |
String |
Return the current play-session GUID (auto-generated on first access). |
- The event name and every
dimensions/measurementsfield name must match the title's Xbox Live service-configuration event manifest (case-insensitive). Events whose names do not match are silently dropped by the service. - When the GDK XGameEvent telemetry feature is unavailable in the current
runtime,
write_event()returnsevents_feature_unavailable(HRESULTE_NOTIMPL) without writing.
var user: XboxUser = GDK.users.get_primary_user()
# Tag the play session (optional; a GUID is generated automatically otherwise)
GDK.events.set_play_session_id("") # regenerate, or pass your own id
var result: XboxResult = GDK.events.write_event(
user,
"LevelComplete",
{"level_id": "forest_01", "difficulty": "hard"}, # dimensions
{"score": 1450, "time_seconds": 92.5}) # measurements
if not result.ok:
push_warning("Event not written: %s" % result.code)GDK.game_save is a RefCounted service object returned by
GDK.get_game_save(). It wraps the GDK-native file-style save API
(XGameSaveFiles.h), which is backed by Connected Storage. This is
distinct from PlayFab Game Saves (godot_playfab) and from Xbox Services
Title Storage (GDK.title_storage).
These calls authenticate through Xbox services, so the title must be configured for them:
MicrosoftGame.configcarries theTitleIdandMSAAppIdissued by Partner Center.- The SCID handed to the native API matches the title's SCID in Partner Center (Xbox services → Xbox settings). The addon supplies it from the initialized Xbox services scaffold.
- Connected Storage is enabled for the title in Partner Center. The
option currently lives on the Gameplay settings → Title Storage page,
but it is the only setting on that page that affects Game Saves —
Connected Storage is a separate system from Xbox Services Title Storage
(
GDK.title_storage), so enabling the title/global/universal storage types does nothing forGDK.game_save. - The build runs with registered package identity (
wdapp registeror a packaged build); the per-user store lives under%LOCALAPPDATA%\Packages\<package>\SystemAppData\xgs\.
A mismatch in any of these surfaces as E_GS_NO_ACCESS (0x80830002) from
the native call, which the wrapper propagates verbatim. The
SaveGameStorage element of MicrosoftGame.config is not required here;
it configures the separate no-code cloud-saves feature.
| Method | Returns | Description |
|---|---|---|
get_folder_async(user) |
Signal |
Resolve the user's save folder (may surface a system UI) via XGameSaveFilesGetFolderWithUiAsync. Success data is data.path (absolute folder path). Titles then read/write ordinary files under that folder. |
get_remaining_quota_async(user) |
Signal |
Read the remaining save quota in bytes via XGameSaveFilesGetRemainingQuota. Success data is data.bytes. The native entry point is synchronous and rejects calls from a time-sensitive thread with E_GS_ASYNC_FUNCTION_REQUIRED (0x8083000E), so the wrapper runs it on the shared task queue's work port and completes on the main thread. |
not_initializedwhen the GDK runtime is not yet initialized.invalid_userwhenuseris null or has no underlying handle.xbox_services_uninitializedwhen the shared XBOX services scaffold (SCID) is unavailable.
Neither method exposes a caller-facing cancel API — both return a bare Signal,
and the underlying pending-signal object is engine-internal. Cancellation is
driven by the runtime: GDK.shutdown() cancels every in-flight request and
resolves its awaiter with a cancelled XboxResult, so an await can never hang.
Internally the two differ. get_folder_async() forwards cancellation to
XAsyncCancel. get_remaining_quota_async() does not: it wraps a single
blocking native call that the GDK offers no way to interrupt, so forwarding
would be inert. The awaiter is still resolved as cancelled either way.
var user: XboxUser = GDK.users.get_primary_user()
var folder_result: XboxResult = await GDK.game_save.get_folder_async(user)
if folder_result.ok:
var save_path: String = folder_result.data.path
var f := FileAccess.open(save_path.path_join("save1.dat"), FileAccess.WRITE)
f.store_var({"level": 3, "score": 1450})
f.close()
var quota_result: XboxResult = await GDK.game_save.get_remaining_quota_async(user)
if quota_result.ok:
print("Remaining save quota: %d bytes" % quota_result.data.bytes)GDK.game_chat is a RefCounted service object returned by
GDK.get_game_chat(). It wraps the Game Chat 2 (GameChat2.h) chat_manager
for GDK-native voice and text chat. It is the GDK-native alternative to PlayFab
Party (godot_playfab), which is the batteries-included option that owns its
own transport.
No transport is built or selected. Game Chat encodes its own opaque
audio/text data frames; this wrapper only exposes that surface. While the
manager is pumped each frame (driven automatically by GDK.dispatch()), every
frame Game Chat wants to send is emitted on the outgoing_data_frame signal.
Deliver those bytes over whatever transport your title already has, then call
process_incoming_data_frame() on each receiving instance. The sample and tests
demonstrate this with single-process loopback (feeding each
outgoing_data_frame straight back into process_incoming_data_frame).
Real voice capture and rendering require multi-machine audio hardware and cannot be validated headlessly; headless coverage exercises the service surface, enum constants, lifecycle, and data-frame plumbing.
| Method | Returns | Description |
|---|---|---|
initialize(max_users := 16, default_relationship := RELATIONSHIP_SEND_AND_RECEIVE_ALL) |
XboxResult |
Initialize the chat_manager for max_users combined local + remote users. Errors: not_initialized, already_initialized, invalid_max_users. |
is_initialized() |
bool |
true between a successful initialize() and cleanup(). |
cleanup() |
void |
Release all Game Chat resources (also called on GDK.shutdown). |
add_local_user(user) |
XboxResult |
Add a signed-in XboxUser as a local chat user. Success data is data.xuid. |
add_remote_user(xuid, endpoint_id) |
XboxResult |
Add a remote user by XUID reachable on a title-assigned endpoint_id. Success data is {xuid, endpoint_id}. |
remove_user(xuid) |
XboxResult |
Remove the local or remote user matching xuid. |
set_communication_relationship(local_xuid, target_xuid, relationship) |
XboxResult |
Set the bitwise CommunicationRelationship flags from a local user toward a target. |
set_microphone_muted(local_xuid, muted) |
XboxResult |
Mute/unmute a local user's microphone. |
set_remote_user_muted(local_xuid, target_xuid, muted) |
XboxResult |
Mute/unmute a remote user for a local user. |
set_audio_render_volume(local_xuid, target_xuid, volume) |
XboxResult |
Set the render volume (0.0–1.0) for audio from a remote user. |
send_text(local_xuid, text) |
XboxResult |
Send a 1–1023 character chat text message. |
synthesize_text_to_speech(local_xuid, text) |
XboxResult |
Synthesize text as speech from the local user (when TTS is enabled). |
process_incoming_data_frame(source_endpoint_id, bytes) |
XboxResult |
Hand Game Chat a frame received from a remote endpoint. |
get_chat_users() |
Array |
Snapshot of current users as {xuid, is_local, chat_indicator} dictionaries. |
| Signal | Description |
|---|---|
outgoing_data_frame(target_endpoint_ids, bytes, transport_requirement) |
A frame the title must transmit to each endpoint in target_endpoint_ids. transport_requirement is a TransportRequirement value. |
text_chat_received(sender_xuid, message) |
A text message addressed to one or more local users. |
transcribed_chat_received(speaker_xuid, message) |
A remote speaker's transcribed voice for local users who requested speech-to-text. |
Like PlayFab Party, Game Chat tracks voice and text independently. The
CommunicationRelationship flags carry separate send/receive bits for
microphone audio, text-to-speech audio, and text, and per-user mute/volume is
controlled via set_microphone_muted(), set_remote_user_muted(), and
set_audio_render_volume().
not_initializedbeforeGDK.initialize()(forinitialize()) or beforeGDK.game_chat.initialize()(for every other method).invalid_max_userswhenmax_users <= 0;already_initializedon re-init.invalid_xuid/invalid_userfor empty XUIDs or non-signed-in users;invalid_textfor empty/over-long text;invalid_datafor an empty frame.user_not_found,not_local_user,target_not_found,add_user_failedfor user-lookup and add failures.
GDK.game_chat.initialize()
# Local (signed-in) user plus a remote peer reachable on endpoint 1001.
var me: XboxUser = GDK.users.get_primary_user()
var local := GDK.game_chat.add_local_user(me)
GDK.game_chat.add_remote_user("2814639011419087", 1001)
# Ferry Game Chat's encoded frames over your own networking transport. Game Chat
# hands each outgoing frame to this handler; forward it to the listed endpoints.
GDK.game_chat.outgoing_data_frame.connect(
func(target_endpoint_ids, bytes, transport_requirement):
for endpoint in target_endpoint_ids:
my_transport.send(endpoint, bytes)
)
# On the receiving peer, feed bytes that arrive on your transport back into Game
# Chat (for a single-process loopback test, call this with your own frames):
# GDK.game_chat.process_incoming_data_frame(source_endpoint_id, received_bytes)
GDK.game_chat.text_chat_received.connect(
func(sender_xuid, message): print("%s: %s" % [sender_xuid, message])
)
GDK.game_chat.send_text(local.data.xuid, "hello over game chat")GDK.networking is a RefCounted service object returned by GDK.get_networking().
It wraps the Microsoft GDK XNetworking.h family: the preferred local UDP
multiplayer port, device connectivity hints, Network Security Allow List (NSAL)
information for title endpoints, and the TCP queued-receive-buffer configuration
and statistics surfaces.
| Method | Returns | Description |
|---|---|---|
query_preferred_local_udp_multiplayer_port() |
XboxResult |
Preferred multiplayer UDP port via XNetworkingQueryPreferredLocalUdpMultiplayerPort |
query_preferred_local_udp_multiplayer_port_async() |
Signal |
Same query via XNetworkingQueryPreferredLocalUdpMultiplayerPortAsync; safe on the main thread |
get_connectivity_hint() |
XboxResult |
Current connectivity hint via XNetworkingGetConnectivityHint |
query_security_information_for_url_async(url) |
Signal |
NSAL certificate thumbprints for a registered title endpoint |
query_configuration_setting(setting) |
XboxResult |
Read a TCP queued-receive-buffer setting |
set_configuration_setting(setting, value) |
XboxResult |
Write a TCP queued-receive-buffer setting |
query_statistics(statistics_type) |
XboxResult |
Read TCP queued-receive-buffer usage statistics |
| Signal | Payload | Description |
|---|---|---|
preferred_local_udp_multiplayer_port_changed |
port: int |
The preferred multiplayer UDP port changed; rebind sockets |
connectivity_hint_changed |
hint: Dictionary |
The device connectivity hint changed; same shape as get_connectivity_hint() data |
Both signals also fire once shortly after GDK.initialize(): the GDK delivers an
initial callback on registration, so the first emission carries current state
rather than a change. Like every other GDK callback they arrive on the main
thread during GDK.dispatch().
| Constant | Value | Description |
|---|---|---|
CONNECTIVITY_LEVEL_UNKNOWN |
0 |
Level unknown; also reported before the network is initialized |
CONNECTIVITY_LEVEL_NONE |
1 |
No connectivity |
CONNECTIVITY_LEVEL_LOCAL_ACCESS |
2 |
Local network only, no internet |
CONNECTIVITY_LEVEL_INTERNET_ACCESS |
3 |
Local and internet access |
CONNECTIVITY_LEVEL_CONSTRAINED_INTERNET_ACCESS |
4 |
Captive portal; credentials needed for full access |
CONNECTIVITY_COST_UNKNOWN |
0 |
Cost unknown; also reported before the network is initialized |
CONNECTIVITY_COST_UNRESTRICTED |
1 |
No data limits |
CONNECTIVITY_COST_FIXED |
2 |
Unrestricted up to a cap, then throttled or charged |
CONNECTIVITY_COST_VARIABLE |
3 |
Charged per byte |
THUMBPRINT_TYPE_LEAF |
0 |
Leaf (server) certificate thumbprint |
THUMBPRINT_TYPE_ISSUER |
1 |
Issuing intermediate certificate thumbprint |
THUMBPRINT_TYPE_ROOT |
2 |
Root certificate thumbprint |
CONFIGURATION_SETTING_MAX_TITLE_TCP_QUEUED_RECEIVE_BUFFER_SIZE |
0 |
Max queued received TCP bytes for the title |
CONFIGURATION_SETTING_MAX_SYSTEM_TCP_QUEUED_RECEIVE_BUFFER_SIZE |
1 |
Max queued received TCP bytes for the system |
CONFIGURATION_SETTING_MAX_TOOLS_TCP_QUEUED_RECEIVE_BUFFER_SIZE |
2 |
Max queued received TCP bytes for tools |
STATISTICS_TYPE_TITLE_TCP_QUEUED_RECEIVED_BUFFER_USAGE |
0 |
Queued-receive-buffer usage for title traffic |
STATISTICS_TYPE_SYSTEM_TCP_QUEUED_RECEIVED_BUFFER_USAGE |
1 |
Queued-receive-buffer usage for system traffic |
STATISTICS_TYPE_TOOLS_TCP_QUEUED_RECEIVED_BUFFER_USAGE |
2 |
Queued-receive-buffer usage for tools traffic |
query_preferred_local_udp_multiplayer_port[_async] success payload:
| Key | Type | Description |
|---|---|---|
port |
int |
Preferred UDP port in host byte order (3074 by default) |
get_connectivity_hint success payload (also the connectivity_hint_changed argument):
| Key | Type | Description |
|---|---|---|
connectivity_level |
int |
One of the CONNECTIVITY_LEVEL_* constants |
connectivity_level_name |
String |
unknown, none, local_access, internet_access, or constrained_internet_access |
connectivity_cost |
int |
One of the CONNECTIVITY_COST_* constants |
connectivity_cost_name |
String |
unknown, unrestricted, fixed, or variable |
iana_interface_type |
int |
IANA/NDIS interface type of the active interface |
network_initialized |
bool |
The only authoritative field; gate all networking on it |
approaching_data_limit |
bool |
Nearing a metered-connection data cap |
over_data_limit |
bool |
Past a metered-connection data cap |
roaming |
bool |
Connection is roaming |
query_configuration_setting success payload:
| Key | Type | Description |
|---|---|---|
value |
int |
Setting value. -1 when the native uint64 is UINT64_MAX; any other value above INT64_MAX is clamped to INT64_MAX. Read unlimited rather than testing for -1. |
unlimited |
bool |
true when the native value is UINT64_MAX, which a signed int cannot represent. This is the authoritative flag. |
query_statistics success payload has num_bytes_currently_queued,
peak_num_bytes_ever_queued, total_num_bytes_queued,
num_bytes_dropped_for_exceeding_configured_max, and
num_bytes_dropped_due_to_any_failure (all int).
query_security_information_for_url_async success payload is an
XboxNetworkingSecurityInformation.
query_configuration_setting, set_configuration_setting, and query_statistics
are documented no-ops on Windows: the setter reports E_NOTIMPL (surfaced as
not_supported_on_platform) and the queries report zeros. They are wrapped anyway
so the surface is identical on console-capable Godot forks. Every other method in
this service is fully functional on the PC GDK.
XNetworkingVerifyServerCertificatetakes a WinHTTPHINTERNETrequest handle fromWinHttpOpenRequestand is meant to be called inside aWINHTTP_CALLBACK_STATUS_SENDING_REQUESTcallback. Godot'sHTTPClientandHTTPRequestdo not expose such a handle, so there is no way to call it correctly from GDScript. Read the thumbprints fromXboxNetworkingSecurityInformationand validate in your own native code.XNetworkingQuerySecurityInformationForUrlUtf16Asyncdiffers from the UTF-8 entry point only in input encoding, which is not observable through Godot's singleStringtype.
- All methods return
not_initializedwhen called beforeGDK.initialize(). query_configuration_setting/set_configuration_settingreturninvalid_configuration_settingfor unknown settings;set_configuration_settingreturnsinvalid_configuration_valuefor negative values.query_statisticsreturnsinvalid_statistics_typefor unknown types.query_security_information_for_url_asyncreturnsinvalid_urlfor an empty URL.
Ref-counted wrapper around the native XNetworkingSecurityInformation record. It
owns the native result buffer for its whole lifetime, because the native record's
pointers point into it.
| Method | Returns | Description |
|---|---|---|
get_enabled_http_security_protocol_flags() |
int |
Bitmask of HTTP security protocols enabled for the URL |
get_thumbprints() |
Array |
One Dictionary per thumbprint: type, type_name, bytes (PackedByteArray), hex |
to_dictionary() |
Dictionary |
enabled_http_security_protocol_flags plus thumbprints |
Construction is internal — instances are produced by
GDK.networking.query_security_information_for_url_async().
var init: XboxResult = GDK.initialize()
if not init.is_ok():
push_error(init.message)
return
# Gate networking on network_initialized, not on the level hint.
GDK.networking.connectivity_hint_changed.connect(func(hint: Dictionary) -> void:
if hint["network_initialized"]:
start_matchmaking()
else:
show_offline_banner(hint["connectivity_level_name"])
)
# Rebind when the system changes the preferred multiplayer port.
GDK.networking.preferred_local_udp_multiplayer_port_changed.connect(
func(port: int) -> void: rebind_udp_socket(port)
)
# Prefer the async query on the main thread; the sync overload is documented as
# unsafe on time-sensitive threads.
var port_result: XboxResult = await GDK.networking.query_preferred_local_udp_multiplayer_port_async()
if port_result.is_ok():
rebind_udp_socket(port_result.data["port"])
# Certificate thumbprints for a title endpoint registered in Partner Center.
var security: XboxResult = await GDK.networking.query_security_information_for_url_async("https://api.example.com")
if security.is_ok():
var info: XboxNetworkingSecurityInformation = security.data
for thumbprint in info.get_thumbprints():
print("%s: %s" % [thumbprint["type_name"], thumbprint["hex"]])