Skip to content

Xbox Live Module

Jump to bottom
Francisco Dias edited this page Oct 20, 2022 · 1 revision

Back To Top

Xbox Live Module

The GDK extension allows your Microsoft Store game to use all features from the Xbox Live services including stats, leaderboards, achievements and rich presence. This module contains all the functions that are available to handle Xbox Live services. Xbox Live services can either be Event-Based or Title-Managed and this choice is made on the Partner Center (check the help article on the Partner Center for more information). The functions below are grouped according these two systems.

Event Based Functions

⚠️ IMPORTANT

Using the Event-Based system requires some additional configuration detailed under Manifest File guide.

The following functions are provided for event based stats/leaderboards/achievements (Microsoft recommends using these for stats and leaderboards but not achievements ):

Title Managed Functions

The following functions are provided for title managed stats/leaderboards/achievements (Microsoft recommends using these for achievements ):

General Functions

The following functions can be used regardless of whether Event-Based or Title-Managed services are used:



Back To Top

xboxone_achievements_set_progress

This function can be used to update the progress of an achievement. You supply the user_id as returned by the function xboxone_get_user, a string containing the achievement's numeric ID (as assigned in the Partner Center when it was created), and finally the progress value to set (from 0 to 100).

⚠️ IMPORTANT

Note that the achievement system will refuse updates that are lower than the current progress value.

This is an asynchronous function that will trigger the Async System event when the task is finished.


Syntax:

xboxone_achievements_set_progress(user_id, achievement, progress);
Argument Type Description
user_id pointer The user ID pointer.
achievement string The achievement identification string (obtained from the Partner Center).
progress real The new progress value of the achievement (is a value between 0 and 100).

Returns:

Real (negative if error, otherwise the System Request ID)
Error Description
-1 Invalid user_id was specified.
-2 Xbox Live context could not be retrieved.

Triggers:

Asynchronous System Event
Key Type Description
event_type string The string "achievement result"
requestID real The id of the request that fired this callback.
achievement string The achievement ID string passed to the function call.
progress real The updated progress value.
error real This will be: 0 if the progress update was successful; xboxone_achievement_already_unlocked if the achievement was unlocked in a previous request; or a negative number with the error code if request fails.

Example:

requestId = xboxone_achievements_set_progress(user_id, "KilledFirstBoss", 100);

In the code above we setting the "KilledFirstBoss" achievement as 100% complete, tshe function call will then return a request ID (requestId) that can be used inside an Async System event.

if (async_load[? "event_type"] == "achievement_result")
  {
    if (async_load[? "requestID"] == requestId)
      {
        if (async_load[? "error"] >= 0)
        {
            show_debug_message("Request succeeded");
        }
      }
}

The code above matches the response against the correct event_type and requestID , and prints a debug message if the request was successful.



Back To Top

xboxone_get_achievement

This function can be used to update the progress of an achievement. You supply the user_id as returned by the function xboxone_get_user, a string containing the achievement's numeric ID (as assigned in the Partner Center when it was created), and finally the progress value to set (from 0 to 100).

⚠️ IMPORTANT

Note that the achievement system will refuse updates that are lower than the current progress value.

This is an asynchronous function that will trigger the Async System event when the task is finished.


Syntax:

xboxone_get_achievement(user_id, achievement);
Argument Type Description
user_id pointer The user ID pointer.
achievement string The achievement identification string (obtained from the Partner Center).

Returns:

Real (negative if error, otherwise the System Request ID)
Error Description
-1 Invalid user_id was specified.
-2 Xbox Live context could not be retrieved.

Triggers:

Asynchronous System Event
Key Type Description
event_type string The string "achievement info"
requestID real The id of the request that fired this callback.
achievement string The achievement ID string passed to the function call.
progress real The progress value.
name string The UTF-8 encoded localized achievement name.
progress_state real The state of a user's progress towards the earning of the achievement: 0 - unkown; 1 - achieved; 2 - not started; 3 - in progress.
userID int64 The user ID pointer.
error real This will be: 0 if the progress update was successful; xboxone_achievement_already_unlocked if the achievement was unlocked in a previous request; or a negative number with the error code if request fails.

Example:

requestId = xboxone_get_achievement(user_id, "KilledFirstBoss");

In the code above we setting the "KilledFirstBoss" achievement as 100% complete, tshe function call will then return a request ID (requestId) that can be used inside an Async System event.

if (async_load[? "event_type"] == "achievement info")
  {
    if (async_load[? "requestID"] == requestId)
      {
        if (async_load[? "error"] >= 0)
        {
            show_debug_message("Request succeeded");
            if (async_load[? "progress_state"] == 3) show_debug_message("We are almost there: " + string(async_load[? "progress"]));
            else if (async_load[? "progress_state"] == 1) show_debug_message("We did it!!");
        }
      }
}

The code above matches the response against the correct event_type and requestID , and prints a debug message if the request was successful.



Back To Top

xboxone_check_privilege

With this function you can check whether the given user has a privilege. If you set the attempt_resolution argument to true and the privilege isn't enabled, it will also open a system dialogue (suspending the game) to prompt the user to upgrade their account or to get the privilege in a different way as required. If the user then acquires the required privilege, the function will return true. This is an asynchronous function that will trigger the Async System event when the task is finished.


Syntax:

xboxone_check_privilege(user_id, privilege_id, attempt_resolution);
Argument Type Description
user_id pointer The user ID pointer.
privilege_id constant The privilege to check for (is a xboxone_privilege_* constant)
attempt_resolution boolean Requests for this privilege.

Returns:

N/A

Triggers:

Asynchronous System Event
Key Type Description
event_type string The string "check_privilege_result".
result integer One or more (bit-wise combined) of the xboxone_privilege_* constants.
privilege constant The privilege you have requested (is a xboxone_privilege_* constant)

Example:

var user_one = xboxone_get_activating_user();
  xboxone_check_privilege(user_one, xboxone_privilege_multiplayer_sessions, true);

In the code above we are getting the ID of the user that launched the game (using the function xboxone_get_activating_user) and checking if they have privilege for multiplayer sessions and requesting for attempting resolution.



Back To Top

xboxone_fire_event

This function can be used to fire a stat event. The event_name argument is the name of the event to be fired as defined in the Partner Center console for your game, and the following additional parameters will also depend on what you have a set up for the stat. The function will return 0 if the event was sent (and should be received/processed by the server) or -1 if there was an error (e.g. your events manifest file is outdated).

ℹ️ NOTE

The first two parameters for an event usually default to the user_id (obtained from the xboxone_get_user function) and the game's scid (obtained from the Microsoft Partner Center).


Syntax:

xboxone_fire_event(event_name, ...);
Argument Type Description
event_name string The name of the event to be triggered.
... * The parameters to be passed to the event as individual arguments.

Returns:

Real (-1 on error, 0 if the function was successful)

Example:

var uid = xboxone_get_activating_user();
  var result = xboxone_fire_event("PlayerSessionStart", uid, global.scid, 0, 42, 42);

In the code above we are firing the "PlayerSessionStart" event and passing some parameters, including the player's ID and the game's SCID as the first two parameters for the specified event.



Back To Top

xboxone_read_player_leaderboard

This function allows you to read a leaderboard starting at the specified user, regardless of the user's rank or score, and ordered by percentile rank. You supply the user_id as returned by the function xboxone_get_user and a friendfilter that is one of the achievement_filter_* constants.

⚠️ IMPORTANT

This function requires xboxone_stats_setup before it can be used.

This is an asynchronous function that will trigger the Async Social event when the task is finished.


Syntax:

xboxone_read_player_leaderboard(ident, user_id, numitems, friendfilter);
Argument Type Description
ident string The leaderboard id (if filter is all_players) or stat to read.
user_id pointer The user ID pointer.
numitems real The number of items to retrieve.
friendfilter constant One of the achievement_filter_* constants.

Returns:

Real (-1 on error, any other value otherwise)

Triggers:

Asynchronous Social Event
Key Type Description
id constant The constant achievement_leaderboard_info
leaderboardid string The unique ID of the leaderboard as defined on the provider dashboard.
numentries real The number of entries in the leaderboard that you have received.
PlayerN string The name of the player, where N is position within the received entries list.
PlayeridN pointer The unique user id of the player N
RankN real The rank of the player N within the leaderboard.
ScoreN real The score of the player N

Example:

var uid = xboxone_get_activating_user();
      xboxone_read_player_leaderboard("MyLeaderboard", uid, 10, achievement_filter_all_players);

In the code above we are querying the leaderboard with the ID "MyLeaderboard" for the first 10 entries including all players. We can catch the triggered callback using the the Async Social event.

if (async_load[? "id"] == achievement_leaderboard_info)
  {
    global.numentries = async_load[? "numentries"];
      for (var i = 0; i < numentries; i++)
        {
            global.playername[i] = async_load[? "Player" + string(i)];
              global.playerid[i] = async_load[? "Playerid" + string(i)];
                global.playerrank[i] = async_load[? "Rank" + string(i)];
                  global.playerscore[i] = async_load[? "Score" + string(i)];
      }
}

The code above matches the response against the correct id and stores the information of the top player names, ids, ranks and scores in global arrays.



Back To Top

xboxone_set_rich_presence

This function is used to set the rich presence string for the given user. A Rich Presence string shows the user's in-game activity after the name of the game that the user is playing, separated by a hyphen. This string is displayed under a player's Gamertag in the "Friends & Clubs" list as well as in the player's Xbox Live profile. When using this function you need to supply the user_id for the user, and then you can flag the user as currently active in the game or not (using true/false). The next argument is the rich_presence_string ID to show, and then finally you can (optionally) supply a scid string. Note that this is an optional argument -- if you have called xboxone_stats_setup you don't need to pass the scid here.

ℹ️ TIP

For more information on rich presence and how to set up the strings to use in the Partner Center, please see the Microsoft's Rich Presence documentation.

⚠️ IMPORTANT

On the Windows platform it is not possible to check your rich presence string during development (when it's a sandboxed project).


Syntax:

xboxone_set_rich_presence(user_id, is_user_active, rich_presence_id, scid);
Argument Type Description
user_id pointer The user ID pointer
is_user_active boolean Flag the user as active or not
rich_presence_id string The rich present ID (defined in the Partner Center)
scid string ✴️ OPTIONAL The Service Configuration ID string

Returns:

N/A

Example:

var user_one = xboxone_get_activating_user();
    xboxone_set_rich_presence(userId, true, "Playing_Challenge", global.scid);

In the code above we are getting the active user (using the function xboxone_get_activating_user) and setting its current presence string. We are providing a scid (global.scid) otherwise we were required to first call the function xboxone_stats_setup.



Back To Top

xboxone_gamertag_for_user

This function is used to get the gamer tag for the given user. This tag is displayed in a players "Friends & Clubs" list as well as in the player's Xbox Live profile.

ℹ️ TIP

For more information on gamer tags, please see the Microsoft's Modern Gamertag documentation.


Syntax:

xboxone_gamertag_for_user(user_id);
Argument Type Description
user_id int64 The user unique ID

Returns:

string

Example:

var userId = xboxone_get_activating_user();
    var gamertag = xboxone_gamertag_for_user(userId);

In the code above we are getting the active user (using the function xboxone_get_activating_user) and getting its current gamertag.



Back To Top

xboxone_stats_setup

This function needs to be called before you can use any of the other Xbox stat functions, and simply initializes the required libraries on the system. The user_id argument is the user ID as returned by the function xboxone_get_user, while the scid and title_id are the unique ID's for your game on the Microsoft Partner Center.


Syntax:

xboxone_stats_setup(user_id, scid, title_id);
Argument Type Description
user_id pointer The user ID pointer.
scid string The Service Configuration ID (SCID)
title_id integer (hex) The title ID (as shown in "MicrosoftGame.Config")

Returns:

N/A

Example:

var user_id = xboxone_get_user(0);
  xboxone_stats_setup(user_id, "00000000-0000-0000-0000-000000000000", 0xFFFFFFFF);

In the code above first we retrieve the user ID of the user with index 0 (using the xboxone_get_user function) and use it to setup the event based stat system.



Back To Top

xbox_stats_add_user

This function can be used to add the given user to the statistics manager. This must be done before using any of the other stats functions to automatically sync the game with the Xbox Live server and retrieve the latest values. You supply the user_id as returned by the function xboxone_get_user, and the function will return -1 if there was an error or the user_id is invalid, or an async request ID if the function was successfully called. This is an asynchronous function that will trigger the Async Social event when the task is finished.


Syntax:

xboxone_stats_add_user(user_id);
Argument Type Description
user_id pointer The user ID pointer.

Returns:

Real (-1 on error, otherwise an async request ID)

Triggers:

Asynchronous Social Event
Key Type Description
id constant The constant achievement_stat_event
event string The string "LocalUserAdded".
userid pointer The user ID associated with the request.
error real 0 if successful, some other value on error.
errorMessage string ✴️ OPTIONAL A string with an error message

Example:

for(var i = 0; i < xboxone_get_user_count(); i++)
  {
      user_id[i] = xboxone_get_user(i);
        xboxone_stats_add_user(user_id[i]);
  }

In the code above we are looping though all the available users (using the function xboxone_get_user_count) getting their user id (using the xboxone_get_user function) and adding them to the statistics manager. We can catch the triggered callbacks using the the Async Social event.

if (async_load[? "event"] == "LocalUserAdded")
{
    if (async_load[? "error"] != 0)
    {
        show_debug_message("Error while adding user to statistics manager");
    }
}

The code above matches the response against the correct event , providing a failure message if error is not 0.



Back To Top

xboxone_stats_delete_stat

This function can be used to delete a stat from the stat manager for the given user ID. You supply the user ID as returned by the function xboxone_get_user, then the stat string to delete. This clears the stat value and removed it from the stat manager, meaning it will no longer be returned by the functions xboxone_stats_get_stat_names and xboxone_stats_get_stat.


Syntax:

xboxone_stats_delete_stat(user_id, stat_name)
Argument Type Description
user_id pointer The user ID pointer.
stat_name string The stat to be deleted.

Returns:

Real (-1 on error, any other value otherwise)

Example:

for (var i = 0; i < xboxone_get_user_count(); i++)
    {
        user_id[i] = xboxone_get_user(i);
        xboxone_stats_delete_stat(user_id[i], "highScore");
    }

In the code above we are looping though all the available users (using the function xboxone_get_user_count) getting their user id (using the xboxone_get_user function) and deleting the stat &quot;highScore&quot; from each one of them.



Back To Top

xbox_stats_flush_user

This function can be used to flush the stats data for the given user from the statistics manager to the live server, ensuring that the server is up to date with the current values. To use the function, you supply the user_id as returned by the function xboxone_get_user, and then give a priority value (0 for low priority and 1 for high priority). The function will will return -1 if there was an error or the user ID was invalid, or an async request ID if the function was successfully called.

⚠️ IMPORTANT

According to Xbox documentation, developers should be careful not to call this too often as the Xbox system will rate-limit the requests, and the GDK Extension will also automatically flush stats approximately every 5 minutes.

This is an asynchronous function that will trigger the Async Social event when the task is finished.


Syntax:

xboxone_stats_flush_user(user_id, high_priority);
Argument Type Description
user_id pointer The user ID pointer.
high_priority boolean Whether or not flush is high priority.

Returns:

Real (-1 on error, otherwise an async request ID)

Triggers:

Asynchronous Social Event
Key Type Description
id constant The constant achievement_stat_event
event string The string "StatisticUpdateComplete".
userid pointer The user ID associated with the request.
error real 0 if successful, some other value on error.
errorMessage string A string with an error message [OPTIONAL]

Example:

for(var i = 0; i < array_length(user_ids); i++)
  {
        xboxone_stats_flush_user(user_ids[i]);
  }

In the code above we are looping though an array of user ids (user_ids) and flushing their local data to the live server. We can catch the triggered callbacks using the the Async Social event.

if (async_load[? "event"] == "StatisticsUpdateComplete")
{
    if (async_load[? "error"] != 0)
    {
        show_debug_message("Error while updating user statistics");
    }
}

The code above matches the response against the correct event , providing a failure message if error is not 0.



Back To Top

xboxone_stats_get_leaderboard

This function can be used to retrieve a global leaderboard with ranks for a given statistic. You supply the user ID (as returned by the function xboxone_get_user), the stat string (as defined when you registered it as a "Featured Stat"), and then you specify a number of details about what leaderboard information you want to retrieve. Note that you can only retrieve a global leaderboard for int or real stats, but not for string stats.

⚠️ IMPORTANT

Stats used in global leaderboards must be registered as "Featured Stats" in the Partner Center otherwise an error will be returned. If you want local (social) leaderboards, then please see the function xboxone_stats_get_social_leaderboard.

⚠️ IMPORTANT

The user ID passed into this function should first be added to the statistics manager using the xboxone_stats_add_user function. ****

This is an asynchronous function that will trigger the Async Social event when the task is finished.


Syntax:

xboxone_stats_get_leaderboard(user_id, stat, num_entries, start_rank, start_at_user, ascending);
Argument Type Description
user_id pointer The user ID pointer.
stat string The stat to create the global leaderboard from.
num_entries real The number of entries from the leaderboard to retrieve.
start_rank real The rank in the leaderboard to start from (set to 0 if start_at_user is set to true.
start_at_user boolean Set to true to start at the user ID.
ascending boolean Set to true or ascending or false for descending order.

Returns:

N/A

Triggers:

Asynchronous Social Event
Key Type Description
id constant The constant achievement_leaderboard_info
event string The string "GetLeaderboardComplete".
userid pointer The user ID associated with the request.
error real 0 if successful, some other value on error.
errorMessage string A string with an error message [OPTIONAL]
displayName string The unique ID for the leaderboard as defined on the provider dashboard.
numentries real The number of entries in the leaderboard that you have received.
PlayerN string The name of the player, where N is position within the received entries list.
PlayeridN pointer The unique user id of the player N
RankN real The rank of the player N within the leaderboard.
ScoreN real The score of the player N

Example:

xboxone_stats_get_leaderboard(user_id, "GlobalTime", 20, 1, false, true);

In the code above we are querying a leaderboard for the stat &quot;GlobalTime&quot; with the first 20 entries starting on rank 1 in ascending order. We can catch the triggered callback using the the Async Social event.

if (async_load[? "id"] == achievement_leaderboard_info)
  {
    if (async_load[? "event"] == "GetLeaderboardComplete")
      {
        global.numentries = async_load[? "numentries"];
          for (var i = 0; i < numentries; i++)
            {
                global.playername[i] = async_load[? "Player" + string(i)];
                  global.playerid[i] = async_load[? "Playerid" + string(i)];
                    global.playerrank[i] = async_load[? "Rank" + string(i)];
                      global.playerscore[i] = async_load[? "Score" + string(i)];
            }
      }
}

The code above matches the response against the correct id and event , and stores the information of the top player names, ids, ranks and scores in global arrays.



Back To Top

xboxone_stats_get_social_leaderboard

This function can be used to retrieve a social leaderboard with ranks for a given statistic. You supply the user ID (as returned by the function xboxone_get_user), the stat string (as defined when you created it using the xboxone_stats_set_stat_* functions), and then you specify a number of details about what leaderboard information you want to retrieve. Note that you can only retrieve a social leaderboard for int or real stats, but not for string stats, and that if you flag the favourites_only argument as true, then the results will only contain data for those friends that are marked by the user as "favorites".

⚠️ IMPORTANT

The user ID passed into this function should first be added to the statistics manager using the xboxone_stats_add_user function.

ℹ️ TIP

Stats used in social leaderboards do not need to be registered as "Featured Stats" in the Partner Center.

This is an asynchronous function that will trigger the Async Social event when the task is finished.


Syntax:

xboxone_stats_get_social_leaderboard(user_id, stat, num_entries, start_rank, start_at_user, ascending, favourites);
Argument Type Description
user_id pointer The user ID pointer.
stat string The stat to create the global leaderboard from.
num_entries real The number of entries from the leaderboard to retrieve.
start_rank real The rank in the leaderboard to start from (set to 0 if start_at_user is set to true.
start_at_user boolean Set to true to start at the user ID.
ascending boolean Set to true or ascending or false for descending order.
favourites_only boolean Set to true to show only friends that are marked as favourites.

Returns:

N/A

Triggers:

Asynchronous Social Event
Key Type Description
id constant The constant achievement_leaderboard_info
event string The string "GetLeaderboardComplete".
userid pointer The user ID associated with the request.
error real 0 if successful, some other value on error.
errorMessage string A string with an error message [OPTIONAL]
displayName string The unique ID for the leaderboard as defined on the provider dashboard.
numentries real The number of entries in the leaderboard that you have received.
PlayerN string The name of the player, where N is position within the received entries list.
PlayeridN pointer The unique user id of the player N
RankN real The rank of the player N within the leaderboard.
ScoreN real The score of the player N

Example:

xboxone_stats_get_social_leaderboard(user_id, "GlobalTime", 20, 1, false, true, true);

In the code above we are querying a leaderboard for the stat &quot;GlobalTime&quot; with the first 20 entries starting on rank 1 in ascending order, selecting only friends marked as favourites. We can catch the triggered callback using the the Async Social event.

if (async_load[? "id"] == achievement_leaderboard_info)
  {
    if (async_load[? "event"] == "GetLeaderboardComplete")
      {
        global.numentries = async_load[? "numentries"];
          for (var i = 0; i < numentries; i++)
            {
                global.playername[i] = async_load[? "Player" + string(i)];
                  global.playerid[i] = async_load[? "Playerid" + string(i)];
                    global.playerrank[i] = async_load[? "Rank" + string(i)];
                      global.playerscore[i] = async_load[? "Score" + string(i)];
            }
      }
}

The code above matches the response against the correct id and event , and store the information of the top favourite friends player names, ids, ranks and scores in global arrays.



Back To Top

xboxone_stats_get_stat

This function can be used to retrieve a single stat value from the stat manager for the given user. You supply the user_id as returned by the function xboxone_get_user, and then the stat_name as defined when you created it using the one of the xboxone_stats_set_stat_* functions. The return value can be either a string or a real (depending on the stat being checked) or the GML constant undefined if the stat does not exist or there has been an error.

⚠️ IMPORTANT

The user ID passed into this function should first be added to the statistics manager using the xboxone_stats_add_user function.


Syntax:

xboxone_stats_get_stat(user_id, stat_name)
Argument Type Description
user_id pointer The user ID pointer.
stat_name string The statistic to get.

Returns:

Real/String (The value for the given stat) or undefined

Example:

if (game_over == true)
    {
        if (xboxone_stats_get_stat(user_id, "PercentDone") < 100)
        {
            var _val = (global.LevelsFinished / global.LevelsTotal)*100;
            xboxone_stats_set_stat_real(user_id, "PercentDone", _val);
        }
    }

In the code above we are checking if the given user complete percentage (&quot;PercentDone&quot;) is less then 100 and if so updated it to a new value (using the xboxone_stats_set_stat_real function).



Back To Top

xboxone_stats_get_stat_names

This function can be used to retrieve all the defined stats from the stat manager for the given user. You supply the user ID as returned by the function xboxone_get_user, and the function returns an array of strings containing the statistics for the user. If an error occurs or the user has no stats, an empty array will be returned.

⚠️ IMPORTANT

The user ID passed into this function should first be added to the statistics manager using the xboxone_stats_add_user function.


Syntax:

xboxone_stats_get_stat_names(user_id)
Argument Type Description
user_id pointer The user ID pointer.

Returns:

Array (Array with all the stat names, strings)

Example:

var _stats = xboxone_stats_get_stat_names(user_id);
    for (var i = 0; i < array_length(_stats); i++)
    {
        xboxone_stats_delete_stat(user_id, _stats[i]);
    }

In the code above we are getting an array of stat names (_stats) for a given user and looping though it deleting each stat (using the xboxone_stats_delete_stat function).



Back To Top

xboxone_stats_remove_user

This function can be used to remove (unregister) the given user from the statistics manager, performing a flush of the stat data to the live server. According to the Xbox documentation the game does not have to remove the user from the stats manager, as the GDK Extension will periodically flush the stats anyway. To use the function, you supply the user_id as returned by the function xboxone_get_user, and the function will will return -1 if there was an error or the user ID was invalid, or any other value if the function was successfully called.

⚠️ IMPORTANT

The user ID passed into this function should first be added to the statistics manager using the xboxone_stats_add_user function.

⚠️ IMPORTANT

Removing the user can return an error if the statistics that have been set on the user are invalid (such as the stat names containing non-alphanumeric characters).

ℹ️ TIP

If you want to flush the stats data to the live server at any time without removing the user, you can use the function xboxone_stats_flush_user.

This is an asynchronous function that will trigger the Async Social event when the task is finished.


Syntax:

xboxone_stats_remove_user(user_id);
Argument Type Description
user_id pointer The user ID pointer.

Returns:

Real (-1 on error, any other value otherwise)

Triggers:

Asynchronous Social Event
Key Type Description
id constant The constant achievement_stat_event
event string The string "LocalUserRemoved".
userid pointer The user ID associated with the request.
error real 0 if successful, some other value on error.
errorMessage string A string with an error message [OPTIONAL]

Example:

for(var i = 0; i < array_length(user_ids); i++)
  {
        xboxone_stats_remove_user(user_ids[i]);
  }

In the code above we are looping though an array of user ids (user_ids) and removing them from the statistics manager. We can catch the triggered callbacks using the the Async Social event.

if (async_load[? "event"] == "LocalUserRemoved")
{
    if (async_load[? "error"] != 0)
    {
        show_debug_message("Error while removing user from statistics manager");
    }
}

The code above matches the response against the correct event , providing a failure message if error is not 0.



Back To Top

xboxone_stats_set_stat_int

This function can be used to set the value of a stat for the given user ID. You supply the user ID as returned by the function xboxone_get_user, then the stat string to set (if the stat string does not already exist then a new stat will be created and set to the given value) and a value (an integer ) to set the stat to. Note that the stat name must be alphanumeric only, with no symbols or spaces.

⚠️ IMPORTANT

The user ID passed into this function should first be added to the statistics manager using the xboxone_stats_add_user function.

ℹ️ TIP

When setting a stat value, any previous values will be overwritten, therefore it is up to you to determine if the stat value should be updated or not (ie. check that the high score is actually the highest) by comparing to the current stat value with the new one before setting it.


Syntax:

xboxone_stats_set_stat_int(user_id, stat_name, stat_value)
Argument Type Description
user_id pointer The user ID pointer.
stat_name string The statistic to set.
stat_value integer The value to set the stat to.

Returns:

Real (-1 on error, any other value otherwise)

Example:

var _highscore = 123;
  xboxone_stats_set_stat_int(users_ids[0], "Highscore", _highscore);

In the code above we are setting the stat &quot;Highscore&quot; of the selected user (user_ids[0]) to a new value, overwriting any previous recorded value.



Back To Top

xboxone_stats_set_stat_real

This function can be used to set the value of a stat for the given user ID. You supply the user ID as returned by the function xboxone_get_user, then the stat string to set (if the stat string does not already exist then a new stat will be created and set to the given value) and a value (a real ) to set the stat to. Note that the stat name must be alphanumeric only, with no symbols or spaces.

⚠️ IMPORTANT

The user ID passed into this function should first be added to the statistics manager using the xboxone_stats_add_user function.

ℹ️ TIP

When setting the stat value, any previous values will be overwritten, therefore it is up to you to determine if the stat value should be updated or not (ie. check that the high score is actually the highest) by comparing to the current stat value with the new one before setting it.


Syntax:

xboxone_stats_set_stat_real(user_id, stat_name, stat_value)
Argument Type Description
user_id pointer The user ID pointer.
stat_name string The statistic to set.
stat_value real The value to set the stat to.

Returns:

Real (-1 on error, any other value otherwise)

Example:

var _bestTime = 123.45;
  xboxone_stats_set_stat_real(users_ids[0], "BestTime", _bestTime);

In the code above we are setting the stat &quot;BestTime&quot; of the selected user (user_ids[0]) to a new value, overwriting any previous recorded value.



Back To Top

xboxone_stats_set_stat_string

This function can be used to set the value of a stat for the given user ID. You supply the user ID as returned by the function xboxone_get_user, then the stat string to set (if the stat string does not already exist then a new stat will be created and set to the given value) and a value (a string ) to set the stat to. Note that the stat name must be alphanumeric only, with no symbols or spaces.

⚠️ IMPORTANT

The user ID passed into this function should first be added to the statistics manager using the xboxone_stats_add_user function.

ℹ️ TIP

When setting the stat value, any previous values will be overwritten, therefore it is up to you to determine if the stat value should be updated or not (ie. check that the high score is actually the highest) by comparing to the current stat value with the new one before setting it.


Syntax:

xboxone_stats_set_stat_string(user_id, stat_name, stat_value)
Argument Type Description
user_id pointer The user ID pointer.
stat_name string The statistic to set.
stat_value string The value to set the stat to.

Returns:

Real (-1 on error, any other value otherwise)

Example:

xboxone_stats_set_stat_string(users_ids[0], "Team", "YoYo Games");

In the code above we are setting the stat &quot;Team&quot; of the selected user (user_ids[0]) to a new value, overwriting any previous recorded value.



YoYoGames 2024

Clone this wiki locally