Skip to content

Latest commit

 

History

History
1842 lines (1434 loc) · 90.6 KB

api-reference.md

File metadata and controls

1842 lines (1434 loc) · 90.6 KB

Godot Microsoft GDK API reference

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.

Root singleton: GDK

GDK is the only engine singleton registered by the addon. All services are accessed as namespaces under this root.

Methods

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

Signals

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).

Usage

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

Initialization config

When config is a Dictionary, the XBOX services bootstrap accepts the first matching SCID override it finds in this order:

  1. config["scid"]
  2. config["service_configuration_id"]
  3. config["XBOX_live/scid"]
  4. 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.

System service: GDK.system

GDK.system is a RefCounted service object returned by GDK.get_system().

Methods

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().

Usage

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)

Users service: GDK.users

GDK.users is a RefCounted service object returned by GDK.get_users().

Methods

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.

Signals

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: users and controllers on activation and resume

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)

Privilege payloads

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.

Usage

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])

Game UI service: GDK.game_ui

GDK.game_ui is a RefCounted service object returned by GDK.get_game_ui().

Methods

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.

Signals

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.

Validation

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.

XboxUser

Script-visible wrapper around a local XBOX user.

Properties

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

Methods

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.

XboxUserSignOutDeferral

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

Accessibility service: GDK.accessibility

GDK.accessibility is a RefCounted service object returned by GDK.get_accessibility().

Methods

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

Notes

  • 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.

XboxClosedCaptionProperties

Script-visible wrapper around the native XClosedCaptionProperties payload.

Properties

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

Achievements service: GDK.achievements

GDK.achievements is a RefCounted service object returned by GDK.get_achievements(). It uses the Achievements Manager pattern with direct-await completion signals.

Methods

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.

Signals

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.

Usage

# 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)

XboxAchievement

Script-visible wrapper around a cached achievement.

Properties

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

Methods

Method Returns Description
is_unlocked() bool Whether the achievement is fully unlocked
is_secret() bool Whether the achievement is hidden until unlocked

Package service: GDK.package

GDK.package is a RefCounted service object returned by GDK.get_package().

Methods

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

Notes

  • 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 until GDK.shutdown().
  • If shutdown cancels an in-flight package mount/resource-pack load, the completion signal resolves with XboxResult.code == "cancelled".

Package dictionary keys

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

Resource-pack path example

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.

Stats service: GDK.stats

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.

Methods

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

Signals

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

Data shape

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.

Usage

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")

Leaderboards service: GDK.leaderboards

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.

Methods

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

Signals

Signal Description
leaderboard_updated(stat_name: String, leaderboard: XboxLeaderboard) A leaderboard query or next-page request updated the cache

XboxLeaderboard

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.

Usage

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)

Privacy service: GDK.privacy

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.

Methods

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

Data shape

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".

Usage

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)

Presence service: GDK.presence

GDK.presence is a RefCounted service object returned by GDK.get_presence().

Methods

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:

  • state is 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, so GDK.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.

Signals

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

Usage

# 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])

XboxPresenceRecord

Script-visible wrapper around a cached XBOX presence record.

Properties

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

Methods

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.

Social service: GDK.social

GDK.social is a RefCounted service object returned by GDK.get_social().

Methods

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_teammates
  • fair_play_cheater
  • fair_play_tampering
  • fair_play_quitter
  • fair_play_kicked
  • communications_inappropriate_video
  • communications_abusive_voice
  • inappropriate_user_generated_content
  • positive_skilled_player
  • positive_helpful_player
  • positive_high_quality_user_generated_content
  • comms_phishing
  • comms_picture_message
  • comms_spam
  • comms_text_message
  • comms_voice_message
  • fair_play_console_ban_request
  • fair_play_idler
  • fair_play_user_ban_request
  • user_content_gamerpic
  • user_content_personal_info
  • fair_play_unsporting
  • fair_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.

Signals

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.

Usage

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)

XboxSocialUser

Script-visible wrapper around a tracked social user.

Properties

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

Additional getters

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.

XboxSocialGroup

Script-visible wrapper around a Social Manager group.

Properties

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

XboxSocialFilter

Namespace for social filter enums.

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

Store service: GDK.store

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.

Methods

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.

Usage

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)

XboxStoreLicenseStatus

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.

Profile service: GDK.profile

GDK.profile is a RefCounted service object returned by GDK.get_profile().

Methods

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.

Usage

var result = await GDK.profile.get_profile_async(user, target_xuid)
if result.ok:
    var profile: XboxUserProfile = result.data
    print(profile.unique_modern_gamertag)

XboxUserProfile

Script-visible wrapper around an XBOX Services profile record.

Properties

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

String verification service: GDK.string_verify

GDK.string_verify is a RefCounted service object returned by GDK.get_string_verify().

Methods

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.

Usage

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)

Title Storage service: GDK.title_storage

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.

Methods

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.

Usage

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)

XboxTitleStorageBlobMetadata

Script-visible wrapper around Title Storage blob metadata.

Properties

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

XboxTitleStorageBlobMetadataResult

Paged Title Storage metadata result. Keep the object alive while requesting additional pages.

Properties

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

Error reporting service: GDK.error_reporting

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.

Methods

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

ErrorOptions enum

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

Signals

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.

Multiplayer activity service: GDK.multiplayer_activity

GDK.multiplayer_activity is a RefCounted service object returned by GDK.get_multiplayer_activity().

Methods

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

Signals

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.

Invite sequencing

send_invites_async() resolves its connection string in this order:

  1. Use the explicit connection_string argument when it is non-empty.
  2. Otherwise reuse the cached local activity connection string set by set_activity_async().
  3. If neither path yields a non-empty value, the call fails with XboxResult.code == "missing_connection_string".

Usage

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
)

XboxMultiplayerActivityInfo

Script-visible wrapper around a cached multiplayer activity snapshot.

Methods

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

Capture service: GDK.capture

GDK.capture is a RefCounted service object returned by GDK.get_capture().

Methods

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.

Microsoft GDK availability

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.

Usage

# 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")

XboxCaptureMetaData

Script-side write context for the process-wide XAppCaptureMetadata* APIs. Created by GDK.capture.create_metadata().

Methods

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)

Launcher service: GDK.launcher

GDK.launcher is a RefCounted service object returned by GDK.get_launcher(). It wraps PC-supported XLaunchUri flows.

Methods

Method Returns Description
launch_uri(uri, user := null) XboxResult Launch an absolute URI with XLaunchUri

Validation notes

  • Blank or malformed URIs return invalid_uri.
  • unsupported_launcher_destination is returned for blocked destinations such as file:, javascript:, data:, and about: URIs, and for ms-* URIs other than ms-settings: and ms-windows-store:.
  • Unsigned/invalid optional users return invalid_user.

Manual smoke coverage

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)

XboxResult

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)

Display service: GDK.display

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.

Methods

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

Constants

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

Result data

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.

Validation notes

  • All methods return not_initialized when called before GDK.initialize().
  • try_enable_hdr_mode returns invalid_preference for unknown preference values.
  • Native failures surface as hdr_mode_failed / acquire_timeout_deferral_failed with the underlying HRESULT formatted into message.

XboxDisplayTimeoutDeferral

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().

Activation service: GDK.activation

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.

Methods

Method Returns Description
accept_pending_invite(invite_uri) XboxResult Accept a pending invite URI (XGameActivationAcceptPendingInvite, or XGameInviteAcceptPendingInvite on October 2025 editions)

Signals

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.

Constants

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

Validation notes

  • accept_pending_invite returns not_initialized before GDK.initialize().
  • Empty or whitespace-only URIs return invalid_invite_uri.
  • Native failures surface as accept_pending_invite_failed with the underlying HRESULT formatted into message.
  • If activation registration fails on this host (e.g., a partially registered package), the synchronous accept_pending_invite API still works; the signal-driven flow simply emits no events. A push_warning is logged once.

Speech service: GDK.speech

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().

Methods

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

Validation notes

  • Calls before GDK.initialize() return not_initialized.
  • Empty text/ssml returns invalid_input; an empty voice_id returns invalid_voice_id.
  • If the synthesizer cannot be created on this host, calls return speech_synthesizer_unavailable.

Usage

# 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()

Events service: GDK.events

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.

Methods

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).

Notes

  • The event name and every dimensions/measurements field 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() returns events_feature_unavailable (HRESULT E_NOTIMPL) without writing.

Usage

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)

Game Save service: GDK.game_save

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.config carries the TitleId and MSAAppId issued 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 for GDK.game_save.
  • The build runs with registered package identity (wdapp register or 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.

Methods

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.

Validation notes

  • not_initialized when the GDK runtime is not yet initialized.
  • invalid_user when user is null or has no underlying handle.
  • xbox_services_uninitialized when the shared XBOX services scaffold (SCID) is unavailable.

Cancellation

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.

Usage

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)

Game Chat service: GDK.game_chat

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.

Methods

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.

Signals

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.

Independent voice and text control

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().

Validation notes

  • not_initialized before GDK.initialize() (for initialize()) or before GDK.game_chat.initialize() (for every other method).
  • invalid_max_users when max_users <= 0; already_initialized on re-init.
  • invalid_xuid / invalid_user for empty XUIDs or non-signed-in users; invalid_text for empty/over-long text; invalid_data for an empty frame.
  • user_not_found, not_local_user, target_not_found, add_user_failed for user-lookup and add failures.

Usage

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")

Networking service: GDK.networking

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.

Methods

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

Signals

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().

Constants

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

Result data

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.

Windows behavior

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.

Not wrapped

  • XNetworkingVerifyServerCertificate takes a WinHTTP HINTERNET request handle from WinHttpOpenRequest and is meant to be called inside a WINHTTP_CALLBACK_STATUS_SENDING_REQUEST callback. Godot's HTTPClient and HTTPRequest do not expose such a handle, so there is no way to call it correctly from GDScript. Read the thumbprints from XboxNetworkingSecurityInformation and validate in your own native code.
  • XNetworkingQuerySecurityInformationForUrlUtf16Async differs from the UTF-8 entry point only in input encoding, which is not observable through Godot's single String type.

Validation notes

  • All methods return not_initialized when called before GDK.initialize().
  • query_configuration_setting / set_configuration_setting return invalid_configuration_setting for unknown settings; set_configuration_setting returns invalid_configuration_value for negative values.
  • query_statistics returns invalid_statistics_type for unknown types.
  • query_security_information_for_url_async returns invalid_url for an empty URL.

XboxNetworkingSecurityInformation

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().

Usage

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"]])