Documentation

Steamworks Extension

This section is for those users that have been given access to the Steam API for publishing your game to that platform. To be able to use these functions you must have been accepted onto Steam previously, either through a publisher or through the self-publishing system.

Guides

This sections provides a variety of important guides to get you started using the extension:

Management

This extension provides the following management functions:

Modules

There are a great number of different functions related to the Steam API. We've split them up into the following sections to make it easier to navigate:



Guides

Back To Top

Setup Guide (IDE/Runtime 2022.6+)

To use the Steam API extension you should follow these steps:

  1. Import this Steamworks extension into your project, if you haven't done that already.
  2. The Steam app needs to be installed, running and with an account logged in (official site).
  3. Download Steamworks SDK (1.55) from Steam's partner site and extract the contents of the zip into a directory of your choice (e.g.: C:\steamworks\sdk).
  4. To set up your AppID and environment status, double click on the Steamworks extension in your Asset Browser in the IDE.
  5. In the bottom section you will see the new extension options. Those are all you will need to configure to use this extension. The build options require the path to the SDK downloaded on step 3 and the application options required your Application ID.



Back To Top

Migration Changes

During the migration of the Steamworks function library from the base GameMaker runner into this extension, there were some new functions that were added, and others that were slightly changed. This document covers the changes that happened during that migration.

Changed Functions

These are the functions that changed:

This function is now asynchronous, meaning it will return an Async request ID that should be used inside a Steam Async Event to check when the task is finished.

New Functions

These are the new functions that were added to the Steam extension:



Management

Back To Top

steam_init

This function initialises the steam APIs.

ℹ️ NOTE

This function is already configured to be called at Game Start by the extension, and should not be called from your game code.


Syntax:

steam_init();


Returns:

N/A



Back To Top

steam_update

This function updates the steam APIs.

⚠️ IMPORTANT

This function is required to be called in order for the Steamworks extension to work. We recommend you place this function in a persistent controller object that calls it inside its Step Event.


Syntax:

steam_update();


Returns:

N/A


Example:

steam_update();

The above code will update the steam APIs.



Back To Top

steam_shutdown

This function shuts down the Steamworks API, releases pointers and frees memory.

⚠️ IMPORTANT

This function is required to be called in order for the Steamworks extension to work. We recommend you place this function in the GameEnd Event of a controller object. You need to check if this is not a game_restart().


Syntax:

steam_shutdown();


Returns:

N/A


Example:

global.is_game_restarting = true;
game_restart();

The code above should be used when you want to restart your game. We set the is_game_restarting global variable to true announcing the game being restarted to true (this global variable should already be declared at the begining of your game and be set to false by default). Now inside our Game End Event we can use the following code.

if (global.is_game_restarting == false) {
    steam_shutdown();
}
global.is_game_restarting = false;

First we check if the game is not restarting and in that case we know we are actually ending so we call the steam_shutdown method.



General

Back To Top

General

The following set of functions are all for checking the availability of certain aspects of the Steam client or server API. This means that these functions should be used before any other Steam API function call to ensure that the client/server setup is correct and communicating with your game:



Back To Top

steam_initialised

When using the Steam API, this function can be called to check that the Steam client API has been initialised correctly before any doing any further calls to Steam specific functions in your game.


Syntax:

steam_initialised();


Returns:

Bool


Example:

global.steam_api = false;
if (steam_initialised())
{
    if (steam_stats_ready() && steam_is_overlay_enabled())
    {
        global.steam_api = true;
    }
}

The above code will set a global variable to true if the Steam client API is correctly initialised, along with the Steam statistics and overlay functionality, or it will set the variable to false otherwise.



Back To Top

steam_stats_ready

When using the Steam API, this function can be called to check that the Steam client API has correctly initialised the statistics for your game.


Syntax:

steam_stats_ready();


Returns:

Bool


Example:

global.steam_api = false;
if steam_initialised()
{
    if steam_stats_ready() && steam_is_overlay_enabled()
    {
        global.steam_api = true;
    }
}

The above code will set a global variable to true if the Steam client API is correctly initialised, along with the Steam statistics and overlay functionality, or it will set the variable to false otherwise.



Back To Top

steam_get_app_id

This function is used retrieve the unique app ID that Steam assigns for your game, which is required for using some of the User Generated Content functions.


Syntax:

steam_get_app_id();


Returns:

Real


Example:

global.app_id = steam_get_app_id();

The above code gets the unique app ID for your game on Steam and stores it in a global variable.



Back To Top

steam_get_user_account_id

This function is used retrieve the unique User ID that Steam assigns to each user, which is required for using some of the User Generated Content functions.


Syntax:

steam_get_user_account_id();


Returns:

Real


Example:

global.user_id = steam_get_user_account_id();

The above code gets the unique user ID for the person who owns the game and stores it in a global variable.



Back To Top

steam_get_user_steam_id

You can use this function to return the unique Steam user id of the user currently logged into the Steam client. If you need to get the user's on screen user name you should refer to the function steam_get_persona_name.


Syntax:

steam_get_user_steam_id();


Returns:

int64


Example:

if steam_initialised()
{
    global.u_id = steam_get_user_steam_id();
}

The above code will set a global variable to the current users unique Steam ID if the Steam client API is correctly initialised.



Back To Top

steam_get_persona_name

You can use this function to return the user name of the user currently logged into the Steam client. This is the visible screen name and not the unique user id (this can be found using the function steam_get_user_steam_id).


Syntax:

steam_get_persona_name();


Returns:

String


Example:

if steam_initialised()
{
    global.p_name = steam_get_persona_name();
}

The above code will set a global variable to current users screen name if the Steam client API is correctly initialised.



Back To Top

steam_get_user_persona_name

This function can be used to retrieve the user name (screen name) for any specific user ID. This is an asynchronous function that will return an asynchronous id and trigger the Steam Async Event when the task is finished.


Syntax:

steam_get_user_persona_name(steamID);
Argument Type Description
steamID int64 The unique Steam ID for a user.


Returns:

Real


Triggers:

Asynchronous Steam Event
Key Type Description
id real The asynchronous request ID
event_type string The string value "user_persona_name"
steamid int64 The unique user id of the user currently logged into the Steam client
persona_name string The visible screen name of the user currently logged into the Steam client


Example:

request = steam_get_user_persona_name(global.UGC_UserID);

The above code will request the user name of the user ID stored in the global variable "UGC_UserID", storing the returned value in a variable for parsing in the Async Event.



Back To Top

steam_is_user_logged_on

This function will return true if the Steam client currently has a live connection to the Steam servers. If it returns false, it means there is no active connection due to either a networking issue on the local machine, or the Steam server being down or busy.


Syntax:

steam_is_user_logged_on();


Returns:

Bool


Example:

if (steam_is_user_logged_on())
{
    global.user_id = steam_get_user_account_id();
}

The above code will check to see if the user is logged onto the Steam server and if it stores the user ID in a global variable.



Back To Top

steam_current_game_language

This function is used retrieve the current language that Steam is using (as a string), for example "english".


Syntax:

steam_current_game_language();


Returns:

String


Example:

language = steam_current_game_language();

The above code gets the language used for the current game.



Back To Top

steam_available_languages

This function can be used to retrieve a list of all available languages for Steam. The returned value is simply a comma-separated list of languages.


Syntax:

steam_available_languages();


Returns:

String


Example:

language = steam_available_languages();

The above gets the available languages for Steam as a string and stores it in a variable.



Back To Top

steam_is_subscribed

This function checks if the active user is subscribed to the current App ID.

ℹ️ NOTE

This will always return true if you're using Steam DRM.


Syntax:

steam_is_subscribed();


Returns:

Bool


Example:

if (steam_is_subscribed())
{
    show_debug_message("is_subscribed")
}

The above code will check to see if the user is logged onto the Steam server and if it stores the user ID in a global variable.



Back To Top

steam_set_warning_message_hook

This function sets a warning message hook to receive SteamAPI warnings and info messages in the console.


Syntax:

steam_set_warning_message_hook();


Returns:

N/A


Example:

steam_set_warning_message_hook();

The above code start Steamworks logging messages in console.



Overlay

Back To Top

Overlay

The Steam Overlay is the visual display that can be brought up to display the Steam interface to the user. This is normally done by the user themselves using a combination of keys, but you also have the possibility of doing it from within your game, so that you can map a button or an event to show the overlay.

Functions

The extension provides you with the following functions:

Constants

This section also provides the following constants to use with the functions:



Back To Top

steam_is_overlay_enabled

When using the Steam API, this function can be called to check that the Steam client API has the overlay functionality enabled.


Syntax:

steam_is_overlay_enabled();


Returns:

Bool


Example:

global.steam_api = false;
if steam_initialised()
{
    if steam_stats_ready() && steam_is_overlay_enabled()
    {
        global.steamapi = true;
    }
}

The above code will set a global variable to true if the Steam client API is correctly initialized, along with the Steam statistics and overlay functionality, or it will set the variable to false otherwise.



Back To Top

steam_is_overlay_activated

This function can be used to find out if the user has the Steam Overlay active or not. If the overlay is active and visible to the user the function will return true, and if it is not, then it will return false. An example of what this function can be used for would be for polling the Steam API for the overlay so that you can pause your game while the overlay is being shown.


Syntax:

steam_is_overlay_activated();


Returns:

Bool


Example:

if steam_is_overlay_activated()
{
    global.Pause = true;
}

The above code will check to see if the Steam overlay is active and if it is it will set the global variable "Pause" to true.



Back To Top

steam_activate_overlay

The Steam overlay is a piece of the Steam user interface that can be activated over the top of almost any game launched through Steam. It lets the user access their friends list, web browser, chat, and in-game DLC purchasing. The default key for a user to access the overlay while in a game is SHIFT + TAB, but you can also bring up any page of the overlay using this function. It takes one of six constants that are listed below:


Syntax:

steam_activate_overlay(overlay_type);
Argument Type Description
overlay_type constant.OverlayType The page index of the Steam API UI to show (see OverlayType constants).


Returns:

N/A


Example:

var key = keyboard_lastkey;
switch (key)
{
    case vk_f1: steam_activate_overlay(ov_friends); break;
    case vk_f2: steam_activate_overlay(ov_community); break;
    case vk_f3: steam_activate_overlay(ov_players); break;
    case vk_f4: steam_activate_overlay(ov_settings); break;
    case vk_f5: steam_activate_overlay(ov_gamegroup); break;
    case vk_f6: steam_activate_overlay(ov_achievements); break;
}

The above code polls the last keyboard key pressed and if it is any of the function keys from 1 to 6 it will open the corresponding page of the Steam overlay.



Back To Top

steam_activate_overlay_browser

With this function you can open the Steam game overlay to its web browser and then have it load the specified URL. you need to use the full URL as a string for this to resolve correctly, for example: "http://www.steamgames.com/".


Syntax:

steam_activate_overlay(url);
Argument Type Description
url string The (full) URL for the overlay to open.


Returns:

N/A


Example:

if keyboard_check_pressed(vk_f1)
{
    steam_activate_overlay_browser("http://www.steamgames.com/");
}

The above code polls the keyboard for the F1 key and if it is then Steam overlay will be opened and resolve to the given URL.



Back To Top

steam_activate_overlay_store

With this function you can open the Steam overlay on the store page for a game so that users can buy or download DLC (for example). You need to supply the unique App ID for the game or DLC which you would get from the Steam dashboard when you set it up.


Syntax:

steam_activate_overlay_store(app_id);
Argument Type Description
app_id integer The unique App ID for your game.


Returns:

N/A


Example:

if keyboard_check_pressed(vk_f1)
{
    steam_activate_overlay_store(global.DLC_id);
}

The above code polls the keyboard for the F1 key and if it is then Steam overlay will be opened on the page for the game content using the app ID stored in the global variable.



Back To Top

steam_activate_overlay_user

This function will open the Steam overlay to one of the chosen dialogues relating to the user ID given. Note that Steam IDs can be large numbers and so you may need to cast your ID value as an int64() before supplying it to the function.


Syntax:

steam_activate_overlay_user(dialog_name, steamid);
Argument Type Description
dialog_name string The dialogue to open the overlay on (see below).
steamid int64 The Steam user ID or group ID to use.
Dialog Names Description
"steamid" Opens the Steam Community web browser to the page of the user or group
"chat" Opens a chat window to the specified user


Returns:

N/A


Example:

var key = keyboard_lastkey;
switch (key)
{
    case vk_f1: steam_activate_overlay_user("steamid", global.GameGroupID); break;
    case vk_f2: steam_activate_overlay_user("chat", global.FriendID); break;
}

The above code polls the last keyboard key pressed and if it is function key 1 or function key 2, it will open the Steam overlay to either see the Steam group stored in the global variable "GamegroupID", or it will open the chat window to chat with the user stored in the global "FriendID" variable.



Back To Top

steam_set_overlay_notification_inset

Sets the inset of the overlay notification from the corner specified by steam_set_overlay_notification_position


Syntax:

steam_set_overlay_notification_inset(hor_inset, vert_inset);
Argument Type Description
hor_inset real The horizontal (left-right) distance in pixels from the corner.
vert_inset real The vertical (up-down) distance in pixels from the corner.


Returns:

Bool


Example:

steam_set_overlay_notification_inset(10, 10);

The code above will inset the over lay 10px on the horizontal axis and 10px in the vertical axis.



Back To Top

steam_set_overlay_notification_position

Changes the corner in which the overlay notifications will appear.


Syntax:

steam_set_overlay_notification_position(position);
Argument Type Description
position OverlayNotificationPosition A constant that indicates the position where the notification overlay should render


Returns:

N/A


Example:

steam_set_overlay_notification_position(steam_overlay_notification_position_bottom_right);

The above code will change the notification position to the bottom right corner.



Back To Top

OverlayType

These constants specify the type of overlay to be activated when using the function steam_activate_overlay.

Overlay Type Constant Description
ov_friends The friends page for the current user
ov_community The community page for your game
ov_players The page showing others that are playing the same game or that you have recently played with
ov_settings The Steam client overlay settings
ov_gamegroup Opens the Steam Community web browser to the official game group for this game
ov_achievements The achievements page for your game



Back To Top

OverlayNotificationPosition

These constants specify the position of the notification overlay onscreen an should be used with the function steam_set_overlay_notification_position.

Overlay Notification Position Constant Description
steam_overlay_notification_position_top_left Point to the top left position
steam_overlay_notification_position_top_right Point to the top right position
steam_overlay_notification_position_bottom_left Point to the bottom left position
steam_overlay_notification_position_bottom_right Point to the bottom right position



Leaderboards

Back To Top

Leaderboards

The Steam API supports persistent leaderboards with automatically ordered entries. These leaderboards can be used to display global and friend leaderboards in your game and on the community web page for your game. Each game can have up to 10,000 leaderboards, and each leaderboard can be retrieved immediately after a player's score has been inserted into it, but note that for each leaderboard, a player can have only one entry, although there is no limit on the number of players per leaderboard.

Functions

Each leaderboard entry contains a name, a score and a rank for the leaderboard, and this data will be replaced when a new leaderboard entry is created for the user, and the following functions can be used to add and retrieve this data form the leaderboards for your game:

Data Types

The following data types are used by the leaderboard functions:

Constants

The following constants are used by the leaderboard functions:



Back To Top

steam_create_leaderboard

With this function you can create a new leaderboard for your game. The first argument is a string which defines the name of your leaderboard, and this name should be used in any further function calls relating to the leaderboard being created. You can then define the sort order (see LeaderboardSortOrder constants) as well as the way in which the information is displayed (see LeaderboardDisplayType constants). This is an asynchronous function that will trigger the Steam Async Event when the task is finished.

ℹ️ NOTE

If you have previously created a leaderboard with the same name (either through code or through your Steam page for the game), then this function will not create a new one.


Syntax:

steam_create_leaderboard(lb_name, sort_order, display_type);
Argument Type Description
lb_name string The name of the leaderboard that you are creating
sort_order LeaderboardSortOrder constant The method for sorting the leaderboard entries (see LeaderboardSortOrder constants)
display_type LeaderboardDisplayType constant The way to display the leaderboard to the user (see LeaderboardDisplayType constants)


Returns:

Real


Triggers:

Asynchronous Steam Event
Key Type Description
id real The asynchronous request ID
event_type string The string value "create_leaderboard"
status real The status code, 0 if the leaderboard was create and 1 if it already existed
lb_name string The name of the leaderboard


Example:

steam_create_leaderboard("Game Times", lb_sort_ascending, lb_disp_time_sec);

The above code will create a leaderboard called "Game Times", and set it to display the results in ascending order and with a display in seconds.



Back To Top

steam_upload_score

This function will send a score to the given leaderboard. The score to be uploaded is a real number, and the leaderboard name is a string that was defined when you created the leaderboard using the function steam_create_leaderboard. This is an asynchronous function that will trigger the Steam Async Event when the task is finished.

ℹ️ NOTE

If the function call fails for any reason it will return -1 and the Async event will not be triggered.


Syntax:

steam_upload_score(lb_name, score);
Argument Type Description
lb_name string The name of the leaderboard that you are uploading the scores to
score real The score to upload


Returns:

Real


Triggers:

Asynchronous Steam Event
Key Type Description
post_id real The asynchronous request ID
event_type string The string value "leaderboard_upload"
lb_name string The name of the leaderboard
num_entries real The number of returned entries
success bool Whether or not the request was successful
updated bool Whether or not the leaderboard was updated (ie: the new score was better)
score real The score that was posted to the leaderboard


Extended Example:

In this example, we first upload a score and then parse the async_load map returned if successful. The code below shows a typical example for uploading:

if (hp <= 0)
{
    upload_ID = steam_upload_score("Game Scores", score);
    if (!upload_ID)
    {
        alarm[0] = room_speed;
    }
}

Note that we have set an alarm if the call fails. This would be used to try the upload again at a later time and you can add extra code there to retry the upload or to save the score to a text file should it continue to fail, etc... We now add the following into the Steam Async Event for the instance controlling the scores:

var type = ds_map_find_value(async_load, "event_type");
if (type == "leaderboard_upload")
{
    var lb_ID = ds_map_find_value(async_load, "post_id");
    if lb_ID == upload_ID
    {
        var lb_name = ds_map_find_value(async_load, "lb_name");
        var lb_done = ds_map_find_value(async_load, "success");
        var lb_score = ds_map_find_value(async_load, "score");
        var lb_updated = ds_map_find_value(async_load, "updated");
        show_debug_message("leaderboard post id:" + string(lb_ID) + " to lb:" + string(lb_name) + " with score:" + string(lb_score) + " updated=" + string(lb_updated));
        if (lb_done)
        {
            show_debug_message("- Succeeded");
        }
        else
        {
            show_debug_message("- Failed");
        }
    }
}

in the example we are simply outputting the return values to the compiler window as debug messages, but you can use this event to deal with the information in any way you choose.



Back To Top

steam_upload_score_ext

This function will send a score to the given leaderboard. It is similar to the function steam_upload_scorebut has an extra argument that will allow you to force the update of the score, as by default Steam only updates the score if it is better than the previous one. This is an asynchronous function that will trigger the Steam Async Event when the task is finished.

ℹ️ NOTE

If the function call fails for any reason it will return -1 and the Async event will not be triggered.


Syntax:

steam_upload_score_ext(lb_name, score, force_update);
Argument Type Description
lb_name string The name of the leaderboard that you are uploading the scores to
score real The score to upload
force_update bool Whether or not the value should be replaced


Returns:

Real


Triggers:

Asynchronous Steam Event
Key Type Description
post_id real The asynchronous request ID
event_type string The string value "leaderboard_upload"
lb_name string The name of the leaderboard
num_entries real The number of returned entries
success bool Whether or not the request was successful
updated bool Whether or not the leaderboard was updated (ie: the new score was better or forceUpdate was set to true)
score real The score that was posted to the leaderboard


Extended Example:

In this example, we first upload a score and then parse the async_load map returned if successful. The code below shows a typical example for uploading:

if (hp <= 0)
{
    upload_ID = steam_upload_score_ext("Game Scores", score, true);
    if (!upload_ID)
    {
        alarm[0] = room_speed;
    }
}

Note that we have set an alarm if the call fails. This would be used to try the upload again at a later time and you can add extra code there to retry the upload or to save the score to a text file should it continue to fail, etc... We now add the following into the Steam Async Event for the instance controlling the scores:

var type = ds_map_find_value(async_load, "event_type");
if (type == "leaderboard_upload")
{
    var lb_ID = ds_map_find_value(async_load, "post_id");
    if lb_ID == upload_ID
    {
        var lb_name = ds_map_find_value(async_load, "lb_name");
        var lb_done = ds_map_find_value(async_load, "success");
        var lb_score = ds_map_find_value(async_load, "score");
        var lb_updated = ds_map_find_value(async_load, "updated");
        show_debug_message("leaderboard post id:" + string(lb_ID) + " to lb:" + string(lb_name) + " with score:" + string(lb_score) + " updated=" + string(lb_updated));
        if (lb_done)
        {
            show_debug_message("- Succeeded");
        }
        else
        {
            show_debug_message("- Failed");
        }
    }
}

in the example we are simply outputting the return values to the compiler window as debug messages, but you can use this event to deal with the information in any way you choose.



Back To Top

steam_upload_score_buffer

This function will send a score to the given leaderboard along with a data package created from a buffer. The buffer should be no more than 256 bytes in size - anything beyond that will be chopped off - and can contain any data you require. The score to be uploaded should be a real number, and the leaderboard name is a string that was defined when you created the leaderboard using the function steam_create_leaderboard. This is an asynchronous function that will trigger the Steam Async Event when the task is finished.

ℹ️ NOTE

If the function call fails for any reason it will return -1 and the Async event will not be triggered.


Syntax:

steam_upload_score_buffer(lb_name, score, buffer);
Argument Type Description
lb_name string The name of the leaderboard that you are uploading the scores to
score real The score to upload
buffer buffer ID The ID of the buffer to attach


Returns:

Real


Triggers:

Asynchronous Steam Event
Key Type Description
post_id real The asynchronous request ID
event_type string The string value "leaderboard_upload"
lb_name string The name of the leaderboard
num_entries real The number of returned entries
success bool Whether or not the request was successful
updated bool Whether or not the leaderboard was updated (ie: the new score was better). Note that if you score was not updated neither will be the data buffer.
score real The score that was posted to the leaderboard


Extended Example:

In this example, we first upload a score and then parse the async_load map returned if successful. The code below shows a typical example for uploading, with a buffer being created to hold a string telling us which level the score was uploaded from:

if (hp <= 0)
{
    var buff = buffer_create(256, buffer_fixed, 1 );
    buffer_write(buff, buffer_string, "Uploaded on level " + string(global.Level));
    upload_ID = steam_upload_score("Game Scores", score, buff);

    if (!upload_ID)
    {
        alarm[0] = room_speed;
    }

    buffer_delete(buff);
}

Note that we have set an alarm if the call fails. This would be used to try the upload again at a later time and you can add extra code there to retry the upload or to save the score to a text file should it continue to fail, etc... Also note that we immediately delete the buffer, since it is no longer required for the function. We now add the following into the Steam Async Event for the instance controlling the scores:

var type = ds_map_find_value(async_load, "event_type");
if (type == "leaderboard_upload")
{
    var lb_ID = ds_map_find_value(async_load, "post_id");
    if lb_ID == upload_ID
    {
        var lb_name = ds_map_find_value(async_load, "lb_name");
        var lb_done = ds_map_find_value(async_load, "success");
        var lb_score = ds_map_find_value(async_load, "score");
        var lb_updated = ds_map_find_value(async_load, "updated");
        show_debug_message("leaderboard post id:" + string(lb_ID) + " to lb:" + string(lb_name) + " with score:" + string(lb_score) + " updated=" + string(lb_updated));
        if (lb_done)
        {
            show_debug_message("- Succeeded");
        }
        else
        {
            show_debug_message("- Failed");
        }
    }
}

In the example we are simply outputting the return values to the compiler window as debug messages, but you can use this event to deal with the information in any way you choose.



Back To Top

steam_upload_score_buffer_ext

This function will send a score to the given leaderboard along with a data package created from a buffer. The buffer should be no more than 256 bytes in size - anything beyond that will be chopped off - and can contain any data you require. This function is similar to steam_upload_score_buffer but has an extra argument that will allow you to force the update of the score, as by default Steam only updates the score if it is better than the previous one. This is an asynchronous function that will trigger the Steam Async Event when the task is finished.

ℹ️ NOTE

If the function call fails for any reason it will return -1 and the Async event will not be triggered.


Syntax:

steam_upload_score_buffer_ext(lb_name, score, buffer, force_update);
Argument Type Description
lb_name string The name of the leaderboard that you are uploading the scores to
score real The score to upload
buffer buffer ID The ID of the buffer to attach
force_update bool Whether or not the value should be replaced


Returns:

Real


Triggers:

Asynchronous Steam Event
Key Type Description
post_id real The asynchronous request ID
event_type string The string value "leaderboard_upload"
lb_name string The name of the leaderboard
num_entries real The number of returned entries
success bool Whether or not the request was successful
updated bool Whether or not the leaderboard was updated (ie: the new score was better or forceUpdate was set to true). Note that if you score was not updated neither will be the data buffer.
score real The score that was posted to the leaderboard


Extended Example:

In this example, we first upload a score and then parse the async_load map returned if successful. The code below shows a typical example for uploading, with a buffer being created to hold a string telling us which level the score was uploaded from:

if (hp <= 0)
{
    var buff = buffer_create(256, buffer_fixed, 1 );
    buffer_write(buff, buffer_string, "Uploaded on level " + string(global.Level));
    upload_ID = steam_upload_score_buffer_ext("Game Scores", score, buff, true);

    if (!upload_ID)
    {
        alarm[0] = room_speed;
    }

    buffer_delete(buff);
}

Note that we have set an alarm if the call fails. This would be used to try the upload again at a later time and you can add extra code there to retry the upload or to save the score to a text file should it continue to fail, etc... Also note that we immediately delete the buffer, since it is no longer required for the function. We now add the following into the Steam Async Event for the instance controlling the scores:

var type = ds_map_find_value(async_load, "event_type");
if (type == "leaderboard_upload")
{
    var lb_ID = ds_map_find_value(async_load, "post_id");
    if lb_ID == upload_ID
    {
        var lb_name = ds_map_find_value(async_load, "lb_name");
        var lb_done = ds_map_find_value(async_load, "success");
        var lb_score = ds_map_find_value(async_load, "score");
        var lb_updated = ds_map_find_value(async_load, "updated");
        show_debug_message("leaderboard post id:" + string(lb_ID) + " to lb:" + string(lb_name) + " with score:" + string(lb_score) + " updated=" + string(lb_updated));
        if (lb_done)
        {
            show_debug_message("- Succeeded");
        }
        else
        {
            show_debug_message("- Failed");
        }
    }
}

In the example we are simply outputting the return values to the compiler window as debug messages, but you can use this event to deal with the information in any way you choose.



Back To Top

steam_download_scores

This function is used retrieve a sequential range of leaderboard entries by leaderboard ranking. The start_idx and end_idx parameters control the requested range of ranks, for example, you can display the top 10 on a leaderboard for your game by setting the start value to 1 and the end value to 10. The leaderboard name is a string that was defined when you created the leaderboard using the function steam_create_leaderboard. This is an asynchronous function that will trigger the Steam Async Event when the task is finished.

ℹ️ NOTE

If the function call fails for any reason it will return -1 and the async event will not be triggered.


Syntax:

steam_download_scores(lb_name, start_idx, end_idx);
Argument Type Description
lb_name string The name of the leaderboard that you are downloading the scores from
start_idx integer The start position within the leaderboard
end_idx integer The end position within the leaderboard


Returns:

Real


Triggers:

Asynchronous Steam Event
Key Type Description
id real The asynchronous request ID
event_type string The string value "leaderboard_download"
status int64 The status code if download fails
lb_name string The name of the leaderboard
num_entries real The number of returned entries
entries string A json formatted string with all the downloaded entries (see LeaderboardEntry for details)


Extended Example:

In this extended example we will request the top ten ranking for the given leaderboard and parse its results in the Steam Async Event. to start with we need to request the scores with the following code:

score_get = steam_download_scores("Game Scores", 1, 10);

This will send off a request to the Steam Server for the scores from the leaderboard "Game Scores", storing the async id of the request in the variable "score_get". this will then be handled in the Steam Async Event in the following way:

var async_id = ds_map_find_value(async_load, "id");
if async_id == score_get
{
    var entries = ds_map_find_value(async_load, "entries");
    var map = json_decode(entries);
    if ds_map_exists(map, "default")
    {
        ds_map_destroy(map);
        exit;
    }
    else
    {
        var list = ds_map_find_value(map, "entries");
        var len = ds_list_size(list);
        var entry;
        for(var i = 0; i < len; i++;)
        {
            entry = ds_list_find_value(list, i );
            steam_name[i] = ds_map_find_value(entry, "name");
            steam_score[i] = ds_map_find_value(entry, "score");
            steam_rank[i] = ds_map_find_value(entry, "rank");
            steam_data[i] = ds_map_find_value(entry, "data");
        }
    }
    ds_map_destroy(map)
}

What we do here is first check the "id" key of the special async_load DS map. If this value is the same as the value of the original call-back function (stored in the "score_get" variable) we then continue to process the data. The first thing we do is parse the async_load DS map for the key "entries" which will contain a JSON formatted string containing the leaderboard data. This JSON object is then decoded (see json_decode) as another DS map, and this new map id is stored in the variable "map". This map is checked for the key "default" and if that is found then the map is destroyed and the event is exited. If no "default" key is found, the code will then parse the map to extract the necessary information about the leaderboard, by first extracting a DS list from the "entries" key of the DS map, and then looping through each entry of the list to get another DS map with the name, score and rank of each entry. These values are then stored to arrays. Once the loop has finished, the JSON DS map is destroyed (which in turn destroys all the internal maps and lists). There is no need to destroy the async_load DS map as this is handled for you by GameMaker Studio 2.



Back To Top

steam_download_scores_around_user

This function is used to retrieve leaderboard entries relative the current users entry. The range_start parameter is the number of entries to retrieve before the current users entry, and the range_end parameter is the number of entries after the current user's entry, and the current user's entry is always included in the results. For example, if the current user is number 5 on a given leaderboard, then setting the start range to -2 and the end range to 2 will return 5 entries: 3 through 7. If there are not enough entries in the leaderboard before or after the user's entry, Steam will adjust the range start and end points trying to maintained the range size. For example, if the user is #1 on the leaderboard, start is set to -2, and end is set to 2, Steam will return the first 5 entries in the leaderboard. This is an asynchronous function that will trigger the Steam Async Event when the task is finished.

ℹ️ NOTE

If the function call fails for any reason it will return -1 and the async event will not be triggered.


Syntax:

steam_download_scores_around_user(lb_name, range_start, range_end);
Argument Type Description
lb_name string The name of the leaderboard that you are downloading the scores from
range_start integer The start position within the leaderboard
range_end integer The end position within the leaderboard


Returns:

Real


Triggers:

Asynchronous Steam Event
Key Type Description
id real The asynchronous request ID
event_type string The string value "leaderboard_download"
status int64 The status code if download fails
lb_name string The name of the leaderboard
num_entries real The number of returned entries
entries string A json formatted string with all the downloaded entries (see LeaderboardEntry for details)


Example:

request_id = steam_download_scores_around_user("Game Scores", -4, 5);

This will send off a request to the Steam Server for a range of 10 scores from the leaderboard &quot;Game Scores&quot;, centered on the player and will store the async id of the request in the variable request_id. This will then be handled in the Steam Async Event, as shown in the Extended Example for steam_download_scores.



Back To Top

steam_download_friends_scores

With this function you can retrieve only the scores on the leaderboard that belong to those people that are marked as "friends" in the Steam client. So, if your leaderboard has 200 entries, and 50 of them are your friends, this function will retrieve only those 50 results. The leaderboard name is a string that was defined when you created the leaderboard using the function steam_create_leaderboard. This is an asynchronous function that will trigger the Steam Async Event when the task is finished.

ℹ️ NOTE

If the function call fails for any reason it will return -1 and the async event will not be triggered.


Syntax:

steam_download_friends_scores(lb_name);
Argument Type Description
lb_name string The name of the leaderboard that you are downloading the scores from


Returns:

Real


Triggers:

Asynchronous Steam Event
Key Type Description
id real The asynchronous request ID
event_type string The string value "leaderboard_download"
status int64 The status code if download fails
lb_name string The name of the leaderboard
num_entries real The number of returned entries
entries string A json formatted string with all the downloaded entries (see LeaderboardEntry for details)


Example:

request_id = steam_download_friends_scores("Game Scores");

This will send off a request to the Steam Server for the users friends scores from the given leaderboard and will store the async id of the request in the variable request_id. This will then be handled in the Steam Async Event, as shown in the Extended Example for steam_download_scores.



Back To Top

LeaderboardEntry

A leaderboard entry is represented by a json formatted string that can be returned by the async callback event of the following functions:

Key Type Description
rank real The rank of the entry on the specified leaderboard
data string The base64 encoded string with the data provided when uploading scores using the steam_upload_score_buffer or
steam_upload_score_buffer_ext functions ✴️ OPTIONAL
score real The score attributed to this entry
name string The display name of the player for this entry
userID int64 The unique user id of the player for this entry

ℹ️ NOTE

If steam_upload_score_buffer or steam_upload_score_buffer_ext were used to upload the score, the decoded entry will now have a &quot;data&quot; key so you can retrieve the data of the uploaded buffer (see the Steam Async Event extended code example for further details). This data will be base64 encoded and so you will need to use the function buffer_base64_decode on the data before reading from the buffer.



Back To Top

LeaderboardDisplayType

These constants specify the display type of a leaderboard and should be used with the function steam_create_leaderboard.

Leaderboard Display Type Constant Description
lb_disp_none Show the leaderboard "as is".
lb_disp_numeric Show the leaderboard as a numeric display.
lb_disp_time_sec Show the leaderboard values as times, with the base value being seconds.
lb_disp_time_ms Show the leaderboard values as times, with the base value being milliseconds



Back To Top

LeaderboardSortOrder

These constants specify the sort order of a leaderboard and should be used with the function steam_create_leaderboard.

Leaderboard Sort Order Constant Description
lb_sort_none No sorting. The information will be displayed "as is".
lb_sort_ascending Sort the leaderboard in ascending order.
lb_sort_descending Sort the leaderboard in descending order.



Lobbies

Back To Top

Lobbies & Matchmaking

The following functions and constants allow you to use Steam's Lobbies and Matchmaking functionality.

Current Lobby

These functions are provided for handling the current lobby:

Matchmaking

The following functions allow retrieving and handling lists of public lobbies.

Constants

These are the constants used by this API:



Back To Top

steam_lobby_activate_invite_overlay

Displays an invitation overlay if currently in a lobby. The invitation overlay is much akin to the friends-list overlay, but only shows online friends, and shows an "invite" buttons on each row.


Syntax:

steam_lobby_activate_invite_overlay();


Returns:

bool


Triggers:

Asynchronous Steam Event (when an invitation is accepted)
Key Type Description
event_type string The string value "lobby_join_requested"
lobby_id int64 The lobby unique identifier
success bool Whether or not the task was successful
result real The code of the result


Example:

steam_lobby_activate_invite_overlay();

The above code will show the Steam invite overlay.



Back To Top

steam_lobby_create

Starts creating a lobby. Returns whether or not the task was successfully created. This is an asynchronous function that will trigger the Steam Async Event when the task is finished.


Syntax:

steam_lobby_create(type, max_members);
Argument Type Description
type LobbyType Constant that indicate the status of the lobby
max_members real Indicates the maximum allowed number of users in the lobby (including the lobby's creator)


Returns:

bool


Triggers:

Asynchronous Steam Event
Key Type Description
event_type string The string value "lobby_created"
lobby_id int64 The name of the leaderboard
success real Whether or not the request was successful
result bool The status code (descriptions can be found in Steam API documentation)


Example:

steam_lobby_create(steam_lobby_type_public, 4);

The above code will create a lobby with a maximum of 4 users. We now add the following into the Steam Async Event for checking the success of task:

var type = async_load[? "type"];
if (type == "lobby_created")
{
    if (async_load[? "success"])
        show_debug_message("Lobby created");
    else
        show_debug_message("Failed to create lobby");
}

in the example we are simply outputting the success of the lobby creation task.



Back To Top

steam_lobby_get_chat_message_data

Returns the data of a message sent using steam_lobby_send_chat_message_buffer. Returns whether or not the buffer was successfully filled with the message data.


Syntax:

steam_lobby_get_chat_message_data(message_index, buffer);
Argument Type Description
message_index real The message unique identifier
buffer buffer ID The buffer to write the data to


Returns:

bool


Example:

chat_message_buf = buffer_create(steam_lobby_max_chat_message_size, buffer_fixed, 1);
steam_lobby_get_chat_message_data(_msg_index, chat_message_buf)

The code above will get the current message data and place it into a buffer (resizing if required and allowed, ie.: buffer_grow ).



Back To Top

steam_lobby_get_chat_message_size

Return the size of a message


Syntax:

steam_lobby_get_chat_message_size(message_index)
Argument Type Description
message_index real The argument to be passed in


Returns:

real


Example:

// ... INSIDE A STEAM ASYNC EVENT ...
switch (async[? "event_type"])
{
    case "lobby_chat_message":
        size = steam_lobby_get_chat_message_size(async_load[?"message_index"]);
        break;
}

The code above will get the current message size in bytes.



Back To Top

steam_lobby_get_chat_message_text

Return the text of a message.


Syntax:

steam_lobby_get_chat_message_text(index);
Argument Type Description
index real Message index


Returns:

string


Example:

// ... INSIDE A STEAM ASYNC EVENT ...
switch (async[? "event_type"])
{
    case "lobby_chat_message":
        text = steam_lobby_get_chat_message_text(async_load[?"message_index"]);
        break;
}

The code above will get the current message text.



Back To Top

steam_lobby_get_data

Returns a lobby field value, as set by steam_lobby_set_data.


Syntax:

steam_lobby_get_data(key);
Argument Type Description
key string String representation of the data


Returns:

string


Example:

var title = steam_lobby_get_data("title");

The code above will return the data of the title field of the current value.



Back To Top

steam_lobby_get_lobby_id

Returns the Steam ID of the current lobby.


Syntax:

steam_lobby_get_lobby_id();


Returns:

int64


Example:

var lobby_id = steam_lobby_get_lobby_id()

The code above will get the current lobby id and store it in a variable.



Back To Top

steam_lobby_get_member_count

Returns the number of users in the current lobby (including you). If the lobby is not valid, returns 0.


Syntax:

steam_lobby_get_member_count();


Returns:

real


Example:

for(var i = 0 ; i < steam_lobby_get_member_count() ; i++)
{
    var user_id = steam_lobby_get_member_id(i)
    //Do something with the user id
}

The code sample above will get the total number of member in the current lobby and iterate over all of them getting their unique ids, using the steam_lobby_get_member_id function.



Back To Top

steam_lobby_get_member_id

Returns the user ID of the member at the given index in the current lobby.


Syntax:

steam_lobby_get_member_id(index);
Argument Type Description
index real Position of the member of the lobby to return


Returns:

int64


Example:

for(var i = 0 ; i < steam_lobby_get_member_count() ; i++)
{
    var user_id = steam_lobby_get_member_id(i)
    //Do something with the user id
}

The code sample above will iterate over all of the members inside a lobby and get their unique ids.



Back To Top

steam_lobby_get_owner_id

Returns the lobby's owner's Steam ID. If the lobby is not valid, returns ID 0.


Syntax:

steam_lobby_get_owner_id();


Returns:

int64


Example:

var lobby_owner = steam_lobby_get_owner_id()

The code above will return the unique id of the owner of the current lobby.



Back To Top

steam_lobby_is_owner

Returns whether the local player is the lobby's owner.

ℹ️ NOTE

If the lobby is not valid, returns false.


Syntax:

steam_lobby_is_owner()


Returns:

bool


Example:

for (var i = 0; i < steam_lobby_get_member_count(); i++)
{
    if (!steam_lobby_is_owner())
    {
        var user_id = steam_lobby_get_member_id(i)
        steam_lobby_set_owner_id(user_id)
        break;
    }
}

The code example will loop through all the members in a lobby and transfers ownership to the first member that is not the owner.



Back To Top

steam_lobby_join_id

Starts joining a lobby with the given ID. Returns whether or not the API was correctly initialized. This is an asynchronous function that will trigger the Steam Async Event when the task is finished.


Syntax:

steam_lobby_join_id(lobby_id);
Argument Type Description
lobby_id int64 Identifier of the lobby


Returns:

N/A


Triggers:

Asynchronous Steam Event
Key Type Description
event_type string The string value "lobby_joined"
lobby_id int64 The lobby unique identifier
success bool Whether or not the task was successful
result real The code of the result


Example:

steam_lobby_join_id(lobbyID)

The code will attempt the join a lobby with a given id, the task callback can be listened to inside the the Steam Async Event with the folllowing sample code:

var type = async_load[? "type"];
if (type == "lobby_joined")
{
    var lobby_id = async_load[? "lobby_id"];
    var success = async_load[? "success"];

    // Do something with the data
}

In the example we are simply caching the data into variables.



Back To Top

steam_lobby_leave

Leaves the current lobby (if any). Does not raise any errors if currently not in a lobby.

ℹ️ NOTE

If you are the lobby owner and leave the lobby, Steam transfers lobby ownership to any other available user, so you may need to manually handle ownership transfer using steam_lobby_set_owner_id before leaving.


Syntax:

steam_lobby_leave();


Returns:

N/A


Example:

steam_lobby_leave();

The code sample above will make the user leave the current lobby.



Back To Top

steam_lobby_send_chat_message

Broadcasts a chat text message to all the users in the lobby.


Syntax:

steam_lobby_send_chat_message(text);
Argument Type Description
text string The string to be sent (up to 4000 characters)


Returns:

bool


Triggers:

Asynchronous Steam Event
Key Type Description
event_type string The string value "lobby_chat_message"
user_id string The sender unique identifier
message_index real The message unique identifier


Example:

steam_lobby_send_chat_message("Hello World");

The code will broadcast a text message to all the members in the current lobby, the message can be read using the Steam Async Event callback:

var type = async_load[? "type"];
if (type == "lobby_chat_message")
{
    var user_id = async_load[? "user_id"];
    var msg_id = async_load[? "message_index"];

    var user_name = steam_get_user_persona_name_sync(user_id);
    var message = steam_lobby_get_chat_message_text(msg_id);

    // Do something with the data
}

In the example we are simply caching the data into variables notice that use use the function steam_get_user_persona_name_sync and steam_lobby_get_chat_message_text to get both the user name and the text inside the message, respectively.



Back To Top

steam_lobby_send_chat_message_buffer

Broadcasts a chat (text or binary data) message to all the users in the lobby.


Syntax:

steam_lobby_send_chat_message_buffer(buffer, size);
Argument Type Description
buffer buffer ID The buffer to be sent (up to 4 Kilobytes in size)
size real The amount of byte to be sent (there is no offset).


Returns:

bool


Triggers:

Asynchronous Steam Event
Key Type Description
event_type string The string value "lobby_chat_message"
user_id string The sender unique identifier
entry_type real Type of message received.
message_index real The message unique identifier
message_size real The size of the message being broadcasted


Example:

var buff = buffer_create(256, buffer_fixed, 1);
buffer_write(buff, buffer_string, "This is a buffer!");
steam_lobby_send_chat_message_buffer(buff);

The code will broadcast a message (text or binary data) to all the members in the current lobby, the message can be read using the Steam Async Event callback:

var type = async_load[? "type"];
if (type == "lobby_chat_message")
{
    var user_id = async_load[? "user_id"];
    var msg_id = async_load[? "message_index"];

    var user_name = steam_get_user_persona_name_sync(user_id);
    var data = steam_lobby_get_chat_message_data(global.chat_buffer, msg_id);

    // Do something with the data
}

In the example we are simply caching the data into variables notice that use use the function steam_get_user_persona_name_sync and steam_lobby_get_chat_message_data to get both the user name and the data inside the message, respectively.



Back To Top

steam_lobby_set_data

Changes a lobby's field. You must be the lobby's owner to do this. Returns whether or not the data was set. Fields can then be used to filter lobbies via matchmaking functions.

ℹ️ NOTE

If your value is numeric, convert it to string prior to passing it to the function.


Syntax:

steam_lobby_set_data(key, value);
Argument Type Description
key string The key to set the data for
value string The value to set


Returns:

bool


Example:

steam_lobby_set_data("LobbyName","GreatLobby")

The code sample will set the &quot;LobbyName&quot; lobby field to the provided value (&quot;GreatLobby&quot;).



Back To Top

steam_lobby_set_joinable

Sets whether or not a lobby is join-able by other players. This always defaults to enabled for a new lobby. Returns whether or not the property was set.

ℹ️ NOTE

If joining is disabled, then no players can join, even if they are a friend or have been invited.

ℹ️ NOTE

Lobbies with joining disabled will not be returned from a lobby search.


Syntax:

steam_lobby_set_joinable(joinable);
Argument Type Description
joinable bool Allow ( true ) or prevent ( false ) users from joining this lobby


Returns:

bool


Example:

steam_lobby_set_joinable(false);

The code above will prevent user from joining the current lobby.



Back To Top

steam_lobby_set_owner_id

If you are a lobby owner, transfers the lobby ownership to the specified player, which must be in this same lobby. Returns whether or not the property was set.

ℹ️ NOTE

You need to be the lobby owner in order to use the function.


Syntax:

steam_lobby_set_owner_id(user_id);
Argument Type Description
user_id bool The user to set as owner of the lobby


Returns:

bool


Example:

for(var i = 0 ; i < steam_lobby_get_member_count() ; i++)
{
    if(!steam_lobby_is_owner())
    {
        var user_id = steam_lobby_get_member_id(i)
        steam_lobby_set_owner_id(user_id)
        break;
    }
}

The code example will loop through all the members in a lobby and transfers ownership to the first member that is not the owner.



Back To Top

steam_lobby_set_type

Changes the lobby's type. Useful, if you don't allow mid-session joining, you could have the game make lobbies private on session start (or use steam_lobby_set_joinable).

ℹ️ NOTE

You need to be the lobby owner in order to use the function.


Syntax:

steam_lobby_set_type(type)
Argument Type Description
type LobbyType The lobby visibility


Returns:

N/A


Example:

steam_lobby_set_type(steam_lobby_type_private)

The code above will change the lobby joining policy.



Back To Top

steam_lobby_list_add_distance_filter

Restricts results by region and sorts them based on geographical proximity.


Syntax:

steam_lobby_list_add_distance_filter(mode);
Argument Type Description
mode LobbyFilterDistanceMode Distance filter to be applied


Returns:

bool


Example:

steam_lobby_list_add_distance_filter(steam_lobby_list_distance_filter_far);
steam_lobby_list_add_near_filter("myNearFilter", 77);
steam_lobby_list_add_numerical_filter("level", 10, steam_lobby_list_filter_gt);
steam_lobby_list_add_string_filter("Stage","BattleZone", steam_lobby_list_filter_eq)
steam_lobby_list_request();

The code above will apply some filters to be lobby list request before requesting the results.



Back To Top

steam_lobby_list_add_near_filter

Sorts the results based on how close their field's (key)'s value is to the provided one.

ℹ️ NOTE

If multiple near-filters are specified, the earlier-set ones take precedence.


Syntax:

steam_lobby_list_add_near_filter(key, value);
Argument Type Description
key string The filter key name to match.
value real The value that lobbies will be sorted on.


Returns:

bool


Example:

steam_lobby_list_add_distance_filter(steam_lobby_list_distance_filter_far);
steam_lobby_list_add_near_filter("myNearFilter", 77);
steam_lobby_list_add_numerical_filter("level", 10, steam_lobby_list_filter_gt);
steam_lobby_list_add_string_filter("Stage","BattleZone", steam_lobby_list_filter_eq)
steam_lobby_list_request();

The code above will apply some filters to be lobby list request before requesting the results.



Back To Top

steam_lobby_list_add_numerical_filter

Sets up a numeric filter for the next lobby list request. That is, lobbies not matching the condition will be excluded from results.

ℹ️ NOTE

Lobbies without the given field (key) will be excluded.


Syntax:

steam_lobby_list_add_numerical_filter(key, value, comparison_type)
Argument Type Description
key string The filter key name to match
value real The number to compare.
comparison_type LobbyFilterComparisonType The type of comparison to make.


Returns:

bool


Example:

steam_lobby_list_add_distance_filter(steam_lobby_list_distance_filter_far);
steam_lobby_list_add_near_filter("myNearFilter", 77);
steam_lobby_list_add_numerical_filter("level", 10, steam_lobby_list_filter_gt);
steam_lobby_list_add_string_filter("Stage","BattleZone", steam_lobby_list_filter_eq)
steam_lobby_list_request();

The code above will apply some filters to be lobby list request before requesting the results.



Back To Top

steam_lobby_list_add_string_filter

Sets up a string filter for the next lobby list request. That is, lobbies not matching the condition will be excluded from results.

ℹ️ NOTE

Lobbies without the given field (key) will be assumed to have it as &quot;&quot;.


Syntax:

steam_lobby_list_add_string_filter(key, value, comparison_type)
Argument Type Description
key string The filter key name to match
value string The string to compare
comparison_type LobbyFilterComparisonType The type of comparison to make (strings only accepts equal or not equal comparison)


Returns:

bool


Example:

steam_lobby_list_add_distance_filter(steam_lobby_list_distance_filter_far);
steam_lobby_list_add_near_filter("myNearFilter", 77);
steam_lobby_list_add_numerical_filter("level", 10, steam_lobby_list_filter_gt);
steam_lobby_list_add_string_filter("Stage","BattleZone", steam_lobby_list_filter_eq)
steam_lobby_list_request();

The code above will apply some filters to be lobby list request before requesting the results.



Back To Top

steam_lobby_list_get_count

Return count of lobbies, after a successful call to steam_lobby_list_request.


Syntax:

steam_lobby_list_get_count();


Returns:

real


Example:

for(var a = 0 ; a < steam_lobby_list_get_count() ; a++)
{
    ins = instance_create_depth(600,200+90*a,0,Obj_Steam_Networking_List_Slot);
    ins.index = a
    ins.lobby_id = steam_lobby_list_get_lobby_id(a)
    ins.creator = steam_lobby_list_get_data(a, "Creator")
}

After a successful steam_lobby_list_request this function will return the number of results in the lobby query.



Back To Top

steam_lobby_list_get_data

Gets the metadata associated with the specified key from the specified lobby.

ℹ️ NOTE

The argument lobby_index is not a lobby id but instead the position of the lobby (from 0 to steam_lobby_list_get_count) on the query array after a steam_lobby_list_request async event is triggered.


Syntax:

steam_lobby_list_get_data(lobby_index, key);
Argument Type Description
lobby_index real The lobby list index from the queried result.
key string The key to get the value of.


Returns:

string


Example:

for(var a = 0 ; a < steam_lobby_list_get_count() ; a++)
{
    ins = instance_create_depth(600,200+90*a,0,Obj_Steam_Networking_List_Slot);
    ins.index = a
    ins.lobby_id = steam_lobby_list_get_lobby_id(a)
    ins.creator = steam_lobby_list_get_data(a, "Creator")
}

The above code will show a code example.



Back To Top

steam_lobby_list_get_lobby_id

Gets the lobby id associated to the index.

ℹ️ NOTE

The argument lobby_index is not a lobby id but instead the position of the lobby (from 0 to steam_lobby_list_get_count) on the query array after a steam_lobby_list_request async event is triggered.


Syntax:

steam_lobby_list_get_lobby_id(lobby_index);
Argument Type Description
lobby_index real The lobby index in the current lobby list


Returns:

int64


Example:

for(var a = 0; a < steam_lobby_list_get_count(); a++)
{
    ins = instance_create_depth(600, 200+90*a, 0, Obj_Steam_Networking_List_Slot);
    ins.index = a;
    ins.lobby_id = steam_lobby_list_get_lobby_id(a);
    ins.creator = steam_lobby_list_get_data(a, "Creator");
}

The above code will show a code example.



Back To Top

steam_lobby_list_get_lobby_member_count

Gets the number of users in a lobby. **

ℹ️ NOTE

The argument lobby_index is not a lobby id but instead the position of the lobby (from 0 to steam_lobby_list_get_count) on the query array after a steam_lobby_list_request async event is triggered.


Syntax:

steam_lobby_list_get_lobby_member_count(lobby_index);
Argument Type Description
lobby_index real The lobby ID of the lobby to get the number of members of.


Returns:

real


Example:

steam_lobby_list_get_lobby_member_count(steam_lobby_get_lobby_id());

The above code will show a code example.



Back To Top

steam_lobby_list_get_lobby_member_id

Gets the Steam ID of the lobby member at the given index.

ℹ️ NOTE

The argument lobby_index is not a lobby id but instead the index representation of the lobby (ranging from 0 to steam_lobby_list_get_count) on the query array after a steam_lobby_list_request async event is triggered. By the same logic the member_index is also not the user id but the indexed representation of the user within the lobby (this value ranges from 0 to steam_lobby_list_get_lobby_member_count).


Syntax:

steam_lobby_list_get_lobby_member_id(lobby_index, member_index);
Argument Type Description
lobby_index real This MUST be an index ranging from 0 to steam_lobby_list_get_count
member_index real This MUST be an index ranging from 0 to steam_lobby_list_get_lobby_member_count of the lobby index


Returns:

int64


Example:

var count = steam_lobby_list_get_lobby_member_count(steam_lobby_get_lobby_id())
for(var i = 0 ; i < count ; i++)
{
     var member = steam_lobby_list_get_lobby_member_id(i)
     //do something with the member id
}

The above code will show a code example.



Back To Top

steam_lobby_list_get_lobby_owner_id

Returns the current lobby owner.

ℹ️ NOTE

The argument lobby_index is not a lobby id but instead the position of the lobby (from 0 to steam_lobby_list_get_count) on the query array after a steam_lobby_list_request async event is triggered.


Syntax:

steam_lobby_list_get_lobby_owner_id(index);
Argument Type Description
index real The lobby index from the lobby list request result


Returns:

int64


Example:

steam_lobby_list_get_lobby_owner_id(steam_lobby_get_lobby_id());

The above code will show a code example.



Back To Top

steam_lobby_list_is_loading

Returns whether a lobby list request is currently underway.


Syntax:

steam_lobby_list_is_loading();


Returns:

bool


Example:

steam_lobby_list_request();

// Later in code

if (steam_lobby_list_is_loading)
    show_message("Loading");

The above will code will check to see if the lobby list request is still loading or has finished.



Back To Top

steam_lobby_list_join

Starts joining a lobby with the given ID. This is an asynchronous function that will trigger the Steam Async Event when the task is finished.


Syntax:

steam_lobby_list_join(index);
Argument Description
index Position of the lobby in the list


Returns:

N/A


Triggers:

Asynchronous Steam Event
Key Type Description
event_type string The string value "lobby_joined"
lobby_id int64 The lobby unique identifier
success bool Whether or not the task was successful
result real The code of the result


Example:

steam_lobby_list_join(0)

The code sample above can be used to join a lobby with the given index after a steam_lobby_list_request as been preformed.



Back To Top

steam_lobby_list_request

Starts loading the list of lobbies matching the current filters. This is an asynchronous function that will trigger the Steam Async Event when the task is finished.

ℹ️ NOTE

Filters are reset afterwards and have to be set again for subsequent request(s).

ℹ️ NOTE

Existing results are kept up until the event is dispatched.


Syntax:

steam_lobby_list_request()


Returns:

N/A


Triggers:

Asynchronous Steam Event
Key Type Description
event_type string The string value "lobby_list"
lobby_count int64 The number of lobbies in retrieved (same as steam_lobby_list_get_count)
success bool Whether or not the task was successful
result real The code of the result


Example:

steam_lobby_list_add_distance_filter(steam_lobby_list_distance_filter_far);
steam_lobby_list_add_near_filter("myNearFilter", 77);
steam_lobby_list_add_numerical_filter("level", 10, steam_lobby_list_filter_gt);
steam_lobby_list_add_string_filter("Stage","BattleZone", steam_lobby_list_filter_eq)
steam_lobby_list_request();

In this extended example we will request the lobby list that matches the requested filter criteria and parse its results in the Steam Async Event. to start with we need to request the lobbies with the code above. And afterwards proceed to catch the results after/during the corresponding asynchronous event:

var type = ds_map_find_value(async_load, "event_type");
if (type == "lobby_list")
{
    var lb_count = steam_lobby_list_get_count();
    for (var i = 0; i < lb_count; i++)
    {
        var lb_ID = steam_lobby_list_get_lobby_id(i);
        var lb_owner = steam_lobby_list_get_lobby_owner_id(i);
        var lb_members_count = steam_lobby_list_get_lobby_member_count(i);
        for (var j = 0; j < lb_members_count; j++)
        {
            var lb_member_ID = steam_lobby_list_get_lobby_member_id(i, j);
            // Do what even you need with the queried information
        }
    }
}

This code will loop through all the loobies and respective members on the query result.



Back To Top

LobbyFilterComparisonType

These constants specify the comparison type when applying a filter to a lobby list request by calling the following functions:

Lobby Filter Comparison Type Constant Description
steam_lobby_list_filter_eq Equal (==).
steam_lobby_list_filter_ne Not-equal (!=)
steam_lobby_list_filter_lt Less-than (<), only applies to steam_lobby_list_add_numerical_filter
steam_lobby_list_filter_gt Greater-than (>), only applies to steam_lobby_list_add_numerical_filter
steam_lobby_list_filter_le Less-than-or-equal (<=), only applies to steam_lobby_list_add_numerical_filter
steam_lobby_list_filter_ge Greater-than-or-equal (>=), only applies to steam_lobby_list_add_numerical_filter



Back To Top

LobbyFilterDistanceMode

These constants specify the distance mode to be used when applying a filter to a lobby list request by calling the steam_lobby_list_add_distance_filter function.

Constant Description
steam_lobby_list_distance_filter_close Only allows lobbies in same immediate region
steam_lobby_list_distance_filter_default Allows lobbies in same or nearby regions (same continent)
steam_lobby_list_distance_filter_far Allows lobbies from up to half-way around the globe (nearby continents)
steam_lobby_list_distance_filter_worldwide Allows any lobbies. May result in very high latencies, so use with care



Back To Top

LobbyType

These constants specify the type of lobby should be used creating a new lobby using the steam_lobby_create function.

Lobby Type Constant Description
steam_lobby_type_private The lobby can only be joined by invitation
steam_lobby_type_friends_only The lobby can be joined by invitation or via friends-list (by opening the user's menu and picking "Join game")
steam_lobby_type_public The lobby can be joined by invitation, via friends-list and shows up in the public list (see matchmaking functions)



Achievements

Back To Top

Stats and Achievements

The Steam Stats and Achievements API provides an easy way for your game to provide persistent, roaming achievement and statistics tracking for your users. The user's data is associated with their Steam account, and each user's achievements and statistics can be formatted and displayed in their Steam Community Profile.

ℹ️ NOTE

You must wait until steam_stats_ready has returned true, before attempting to read or write stats and achievements.

Achievements

In addition to providing highly-valued rewards to players of your games, achievements are useful for encouraging and rewarding teamwork and player interaction, providing extra dimensionality to the game objectives, and rewarding users for spending more of their time in-game, and as such it is recommended that your game has a few. They are easily set up from the Steam Dashboard, but will require that you create special Icons for them. The following functions are provided for working with achievements:

Statistics Functions

Statistics track fine-grained pieces of information, such as play time, number of power-ups used, etc. You may choose to use them simply for tracking internal game data - so that, for instance, you can grant an achievement based on multi-session game-play statistics collected from the user across multiple computers. Or, you can track interesting game data for display on the user's Steam Community page, where users can compare their own stats against their friends.

ℹ️ NOTE

Previously to being used statistics must be initialized from the Steamworks control panel for your game.

The following functions are provided for working with statistics:

Debug Functions

The following functions are provided for debugging purposes and are not recommended in the production version of you game:

  • steam_reset_all_stats

  • steam_reset_all_stats_achievements

    If the user is in Offline Mode, Steam keeps a local cache of the stats and achievement data so that the APIs can be use as normal. Any stats unable to be committed are saved for the next time the user is online. In the event that there have been modifications on more than one machine, Steam will automatically merge achievements and choose the set of stats that has had more progress. Because Steam keeps a local cache of stats data it is not necessary for the game to also keep a local cache of the data on disk, especially as such caches often come in conflict and when they do it looks to a users as if their progress has been reverted, which is a frustrating experience.



Back To Top

steam_set_achievement

With this function you can tell the Steam API to award ("set") an achievement for the player. These achievements should have been defined on the Steamworks control panel accounts page for your game and the string that is passed to the function should match that used as the API Name on the control panel. The Steam Game Overlay will display a notification panel to the user informing them of the achievement that they have received, unless the achievement has already been awarded, in which case nothing will happen.


Syntax:

steam_set_achievement(ach_name);
Argument Type Description
ach_name string The name of the achievement to set.


Returns:

N/A


Example:

if hp <= 0
{
    global.Deaths += 1;
    if global.Deaths == 10
    {
        if !steam_get_achievement("ach_Player_Dies_Ten_Times") steam_set_achievement("ach_Player_Dies_Ten_Times");
    }
}

The above code will reward the player an achievement if the global variable "Deaths" is equal to 10 and if the achievement has not already been awarded.



Back To Top

steam_get_achievement

With this function you can check the Steam API to see if a specific achievement has been awarded. The achievement should have been previously defined on the Steamworks control panel accounts page for your game and the string that is passed to the function should match that used as the API Name on the control panel.


Syntax:

steam_get_achievement(ach_name);
Argument Type Description
ach_name string The name of the achievement to get.


Returns:

Bool


Example:

if hp <= 0
{
    global.Deaths += 1;
    if global.Deaths == 10
    {
        if !steam_get_achievement("ach_Player_Dies_Ten_Times") steam_set_achievement("ach_Player_Dies_Ten_Times");
    }
}

The above code will reward the player an achievement if the global variable "Deaths" is equal to 10 and if the achievement has not already been awarded.



Back To Top

steam_clear_achievement

With this function you can tell the Steam API to clear (reset) a specific achievement. The achievement should have been previously defined on the Steamworks control panel accounts page for your game and the string that is passed to the function should match that used as the API Name on the control panel.


Syntax:

steam_clear_achievement(ach_name);
Argument Type Description
ach_name string The name of the achievement to clear.


Returns:

N/A


Example:

if mouse_check_button_pressed(mb_left)
{
    steam_clear_achievement("Ach_Game_Win");
    steam_clear_achievement("Ach_Died_10_Times");
    steam_clear_achievement("Ach_Killed_100_Enemies");
    steam_clear_achievement("Ach_Beat_Boss_Level_1");
}

The above code will reset the achievements of the game when the user clicks the left mouse button.




Back To Top

steam_set_stat_int

With this function you can set a specific statistic to a new, signed integer, value. The statistic should have been previously defined on the Steamworks control panel accounts page for your game and the string that is passed to the function should match that used as the API Name on the control panel. Examples of when you could use this are for tracking how many times the player dies or for tracking progress towards an achievement.


Syntax:

steam_set_stat_int(stat_name, value);
Argument Type Description
stat_name string The name of the statistic to set.
value integer The value to set the stat to.


Returns:

N/A


Example:

xp += 100;
steam_set_stat_int("Total_XP", steam_get_stat_int("Total_XP") + 100);
if steam_get_stat_int("Total_XP") > 1000
{
    if !steam_get_achievement("Ach_1000XP") steam_set_achievement("Ach_1000XP");
}

The above code sets a statistic and then checks the final value for it to decide whether to award an achievement or not.



Back To Top

steam_set_stat_float

With this function you can set a specific statistic to a new, floating point, value. The statistic should have been previously defined on the Steamworks control panel accounts page for your game and the string that is passed to the function should match that used as the API Name on the control panel. Examples of when you could use this are for tracking how far your player has travelled, or what percentage of the game is complete.


Syntax:

steam_set_stat_float(stat_name, value);
Argument Type Description
stat_name string The name of the statistic to set.
value real The value to set the stat to.


Returns:

N/A


Example:

var dist_pc = (dist / dist_max) * 100;
steam_set_stat_float("Travelled", dist_pc);

The above code calculates a percentage based on the distance travelled variable "dist" and the maximum distance you can travel "dist_max" and then sets the stat "Travelled" to the new value.



Back To Top

steam_set_stat_avg_rate

This function permits you to set an average statistic type with a "sliding window" effect on the average. The "session_count" value is the current value that you wish to average out, while the "session_length" is the amount of game time since the last call to the function. Please see the extended Example below for further details on how this can be used.


Syntax:

steam_set_stat_avg_rate(stat_name, session_count, session_length);
Argument Type Description
stat_name string The name of the statistic to set.
session_count real The value to get the average of.
session_length real The time that has been taken since the last time the stat was set.


Returns:

N/A


Extended Example:

Since the average stat function can be complex to understand, we will illustrate its use with the following example. Consider the case where you'd like to track an average statistic, such as "Points earned per hour". One approach would be to have two stats: an integer stat, "TotalPoints", and a float stat "TotalPlayTimeHours", and then divide the total points by the total time to get the "Points per Hour" value. However, once the player has accumulated a significant amount of playtime, the calculated average will change extremely slowly, and the more the user plays the game, the less responsive that average will be. If the user has spent 100 hours playing the game, the calculated average will "lag" by about 50 hours of that, and if they increase their skill, they will not see the increase in "Points Per Hour" that they expect. To get around that we can use a "sliding window" to only calculate the "Points per hour" for the last 10 hours played. So, to use this function, we would need to create a Steam stat (in the control panel for the game on the Workshop) called "AvgPointsPerHour" and set its Window property to 10. Now in your game you would have to add some global variables into an instance at the start:

global.Points = 0;
global.Time = 0;

You would then have some controller object to count up the global "Time" variable in an alarm (for example) every second, while your game-play would affect the global "Points" variable. At regular intervals while playing (again, in a controller object, perhaps in an Alarm, or at intervals from polling the "Time" value) you would set the stat like this:

steam_set_stat_avg_rate("AvgPointsPerHour", global.Points, (global.Time / 3600));
global.Points = 0;
global.Time = 0;

Note that we divide time by 3600 since we want the time in hours and not in seconds, and afterward we reset the global "Points" variable and the global "Time" variable to 0 so that the next time the function is called, we get a new average for the statistic. Now, what Steam will do is take this value that you have sent and create an average value over the time that was set for our "window".



Back To Top

steam_get_stat_int

With this function you can get the value of a specific signed integer statistic. The statistic should have been previously defined on the Steamworks control panel accounts page for your game and the string that is passed to the function should match that used as the API Name on the control panel.


Syntax:

steam_get_stat_int(stat_name);
Argument Type Description
stat_name string The name of the statistic to get.


Returns:

Real


Example:

xp += 100;
steam_set_stat_int("Total_XP", steam_get_stat_int("Total_XP") + 100);
if steam_get_stat_int("Total_XP") > 1000
{
    if !steam_get_achievement("Ach_1000XP") steam_set_achievement("Ach_1000XP");
}

The above code sets a statistic and then checks the final value for it to decide whether to award an achievement or not.



Back To Top

steam_get_stat_float

With this function you can get the value of a specific floating point statistic. The statistic should have been previously defined on the Steamworks control panel accounts page for your game and the string that is passed to the function should match that used as the API Name on the control panel.


Syntax:

steam_get_stat_float(stat_name);
Argument Type Description
stat_name string The name of the statistic to get.


Returns:

Real


Example:

var dist_pc = (dist / dist_max) * 100;
if steam_get_stat_float("Travelled") < dist_pc
{
    steam_set_stat_int("Travelled", dist_pc);
}

The above code calculates a percentage based on the distance travelled variable "dist" and the maximum distance you can travel "dist_max". It then polls the current value for the statistic "Travelled" and if it is less than the calculated value, it sets the stat again.



Back To Top

steam_get_stat_avg_rate

With this function you can get the value of a specific average statistic. The statistic should have been previously defined on the Steamworks control panel accounts page for your game and the string that is passed to the function should match that used as the API Name on the control panel.


Syntax:

steam_get_stat_avg_rate(stat_name);
Argument Type Description
stat_name string The name of the statistic to get.


Returns:

Real


Example:

var avg = steam_get_stat_avg_rate("PointsPerHour");
draw_text(8, 8, "PPH = " + string(avg);

The above code gets the current value for the average statistic "PointsPerHour" and draws it on the screen.



Back To Top

steam_reset_all_stats

With this function you can reset all the statistics for the current user to their default values (as defined in the Steamworks control panel for your game). If need to also reset the achievement to their default values use the steam_reset_all_stats_achievements instead.

ℹ️ TIP

It is recommended that you only use this function as a debug tool when developing your game.


Syntax:

steam_reset_all_stats();


Returns:

N/A


Example:

ini_open("Save.ini");
if global.Version != ini_read_real("Data", "Version", 0)
{
    ini_write_real("Data", "Version", global.Version);
    steam_reset_all_stats();
}
ini_close();

The above code checks a stored value in an ini file against that of a global variable and if they are different, it resets the statistics for the game.



Back To Top

steam_reset_all_stats_achievements

With this function you can reset all the statistics and achievements for the current user to their default values (as defined in the Steamworks control panel for your game). If you only need to reset the stats to their default values use the steam_reset_all_stats instead.

ℹ️ TIP

It is recommended that you only use this function as a debug tool when developing your game.


Syntax:

steam_reset_all_stats_achievements();


Returns:

N/A


Example:

ini_open("Save.ini");
if global.Version != ini_read_real("Data", "Version", 0)
{
    ini_write_real("Data", "Version", global.Version);
    steam_reset_all_stats_achievements();
}
ini_close();

The above code checks a stored value in an ini file against that of a global variable and if they are different, it resets the statistics and achievements for the game.



Cloud

Back To Top

Cloud

The Steam Cloud provides an easy and transparent remote file storage system for your game. All files written to disk using the cloud functions will be replicated to the Steam servers after the game exits. If the user then changes computers, the files will then be downloaded to the new computer before the game launches, meaning that the game can then access the files by reading them using the appropriate Steam functions. The Steam Client does the work of ensuring that the files are kept synchronized across all computers the user may be accessing.

ℹ️ NOTE

By default, the Cloud is not enabled for a game on Steamworks. it must be enabled previously from the 'Cloud' tab of the Steamworks game admin, where you should set the byte and file quota. The next time you publish your games Steamworks configuration, the Cloud storage will be ready to use.

The following functions can be used to access the Steam Cloud from within GameMaker Studio 2



Back To Top

steam_is_cloud_enabled_for_app

With this function you can check to make sure that the Steam Cloud service is enabled for your game. It will return true if it is and false otherwise.

⚠️ IMPORTANT

This does not automatically mean that you can use the Cloud functions as the user can switch off Cloud synchronization from their Steam Client. You can check this using the function steam_is_cloud_enabled_for_account, but, even if it is disabled for the user (and enabled for the game), the functions will still work to store and retrieve data from a local copy of all files, it will just not upload them to the cloud on the game end, nor synchronize on the game start.


Syntax:

steam_is_cloud_enabled_for_app();


Returns:

Bool


Example:

if (steam_is_cloud_enabled_for_app())
{
    quota = steam_get_quota_total();
}

The above code checks to see if the steam cloud is enabled for the game and if so it gets the size of the storage quota and stores it in a variable.



Back To Top

steam_is_cloud_enabled_for_account

With this function you can check to make sure that the Steam Cloud service is enabled by the user in their Steam Client settings. It will return true if it is and false otherwise.

⚠️ IMPORTANT

This does not automatically mean that you can store data to the Cloud, as it will also have to have been enabled for your game (you can check this using the function steam_is_cloud_enabled_for_app). If the Steam Cloud is enabled for your game, but the user has it switched off locally, you can still use the Cloud functions to store and retrieve data from a local copy of all files, it will just not upload them to the cloud on the game end, nor synchronize on the game start.


Syntax:

steam_is_cloud_enabled_for_account();


Returns:

Bool


Example:

if (steam_is_cloud_enabled_for_account())
{
    steam_file_share("Save.txt");
}

The above code checks to see if the user has the Steam Cloud enabled and if it returns true, it will then synchronize the given file.



Back To Top

steam_get_quota_total

When using the Steam Cloud to store and synchronize files, you must set up the quota of space that your game will need. This quota is enforced on each Cloud-enabled game, on a per-user-per-game basis, so, for example, if the quota for Game X is 1 megabyte, then each Steam account that owns Game X may store, at most, 1 megabyte of data associated with that game in the Cloud. Any other Cloud-enabled games that the user owns (say, Game Y) will not be affected by the data stored by Game X. The default quota for new Steamworks games is one gigabyte, but you can change this from the Steamworks control panel for your game.

ℹ️ NOTE

Once the quota is exhausted file writes will fail. If you think it may be possible for the quota to be exhausted for the user of your game, you should create code to handle it, as by doing nothing you leave users in a situation where they are unable to fix things and that will lead to a poor experience of your game.


Syntax:

steam_get_quota_total();


Returns:

Real


Example:

if (steam_is_cloud_enabled_for_app())
{
    quota = steam_get_quota_total();
}

The above code checks to see if the steam cloud is enabled for the game and if so it gets the size of the storage quota and stores it in a variable.



Back To Top

steam_get_quota_free

With this function you can find out how much free space is left for the user of the Steam Cloud quota. The value returned is in bytes.


Syntax:

steam_get_quota_free();


Returns:

Real


Example:

if (steam_is_cloud_enabled_for_app())
{
    quota = steam_get_quota_free();
}

The above code checks to see if the steam cloud is enabled for the game and if so it gets the size of the free storage space and stores it in a variable.



Back To Top

steam_file_exists

With this function you can check to see if a file from the Steam Cloud exists or not, with a return value of true if it exists, or false otherwise.


Syntax:

steam_file_exists(filename);
Argument Type Description
filename string The name of the file to check for.


Returns:

Bool


Example:

if (steam_file_exists("Save.txt"))
{
    save_str = steam_file_read("Save.txt");
}

The above code checks to see if a file exists on the Steam Cloud and if it does, it opens it and reads its contents into the variable "save_str".



Back To Top

steam_file_size

With this function you can check the size of a file stored on the Steam Cloud. The returned real number is the size, in bytes, of the file.


Syntax:

steam_file_size(filename);
Argument Type Description
filename string The name of the file to check the size of.


Returns:

Real


Example:

file_bytes = steam_file_size("Save.txt");

The above code stores the size of a file from the Steam Cloud in the variable "file_bytes".



Back To Top

steam_file_persisted

With this function you can check the given file to see if it has been synchronized with the Steam Cloud. A return value of true means that it is, while false means it is not.


Syntax:

steam_file_persisted(filename);
Argument Type Description
filename string The name of the file to check.


Returns:

Bool


Example:

if (!steam_file_persisted("Save.txt"))
{
    steam_file_share("Save.txt");
}

The above code will check to see if a file has been stored to the Steam Cloud, and if it has not it will then synchronize it.



Back To Top

steam_file_write

You can use this function to write data to a file, which will then be synchronized with the Steam Cloud when the user exits the game. if the file does not exist, this function will create it for you, and if it does already exists, it will overwrite any data that is already stored within the file with the new data string. The function will return a value of 0 if it fails for whatever reason and a value greater than 0 if it succeeds.


Syntax:

steam_file_write(filename, data, size);
Argument Type Description
filename string The name of the file to write to.
data string The data to write (a string).
size integer the size of the data to be written.


Returns:

Real


Example:

var fname = "SaveData.txt";
var data = string(global.Level) + "|" + string(global.Points) + "|" + string(global.HP);
var len = string_length(data);
steam_file_write_file(fname, data, len);

The above code will prepare a number of local variables and then use them to write to (or create) a file which will then be synchronized with the Steam Cloud.



Back To Top

steam_file_write_file

With this function you can copy the contents of a locally saved file to a file that is synchronized with the Steam Cloud. The local file must exist before using this function, and it will return a value of 0 if it fails for whatever reason and a value greater than 0 if it succeeds.


Syntax:

steam_file_write_file(steam_filename, local_filename);
Argument Type Description
steam_filename string The Steam Cloud file to copy over.
local_filename string The local file to use to copy from.


Returns:

real


Example:

steam_file_write_file("rm_koala.png", "Koala2.png");

The above code will copy the contents of the file "Koala2.png" to the Steam Cloud file "rm_koala.png".



Back To Top

steam_file_read

This function will read the contents of the given file into a string which can later be parsed in your game.


Syntax:

steam_file_read(filename);
Argument Type Description
filename string The name of the file to read from.


Returns:

String


Example:

if steam_file_exists("Save.txt")
{
    save_str = steam_file_read("Save.txt");
}

The above code checks to see if a file exists on the Steam Cloud and if it does, it opens it and reads its contents into the variable "save_str".



Back To Top

steam_file_share

With this function you can force your game to synchronize the given file with the Steam Cloud. This is not normally necessary due to the fact that the game will synchronize automatically at the end of the player's session, nor is it recommended by Steam, but it can be useful to ensure sensitive information is synchronized immediately. The function will return a value of 0 if it fails for whatever reason and a value greater than 0 if it succeeds.


Syntax:

steam_file_share(filename);
Argument Type Description
filename string The name of the file synchronize.


Returns:

Real


Example:

if (!steam_file_persisted("Save.txt"))
{
    steam_file_share("Save.txt");
}

The above code will check to see if a file has been stored to the Steam Cloud, and if it has not it will then synchronize it.



Back To Top

steam_file_delete

This function will delete the given file from the Steam Cloud. The function will return a value of 0 if it fails for whatever reason and a value greater than 0 if it succeeds.


Syntax:

steam_file_delete(filename);
Argument Type Description
filename string The name of the file delete.


Returns:

Real


Example:

if (steam_file_exists("Save.txt"))
{
    steam_file_delete("Save.txt");
}

The above code will check to see if a file exists, and if it does, it deletes the file from the Steam Cloud.



DLC

Back To Top

DLC

Steam supports both free and paid downloadable content (DLC), and in the Steam client, a game with downloadable content appears as a single application in the user's game list with the downloadable content viewable through the games properties dialog. Once owned, downloadable content is treated as an integral part of the game and Steam will automatically update the content when a patch is available and installs the content when the user installs the game. Since this is all handled by the Steam servers and the configuration of any DLC is done through the Steamworks control panel, there are only a couple of functions necessary in GameMaker Studio 2 to check for this extra content:



Back To Top

steam_user_owns_dlc

If your game has DLC created for it, you can use this function to check whether the user has bought it before accessing any files associated with it. The function will return true (1) if the player owns the content, false (0) if they don't own it or the given DLC ID is invalid, or -1 if they're not logged into Steam.

ℹ️ NOTE

Even if the user owns the DLC it doesn't mean that they have it installed in their local account, so you should additionally use the function steam_user_installed_dlc to make sure that it is before using it.


Syntax:

steam_user_owns_dlc(dlc_id);
Argument Type Description
dlc_id int64 The unique identifier for the DLC to be checked.


Returns:

Integer


Example:

global.Level_Max = 100;
if steam_user_owns_dlc(10354)
{
    if steam_user_installed_dlc(10354)
    {
        global.Level_max = 200;
    }
}

The above code will check to see if the user has bought, and installed, the DLC with the id 10354, and if so set a global variable to a different value.



Back To Top

steam_user_installed_dlc

If your game has DLC created for it, you can use this function to check and see whether the user has installed it before accessing any files associated with it. The function returns true if the player has the content installed, and false if the user does not, but note that the user must also own the DLC, so you should use the additional function of steam_user_owns_dlc to check that it is owned as well before using it.


Syntax:

steam_user_installed_dlc(dlc_id);
Argument Type Description
dlc_id int64 The unique identifier for the DLC to be checked.


Returns:

Bool


Example:

global.Level_Max = 100;
if (steam_user_owns_dlc(10354))
{
    if (steam_user_installed_dlc(10354))
    {
        global.Level_max = 200;
    }
}

The above code will check to see if the user has bought, and installed, the DLC with the id 10354, and if so set a global variable to a different value.



UGC

Back To Top

UGC

This section is for those users that have been given access to the Steam API for publishing your game to that platform and that want to use the possibilities that the Steam Workshop and Community gives you for adding and generating user content in your projects. The simplest form of user generated content is the ability for the user to take and share screenshots, which is facilitated using the following two functions:

ℹ️ NOTE

You need to have your game accepted for the Steam online store and have access to the developer areas of the Steam API documentation.

All subscribed UGC items will be downloaded by the Steam client automatically, and you should have code in the Steam Asynchronous Event to catch this and store the ID of the UGC that has been downloaded for use in the other UGC functions.

⚠️ IMPORTANT

Steam UGC IDs can be huge numbers This means that sometimes you may need to store these as a string rather than try and store them as a real value, especially if working with buffers or trying to write the value to a text file (since this will convert it to a simplified standard format like "6.6624e+003" which will cause issues being read back).

The normal workflow for getting UGC into your game would be as follows:

  1. The user would subscribe to an item (either from your game using steam_ugc_subscribe_item or from the client/browser). If done from the game you are able to "listen" to the callback from the Steam Async Event.
  2. When you get a successful subscription callback this means that your game is now downloading the UGC. You would then check if the item is installed (ie: download completed) with steam_ugc_get_item_install_info.

  3. If the item is not completely installed, you can use steam_ugc_get_item_update_info to track the download progress.

    The following sections explain all the functions required to get UGC functioning in GameMaker Studio 2:

Creating And Editing Content

The following functions are essentially "wrapper" functions for those supplied in the Steam API for creating and uploading content to their servers. As such, we recommend that you read over the linked Steam documentation before using them to gain a greater understanding of how they work: Creating And Uploading Content.

Consuming Content

Once your user content has been created and the workshop has it available for download, people can subscribe to it through the Steam App or through the Web portal. However GameMaker Studio 2 also includes the following functions to use the Steam API for creating and canceling subscriptions as well as for getting information about what the user is subscribed to currently:

Querying Content

There are also a large number of functions available to query the Steam API about the UGC items available:

Constants

This section also provides a set of constants to be used along side the functions provided above:



Back To Top

steam_is_screenshot_requested

This function will poll the Steam API to see if the key for taking a screenshot of the game has been pressed. The function will only return true for one step (game tick) when the key is pressed, and will returnfalse at all other times. Please note that if the screenshot key is pressed, this function will only return true once for each step that it is pressed, and return false for any subsequent calls within the same step . For example, if a screenshot is requested in the current frame and you call this function in the Step event to find that out, you will get true; however, if you call it again in Draw GUI to check whether a screenshot was requested, you will get false as the function had already been "used up" in the Step event. To use the function's return value multiple times within the same frame, it is recommended to store it in a variable and read that instead of calling the function again.

ℹ️ NOTE

This function does not take a screenshot for you. This only signals that the key has been pressed and you must use the GameMaker Studio 2 functions screen_save or screen_save_part to save a local copy of the file to be uploaded.


Syntax:

steam_is_screenshot_requested();


Returns:

Bool


Example:

if steam_is_screenshot_requested()
{
    var file = "Catch_The_Haggis_" + string(global.scrn_num) + ".png");
    screen_save(file)
    steam_send_screenshot(file, window_get_width(), window_get_height());
    global.scrn_num += 1;
}

The above code will poll the Steam API for a screenshot request and if it has been, a unique name for the image file will be generated, a screenshot will be taken, and the file will be sent to the Steam Community page for the user.



Back To Top

steam_send_screenshot

With this function you can upload a screenshot to the Steam Community profile page of the currently logged in user. The filename you supply is the name of the local file that was created when you took the screenshot using the GameMaker Studio 2 functions screen_save or screen_save_part. The width and height define the image size, and the function will return a value of 0 if it fails for whatever reason and a value greater than 0 if it succeeds.


Syntax:

steam_send_screenshot(filename, width, height);
Argument Type Description
filename string The name of the image file to upload.
width real The width of the image.
height real The height of the image.


Returns:

Real


Example:

if steam_is_screenshot_requested()
{
    var file = "Catch_The_Haggis_" + string(global.scrn_num) + ".png");
    screen_save(file)
    steam_send_screenshot(file, window_get_width(), window_get_height());
    global.scrn_num += 1;
}

The above code will poll the Steam API for a screenshot request and if it has been, a unique name for the image file will be generated, a screenshot will be taken, and the file will be sent to the Steam Community page for the user.



Back To Top

steam_ugc_create_item

This function is used to prepare the Workshop API and generate a published file ID for the item to be added. The function must be called before doing anything else with the item to be uploaded, as you will be required to use the unique published ID value that it returns in the Steam Async Event for updating. This is an asynchronous function that will return an asynchronous id and trigger the Steam Async Event when the task is finished.


Syntax:

steam_ugc_create_item(consumer_app_id, file_type);
Argument Type Description
consumer_app_id integer The unique App ID for your game on Steam.
file_type constant.UGCFileType One of the available file type constants (see UGCFileType constants).


Returns:

Real


Triggers:

Asynchronous Steam Event
Key Type Description
id real The asynchronous request ID
event_type string The string value "ugc_create_item"
result real This will either be the GML constant ugc_result_success or some other real number (see theSteam docs, for more details)
legal_agreement_required bool Will be true or false (see the Steam docs for more details)
published_file_id int64 This key holds the unique published ID for the item (you may need to cast it using the int64() function)


Extended Example:

In this example we first call the function and store the async ID value in a variable:

var app_id = steam_get_app_id();
new_item = steam_ugc_create_item(app_id, ugc_filetype_community);

This would then send off a request to the Steam API to create the new Workshop item, generating an async event which we would deal with as follows:

var event_id = async_load[? "id"];
if event_id == new_item
{
    var type = async_load[? "event_type"];
    if type == "ugc_create_item"
    {
        global.Publish_ID = async_load[? "published_file_id"];
    }
}

The above code checks the event type and if it is "ugc_create_item" then it retrieves the published file ID and stores it in a global variable for future reference.



Back To Top

steam_ugc_delete_item

This function attempts to delete a previously published UGC item. This is an asynchronous function that will return an asynchronous id and trigger the Steam Async Event when the task is finished.


Syntax:

steam_ugc_delete_item(ugc_query_handle);
Argument Type Description
ugc_query_handle real The query handle to use.


Returns:

Real


Triggers:

Asynchronous Steam Event
Key Type Description
id real The asynchronous request ID
event_type string The string value "ugc_item_delete"
result real This will either be the GML constant ugc_result_success or some other real number (see theSteam docs, for more details)


Example:

steam_ugc_delete_item(ugc_query_handle);

The above code creates a deletion request for ugc_query_handle.



Back To Top

steam_ugc_start_item_update

This function must be called before adding or updating information on a UGC item. You need to supply the unique App ID for your game on Steam, along with the unique published file ID that was returned for the item when you created it using the function steam_ugc_create_item. The function will return a unique update handle for the item, which you can then use in the UGC item functions to update (or add) information for uploading.


Syntax:

steam_ugc_start_item_update(consumer_app_id, published_file_id);
Argument Type Description
consumer_app_id real The unique App ID for your game on Steam.
published_file_id int64 The unique published file ID value for the item.


Returns:

Real


Example:

var app_id = steam_get_app_id();
var updateHandle = steam_ugc_start_item_update(app_id, global.Publish_ID);
steam_ugc_set_item_title(updateHandle, "My workshop item(3)!");
steam_ugc_set_item_description( updateHandle, "testing workshop...");
steam_ugc_set_item_visibility(updateHandle, ugc_visibility_public);
var tagArray;
tagArray[0] = "Test";
tagArray[1] = "New";
steam_ugc_set_item_tags(updateHandle, tagArray);
steam_ugc_set_item_preview(updateHandle, "promo.jpg");
steam_ugc_set_item_content(updateHandle, "WorkshopContent1");
requestId = steam_ugc_submit_item_update(updateHandle, "Version 1.2");

The above code gets the game ID, then uses that along with a previously stored published file ID to generate an update handle for the item. This handle is then used to update various pieces of information before the update is pushed to the Workshop servers.



Back To Top

steam_ugc_set_item_title

This function will set the title to be used for the given item. The function will return true if the API was successfully accessed and false if there was an issue.


Syntax:

steam_ugc_set_item_title(ugc_update_handle, title);
Argument Type Description
ugc_update_handle real The unique handle for the UGC to be updated (returned from steam_ugc_start_item_update)
title string The title (max 128 characters) to be used for the item.


Returns:

Bool


Example:

var app_id = steam_get_app_id();
var updateHandle = steam_ugc_start_item_update(app_id, global.Publish_ID);
steam_ugc_set_item_title(updateHandle, "My workshop item(3)!");
steam_ugc_set_item_description( updateHandle, "testing workshop...");
steam_ugc_set_item_visibility(updateHandle, ugc_visibility_public);
var tagArray;
tagArray[0] = "Test";
tagArray[1] = "New";
steam_ugc_set_item_tags(updateHandle, tagArray);
steam_ugc_set_item_preview(updateHandle, "promo.jpg");
steam_ugc_set_item_content(updateHandle, "WorkshopContent1");
requestId = steam_ugc_submit_item_update(updateHandle, "Version 1.2");

The above code gets the game ID, then uses that along with a previously stored published file ID to generate an update handle for the item. This handle is then used to update various pieces of information before the update is pushed to the Workshop servers.



Back To Top

steam_ugc_set_item_description

This function will set the description to be used for the given item. The function will return true if the API was successfully accessed and false if there was an issue.


Syntax:

steam_ugc_set_item_description(ugc_update_handle, description);
Argument Type Description
ugc_update_handle real The unique handle for the UGC to be updated (returned from steam_ugc_start_item_update)
description string The description (max 8000 characters) to be used for the item.


Returns:

Bool


Example:

var app_id = steam_get_app_id();
var updateHandle = steam_ugc_start_item_update(app_id, global.Publish_ID);
steam_ugc_set_item_title(updateHandle, "My workshop item(3)!");
steam_ugc_set_item_description( updateHandle, "testing workshop...");
steam_ugc_set_item_visibility(updateHandle, ugc_visibility_public);
var tagArray;
tagArray[0] = "Test";
tagArray[1] = "New";
steam_ugc_set_item_tags(updateHandle, tagArray);
steam_ugc_set_item_preview(updateHandle, "promo.jpg");
steam_ugc_set_item_content(updateHandle, "WorkshopContent1");
requestId = steam_ugc_submit_item_update(updateHandle, "Version 1.2");

The above code gets the game ID, then uses that along with a previously stored published file ID to generate an update handle for the item. This handle is then used to update various pieces of information before the update is pushed to the Workshop servers.



Back To Top

steam_ugc_set_item_visibility

This function will set the visibility of the given item, using one of the UGCFileVisibility constants. The function will return true if the API was successfully accessed and false if there was an issue.


Syntax:

steam_ugc_set_item_visibility(ugc_update_handle, visibility);
Argument Type Description
ugc_update_handle real The unique handle for the UGC to be updated (returned from steam_ugc_start_item_update)
visibility constant.UGCFileVisibility The visibility to be used for the item (see UGCFileVisibility constant)


Returns:

Bool


Example:

var app_id = steam_get_app_id();
var updateHandle = steam_ugc_start_item_update(app_id, global.Publish_ID);
steam_ugc_set_item_title(updateHandle, "My workshop item(3)!");
steam_ugc_set_item_description( updateHandle, "testing workshop...");
steam_ugc_set_item_visibility(updateHandle, ugc_visibility_public);
var tagArray;
tagArray[0] = "Test";
tagArray[1] = "New";
steam_ugc_set_item_tags(updateHandle, tagArray);
steam_ugc_set_item_preview(updateHandle, "promo.jpg");
steam_ugc_set_item_content(updateHandle, "WorkshopContent1");
requestId = steam_ugc_submit_item_update(updateHandle, "Version 1.2");

The above code gets the game ID, then uses that along with a previously stored published file ID to generate an update handle for the item. This handle is then used to update various pieces of information before the update is pushed to the Workshop servers.



Back To Top

steam_ugc_set_item_tags

This function will set the tags to be used for the given item. The tags should be added to a 1D array as string elements and the array passed to the function. The function will return true if the API was successfully accessed and false if there was an issue.


Syntax:

steam_ugc_set_item_tags(ugc_update_handle, tags);
Argument Type Description
ugc_update_handle real The unique handle for the UGC to be updated (returned from steam_ugc_start_item_update)
tags string The tags (as an string json array) to be used for the item.


Returns:

Bool


Example:

var app_id = steam_get_app_id();
var updateHandle = steam_ugc_start_item_update(app_id, global.Publish_ID);
steam_ugc_set_item_title(updateHandle, "My workshop item(3)!");
steam_ugc_set_item_description( updateHandle, "testing workshop...");
steam_ugc_set_item_visibility(updateHandle, ugc_visibility_public);
var tagArray;
tagArray[0] = "Test";
tagArray[1] = "New";
steam_ugc_set_item_tags(updateHandle, string(tagArray));
steam_ugc_set_item_preview(updateHandle, "promo.jpg");
steam_ugc_set_item_content(updateHandle, "WorkshopContent1");
requestId = steam_ugc_submit_item_update(updateHandle, "Version 1.2");

The above code gets the game ID, then uses that along with a previously stored published file ID to generate an update handle for the item. This handle is then used to update various pieces of information before the update is pushed to the Workshop servers.



Back To Top

steam_ugc_set_item_content

This function will set the content path to be used for the given item, and it should be a relative path to the folder which contains the content files to upload - which in turn should be in the save are or the game bundle (ie: an included file). The function will return true if the API was successfully accessed and false if there was an issue.


Syntax:

steam_ugc_set_item_content(ugc_update_handle, content);
Argument Type Description
ugc_update_handle real The unique handle for the UGC to be updated (returned from steam_ugc_start_item_update)
content string The content path to be used for the item


Returns:

Bool


Example:

var app_id = steam_get_app_id();
var updateHandle = steam_ugc_start_item_update(app_id, global.Publish_ID);
steam_ugc_set_item_title(updateHandle, "My workshop item(3)!");
steam_ugc_set_item_description( updateHandle, "testing workshop...");
steam_ugc_set_item_visibility(updateHandle, ugc_visibility_public);
var tagArray;
tagArray[0] = "Test";
tagArray[1] = "New";
steam_ugc_set_item_tags(updateHandle, tagArray);
steam_ugc_set_item_preview(updateHandle, "promo.jpg");
steam_ugc_set_item_content(updateHandle, "WorkshopContent1");
requestId = steam_ugc_submit_item_update(updateHandle, "Version 1.2");

The above code gets the game ID, then uses that along with a previously stored published file ID to generate an update handle for the item. This handle is then used to update various pieces of information before the update is pushed to the Workshop servers.



Back To Top

steam_ugc_set_item_preview

This function will set the preview image to be used for the given item. The image should be supplied as either a PNG, JPG or GIF format file with a maximum size of 1MB. The path to the image should be a relative path in the save are or the game bundle (ie: an included file). The function will return true if the API was successfully accessed and false if there was an issue.


Syntax:

steam_ugc_set_item_preview(ugc_update_handle, preview);
Argument Type Description
ugc_update_handle real The unique handle for the UGC to be updated (returned from steam_ugc_start_item_update)
preview string The preview image (JPG, GIF or PNG - max size 1MB) to be used for the item.


Returns:

Bool


Example:

var app_id = steam_get_app_id();
var updateHandle = steam_ugc_start_item_update(app_id, global.Publish_ID);
steam_ugc_set_item_title(updateHandle, "My workshop item(3)!");
steam_ugc_set_item_description( updateHandle, "testing workshop...");
steam_ugc_set_item_visibility(updateHandle, ugc_visibility_public);
var tagArray;
tagArray[0] = "Test";
tagArray[1] = "New";
steam_ugc_set_item_tags(updateHandle, tagArray);
steam_ugc_set_item_preview(updateHandle, "promo.jpg");
steam_ugc_set_item_content(updateHandle, "WorkshopContent1");
requestId = steam_ugc_submit_item_update(updateHandle, "Version 1.2");

The above code gets the game ID, then uses that along with a previously stored published file ID to generate an update handle for the item. This handle is then used to update various pieces of information before the update is pushed to the Workshop servers.



Back To Top

steam_ugc_submit_item_update

This function will submit the UGC item indexed by the given handle to the Steam Workshop servers, adding the change notes to be used for the given item. This is an asynchronous function that will return an asynchronous id and trigger the Steam Async Event when the task is finished.


Syntax:

steam_ugc_submit_item_update(ugc_update_handle, change_note);
Argument Type Description
ugc_update_handle real The unique handle for the UGC to be updated (returned from steam_ugc_start_item_update)
change_note string The change notes to be used for the item.


Returns:

Real


Triggers:

Asynchronous Steam Event
Key Type Description
id real The asynchronous request ID
event_type string The string value "ugc_update_item"
result real This will either be the GML constant ugc_result_success or some other real number (see theSteam docs, for more details)
legal_agreement_required bool Will be true or false (see the Steam docs for more details)


Example:

var app_id = steam_get_app_id();
var updateHandle = steam_ugc_start_item_update(app_id, global.Publish_ID);
steam_ugc_set_item_title(updateHandle, "My workshop item(3)!");
steam_ugc_set_item_description( updateHandle, "testing workshop...");
steam_ugc_set_item_visibility(updateHandle, ugc_visibility_public);
var tagArray;
tagArray[0] = "Test";
tagArray[1] = "New";
steam_ugc_set_item_tags(updateHandle, tagArray);
steam_ugc_set_item_preview(updateHandle, "promo.jpg");
steam_ugc_set_item_content(updateHandle, "WorkshopContent1");
requestId = steam_ugc_submit_item_update(updateHandle, "Version 1.2");

The above code gets the game ID, then uses that along with a previously stored published file ID to generate an update handle for the item. This handle is then used to update various pieces of information before the update is pushed to the Workshop servers.



---

Back To Top

steam_ugc_get_item_update_progress

This function can be used to track the update status for an item. You give the item handle (as returned by the function [steam_ugc_start_item_update](#steam_ugc_start_item_update)) and an empty [DS map](https://manual.yoyogames.com/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/DS_Maps.htm) which will then be populated with the update information (see table below)
If there is an error the function will return `false` and the map will be empty, otherwise the function returns `true`.


Syntax:

steam_ugc_get_item_update_progress(ugc_update_handle, info_map);
Argument Type Description
ugc_update_handle integer The unique handle for the UGC to be updated.
info_map DS Map ID A (previously created) DS map index.
Key Type Description
status_code real The Steam status code
status_string string A string for the current status
bytes_processed real The bytes processed so far
bytes_total real The total number of bytes in the update


Returns:

Bool


Example:

var uploadMap = ds_map_create();

  steam_ugc_get_item_update_progress(global.itemHandle, uploadMap);

  var statusCode = uploadMap[? "status_code"];

  var status = uploadMap[? "status_string"];

  var processed = uploadMap[? "bytes_processed"];

  var total = uploadMap[? "bytes_total"];

  draw_text(32, 0, "Upload info for item:" + string(global.itemHandle));

  draw_text(32, 15, "status code:" + string(statusCode));

  draw_text(32, 30, "status:" + string(status));

  draw_text(32, 45, "bytes processed:" +string(processed));

  draw_text(32, 60, "bytes total:" + string( total));

  ds_map_destroy(uploadMap);
The above code will query the upload status of the item indexed in the global variable &quot;itemHandle&quot;, using a `DS Map` to store the information. This is then parsed and the resulting values drawn to the screen.

<!-- KEYWORDS

steam_ugc_get_item_update_progress -->

Back To Top

steam_ugc_subscribe_item

This function can be used to subscribe to a UGC item. This is an asynchronous function that will return an asynchronous id and trigger the Steam Async Event when the task is finished.


Syntax:

steam_ugc_subscribe_item(published_file_id);
Argument Type Description
published_file_id int64 The unique file ID for the UGC to subscribe to.


Returns:

Real


Triggers:

Asynchronous Steam Event
Key Type Description
id real The asynchronous request ID
event_type string The string value "ugc_subscribe_item"
result real This will either be the GML constant ugc_result_success or some other real number (see theSteam docs, for more details)
published_file_id int64 This key holds the unique published ID for the item (you may need to cast it using the int64 function, before passing it to subsequent functions)


Example:

steam_sub = steam_ugc_subscribe_item(global.pubFileID);

The above code will subscribe (and download) the item with the file ID stored in the global variable "pubFileID".



Back To Top

steam_ugc_unsubscribe_item

This function can be used to unsubscribe from a UGC item. This is an asynchronous function that will return an asynchronous id and trigger the Steam Async Event when the task is finished.


Syntax:

steam_ugc_unsubscribe_item(published_file_id);
Argument Type Description
published_file_id int64 The unique file ID for the UGC to unsubscribe from.


Returns:

Real


Triggers:

Asynchronous Steam Event
Key Type Description
id real The asynchronous request ID
event_type string The string value "ugc_unsubscribe_item"
result real This will either be the GML constant ugc_result_success or some other real number (see theSteam docs, for more details)
published_file_id int64 This key holds the unique published ID for the item (you may need to cast it using the int64 function)


Example:

steam_sub = steam_ugc_unsubscribe_item(global.pubFileID);

The above code will unsubscribe (and remove) the item with the file ID stored in the global variable "pubFileID".



Back To Top

steam_ugc_num_subscribed_items

This function can be used to get the number of items that the current user has subscribed to.


Syntax:

steam_ugc_num_subscribed_items();


Returns:

Real


Example:

numSub = steam_ugc_num_subscribed_items();

The above code will store the number of subscribed items in a variable.



---

Back To Top

steam_ugc_get_subscribed_items

This function will populate a DS list with all the published file IDs for the items that the user is currently subscribed to. You must first create the list and store the index in a variable, then pass this to the function.
The function will return ```true` if everything is correct and the Steam API is initialized, or `false` if there is an error.


Syntax:

steam_ugc_get_subscribed_items(item_list);
Argument Type Description
item_list DS List ID A (previously created) DS list index.


Returns:

Bool


Example:

steam_list = ds_list_create();

  steam_ugc_get_subscribed_items(steam_list);
The above code will create an empty DS list and then populate it with the file IDs for all subscribed items for the user.

<!-- KEYWORDS

steam_ugc_get_subscribed_items -->

---

Back To Top

steam_ugc_get_item_install_info

This function can be used to retrieve information about any given published file item that has been subscribed to and downloaded to the Steam local storage area for your game. You give the item ID and supply the index to an empty [DS map](https://manual.yoyogames.com/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/DS_Maps.htm) which will then be populated with the install information (see table below).
If the item exists (ie.: as been subscribed and download was complete) then the function will return `true` and populate the map, otherwise it will return `false` and the map will remain empty.


Syntax:

steam_ugc_get_item_install_info(published_file_id, info_map);
Argument Type Description
published_file_id int64 The unique handle for the UGC to be updated.
info_map DS Map ID A (previously created) DS map index.
Key Type Description
size_on_disk real The file size on disk (in bytes)
legacy_item bool Will be true or false depending on whether it is a legacy file or not
folder string This is the full path to the installed content ( please refer to "Item Installation" in Steam SDK docs, as "legacy" items uploaded with the old method, are treated differently)


Returns:

Bool


Example:

var item_map = ds_map_create();

  steam_ugc_get_item_install_info(global.fileID, item_map);
The above code will query the install status of the item indexed in the global variable &quot;fileID&quot;, using a `DS Map` to store the information.

<!-- KEYWORDS

steam_ugc_get_item_install_info -->

---

Back To Top

steam_ugc_get_item_update_info

This function can be used to retrieve information about the current download state for the given file ID. You give the item ID and supply the index to an empty [DS map](https://manual.yoyogames.com/GameMaker_Language/GML_Reference/Data_Structures/DS_Maps/DS_Maps.htm) which will then be populated with the update information (see table below).
If the item exists then the function will return `true` and populate the map, otherwise it will return `false` and the map will remain empty.


Syntax:

steam_ugc_get_item_update_info(published_file_id, info_map);
Argument Type Description
published_file_id int64 The unique file ID for the UGC to be checked.
info_map DS Map ID A (previously created) DS map index.
Key Type Description
needs_update bool Whether the item needs an update or not
is_downloading bool Whether the item is currently downloading or not
bytes_downloaded real The number of bytes that has been downloaded
bytes_total real The total size (number of bytes) required for the item on disk


Returns:

Bool


Example:

var info_map = ds_map_create();

  var info = steam_ugc_get_item_update_info(global.fileID, info_map);

  if info

  {

  draw_text(32, 15, "needs_update: " + string(info_map[? "needs_update"]));

  draw_text(32, 30, "is_downloading: " + string(info_map[? "is_downloading"]));

  draw_text(32, 45, "bytes_downloaded: " + string(info_map[? "bytes_downloaded"]));

  draw_text(32, 60, "bytes_total: " + string(info_map[? "bytes_total"]));

  }
The above code will query the download status of the item indexed in the global variable &quot;fileID&quot;, using a `DS Map` to store the information.

<!-- KEYWORDS

steam_ugc_get_item_update_info -->

Back To Top

steam_ugc_request_item_details

This function can be used to retrieve information about a given file ID. You give the file ID and supply a maximum age for checking (see the Steam docs for more information). This is an asynchronous function that will return an asynchronous id and trigger the Steam Async Event when the task is finished.


Syntax:

steam_ugc_request_item_details(published_file_id, max_age_seconds);
Argument Type Description
published_file_id real The unique file ID for the UGC to be checked.
max_age_seconds real The age of the data to check (recommended 30 - 60 seconds).


Returns:

Real


Triggers:

Asynchronous Steam Event
Key Type Description
id real The asynchronous request ID
event_type string The string value "ugc_item_details"
result real This will either be the GML constant ugc_result_success or some other real number (see theSteam docs, for more details)
cached_data bool Will be true if the returned details are from the local cache or false if they are taken from the server
published_file_id int64 This key holds the unique published ID for the item (you may need to cast it using the int64 function)
file_type string The type of file used
creator_app_id real The Steam ID of the item creator
consumer_app_id real The Steam ID of the item consumer
title string The title of the item
description string The description of the item
steam_id_owner real The Steam ID of the item owner
time_created real The time the item was first created
time_uploaded real The last time the item was updated
time_added_to_user_list real The time that the item was subscribed to
visibility constant.UGCFileVisibility The visibility of the item (see UGCFileVisibility constant)
banned bool Whether the item has been banned or not
accepted_for_use bool Whether the item has been accepted for use or not
tags_truncated array Short version of the tags as an array
tags array An array of the tags for the item
handle_file int64 The unique file handle for the item
handle_preview_file int64 The unique handle for the image preview for the item (can be used with steam_ugc_download to download a preview image)
filename string The name of the item file
file_size real The size of the item file
preview_file_size real The size of the preview image
url string The full URL for the item
up_votes real The number of up-votes received
down_votes real The number of down-votes received
score real The overall score of the item
account_id_owner real The account ID from the Steam ID owner (this can be used in function steam_ugc_create_query_user_ex)


Extended Example:

In this example we send off a details request for an item and then parse the resulting async_load DS map to set some variables. First we send of the request:

steam_details = steam_ugc_request_item_details(global.fileID, 60);

The above code will request details on the item with the file ID stored in the global variable and will trigger a Steam Async event with the returned information. In this event we can then parse the map and store some of the values in variables which can then be used to display the information to the user:

var map_id = async_load[? "id"];
var result = async_load[? "result"];
if (map_id == steam_details) && (result == ugc_result_success)
{
    mTitle = async_load[? "title"];
    mDesc = async_load[? "description"];
    mTags = async_load[? "tags"];
    m_hPreviewFile = async_load[? "handle_preview_file"];
    m_hOwnerSteamId = async_load[? "steam_id_owner"];
    mOwnerAccountId = async_load[? "account_id_owner"];
    mPubFileId = async_load[? "published_file_id"];
    mScore = async_load[? "score"];
}



Back To Top

steam_ugc_create_query_user

This function can be used to query the UGC data base. The function automatically uses the default ID for the app, user and assumes that the query is being done by the consumer (rather than the creator). The function requires you to use the following constants for the type of data to query (UGCListType), the type of item to match (UGCMatchType) and the order in which the returned items will be sorted (UGCListSortOrder), as well as a page number - note that a query will return a maximum number of 50 items. The function returns a unique query handle value which should be stored in a variable for use in the other query functions. Note that this function only prepares the query but does not actually send it - for that you must call the function steam_ugc_send_query - and you can use further steam_ugc_query_*() functions to refine the search request before it is actually sent.


Syntax:

steam_ugc_create_query_user(list_type, match_type, sort_order, page);
Argument Type Description
list_type constant.UGCListType The type of data list to create (see UGCListType constants)
match_type constant.UGCMatchType The type of UGC items to query (see UGCMatchType constants)
sort_order constant.UGCListSortOrder The way that data should be ordered (see UGCListSortOrder constants)
page real The page number to query.


Returns:

Real


Example:

query_handle = steam_ugc_create_query_user(ugc_list_Published, ugc_match_Items, ugc_sortorder_TitleAsc, 1);

The above code creates a query request and stores it's handle in a variable for future use.



Back To Top

steam_ugc_create_query_user_ex

This function can be used to query the UGC data base. The function requires the ID value for the user and the ID of the game that is going to consume the item and/or the ID of the game that created the item. You also need to use the following constants for the type of data to query (UGCListType), the type of item to query (UGCMatchType) and the order in which the returned items will be sorted (UGCListSortOrder), as well as a page number - note that a query will return a maximum number of 50 items. The function returns a unique query handle value which should be stored in a variable for use in the other query functions. Note that this function only prepares the query but does not actually send it - for that you must call the function steam_ugc_send_query - and you can use further steam_ugc_query_*() functions to refine the search request before it is actually sent.


Syntax:

steam_ugc_create_query_user_ex(list_type, match_type, sort_order, page, account_id, creator_app_id, consumer_app_id);
Argument Type Description
list_type constant.UGCListType The type of data list to create (see UGCListType constants)
match_type constant.UGCMatchType The type of UGC items to query (see UGCMatchType constants)
sort_order constant.UGCListSortOrder The way that data should be ordered (see UGCListSortOrder constants)
page real The page number to query
account_id real The Steam account ID
creator_app_id real The item creator app ID
consumer_app_id real The consumer app ID


Returns:

Real


Example:

query_handle = steam_ugc_create_query_user_ex(ugc_list_Published, ugc_match_Items, ugc_sortorder_TitleAsc, page, global.AccountID, 0, global.GameID);

The above code creates a query request and stores it's handle in a variable for future use.



Back To Top

steam_ugc_create_query_all

This function can be used to query the UGC data base using some predefined query types. The function requires the following constants for the type of query to create (UGCQueryType), the type of item to match (UGCMatchType) and the page number to query - note that a query will return a maximum number of 50 items. The function returns a unique query handle value which should be stored in a variable for use in the other query functions. Note that this function only prepares the query but does not actually send it - for that you must call the function steam_ugc_send_query - and you can use further steam_ugc_query_*() functions to refine the search request before it is actually sent.


Syntax:

steam_ugc_create_query_all(query_type, match_type, page);
Argument Type Description
query_type constant.UGCQueryType The type of query to create (see UGCQueryType constants)
match_type constant.UGCMatchType The type of UGC items to query (see UGCMatchType constants)
page real The page number to query


Returns:

Real


Example:

query_handle = steam_ugc_create_query_all(ugc_query_RankedByVote, ugc_match_Items, 1);

The above code creates a general query request and stores it's handle in a variable for future use.



Back To Top

steam_ugc_create_query_all_ex

This function can be used to query the UGC data base. The function requires the ID of the game that is going to consume the item and/or the ID of the game that created the item, and you need to use the following constants for the type of query to create (UGCQueryType), the type of item to match (UGCMatchType) and the page number to query. Note that a query will return a maximum number of 50 items. The function returns a unique query handle value which should be stored in a variable for use in the other query functions. Note that this function only prepares the query but does not actually send it - for that you must call the function steam_ugc_send_query - and you can use further steam_ugc_query_*() functions to refine the search request before it is actually sent.


Syntax:

steam_ugc_create_query_all_ex(query_type, match_type, page, creator_app_id, consumer_app_id);
Argument Type Description
query_type constant.UGCQueryType The type of query to create (see UGCQueryType constants)
match_type constant.UGCMatchType The type of UGC items to query (see UGCMatchType constants)
page real The page number to query
creator_app_id integer The item creator app ID
consumer_app_id integer The consumer app ID


Returns:

Real


Example:

query_handle = steam_ugc_create_query_all_ex(ugc_query_RankedByVote, page, global.AccountID, 0, global.GameID);

The above code creates a query request and stores it's handle in a variable for future use.



Back To Top

steam_ugc_query_set_cloud_filename_filter

This function can be used to further filter any given UGC query, specifically to check and see if a Workshop item file name must match or not. The query handle is the value returned when you created the query (using, for example, steam_ugc_create_query_user) and the second argument is either true orfalse` depending on whether you require the file names to match. The function will returntrueif the query filter was correctly set, orfalse` otherwise.


Syntax:

steam_ugc_query_set_cloud_filename_filter(ugc_query_handle, should_match);
Argument Type Description
ugc_query_handle integer The query handle to use.
match_cloud_filename bool Sets whether the UGC item file name should match or not.


Returns:

Bool


Example:

var query_handle = steam_ugc_create_query_all(ugc_query_RankedByVote, ugc_match_Items, 1);
steam_ugc_query_set_cloud_filename_filter(query_handle, true);
steam_ugc_query_add_excluded_tag(query_handle, "nasty chips");
steam_ugc_query_set_return_long_description(query_handle, true);
steam_ugc_query_set_allow_cached_response(query_handle, true);
query_ID = steam_ugc_send_query(query_handle);

The above code creates a query request and stores it's handle in a local variable for future use in the rest of the functions which further define the query request before sending the query.



Back To Top

steam_ugc_query_set_match_any_tag

This function can be used to further filter any given UGC query, specifically to switch on or off tag matching. The query handle is the value returned when you created the query (using, for example, steam_ugc_create_query_user) and the second argument is either true orfalse``depending on whether you require a check for matching tags. The function will return true if the query filter was correctly set, or false otherwise.


Syntax:

steam_ugc_query_set_match_any_tag(ugc_query_handle, match_any_tag);
Argument Type Description
ugc_query_handle integer The query handle to use.
match_any_tag bool Sets whether the UGC item tags should match anything or not.


Returns:

Bool


Example:

var query_handle = steam_ugc_create_query_all(ugc_query_RankedByVote, ugc_match_Items, 1);
steam_ugc_query_set_match_any_tag(query_handle, false);
steam_ugc_query_add_excluded_tag(query_handle, "walking simulator");
steam_ugc_query_set_return_long_description(query_handle, true);
steam_ugc_query_set_allow_cached_response(query_handle, true);
query_ID = steam_ugc_send_query(query_handle);

The above code creates a query request and stores it's handle in a local variable for future use in the rest of the functions which further define the query request before sending the query.



Back To Top

steam_ugc_query_set_search_text

This function can be used to further filter any given UGC query, specifically to search for the given string in the title and description of the UGC items. The query handle is the value returned when you created the query (using, for example, steam_ugc_create_query_user) and the second argument is a string you want to use as the search term. The function will return true if the query filter was correctly set, or false otherwise.


Syntax:

steam_ugc_query_set_search_text(ugc_query_handle , search_text);
Argument Type Description
ugc_query_handle real The query handle to use.
search_text string The search text to use for the query.


Returns:

Bool


Example:

var query_handle = steam_ugc_create_query_all(ugc_query_RankedByVote, ugc_match_Items, 1);
steam_ugc_query_set_search_text(query_handle, "texture");
steam_ugc_query_set_return_long_description(query_handle, true);
steam_ugc_query_set_allow_cached_response(query_handle, true);
query_ID = steam_ugc_send_query(query_handle);

The above code creates a query request and stores it's handle in a local variable for future use in the rest of the functions which further define the query request before sending the query.



Back To Top

steam_ugc_query_set_ranked_by_trend_days

This function can be used to further filter any UGC query made using the ugc_query_RankedByTrend constant (UGCQueryType), specifically to search over a number of days. The query handle is the value returned when you created the query (using, for example, steam_ugc_create_query_user) and the second argument is the number of days over which you want the query to run. The function will return true if the query filter was correctly set, or false otherwise.


Syntax:

steam_ugc_query_set_ranked_by_trend_days(ugc_query_handle, days);
Argument Type Description
ugc_query_handle real The query handle to use.
days real The number of days to query.


Returns:

Bool


Example:

var query_handle = steam_ugc_create_query_all(ugc_query_RankedByTrend, ugc_match_Items, 1);
steam_ugc_query_set_ranked_by_trend_days(query_handle, 5);
steam_ugc_query_set_return_long_description(query_handle, true);
steam_ugc_query_set_allow_cached_response(query_handle, true);
query_ID = steam_ugc_send_query(query_handle);

The above code creates a query request and stores it's handle in a local variable for future use in the rest of the functions which further define the query request before sending the query.



Back To Top

steam_ugc_query_add_required_tag

This function can be used to further filter any given UGC query, specifically to search only those UGC items with the given tag. The query handle is the value returned when you created the query (using, for example, steam_ugc_create_query_user) and the second argument is a string you want to use as the tag to include. The function will return true if the query filter was correctly set, or false otherwise.


Syntax:

steam_ugc_query_add_required_tag(ugc_query_handle, tag_name);
Argument Type Description
ugc_query_handle integer The query handle to use.
tag_name string The tag name to include.


Returns:

Bool


Example:

var query_handle = steam_ugc_create_query_all(ugc_query_RankedByTrend, ugc_match_Items, 1);
steam_ugc_query_add_required_tag(query_handle, "RPG");
steam_ugc_query_set_return_long_description(query_handle, true);
steam_ugc_query_set_allow_cached_response(query_handle, true);
query_ID = steam_ugc_send_query(query_handle);

The above code creates a query request and stores it's handle in a local variable for future use in the rest of the functions which further define the query request before sending the query.



Back To Top

steam_ugc_query_add_excluded_tag

This function can be used to further filter any given UGC query, specifically to exclude a given UGC from the query request. The query handle is the value returned when you created the query (using, for example, steam_ugc_create_query_user) and the second argument is a string you want to use as the tag to exclude. The function will return true if the query filter was correctly set, or false otherwise.


Syntax:

steam_ugc_query_add_excluded_tag(ugc_query_handle, tag_name);
Argument Type Description
ugc_query_handle integer The query handle to use.
tag_name string The tag name to exclude.


Returns:

Bool


Example:

var query_handle = steam_ugc_create_query_all(ugc_query_RankedByVote, ugc_match_Items, 1);
steam_ugc_query_add_excluded_tag(query_handle, "walking simulator");
steam_ugc_query_set_return_long_description(query_handle, true);
steam_ugc_query_set_allow_cached_response(query_handle, true);
query_ID = steam_ugc_send_query(query_handle);

The above code creates a query request and stores it's handle in a local variable for future use in the rest of the functions which further define the query request before sending the query.



Back To Top

steam_ugc_query_set_return_long_description

This function can be used to further filter any given UGC query, specifically to retrieve the long description text in the call back event triggered when the query was sent. The query handle is the value returned when you created the query (using, for example, steam_ugc_create_query_user) and the second argument is either true orfalse``. The function will return true if the query filter was correctly set, or false otherwise.


Syntax:

steam_ugc_query_set_return_long_description(ugc_query_handle, should_return);
Argument Type Description
ugc_query_handle real The query handle to use.
long_description bool Whether to have the query return the long description text.


Returns:

Bool


Example:

var query_handle = steam_ugc_create_query_all(ugc_query_RankedByVote, ugc_match_Items, 1);
steam_ugc_query_set_return_long_description(query_handle, true);
steam_ugc_query_set_allow_cached_response(query_handle, true);
query_ID = steam_ugc_send_query(query_handle);

The above code creates a query request and stores it's handle in a local variable for future use in the rest of the functions which further define the query request before sending the query.



Back To Top

steam_ugc_query_set_return_total_only

This function can be used to further filter any given UGC query, specifically to request only the number of results without any other information (meaning that the DS map generated by the send function will contain the key "num_results" without any further map data). The query handle is the value returned when you created the query (using, for example, steam_ugc_create_query_user) and the second argument is either true orfalse``. The function will return true if the query filter was correctly set, or false otherwise.


Syntax:

steam_ugc_query_set_return_total_only(ugc_query_handle , total_only);
Argument Type Description
ugc_query_handle real The query handle to use.
total_only bool Whether to have the query return only the total number of hits or not.


Returns:

Bool


Example:

var query_handle = steam_ugc_create_query_all(ugc_query_RankedByVote, ugc_match_Items, 1);
steam_ugc_query_set_return_total_only(query_handle, true);
steam_ugc_query_set_allow_cached_response(query_handle, true);
query_ID = steam_ugc_send_query(query_handle);

The above code creates a query request and stores it's handle in a local variable for future use in the rest of the functions which further define the query request before sending the query.



Back To Top

steam_ugc_query_set_allow_cached_response

This function can be used to further filter any given UGC query, specifically to request that the query check the local cache rather than online. The query handle is the value returned when you created the query (using, for example, steam_ugc_create_query_user) and the second argument is either true orfalse````. The function will return true if the query filter was correctly set, or false otherwise.


Syntax:

steam_ugc_query_set_allow_cached_response(ugc_query_handle , check_cache);
Argument Type Description
ugc_query_handle integer The query handle to use.
cache bool Whether to have the query check the local cache or not.


Returns:

Bool


Example:

var query_handle = steam_ugc_create_query_all(ugc_query_RankedByTrend, ugc_match_Items, 1);
steam_ugc_query_add_required_tag(query_handle, "RPG");
steam_ugc_query_set_return_long_description(query_handle, true);
steam_ugc_query_set_allow_cached_response(query_handle, true);
query_ID = steam_ugc_send_query(query_handle);

The above code creates a query request and stores it's handle in a local variable for future use in the rest of the functions which further define the query request before sending the query.



---

Back To Top

steam_ugc_send_query

This function can be used to send a query request. You first define the query using one of the following function:


Syntax:

steam_ugc_send_query(ugc_query_handle);
Argument Type Description
ugc_query_handle real The query handle to send.


Returns:

Real


Triggers:

Asynchronous Steam Event
Key Type Description
id real The asynchronous request ID
event_type string The string value "ugc_query"
result real This will either be the GML constant ugc_result_success or some other real number (see theSteam docs, for more details)
cached_data bool Will be true if the returned details are from the local cache or false if they are taken from the server
total_matching real The total number of matching results
num_results real The number of results returned (max 50)
results_list DS List ID A DS list index, where each list entry is a DS Map index containing details of the particular item (see table below)
Key Type Description
published_file_id int64 This key holds the unique published ID for the item (you may need to cast it using the int64 function)
file_type string The type of file used
creator_app_id real The Steam ID of the item creator
consumer_app_id real The Steam ID of the item consumer
title string The title of the item
description string The description of the item
steam_id_owner real The Steam ID of the item owner
time_created real The time the item was first created
time_uploaded real The last time the item was updated
time_added_to_user_list real The time that the item was subscribed to
visibility constant.UGCFileVisibility The visibility of the item (see UGCFileVisibility constant)
banned bool Whether the item has been banned or not
accepted_for_use bool Whether the item has been accepted for use or not
tags_truncated array Short version of the tags as an array
tags array An array of the tags for the item
handle_file int64 The unique file handle for the item
handle_preview_file int64 The unique handle for the image preview for the item (can be used with steam_ugc_download to download a preview image)
filename string The name of the item file
file_size real The size of the item file
preview_file_size real The size of the preview image
url string The full URL for the item
up_votes real The number of up-votes received
down_votes real The number of down-votes received
score real The overall score of the item
account_id_owner real The account ID from the Steam ID owner (can be used in the function steam_ugc_create_query_user)


Example:

var query_handle = steam_ugc_create_query_all(ugc_query_RankedByTrend, ugc_match_Items, 1);

  steam_ugc_query_add_required_tag(query_handle, "RPG");

  steam_ugc_query_set_return_long_description(query_handle, true);

  steam_ugc_query_set_allow_cached_response(query_handle, true);

  query_ID = steam_ugc_send_query(query_handle);
The above code creates a query request and stores it&#39;s handle in a local variable for future use in the rest of the functions which further define the query request before sending the query.

<!-- KEYWORDS

steam_ugc_send_query -->

Back To Top

steam_ugc_download

With this function you can download a preview image for any given UGC item. The ugc_handle is the unique identifying value for the image (which you can get using the function steam_ugc_send_query), and the destination filename is the name (and local path within the Steam sandbox) that you wish to give the image file when the download is complete. This is an asynchronous function that will return an asynchronous id and trigger the Steam Async Event when the task is finished.


Syntax:

steam_ugc_download(ugc_handle, dest_filename);
Argument Type Description
ugc_handle int64 The unique handle for the preview to be downloaded.
dest_filename string The file name to save the preview with.


Returns:

Real


Triggers:

Asynchronous Steam Event
Key Type Description
id real The asynchronous request ID
event_type string The string value "ugc_create_item"
result real This will either be the GML constant ugc_result_success or some other real number (see theSteam docs under EResult , for more details)
original_filename string This key holds the original name of the image file on the server (a string)
dest_filename string This key holds the image file name you passed in (a string)
ugc_handle integer


Extended Example:

In this example we first call the function and store the async ID value in a variable:

steam_get = steam_ugc_download(steam_handle, "\UGC\Preview_file.png");

This would then send off a file request to the Steam API, generating an async event which we would deal with as follows:

var event_id = async_load[? "id"];
if event_id == steam_get
{
    var type = async_load[? "event_type"];
    if type == "ugc_download"
    {
        sprite_delete(preview_sprite);
        preview_sprite = sprite_add(async_load[? "dest_filename"], 0, false, false, 0, 0);
    }
}

The above code checks the event type and then creates a sprite from the downloaded image.



Back To Top

UGCFileType

These constants specify the way that a shared file will be shared with the community and should be used while creating a new item with steam_ugc_create_item.

ℹ️ NOTE

See Steam Docs for more details.

UGC File Type Constant Description
ugc_filetype_community This is used to create files that will be uploaded and made available to anyone in the community
ugc_filetype_microtrans This is used to describe files that are uploaded but intended only for the game to consider adding as official content



Back To Top

UGCFileVisibility

These constants specify possible visibility states that a Workshop item can be in. They are used with the function steam_ugc_set_item_visibility and are an async callback parameter for the functions steam_ugc_request_item_details and steam_ugc_send_query.

ℹ️ NOTE

See Steam Docs for more details.

UGC File Visibility Constant Description
ugc_visibility_public Set the item to be publicly visible
ugc_visibility_friends_only Set the item to be visible to only people on the users friends list
ugc_visibility_private Set the item to be private



Back To Top

UGCListSortOrder

These constants specify the sorting order of user published UGC lists from queries created using one of the following functions:

ℹ️ NOTE

See Steam UGC Docs for more details.

UGC List Sort Order Constant Description
ugc_sortorder_CreationOrderDesc Returns items by creation date. Descending - the newest items are first
ugc_sortorder_CreationOrderAsc Returns items by creation date. Ascending - the oldest items are first
ugc_sortorder_TitleAsc Returns items by name
ugc_sortorder_LastUpdatedDesc Returns the most recently updated items first
ugc_sortorder_SubscriptionDateDesc Returns the most recently subscribed items first
ugc_sortorder_VoteScoreDesc Returns the items with the more recent score updates first
ugc_sortorder_ForModeration Returns the items that have been reported for moderation



Back To Top

UGCListType

These constants specify the type of published UGC list to obtain from queries created using one of the following functions:

ℹ️ NOTE

See Steam UGC Docs for more details.

UGC List Type Constant Description
ugc_list_Published List of files the user has published
ugc_list_VotedOn List of files the user has voted on. Includes both VotedUp and VotedDown
ugc_list_VotedUp List of files the user has voted up (restricted to the current user only)
ugc_list_VotedDown List of files the user has voted down (restricted to the current user only)
ugc_list_WillVoteLater ⚠️ DEPRECATED
ugc_list_Favorited List of files the user has favorited
ugc_list_Subscribed List of files the user has subscribed to (restricted to the current user only)
ugc_list_UsedOrPlayed List of files the user has spent time in game with
ugc_list_Followed List of files the user is following updates for



Back To Top

UGCMatchType

These constants specify the types of UGC to obtain from queries created using one of the following function:

ℹ️ NOTE

See Steam UGC Docs for more details.

UGC Match Type Constant Description
ugc_match_Items Both microtransaction items and Ready-to-use items
ugc_match_Items_Mtx Microtransaction items
ugc_match_Items_ReadyToUse Regular in game items that players have uploaded
ugc_match_Collections Shared collections of UGC
ugc_match_Artwork Artwork which has been shared
ugc_match_Videos Videos which have been shared
ugc_match_Screenshots Screenshots which have been shared
ugc_match_AllGuides Both web guides and integrated guides
ugc_match_WebGuides Guides that are only available on the steam community
ugc_match_IntegratedGuides Guides that you can use within your game (like Dota 2's in game character guides)
ugc_match_UsableInGame Ready-to-use items and integrated guides
ugc_match_ControllerBindings Controller Bindings which have been shared



Back To Top

UGCQueryType (Sorting & Filtering)

These constants specify the sorting and filtering for queries across all available UGC, and are to be used with the following functions:

ℹ️ NOTE

See Steam UGC Docs for more details.

UGC Query Type Constant Description
ugc_query_RankedByVote Sort by vote popularity all-time
ugc_query_RankedByPublicationDate Sort by publication date descending
ugc_query_AcceptedForGameRankedByAcceptanceDate Sort by date accepted (for mtx items)
ugc_query_RankedByTrend Sort by vote popularity within the given "trend" period (set in steam_ugc_query_set_ranked_by_trend_days)
ugc_query_FavoritedByFriendsRankedByPublicationDate Filter to items the user's friends have favorited, sorted by publication date descending
ugc_query_CreatedByFriendsRankedByPublicationDate Filter to items created by friends, sorted by publication date descending
ugc_query_RankedByNumTimesReported Sort by report weight descending
ugc_query_CreatedByFollowedUsersRankedByPublicationDate Filter to items created by users that the current user has followed, sorted by publication date descending
ugc_query_NotYetRated Filtered to the user's voting queue
ugc_query_RankedByTotalVotesAsc Sort by total # of votes ascending (used internally for building the user's voting queue)
ugc_query_RankedByVotesUp Sort by number of votes up descending. Will use the "trend" period if specified (set in steam_ugc_query_set_ranked_by_trend_days)
ugc_query_RankedByTextSearch Sort by keyword text search relevancy



Social

Back To Top

Social

The following set of functions are used for setting or getting social information.

Rich Presence

The following functions are provided to work with rich presence:

User & Friends

The following functions are provided to work with user and friends data:



Back To Top

steam_set_rich_presence

Sets a Rich Presence key/value for the current user that is automatically shared to all friends playing the same game.


Syntax:

steam_set_rich_presence(key, value);
Argument Type Description
key string The rich presence 'key' to set
value string The rich presence 'value' to associate


Returns:

N/A


Example:

steam_set_rich_presence("game", "MyAwesomeGame");
steam_set_rich_presence("level", "Last");
steam_set_rich_presence("Mood","Happy");

steam_clear_rich_presence();

The code sample above uses sets a couple values for the local user rich presence and after that clears this values (using a call to the steam_clear_rich_presence function) meaning those will no longer show.



Back To Top

steam_set_rich_presence

Clears all of the current user's Rich Presence key/values.


Syntax:

steam_clear_rich_presence()


Returns:

N/A


Example:

steam_set_rich_presence("game", "MyAwesomeGame");
steam_set_rich_presence("level", "Last");
steam_set_rich_presence("Mood","Happy");

steam_clear_rich_presence();

The code sample above uses steam_set_rich_presence to set a couple values for the local user rich presence and after that clears this values meaning those will no longer show.



Back To Top

steam_user_set_played_with

Adds the given user to the "recently played with" list (accessed via "Players" - "Recent games") menu in Steam overlay. This is usually something to do on session start for all remote users.


Syntax:

steam_user_set_played_with(user_id);
Argument Type Description
user_id int64 Other player user id


Returns:

Bool


Example:

steam_user_set_played_with(anyFriendUserID)

This code will add the specified user id to the "recently played with" list, of the local user.



Back To Top

steam_get_friends_game_info

Returns an array of information about what the current user's Steam friends are playing. Equivalent to what can be seen in Steam Friends UI.


Syntax:

steam_get_friends_game_info();


Returns:

array of structs
Key Type Description
friendId int64 The Steam user id
gameId real The Steam game id
lobbyId int64 The Steam lobby id (if hosting a lobby that is open for friends to join - otherwise 0)
name string The friend's user name


Example:

var info_arr = steam_get_friends_game_info();
var info_num = array_length(info_arr);
var _steam_app_id = steam_get_app_id();
for (var i = 0; i < info_num; i++)
{
    var info = info_arr[i];
    // same game!
    if (info.gameId == _steam_app_id)
    {
        var lobby_id = info.lobbyId;
        // has an open lobby!
        if (lobby_id != 0)
        {
            var user_id = info.friendId;
            var name = info.name;
            // Use steam_lobby_join_id(lobby_id) to join the lobby when asked
        }
    }
}

The above code will check all you friends to see if anyone of them is playing the same game as you are (steam_get_app_id) and check if they have an open lobbies and if so we can request to join the lobby they are in using steam_lobby_join_id.



Back To Top

steam_get_user_avatar

Fetches an avatar for the specified user ID. Returns 0 if no avatar is set for the user;
Returns -1 if the request is pending, in which case an Steam Async Event will be triggered. Returns positive IDs if the avatar is ready, this id is to be used with the following function:


Syntax:

steam_get_user_avatar(userID, avatar_size);
Argument Type Description
userID int64 The user Steam unique identifier
avatar_size AvatarSize The size of the avatar to be requested


Returns:

real


Triggers:

Asynchronous Steam Event
Key Type Description
event_type string The string value "avatar_image_loaded"
success bool Whether the async action succeeded
user_id int64 The associated user's ID
image real The image ID that would otherwise be returned by the function
width real The image width, in pixels
height real The image height, in pixels **


Example:

var l_img = steam_get_user_avatar(steam_get_user_steam_id(), steam_user_avatar_size_large);

// Check if avatar is ready
if (l_img > 0)
{
    var l_dims = steam_image_get_size(l_img);
    var buff_size = l_dims[0] * l_dims[1] * 4

    var l_cols = buffer_create(buff_size, buffer_fixed, 1);

    l_ok = steam_image_get_rgba(l_img, l_cols, buff_size);

    if(!l_ok)
    {
        buffer_delete(l_cols);
    }

    var l_surf = surface_create(l_dims[0], l_dims[1]);
    buffer_set_surface(l_cols, l_surf, 0);

    l_sprite = sprite_create_from_surface(l_surf, 0, 0, l_dims[0], l_dims[1], false, false, 0, 0);

    surface_free(l_surf);
    buffer_delete(l_cols);
}

In the code above we query for the current user's (steam_get_user_steam_id) avatar, this function this function will either return:

  • the handle to the function (return value greater than zero): in this case we follow by getting size information (steam_image_get_size), creating a buffer and and getting the avatar image RBGA data into the buffer (steam_image_get_rgba) and lastely creating a sprite from said buffer.
  • no handle at all (return value equal to zero): in this case there is no avatar image for the specified used.
  • a value of -1: in this last case it measn that the request is pending and you can catch the output with a Steam Async Event, using the following code:
// Early exit if event type doesn't match
if (async_load[?"event_type"] != "avatar_image_loaded") exit

// Validate status
var success = async_load[?"success"];
if (success == 1) {

    // Do what you want with the provided image handle
}
else {
    // Failure
    show_debug_message("Failed to get user avatar");
}



Back To Top

steam_image_get_size

Fetches dimensions for the said Steam image ID. If the call succeeds, the return value is a two-element array containing width and height in pixels.


Syntax:

steam_image_get_size(steam_image_id);
Argument Type Description
steam_image_id int64 steam identifier of the image


Returns:

array


Example:

var l_img = steam_get_user_avatar(steam_get_user_steam_id(), steam_user_avatar_size_large);
var l_dims = steam_image_get_size(l_img);
var buff_size = l_dims[0] * l_dims[1] * 4
var l_cols = buffer_create(buff_size, buffer_fixed, 1);
l_ok = steam_image_get_rgba(l_img, l_cols, buff_size);
if(!l_ok)
    exit
var l_surf = surface_create(l_dims[0], l_dims[1]);
buffer_set_surface(l_cols, l_surf, 0);
l_sprite = sprite_create_from_surface(l_surf, 0, 0, l_dims[0], l_dims[1], false, false, 0, 0);
surface_free(l_surf);
buffer_delete(l_cols);

The above code will show a code example.



Back To Top

steam_image_get_rgba

Grabs RGBA data of the specified Steam image ID into a GameMaker buffer. Returns whether successful.

ℹ️ NOTE

The buffer should be appropriately sized in accordance with steam_image_get_size (width height 4).


Syntax:

steam_image_get_rgba(steam_image_id, buffer, size);
Argument Type Description
steam_image_id int64 The steam image identifier
buffer buffer The buffer where data will be written
size real The size of the buffer supplied


Returns:

Boolean


Example:

var l_img = steam_get_user_avatar(steam_get_user_steam_id(), steam_user_avatar_size_large);

// Check if avatar is ready
if (l_img > 0)
{
    var l_dims = steam_image_get_size(l_img);
    var buff_size = l_dims[0] * l_dims[1] * 4

    var l_cols = buffer_create(buff_size, buffer_fixed, 1);

    l_ok = steam_image_get_rgba(l_img, l_cols, buff_size);

    if(!l_ok)
    {
        buffer_delete(l_cols);
    }

    var l_surf = surface_create(l_dims[0], l_dims[1]);
    buffer_set_surface(l_cols, l_surf, 0);

    l_sprite = sprite_create_from_surface(l_surf, 0, 0, l_dims[0], l_dims[1], false, false, 0, 0);

    surface_free(l_surf);
    buffer_delete(l_cols);
}

In the code above we query for the current user's (steam_get_user_steam_id) avatar data and place it inside a buffer (with the RGBA color format). For a more extensive example refer to the steam_get_user_avatar function.



Back To Top

steam_image_get_bgra

Grabs BGRA data of the specified Steam image ID into a GameMaker buffer. Returns whether successful.

ℹ️ NOTE

The buffer should be appropriately sized in accordance with steam_image_get_size (width height 4).


Syntax:

steam_image_get_bgra(steam_image_id, buffer, size);
Argument Type Description
steam_image_id int64 The steam image identifier
buffer buffer ID The buffer where data will be written
size real The size of the buffer supplied


Returns:

Boolean


Example:

var l_img = steam_get_user_avatar(steam_get_user_steam_id(), steam_user_avatar_size_large);

// Check if avatar is ready
if (l_img > 0)
{
    var l_dims = steam_image_get_size(l_img);
    var buff_size = l_dims[0] * l_dims[1] * 4

    var l_cols = buffer_create(buff_size, buffer_fixed, 1);

    l_ok = steam_image_get_bgra(l_img, l_cols, buff_size);

    if(!l_ok)
    {
        buffer_delete(l_cols);
    }

    var l_surf = surface_create(l_dims[0], l_dims[1]);
    buffer_set_surface(l_cols, l_surf, 0);

    l_sprite = sprite_create_from_surface(l_surf, 0, 0, l_dims[0], l_dims[1], false, false, 0, 0);

    surface_free(l_surf);
    buffer_delete(l_cols);
}

In the code above we query for the current user's (steam_get_user_steam_id) avatar data and place it inside a buffer (with the BGRA color format). For a more extensive example refer to the steam_get_user_avatar function.



Inventory

Back To Top

Inventory

The following functions, constants and structures allow to use the Steam Inventory Service.

Pricing and Consumables

These functions are provided for handling pricing, purchases and consumables:

Inventory Management (Async Result)

These asynchronous functions will return a inventory result handle that can be used to get additional information (see section below):

Inventory Result Information

These functions can be called with the inventory result handle (from previous section) to get additional information:

Dynamic Properties

This set of functions can be used to author items dynamic properties:

Constants

These are the constants used by this API:

Structures

These are the structures used by this API:



Back To Top

steam_inventory_consume_item

Consumes items from a user's inventory. If the quantity of the given item goes to zero, it is permanently removed. This is an asynchronous function that will trigger the Steam Async Event when the task is finished.

⚠️ IMPORTANT

You must call steam_inventory_result_destroy on the returned async result ID when you are done with it.

✴️ EXTERNAL

A wrapper around ConsumeItem.


Syntax:

steam_inventory_consume_item(item_id, quantity);
Argument Type Description
item_id int64 The steam_inventory_item_id to consume.
quantity real The number of items in that stack to consume.


Returns:

real


Triggers:

Asynchronous Steam Event
Key Type Description
event_type string The string value "inventory_result_ready"
success bool Whether the async action succeeded
result InventoryResultStatus The status code as returned by steam_inventory_result_get_status
handle real The associated async result ID, which can be used to tell apart what result this event is for.


Example:

steam_inventory_consume_item(player.apple, 1);

The code sample above will try to consume one item (apple, steam_inventory_item_id), and trigger an async event with the task result.



Back To Top

steam_inventory_get_item_price

After a successful call to steam_inventory_request_prices, you can call this method to get the pricing for a specific item definition.

✴️ EXTERNAL

A wrapper around GetItemPrice.


Syntax:

steam_inventory_get_item_price(item);
Argument kind Description
item real The steam_inventory_item_def to get the price of.


Returns:

int64


Example:

var price = steam_inventory_get_item_price(item);

The code sample above will return you the price for the speficied item definition. For more detailed example on using the function check steam_inventory_request_prices



Back To Top

steam_inventory_get_items_with_prices

After a successful call to steam_inventory_request_prices, you can call this method to get all the prices for applicable item definitions.

✴️ EXTERNAL

A wrapper around GetItemsWithPrices.


Syntax:

steam_inventory_get_items_with_prices();


Returns:

array of structs
Name Type Description
item_def real The steam_inventory_item_def representing the item type
price int64 The price of the item definition
base_price int64 The base price of the item definition ✴️ WINDOWS ONLY


Example:

var array = steam_inventory_get_items_with_prices(inv_result);
if(array_length(array) > 0)
{
    var item_def = array[0].item_def
    var price = array[0].price
    var base_price = array[0].base_price
    show_debug_message("Found at one item that costs: " + string(price));
}

The code above will get items with prices and if the returning array size is greater than zero (meaning there is at least one item with a configured price) it prints to the console the item's price.



Back To Top

steam_inventory_request_eligible_promo_item_defs

Requests the list of "eligible" promo items that can be manually granted to the given user. This is an asynchronous function that will trigger the Steam Async Event when the task is finished.

✴️ EXTERNAL

A wrapper around RequestEligiblePromoItemDefinitionsIDs.


Syntax:

steam_inventory_request_eligible_promo_item_defs(user_id);
Argument Description
user_id The user ID of the user to request the eligible promo items for.


Returns:

bool


Triggers:

Asynchronous Steam Event
Key Type Description
event_type string The string value "inventory_request_eligible_promo_item_defs"
user_id int64 The user's unique identifier
item_def_count real The number of items
item_def_json string A json array of items identifiers (must be parsed using json_parse or json_decode)
is_cached_data bool Whether the data was retrieved from the cache and not from the server


Example:

steam_inventory_request_eligible_promo_item_defs(user_id)

For more information on this function call please refer to the official manual.



Back To Top

steam_inventory_request_prices

Request prices for all item definitions that can be purchased in the user's local currency.

This is an asynchronous function that will trigger the Steam Async Event when the task is finished, after which you can use the following functions:

✴️ EXTERNAL

A wrapper around RequestPrices.


Syntax:

steam_inventory_request_prices();


Returns:

bool


Triggers:

Asynchronous Steam Event
Key Type Description
event_type string The string value "inventory_request_prices"
success bool Whether the async action succeeded
result InventoryResultStatus The status code as returned by steam_inventory_result_get_status
currency string The string representing the user's local currency code.


Example:

steam_inventory_request_prices();

The code above will request for price information. The result for this task can be caught inside the Steam Async Event with the following code:

// Early exit if event type doesn't match
if (async_load[? "event_type"] != "inventory_request_prices") exit;

// Early exit if handle doesn't match
if (async_load[? "success"])
{
    show_debug_message("The currenct being used is: " + async_load[? "currency"]);

    var price = steam_inventory_get_item_price(global.swordId);
}

The code above matches the event type and if so shows the currency being used. It also gets the price for a specific item using the steam_inventory_get_item_price function.



Back To Top

steam_inventory_start_purchase

Starts the purchase process for the user, given a "shopping cart" of item definitions that the user would like to buy. The user will be prompted in the Steam Overlay to complete the purchase in their local currency, funding their Steam Wallet if necessary, etc.

✴️ EXTERNAL

A wrapper around StartPurchase.


Syntax:

steam_inventory_start_purchase(array);
Argument Type Description
array array<InventoryItemCreationData> An array of structs representing items to be purchased (see InventoryItemCreationData)


Returns:

N/A


Example:

var arrayCreate = [
              {item_def: item1, quantity: 3},
              {item_def: item2, quantity: 5},
       ]

steam_inventory_start_purchase()

The code above will initialize a purchase intent that will be finalized in the Steam Overlay.



Back To Top

steam_inventory_add_promo_item

Take an Item Definition and grants the user the promo item. Item Definitions are integer numbers ranging from 1 to 999999999. Values below the range are invalid and values above the range are reserved. This is an asynchronous function that will trigger the Steam Async Event when the task is finished.

⚠️ IMPORTANT

You must call steam_inventory_result_destroy on the returned async result ID when you are done with it.

✴️ EXTERNAL

A wrapper around AddPromoItem.


Syntax:

steam_inventory_add_promo_item(item_def)
Argument Type Description
item_def int64 The steam_inventory_item_def to grant the player (number between 1 and 999999999)


Returns:

real


Triggers:

Asynchronous Steam Event
Key Type Description
event_type string The string value "inventory_result_ready"
success bool Whether the async action succeeded
result InventoryResultStatus The status code as returned by steam_inventory_result_get_status
handle real The associated async result ID, which can be used to tell apart what result this event is for.


Example:

steam_inventory_add_promo_item(item)

The above code will grant the user with a specific item. For an example on how to use the Steam Async Event to read the callback response, refer to the function steam_inventory_get_all_items.



Back To Top

steam_inventory_add_promo_items

Takes an array of Item Definitions and grants the user multiple items. Item Definitions are integer numbers ranging from 1 to 999999999. Values below the range are invalid and values above the range are reserved. This is an asynchronous function that will trigger the Steam Async Event when the task is finished.

⚠️ IMPORTANT

You must call steam_inventory_result_destroy on the returned async result ID when you are done with it.

✴️ EXTERNAL

A wrapper around AddPromoItems.


Syntax:

steam_inventory_add_promo_items(item_defs)
Argument Type Description
item_defs array An array of steam_inventory_item_def to grant the user with.


Returns:

real


Triggers:

Asynchronous Steam Event
Key Type Description
event_type string The string value "inventory_result_ready"
success bool Whether the async action succeeded
result InventoryResultStatus The status code as returned by steam_inventory_result_get_status
handle real The associated async result ID, which can be used to tell apart what result this event is for.


Example:

steam_inventory_add_promo_items([item1,item2,item3])

The above code will grant the user with an multiple items specified in an array format. For an example on how to use the Steam Async Event to read the callback response, refer to the function steam_inventory_get_all_items.



Back To Top

steam_inventory_exchange_items

Grants one item in exchange for a set of other items. This is an asynchronous function that will trigger the Steam Async Event when the task is finished.

⚠️ IMPORTANT

You must call steam_inventory_result_destroy on the returned async result ID when you are done with it.

✴️ EXTERNAL

A wrapper around ExchangeItems.


Syntax:

steam_inventory_exchange_items(create_arr, destroy_arr);
Argument Type Description
create_arr array<InventoryItemCreationData> An array of structs representing items to be created (see InventoryItemCreationData)
destroy_arr array<InventoryItemConsumptionData> An array of structs representing items to be consumed (see InventoryItemConsumptionData)


Returns:

real


Triggers:

Asynchronous Steam Event
Key Type Description
event_type string The string value "inventory_result_ready"
success bool Whether the async action succeeded
result InventoryResultStatus The status code as returned by steam_inventory_result_get_status
handle real The associated async result ID, which can be used to tell apart what result this event is for.


Example:

var arrayDestroy = [
    { item_id: player.cursed_sword, quantity: 1 },
    { item_id: player.apple, quantity: 7 },
];

var arrayCreate = [
    { item_def: global.holy_sword, quantity: 1 },
    { item_def: global.orange, quantity: 2 }
];

steam_inventory_exchange_items(arrayCreate, arrayDestroy);

Given the provided items to be destroyed and the items to be create the code above will perform an exchange removing the current items (arrayDestroy) from the inventory and adding the new (arrayCreate) in their place. The result for this task can be caught inside the Steam Async Event with the following code:

// Early exit if event type doesn't match
if (async_load[? "event_type"] != "inventory_result_ready") exit;

// Early exit if handle doesn't match
if (async_load[? "handle"] != handle) exit;

// Early exit if handle doesn't match
if (async_load[? "success"])
{
    show_debug_message("Exchange was a success");
}
else 
{
    show_debug_message("Exchange failed");
}

// Don't forget to clean the ununsed handle
steam_inventory_result_destroy(handle);
handle = undefined;

The code above matches the event type and checks if the handle id matches the one that initialized the request and if so we print a debug message with the success of the task. In the end we also use a call to steam_inventory_result_destroy to make sure we dispose and free all the used memory.



Back To Top

steam_inventory_generate_items

Generates specific items for the current user. This is an asynchronous function that will trigger the Steam Async Event when the task is finished.

ℹ️ NOTE

This is only usable by Steam accounts that belong to the publisher group for your game.

⚠️ IMPORTANT

You must call steam_inventory_result_destroy on the returned async result ID when you are done with it.

✴️ EXTERNAL

A wrapper around GenerateItems.


Syntax:

steam_inventory_generate_items(create_arr);
Argument Type Description
create_arr array<InventoryItemCreationData> An array of structs representing items to be created (see InventoryItemCreationData)


Returns:

real


Triggers:

Asynchronous Steam Event
Key Type Description
event_type string The string value "inventory_result_ready"
success bool Whether the async action succeeded
result InventoryResultStatus The status code as returned by steam_inventory_result_get_status
handle real The associated async result ID, which can be used to tell apart what result this event is for.


Example:

var arrayCreate = [
    {item_def: item1, quantity: 3},
    {item_def: item2, quantity: 5},
];

steam_inventory_generate_items(arrayCreate)

The code above will grant the specific items to the current user. For an example on how to use the Steam Async Event to read the callback response, refer to the function steam_inventory_get_all_items.



Back To Top

steam_inventory_get_all_items

Starts retrieving all items in the current user's inventory. This is an asynchronous function that will trigger the Steam Async Event when the task is finished.

⚠️ IMPORTANT

You must call steam_inventory_result_destroy on the returned async result ID when you are done with it.

✴️ EXTERNAL

A wrapper around GetAllItems.


Syntax:

steam_inventory_get_all_items();


Returns:

real


Triggers:

Asynchronous Steam Event
Key Type Description
event_type string The string value "inventory_result_ready"
success bool Whether the async action succeeded
result InventoryResultStatus The status code as returned by steam_inventory_result_get_status
handle real The associated async result ID, which can be used to tell apart what result this event is for.

✴️ OPTIONAL

The asynchronous event presented below is only triggered when the result is newer/fresher than the last known result. It will not trigger if the inventory hasn't changed, or if results from two overlapping calls are reversed in flight and the earlier result is already known to be stale/out-of-date. The regular callback will still be triggered immediately afterwards; this is an additional notification for your convenience.

Key Type Description
event_type string The string value "inventory_full_update"
success bool Whether the async action succeeded
handle real The associated async result ID, which can be used to tell apart what result this event is for.


Example:

handle = steam_inventory_get_all_items();

The code above will start a query for all the items in current users inventory. The result for this task can be caught inside the Steam Async Event with the following code:

// Early exit if event type doesn't match
if (async_load[? "event_type"] != "inventory_result_ready") exit;

// Early exit if handle doesn't match
if (async_load[? "handle"] != handle) exit;

// Early exit if handle doesn't match
if (async_load[? "success"])
{
    var items = steam_inventory_result_get_items(handle);

    for (var i = 0; i < array_length(items); i++)
    {
        var item = items[i];
        // access item data for each entry
        //
        // item.item_id
        // item.item_def
        // item.quantity
        // item.flags
    }
}

// Don't forget to clean the ununsed handle
steam_inventory_result_destroy(handle);
handle = undefined;

The code above matches the event type and checks if the handle id matches the one that initialized the request and if so gets the items from the result using the function steam_inventory_result_get_items and loops through them. In the end we also use a call to steam_inventory_result_destroy to make sure we dispose and free all the used memory.



Back To Top

steam_inventory_get_items_by_id

Requests information about a subset of the current user's inventory.

⚠️ IMPORTANT

You must call steam_inventory_result_destroy on the returned async result ID when you are done with it.

✴️ EXTERNAL

A wrapper around GetItemsByID.


Syntax:

steam_inventory_get_items_by_id(item_ids);
Argument Type Description
item_ids array An array of steam_inventory_item_id of items to get information of.


Returns:

real


Triggers:

Asynchronous Steam Event
Key Type Description
event_type string The string value "inventory_result_ready"
success bool Whether the async action succeeded
result InventoryResultStatus The status code as returned by steam_inventory_result_get_status
handle real The associated async result ID, which can be used to tell apart what result this event is for.


Example:

handle = steam_inventory_get_items_by_id([item1, item2])

Similar to steam_inventory_get_all_items but you can specify an array of items to query information instead of querying all of them. For an example on how to use the Steam Async Event to read the callback response, refer to the function steam_inventory_get_all_items.



Back To Top

steam_inventory_submit_update_properties

Submits the transaction request to modify dynamic properties on items for the current user. See StartUpdateProperties.

⚠️ IMPORTANT

You must call steam_inventory_result_destroy on the returned async result ID when you are done with it.

✴️ EXTERNAL

A wrapper around SubmitUpdateProperties.


Syntax:

steam_inventory_submit_update_properties(handle);
Argument Type Description
handle real The update handle corresponding to the transaction request


Returns:

real


Triggers:

Asynchronous Steam Event
Key Type Description
event_type string The string value "inventory_result_ready"
success bool Whether the async action succeeded
result InventoryResultStatus The status code as returned by steam_inventory_result_get_status
handle real The associated async result ID, which can be used to tell apart what result this event is for.


Example:

var handle = steam_inventory_start_update_properties()
steam_inventory_set_property_bool(handle, item_id, "invisible", true)
steam_inventory_set_property_float(handle, item_id, "power", 123.54)
steam_inventory_set_property_int(handle, item_id, "uses", 5)
steam_inventory_set_property_string(handle, item_id, "name", "Big Sword")
...
steam_inventory_remove_property(handle, item_id, "invisible")
...
steam_inventory_submit_update_properties(handle)

The code above provides a simple sample on how to set/removed some properties. Starting with a steam_inventory_start_update_properties then multiple calls to set/remove property functions:



Back To Top

steam_inventory_transfer_item_quantity

Transfer items between stacks within a user's inventory.

⚠️ IMPORTANT

You must call steam_inventory_result_destroy on the returned async result ID when you are done with it.

✴️ EXTERNAL

A wrapper around TransferItemQuantity.


Syntax:

steam_inventory_transfer_item_quantity(source_item_id, quantity, dest_item_id);
Argument Type Description
source_item_id int64 The source steam_inventory_item_id to transfer from
quantity real The quantity of the item that will be transferred
dest_item_id int64 The destination steam_inventory_item_id to transfer to


Returns:

real


Triggers:

Asynchronous Steam Event
Key Type Description
event_type string The string value "inventory_result_ready"
success bool Whether the async action succeeded
result InventoryResultStatus The status code as returned by steam_inventory_result_get_status
handle real The associated async result ID, which can be used to tell apart what result this event is for.


Example:

handle = steam_inventory_transfer_item_quantity(global.apple, 2, global.oranges);

The above code will trigger a transfer between to items owned by the used the amount to be transferred in the example, the user will lose 2 apples and receive 2 oranges. For an example on how to use the Steam Async Event to read the callback response, refer to the function steam_inventory_get_all_items.



Back To Top

steam_inventory_trigger_item_drop

Trigger an item drop if the user has played a long enough period of time.

This period can be customized in two places:

  • At the application level within Inventory Service: Playtime Item Grants. This will automatically apply to all "playtimegenerator" items that do not specify any overrides.

  • In an individual "playtimegenerator" item definition. The settings would take precedence over any application-level settings.


    Only item definitions which are marked as "playtime item generators" can be spawned.

    This is an asynchronous function that will trigger the Steam Async Event when the task is finished.

⚠️ IMPORTANT

You must call steam_inventory_result_destroy on the returned async result ID when you are done with it.

✴️ EXTERNAL

A wrapper around TriggerItemDrop.


Syntax:

steam_inventory_trigger_item_drop(item_def);
Argument Type Description
item_def real This must refer to an item definition of the type "playtimegenerator". See the inventory schema for more details.


Returns:

bool


Triggers:

Asynchronous Steam Event
Key Type Description
event_type string The string value "inventory_result_ready"
success bool Whether the async action succeeded
result InventoryResultStatus The status code as returned by steam_inventory_result_get_status
handle real The associated async result ID, which can be used to tell apart what result this event is for.


Example:

handle = steam_inventory_trigger_item_drop(item_def)

For more information on this function call please refer to the official manual. For an example on how to use the Steam Async Event to read the callback response, refer to the function steam_inventory_get_all_items.



Back To Top

steam_inventory_result_destroy

Destroys a result handle and frees all associated memory. This handle is returned by the following functions:

ℹ️ NOTE

This function can be called using an inventory result handle after the corresponding async event has been triggered.

✴️ EXTERNAL

A wrapper around DestroyResult.


Syntax:

steam_inventory_result_destroy(inv_result);
Argument Type Description
inv_result real The inventory result handle to destroy


Returns:

bool


Example:

// Early exit if event type doesn't match
if (async_load[? "event_type"] != "inventory_result_ready") exit;

// Early exit if handle doesn't match
if (async_load[? "handle"] != handle) exit;

// Early exit if handle doesn't match
if (async_load[? "success"])
{
    show_debug_message("Exchange was a success");
}
else 
{
    show_debug_message("Exchange failed");
}

// Don't forget to clean the ununsed handle
steam_inventory_result_destroy(handle);
handle = undefined;

In the code above we have an example of a asynchronous callback that generates a result handle by the end of which we execute a call to steam_inventory_result_destroy to make sure we dispose and free all the used memory.



Back To Top

steam_inventory_result_get_item_property

Gets the dynamic properties from an item in an inventory result set. Property names are always composed of ASCII letters, numbers, and/or underscores.

ℹ️ NOTE

This function can be called using an inventory result handle after the corresponding async event has been triggered.

✴️ EXTERNAL

A wrapper around GetResultItemProperty.


Syntax:

steam_inventory_result_get_item_property(inv_result, item_index, prop_name);
Argument Type Description
inv_result real The inventory result handle
item_index real Position of the item in the result set
prop_name string The property name to get the value for


Returns:

string


Example:

handle = steam_inventory_get_all_items();

The code above will start a query for all the items in current users inventory. The result for this task can be caught inside the Steam Async Event with the following code:

// Early exit if event type doesn't match
if (async_load[? "event_type"] != "inventory_result_ready") exit;

// Early exit if handle doesn't match
if (async_load[? "handle"] != handle) exit;

// Early exit if handle doesn't match
if (async_load[? "success"])
{
    var items = steam_inventory_result_get_items(handle);

    var status = steam_inventory_result_get_status(handle);
    var timestamp = steam_inventory_result_get_unix_timestamp(handle);

    for (var i = 0; i < array_length(items); i++)
    {      
        // It's also possible to get properties from each item using 
        // prop1 = steam_inventory_result_get_item_property(handle, i, "property_name1")
        // prop2 = steam_inventory_result_get_item_property(handle, i, "property_name2")
    }
}

// Don't forget to clean the ununsed handle
steam_inventory_result_destroy(handle);
handle = undefined;

The code above matches the event type and checks if the handle id matches the one that initialized the request and if so gets the items from the result using the function steam_inventory_result_get_items and loops through them to get the item properties we want. In the end we also use a call to steam_inventory_result_destroy to make sure we dispose and free all the used memory.



Back To Top

steam_inventory_result_get_items

Get the items associated with an inventory result handle.

ℹ️ NOTE

This function can be called using an inventory result handle after the corresponding async event has been triggered.

✴️ EXTERNAL

A wrapper around GetResultItems.


Syntax:

steam_inventory_result_get_items(inv_result);
Argument Type Description
inv_result real The inventory result handle


Returns:

array of structs
Name Type Description
item_id real A representing the item instance
item_def real A representing the item type
quantity int64 How many of the said item there is in the slot
flags int64 This is a bit-masked collection of ESteamItemFlags


Example:

var array = steam_inventory_result_get_items(inv_result);
for(var i = 0 ; i < array_lenght(array) ; i++)
{
     var struct = array[i]
     var item_id = struct.item_id
     var item_def = struct.item_def
     var quantity = struct.quantity
}

For a more detailed implementation sample please refer to the steam_inventory_get_all_items function.



Back To Top

steam_inventory_result_get_status

Returns status code of a result.

ℹ️ NOTE

This function can be called using an inventory result handle after the corresponding async event has been triggered.

✴️ EXTERNAL

A wrapper around GetResultStatus.


Syntax:

steam_inventory_result_get_status(inv_result);
Argument Type Description
inv_result real The inventory result handle


Returns:

InventoryResultStatus


Example:

if(steam_inventory_result_get_status(inv_result) != steam_inventory_result_status_ok)
     exit

For a more detailed implementation sample please refer to the steam_inventory_result_get_item_property function.



Back To Top

steam_inventory_result_get_unix_timestamp

Returns a Unix timestamp for the server time at which the result was generated.

ℹ️ NOTE

This function can be called using an inventory result handle after the corresponding async event has been triggered.

✴️ EXTERNAL

A wrapper around GetResultTimestamp.


Syntax:

steam_inventory_result_get_unix_timestamp(inv_result);
Argument Type Description
inv_result real The inventory result handle


Returns:

int64


Example:

var timestamp = steam_inventory_result_get_unix_timestamp(inv_result);

For a more detailed implementation sample please refer to the steam_inventory_result_get_item_property function.



Back To Top

steam_inventory_start_update_properties

Starts a transaction request to update dynamic properties on items for the current user. Returns a steam_inventory_update_handle that can be used with the following functions:

✴️ EXTERNAL

A wrapper around StartUpdateProperties.


Syntax:

steam_inventory_start_update_properties()


Returns:

int64


Example:

handle = steam_inventory_start_update_properties()
steam_inventory_set_property_bool(handle, item_id, "invisible", true)
steam_inventory_set_property_float(handle, item_id, "power", 123.54)
steam_inventory_set_property_int(handle, item_id, "uses", 5)
steam_inventory_set_property_string(handle, item_id, "name", "Big Sword")
steam_inventory_submit_update_properties(handle)

The code above provides a simple sample on how to set/removed some properties. Starting with a steam_inventory_start_update_properties then mutliple calls to set/remove property functions:



Back To Top

steam_inventory_remove_property

Removes a dynamic property of the given item.

✴️ EXTERNAL

A wrapper around RemoveProperty.


Syntax:

steam_inventory_remove_property(handle, item_id, prop_name);
Argument Type Description
handle real The update handle returned by steam_inventory_start_update_properties
item_id int64 The steam_inventory_item_id of the item being modified
prop_name string The dynamic property being removed


Returns:

bool


Example:

var handler = steam_inventory_start_update_properties()
steam_inventory_set_property_bool(handler, item_id, "invisible", true)
steam_inventory_set_property_float(handler, item_id, "power", 123.54)
steam_inventory_set_property_int(handler, item_id, "uses", 5)
steam_inventory_set_property_string(handler, item_id, "name", "Big Sword")
...
steam_inventory_remove_property(handler, item_id, "invisible")
...
steam_inventory_submit_update_properties(handler)

The code above provides a simple sample on how to set/removed some properties. Starting with a steam_inventory_start_update_properties then mutliple calls to set/remove property functions:



Back To Top

steam_inventory_set_property_bool

Sets a dynamic property for the boolean given item

✴️ EXTERNAL

A wrapper around SetProperty.


Syntax:

steam_inventory_set_property_bool(handle, prop_name, val);
Argument Type Description
handle real The update handle corresponding to the transaction request
prop_name string The dynamic property being added or updated.
val bool value being set.


Returns:

bool


Example:

handle = steam_inventory_start_update_properties()
steam_inventory_set_property_bool(handle, item_id, "invisible", true)
steam_inventory_set_property_float(handle, item_id, "power", 123.54)
steam_inventory_set_property_int(handle, item_id, "uses", 5)
steam_inventory_set_property_string(handle, item_id, "name", "Big Sword")
...
steam_inventory_remove_property(handle, item_id, "invisible")
...
steam_inventory_submit_update_properties(handle)

The code above provides a simple sample on how to set/removed some properties. Starting with a steam_inventory_start_update_properties then mutliple calls to set/remove property functions:



Back To Top

steam_inventory_set_property_float

Sets a dynamic property for the float given item

✴️ EXTERNAL

A wrapper around SetProperty.


Syntax:

steam_inventory_set_property_float(handle, prop_name, val);
Argument Type Description
handle real The update handle corresponding to the transaction request
prop_name string The dynamic property being added or updated.
val real value being set.


Returns:

bool


Example:

handle = steam_inventory_start_update_properties()
steam_inventory_set_property_bool(handle, item_id, "invisible", true)
steam_inventory_set_property_float(handle, item_id, "power", 123.54)
steam_inventory_set_property_int(handle, item_id, "uses", 5)
steam_inventory_set_property_string(handle, item_id, "name", "Big Sword")
...
steam_inventory_remove_property(handle, item_id, "invisible")
...
steam_inventory_submit_update_properties(handle)

The code above provides a simple sample on how to set/removed some properties. Starting with a steam_inventory_start_update_properties then mutliple calls to set/remove property functions:



Back To Top

steam_inventory_set_property_int

Sets a dynamic property for the int given item

✴️ EXTERNAL

A wrapper around SetProperty.


Syntax:

steam_inventory_set_property_int(handle, prop_name, val);
Argument Type Description
handle real The update handle corresponding to the transaction request
prop_name string The dynamic property being added or updated.
val real value being set.


Returns:

bool


Example:

handle = steam_inventory_start_update_properties()
steam_inventory_set_property_bool(handle, item_id, "invisible", true)
steam_inventory_set_property_float(handle, item_id, "power", 123.54)
steam_inventory_set_property_int(handle, item_id, "uses", 5)
steam_inventory_set_property_string(handle, item_id, "name", "Big Sword")
...
steam_inventory_remove_property(handle, item_id, "invisible")
...
steam_inventory_submit_update_properties(handle)

The code above provides a simple sample on how to set/removed some properties. Starting with a steam_inventory_start_update_properties then mutliple calls to set/remove property functions:



Back To Top

steam_inventory_result_get_status

Sets a dynamic property for the string given item

✴️ EXTERNAL

A wrapper around SetProperty.


Syntax:

steam_inventory_set_property_string(handle, prop_name, val);
Argument Type Description
handle real The update handle corresponding to the transaction request
prop_name string The dynamic property being added or updated.
val string value being set.


Returns:

bool


Example:

var handle = steam_inventory_start_update_properties()
steam_inventory_set_property_bool(handle, item_id, "invisible", true)
steam_inventory_set_property_float(handle, item_id, "power", 123.54)
steam_inventory_set_property_int(handle, item_id, "uses", 5)
steam_inventory_set_property_string(handle, item_id, "name", "Big Sword")
...
steam_inventory_remove_property(handle, item_id, "invisible")
...
steam_inventory_submit_update_properties(handle)

The code above provides a simple sample on how to set/removed some properties. Starting with a steam_inventory_start_update_properties then mutliple calls to set/remove property functions:



Back To Top

InventoryResultStatus

These constants represent the status of an inventory result async event, and are returned by the async events of the following functions:

Inventory Result Status Constant Description
steam_inventory_result_status_pending Pending
steam_inventory_result_status_ok Ok
steam_inventory_result_status_expired Expired
steam_inventory_result_status_invalid Invalid
steam_inventory_result_status_fail Fail
steam_inventory_result_status_invalid_param Iinvalid
steam_inventory_result_status_service_unavailable Unavailable
steam_inventory_result_status_limit_exceeded Exceeded




Back To Top

InventoryItemConsumptionData

This struct is used as an argument when performing a call to the following functions

Key Type Description
item_id int64 A steam_inventory_item_id of an item to be consumed
quantity real How much of the said item is to be consumed



Back To Top

InventoryItemCreationData

This struct is used as an argument when performing a call to the following functions

Key Type Description
item_def int64 A steam_inventory_item_def representing the item type
quantity real Number of items of type to be created



Networking

Back To Top

Networking

The following functions and constants allow you to use Steam's Networking functionality.

Packets IO

These functions are provided for handling sending and receiving packets:

Session

The following functions allow handling P2P sessions:

Constants

These are the constants used by this API:



Back To Top

steam_net_packet_get_data

Copies the contents of last received packet to the given buffer. Data is copied to the start of the buffer (position remains unaffected), meaning that if you reuse the same buffer, you should "rewind" it prior to reading.

ℹ️ NOTE

If the buffer is not big enough to fit data, it will be resized automatically (the buffer needs to be created using the using the buffer_grow type).


Syntax:

steam_net_packet_get_data(buffer)
Argument Type Description
buffer real The buffer to write the incoming data to.


Returns:

bool


Example:

while (steam_net_packet_receive())
{
    steam_net_packet_get_data(inbuf);
    buffer_seek(inbuf, buffer_seek_start, 0);
    switch (buffer_read(inbuf, buffer_u8))
    {
        case 1: show_debug_message("packet ID 1"); break;
        case 2: show_debug_message("packet ID 2"); break;
        default: show_debug_message("unknown packet"); break;
    }
}

The code above will check for an incoming packet and get its data into a buffer (resizing if necessary) and reads from it.



Back To Top

steam_net_packet_get_sender_id

Returns Steam ID of the user that sent the last received packet. Can be used in conjunction with steam_net_packet_send to send something back and for just telling the senders apart.


Syntax:

steam_net_packet_get_sender_id();


Returns:

int64


Example:

while(steam_net_packet_receive())
{
    var sender = steam_net_packet_get_sender_id();

    buffer_seek(outbuf, buffer_seek_start, 0);
    buffer_write(outbuf, buffer_u8, test_network_packet.ping);

    steam_net_packet_send(sender, outbuf);
}

The above code will show a code example.



Back To Top

steam_net_packet_get_size

Returns the size of last received packet, in bytes.


Syntax:

steam_net_packet_get_size();


Returns:

real


Example:

while (steam_net_packet_receive())
{
    var size = steam_net_packet_size();
    show_debug_message("Received " + string(size) + " bytes.");
}

The code above will display the size of each incoming packet.



Back To Top

steam_net_packet_receive

Attempts to get the next packet from Steam API and returns whether successfully done so. Other steam_net_ functions can then be used to get packet information/contents.


Syntax:

steam_net_packet_receive();


Returns:

bool


Example:

while (steam_net_packet_receive())
{
    // process the received packet
}

The code above will attempt to get the next packet from Steam API, would be used every step while in lobby or with less frequency otherwise.



Back To Top

steam_net_packet_send

Sends a packet to the given endpoint, returns whether successful (as opposed to incorrect arguments/invalid ID). If no packet type is passed in then default value will be used, the default value can be set using the steam_net_packet_set_type function. Returns whether or not the packet was successfully sent.


Syntax:

steam_net_packet_send(user_id, buffer, size, packet_type)
Argument Type Description
user_id int64 The target user to send the packet to
buffer real Buffer that contains the raw byte array for the packet data to send
size real The size of data to send (default -1, sends the entire buffer) ✴️ OPTIONAL
packet_type PacketType The type of packet to be used ✴️ OPTIONAL


Returns:

bool


Example:

var buf = buffer_create(16, buffer_grow, 1);
buffer_write(buf, buffer_string, "Hello!");
steam_net_packet_send(steam_id, buf, -1);
buffer_delete(buff);

The code sample will create a buffer and write to it, sending the total length of it to the given steam_id, the buffer is then deleted.



Back To Top

steam_net_packet_set_type

Set the default connection protocol used when sending the data packets (using the steam_net_packet_send function). Returns whether or not the default protocol was successfully set.


Syntax:

steam_net_packet_set_type(protocol);
Argument Type Description
protocol PacketType The default connection protocol to be used


Returns:

bool


Example:

steam_net_packet_set_type(steam_net_packet_type_reliable)

The above code will set the current connection to use the steam_net_packet_type_reliable protocol to send data packages.



Back To Top

steam_net_accept_p2p_session

Accepts a P2P session request from the specified user. Returns whether successful or not.


Syntax:

steam_net_accept_p2p_session(userID);
Argument Type Description
userID int64 The User ID of the user that sent the initial packet to us.


Returns:

bool


Example:

if (isMyFriend(userID))
{
    steam_net_accept_p2p_session(userID);
}

The code above uses a custom implemented function that will check if a given userID is a friend and if it is it will accept the P2P session.



Back To Top

steam_net_close_p2p_session

Closes a P2P session with the specified user. Returns whether successful or not. Steam will automatically close sessions after a period of inactivity, but you could also do it manually if you so desired.


Syntax:

steam_net_close_p2p_session(user_id)
Argument Type Description
user_id int64 The user ID of the user to close the connection with.


Returns:

bool


Example:

if (global.chat_closed)
{
     steam_net_close_p2p_session(user_id)
}

The code above check to see if a global variable (chat_closed) is true and if so, it will close the P2P session.



Back To Top

steam_net_set_auto_accept_p2p_sessions

Sets whether to auto-accept session requests coming from players in the same lobby. This is enabled by default for convenience. If you disable it, you will need to handle the async event when someone uses the steam_lobby_join_id function.


Syntax:

steam_net_set_auto_accept_p2p_sessions(enable);
Argument Type Description
enable bool disable/enable auto accept sessions


Returns:

N/A


Triggers:

Asynchronous Steam Event (for each request, if disabled)
Key Type Description
type string The string value "lobby_join_requested"
lobby_id int64 The lobby unique identifier
friend_id int64 The friend unique identifier


Example:

steam_net_set_auto_accept_p2p_sessions(false);

The code above will disable the auto accept P2P sessions functionality meaning we should deal with the requests manually. In order to do so we need to use the Steam Async Event to catch the callback:

if (async_load[?"event_type"] == "lobby_join_requested")
{
    steam_net_accept_p2p_session(async_load[?"friend_id"]);
}



Back To Top

PacketType

These constants specify the type of a steam packet and should be used with the function steam_net_packet_set_type.

Packet Type Constant Description
steam_net_packet_type_unreliable Equivalent to UDP the data may or may not be delivered, will not be resent automatically.
steam_net_packet_type_unreliable_nodelay Similar to "unreliable" type, but always sent instantly (as soon as function is called). Intended for things like streaming voice data, where you want lowest latency possible and only care about the current data.
steam_net_packet_type_reliable Equivalent to TCP, the data is warranted to be delivered in order and intact.
steam_net_packet_type_reliable_buffer Similar to "reliable" type, but utilizes Nagle's algorithm to reduce the number of packets at cost of potential delay while the data accumulates until the sending threshold.



Steam Input

Back To Top

Input

The Steam Input API is designed to allow you to easily enable full support for Steam Input devices in your game. This means things such as:

  • Ability to use proper controller-specific glyphs for input hints.
  • Allow the user to easily rebind controls however they like via the Steam Input Configurator.
  • Share input mappings with others via the Steam Workshop.

  • and many more!


    Before proceeding, please read this page about the Steam Input API for developers before reading this page to have a good understanding of what are Input Handles, Action Sets, Action Set Layers, Digital Actions, Analog Actions, Action Origins, the Steam Input Configurator, and bindings.

ℹ️ NOTE

This API is designed for advanced users only, if you don't know why you need it, please use the native GML gamepad_ functions instead.

The following functions can be used to access the Steam Input from within GameMaker Studio 2



Back To Top

steam_input_init

With this function you can initialize the Steam Input API. It will return true if initialization was successful and false otherwise. If argument explicitly_call_run_frame is true, then you must manually call steam_input_run_frame to poll for input data and async events, otherwise that will be performed by the steam_update function. After you initialize the Steam Input API, configuration events will be dispatched for any controllers connected while your game is running, they can be used to detect gamepad connection and when bindings have been updated so you need to refresh the sprites, input hints, etc.

⚠️ IMPORTANT

This function must be called ONLY if you REALLY wish to use the Steam Input API, or some other extensions in your project rely on Steam Input, otherwise calling it may make native GameMaker gamepad_ functions not see any controllers plugged in!


Syntax:

steam_input_init(explicitly_call_run_frame);
Argument Type Description
explicitly_call_run_frame bool Are you going to call steam_input_run_frame manually or not?


async_load contents:

Key Value Description
event_type string A constant string "steam_input_configuration_loaded".
app_id real Your game's app id.
device_handle real Input handle of the device this event refers to.
mapping_creator real Steam ID of the user that created the loaded input mapping or 0 if none.
major_revision real Major version digit of the mapping.
minor_revision real Minor version digit of the mapping.
uses_steam_input_api bool Whether this device is using the Action Set and Actions API.
uses_steam_gamepad_api bool Whether this device is using the XInput emulation API.


Returns:

Bool


Example:

if (!steam_input_init(false))
{
    throw "Failed to initialize the Steam Input API";
}
/// @description Async - Steam event
if (async_load[? "event_type"] == "steam_input_configuration_loaded") {
    // bindings refreshed, update any sprites we've fetched in some handler script
    scr_refresh_input_hints(async_load[? "device_handle"]);
}

The above code checks to see if the Steam Input API was initialized, and throws an exception if it wasn't, then handles "configuration loaded" async events.



Back To Top

steam_input_shutdown

With this function you can tell Steam that you are done using the Steam Input API. It will return true if the operation was successful and false otherwise. Usually you do not need to call this, as when your game ends Steam will automatically release Steam Input for you. After this function had returned, no other Steam Input functions must be called.


Syntax:

steam_input_shutdown();


Returns:

Bool


Example:

steam_input_shutdown();

The above code shuts down the Steam Input API.



Back To Top

steam_input_set_input_action_manifest_file_path

This function can be used to set the absolute path to the input action manifest, in case you do not wish to use the Steam Workshop for this. Returns true if the operation was successful and false otherwise.


Syntax:

steam_input_set_input_action_manifest_file_path(absolute_path);


Argument Type Description
absolute_path string Absolute path to the input action manifest file

Returns:

Bool


Example:

steam_input_set_input_action_manifest_file_path(working_directory + "manifest.vdf");

The above code sets the full path to the input action manifest file the game wants to use.



Back To Top

steam_input_run_frame

With this function you can poll for new input data from Steam Input if it is available, you do not need to call it manually unless you explicitly specified this when calling steam_input_init.


Syntax:

steam_input_run_frame();


Returns:

Bool


Example:

steam_input_run_frame();

The above code asks Steam Input to poll for new data if available.



Back To Top

steam_input_wait_for_data

With this function you can freeze the game until new input data had arrived, returns true if new data did arrive, or false if the timeout had expired or an error had occurred. This function is only useful for lockstep multiplayer games.


Syntax:

steam_input_wait_for_data(wait_forever,timeout);
Argument Type Description
wait_forever bool Whether to wait for data to arrive forever.
timeout real Data arrival timeout.


Returns:

Bool


Example:

steam_input_wait_for_data(true, 0);

The above code will freeze the entire game until new input data is received from Steam Input.



Back To Top

steam_input_new_data_available

With this function you can check if there is new input data available since last read. Returns true if there is, false otherwise.


Syntax:

steam_input_new_data_available();


Returns:

Bool


Example:

if (steam_input_new_data_available())
{
    global.data_check_flag = true;
}

The above code checks if new data has been received since last poll, and sets a flag to true if there is.



Back To Top

steam_input_get_connected_controllers

With this function you can get an array of currently connected controller handles. This function returns an array of controller handles on success, and undefined on failure.


Syntax:

steam_input_get_connected_controllers();


Returns:

Array<Real> OR Undefined


Example:

controllers = steam_input_get_connected_controllers();
if (is_undefined(controllers))
{
    throw "Unable to poll for controllers!";
}

The above code will poll the current connected controllers array, and throw an exception if there was an error.



Back To Top

steam_input_enable_device_callbacks

You can use this function to enable Async - Steam device connection and disconnection events, similar to Async - System type gamepad connected and gamepad lost events. The contents of async_load are described below. Returns true if the operation was successful, and false otherwise. This can be used as an alternative to steam_input_get_connected_controllers since in that case you don't need to iterate through the entire array, which may be faster depending on how your game is coded. Both methods can be used simultaneously without issues. This function needs to be called only once and cannot be undone.

⚠️ IMPORTANT

Depending on the type of the controller, multiple connection or disconnection events may be sent for one handle, be sure to handle that in your code, e.g. don't show a disconnection pop-up if the controller was already lost, and don't show a connection pop-up if this controller was already connected (and is not lost).


Syntax:

steam_input_enable_device_callbacks();


async_load contents:

Key Value Description
event_type String "steam_input_device_connected" or "steam_input_device_disconnected"
disconnected_device_handle Real Only present if event_type is "steam_input_device_disconnected"
connected_device_handle Real Only present if event_type is "steam_input_device_connected"


Returns:

Bool


Extended Example:

/// @description Create event
steam_input_enable_device_callbacks(); // enable connection events
/// @description Async - Steam event
if (async_load[? "event_type"] == "steam_input_device_connected") {
    scr_game_add_device(async_load[? "connected_device_handle"]); // register an input_handle
    show_debug_message("Discovered a new input_handle!");
}
else if (async_load[? "event_type"] == "steam_input_device_disconnected") {
    scr_game_remove_device(async_load[? "disconnected_device_handle"]); // de-register an input_handle
    show_debug_message("Lost an input_handle!");
}

The above code will enable device connection and disconnection events, then it will react to them by calling some handler function.



Back To Top

steam_input_enable_action_event_callbacks

This function will enable Async - Steam action events, this event will be called only when some digital or analog action will change it's state, in case of digital actions that means a button is held or released, in case of analog actions that means the analog stick had moved, or the stick type had changed. The contents of async_load are described below. This is similar to steam_input_get_digital_action_data and steam_input_get_analog_action_data, only here you don't have to poll for the actions manually, but you still need to obtain the handles via steam_input_get_digital_action_handle and steam_input_get_analog_action_handle respectively, otherwise Steam will think you don't care about these actions. This function needs to be called only once and cannot be undone.


Syntax:

steam_input_enable_action_event_callbacks();


async_load contents:

Key Value Description
event_type string "steam_input_action_event"
controller_handle Real Handle of the controller this event is for.
action_event_type Real A steam_input_action_event_type_ constant
action_handle Real Handle of the digital or analog action, depending on the type
active bool Whether or not this action is currently available to be bound in the active action set. If it is not available, OR does not belong to the active action set, this will be false.
state bool DIGITAL ACTIONS ONLY: state of the digital action, true or false.
mode real ANALOG ACTIONS ONLY: A steam_input_source_mode_ constant.
x real ANALOG ACTIONS ONLY: X axis of the input
y real ANALOG ACTIONS ONLY: Y axis of the input


Returns:

Bool


Extended Example:

/// @description Create event
steam_input_enable_action_event_callbacks(); // enable action input events
/// @description Async - System event
if (async_load[? "event_type"] == "steam_input_action_event") {
    var _controller_handle = async_load[? "controller_handle"];
    var _action_handle = async_load[? "action_handle"];
    var _is_action_active = async_load[? "active"];
    if (_is_action_active) { // it's useless to try and handle an inactive action
        if (async_load[? "action_event_type"] == steam_input_action_event_type_digital_action) {
            var _digital_state = async_load[? "state"]; // true or false only, held or not held
            scr_register_digital_input(_controller_handle, _action_handle, _digital_state); // some handler
        }
        else if (async_load[? "action_event_type"] == steam_input_action_event_type_digital_action) {
            var _analog_mode = async_load[? "mode"]; // the user may be using a stick, or a mouse, or a touchpad...
            var _analog_x = async_load[? "x"];
            var _analog_y = async_load[? "y"];
            scr_register_analog_input(_controller_handle, _action_handle, _analog_mode, _analog_x, _analog_y); // some handler
        }
    }
    else {
        show_debug_message("Action " + string(_action_handle) + " not active for con " + string(_controller_handle)); // not bound?
    }
}

The above code will activate action input async events, and handle them correctly.



Back To Top

steam_input_get_action_set_handle

This function will try to resolve an action set by name, returning the handle of that action set.

⚠️ IMPORTANT

Due to a bug in the Steam Input API, if the game was launched without any controllers connected, all action set and action handle resolver functions will return 0, an invalid handle, as such it is required that you try to obtain handles every frame until at least one controller gets connected and you succeed.


Syntax:

steam_input_get_action_set_handle(action_set_name);
Argument Type Description
action_set_name string The name of the action set.


Returns:

Real


Extended Example:

/// @description Create event
main_action_set = 0; // '0' is an invalid handle.
menu_action_set = 0;
/// @description Step event
// due to a bug in the Steam Input API, we have to try and obtain these every frame until we succeed.
// check if any handle is invalid:
if (main_action_set == 0 || menu_action_set == 0) {
    // try to resolve:
    main_action_set = steam_input_get_action_set_handle("Set_Main");
    menu_action_set = steam_input_get_action_set_handle("Set_Menu");
    // if we failed and the functions return 0, we will try again, on the next frame.
}

The above code checks if any handle is 0, and if it is, it tries to obtain all handles again, until it eventually completes and all handles are valid.



Back To Top

steam_input_activate_action_set

With this function you can activate an action set on a specific controller, or all controllers by specifying the steam_input_handle_all_controllers constant as the controller handle. Returns true if the operation was successful, and false otherwise. This function is cheap to call and can be safely called every frame without hitting performance issues.


Syntax:

steam_input_activate_action_set(controller, action_set);
Argument Type Description
controller Real Input handle of the controller.
action_set Real Handle of the action set, cannot be zero.


Returns:

Bool


Example:

switch (state) {
    case game_state.menu: {
        steam_input_activate_action_set(steam_input_handle_all_controllers, menu_action_set);
        scr_do_menu_input();
        break;
    }

    case game_state.play: {
        steam_input_activate_action_set(player_controller_handle, main_action_set);
        scr_do_gameplay_input(player_controller_handle);
        break;
    }
}

The above code will activate the appropriate action set based on which state the game is currently in.



Back To Top

steam_input_get_current_action_set

This function will return the handle of the currently activated action set on a given controller handle, or 0 if there is no action set currently active.


Syntax:

steam_input_get_current_action_set(controller);
Argument Type Description
controller input_handle Handle of the controller.


Returns:

Real


Example:

if (steam_input_get_current_action_set(player_handle) == 0) {
    steam_input_activate_action_set(player_handle, menu_action_set);
}

The above code will check to see if there is no action set activated for a controller, and if there isn't, it will activate a menu action set.



Back To Top

steam_input_activate_action_set_layer

This function will activate an action set layer on top of the current action set on a specified controller. Returns true if the operation was successful and false otherwise.


Syntax:

steam_input_activate_action_set_layer(controller, action_set_layer);
Argument Type Description
controller real Handle of the controller.
action_set_layer real Handle of the action set layer.


Returns:

Bool


Example:

steam_input_activate_action_set_layer(player_handle, action_set_layer_sniper);

The above code will activate a "sniper" action set layer on top of any currently activated action sets. Returns true if the operation was successful and false otherwise.



Back To Top

steam_input_deactivate_action_set_layer

This function will deactivate a specific action set layer from the specified controller. Returns true if the operation was successful and false otherwise.


Syntax:

steam_input_deactivate_action_set_layer(controller, action_set_layer);
Argument Type Description
controller real Handle of the controller.
action_set_layer real Handle of the action set layer.


Returns:

Bool


Example:

steam_input_deactivate_action_set_layer(player_handle, action_set_layer_sniper);

The above code will deactivate the "sniper" action set layer from the player_handle controller.



Back To Top

steam_input_deactivate_all_action_set_layers

This function will deactivate all action set layers on a specified controller. Returns true if the operation was successful and false otherwise.


Syntax:

steam_input_deactivate_all_action_set_layers(controller);
Argument Type Description
controller real Handle of the controller.


Returns:

Bool


Example:

steam_input_deactivate_all_action_set_layers(player_handle);

The above code will deactivate all action set layers on the player_handle controller.



Back To Top

steam_input_get_active_action_set_layers

This function will return an array of currently active action set layer handles on a specified controller. Returns an array of action set layer handles on success, and undefined on failure.


Syntax:

steam_input_get_active_action_set_layers(controller);
Argument Type Description
controller real Handle of the controller.


Returns:

Array<Real> OR Undefined


Example:

var layers = steam_input_get_active_action_set_layers(player_handle);
if (array_length(layers) > 0) {
    steam_input_deactivate_all_action_set_layers(player_handle);
}

The above code will retrieve all currently active action set layers for player_handle, and if there are some active, it will deactivate all action set layers.



Back To Top

steam_input_get_digital_action_handle

This function will resolve a digital action by name, and return that action's handle. Keep in mind that no two actions cannot have the same name, even if they are defined in different action sets, since Steam does not differentiate action names for each set.

⚠️ IMPORTANT

Due to a bug in the Steam Input API, if the game was launched without any controllers connected, all action set and action handle resolver functions will return 0, an invalid handle, as such it is required that you try to obtain handles every frame until at least one controller gets connected and you succeed.


Syntax:

steam_input_get_digital_action_handle(digital_action_name);
Argument Type Description
digital_action_name string Name of the digital action.


Returns:

Real


Extended Example:

/// @description Create event
action_shoot = 0; // '0' is an invalid handle.
action_roll = 0;
/// @description Step event
if (action_shoot == 0 || action_roll == 0) {
    action_shoot = steam_input_get_digital_action_handle("DAction_Shoot");
    action_roll = steam_input_get_digital_action_handle("DAction_Roll");
}

The above code will try to obtain handles of digital actions shoot and roll, if it failed, it will try again on the next frame.



Back To Top

steam_input_get_digital_action_data

This function will return current input data for a given digital action on a given controller. It returns the digital_action_data struct on success and undefined on failure.


Syntax:

steam_input_get_digital_action_data(controller,action_handle);
Argument Type Description
controller Real Handle of the controller to use.
action_handle Real Handle of the digital action to poll for.


Returns:

Struct OR Undefined

Struct fields: |Name|Type|Description| |----|----|----| |active|Bool|Whether the action is bound to any button| |state|Bool|Whether the action is currently held or not|


Example:

var _data = steam_input_get_digital_action_data(player_handle, action_shoot);
with (objPlayer) {
    isShooting = _data.active && _data.state;
}

The above code will set the isShooting variable in the player object to true if the action is active and is currently held, or false otherwise.



Back To Top

steam_input_get_digital_action_origins

This function will retrieve an array of input origins for a specified action and controller handles. This is the function you should use when trying to obtain input hint prompts, keep in mind that it returns an array because multiple buttons can be bound to one action in the Steam Input Configurator. Also keep in mind that input hints may change mid-game as the Steam Input Configurator is accessible inside the Steam Overlay, this is why it's recommended that you update all input sprites when you get a Configuration Async - Steam event for the controller(s) you are interested in.


Syntax:

steam_input_get_digital_action_origins(controller, action_set, digital_action);
Argument Type Description
controller Real Handle of the controller to use.
action_set Real Handle of the action set.
digital_action Real Handle of the digital action inside the action set.


Returns:

Array<Real> OR Undefined


Example:

// this example function returns a horizontal strip of input hints as a single sprite frame
// do not forget to use sprite_delete() when you no longer need the returned sprite.
function scr_sprite_for_action(player_handle, action_set_handle, action_handle, is_digital_action) {
    var _origins = is_digital_action
        ? steam_input_get_digital_action_origins(player_handle, action_set_handle, action_handle)
        : steam_input_get_analog_action_origins(player_handle, action_set_handle, action_handle);
    if (is_undefined(_origins) || array_length(_origins) == 0) {
        // something is wrong or no buttons are bound
        return -1;
    }
    var _hint_count = array_length(_origins),
        _hint_width = 32,
        _hint_height = 32,
        _hint_size = steam_input_glyph_size_small, // _small is 32x32 pixels
        _hint_style = steam_input_glyph_style_dark; // prefer dark glyphs for the sake of this example
    var _surf = surface_create(_hint_count * _hint_width, _hint_height);
    surface_set_target(_surf);
    draw_clear_alpha(c_black, 0);
    for (var _h = 0; _h < _hint_count; ++_h) {
        var _origin = _origins[_h];
        var _path = steam_input_get_glyph_png_for_action_origin(_origin, _hint_size, _hint_style);
        var _tempspr = sprite_add(_path, 1, false, false, 0, 0);
        draw_sprite(_tempspr, 0, _hint_width * _h, 0);
        sprite_delete(_tempspr);
    }
    surface_reset_target();
    var _sprstrip = sprite_create_from_surface(_surf, 0, 0, surface_get_width(_surf), surface_get_height(_surf), false, false, 0, 0);
    // you can add a call to sprite_set_offset() if you wish to auto-set the sprite origin to middle centre.
    surface_free(_surf);
    return _sprstrip;
}

global.shoot_sprite = scr_sprite_for_action(player_handle, main_action_set, action_shoot, true);
draw_sprite(global.shoot_sprite, 0, 64, 64);

The above code defines an example of how to turn action origins into a sprite that you can draw in-game, for example on the GUI Layer.



Back To Top

steam_input_get_string_for_digital_action_name

This function will return the localized name of a digital action as specified by Steam localization settings. Keep in mind that the Steam language may be different than the OS language, and this function will always use the language settings of the Steam client, not the OS.


Syntax:

steam_input_get_string_for_digital_action_name(digital_action);
Argument Type Description
digital_action Real Handle of the digital action.


Returns:

string


Example:

shoot_name_loc = steam_input_get_string_for_digital_action_name(action_shoot);

The above code will get the localized name for the shoot action, and store it in the variable shoot_name_loc.



Back To Top

steam_input_get_analog_action_handle

This function will resolve an analog action by name, and return that action's handle. Keep in mind that no two actions cannot have the same name, even if they are defined in different action sets, since Steam does not differentiate action names for each set.

⚠️ IMPORTANT

Due to a bug in the Steam Input API, if the game was launched without any controllers connected, all action set and action handle resolver functions will return 0, an invalid handle, as such it is required that you try to obtain handles every frame until at least one controller gets connected and you succeed.


Syntax:

steam_input_get_analog_action_handle(analog_action_name);
Argument Type Description
analog_action_name string Name of the analog action.


Returns:

Real


Extended Example:

/// @description Create event
action_move = 0; // '0' is an invalid handle.
action_aim = 0;
/// @description Step event
if (action_move == 0 || action_aim == 0) {
    action_move = steam_input_get_analog_action_handle("AAction_Move");
    action_aim = steam_input_get_analog_action_handle("AAction_Aim");
}

The above code will try to obtain handles of analog actions move and aim, if it failed, it will try again on the next frame.



Back To Top

steam_input_get_analog_action_data

This function will return current input data for a given analog action on a given controller. It returns the analog_action_data struct on success and undefined on failure.


Syntax:

steam_input_get_analog_action_data(controller, action_handle);
Argument Type Description
controller Real Handle of the controller to use.
action_handle Real Handle of the analog action to poll for.


Struct Fields:

Name Type Description
active Bool Whether this action is bound to any input element.
mode Real A steam_input_source_mode_ constant.
x Real X axis of the input.
y Real Y axis of the input, inverted by default. See example code.

Returns:

Struct OR Undefined


Example:

var _data = steam_input_get_analog_action_data(player_handle, action_move);
if (_data.active) {
    with (objPlayer) {
        x += _data.x * move_speed;
        // in Steam Input the Y axis is in a different direction than GameMaker, so we need to invert it.
        y += -_data.y * move_speed;
        // you might want to use different crosshairs if the movement came from a touchpad or an analog stick.
        last_input_mode = _data.mode;
    }
}

The above code will move the player object accordingly to the input data for the move analog action.



Back To Top

steam_input_get_analog_action_origins

This function will retrieve an array of input origins for a specified action and controller handles. This is the function you should use when trying to obtain input hint prompts, keep in mind that it returns an array because multiple buttons can be bound to one action in the Steam Input Configurator. Also keep in mind that input hints may change mid-game as the Steam Input Configurator is accessible inside the Steam Overlay, this is why it's recommended that you update all input sprites when you get a Configuration Async - Steam event for the controller(s) you are interested in.


Syntax:

steam_input_get_analog_action_origins(controller, action_set, action);
Argument Type Description
controller Real Handle of the controller to use.
action_set Real Handle of the action set.
action Real Handle of the analog action inside the action set.


Returns:

Array<Real> OR Undefined


Example:

// this example function returns a horizontal strip of input hints as a single sprite frame
// do not forget to use sprite_delete() when you no longer need the returned sprite.
function scr_sprite_for_action(player_handle, action_set_handle, action_handle, is_digital_action) {
    var _origins = is_digital_action
        ? steam_input_get_digital_action_origins(player_handle, action_set_handle, action_handle)
        : steam_input_get_analog_action_origins(player_handle, action_set_handle, action_handle);
    if (is_undefined(_origins) || array_length(_origins) == 0) {
        // something is wrong or no buttons are bound
        return -1;
    }
    var _hint_count = array_length(_origins),
        _hint_width = 32,
        _hint_height = 32,
        _hint_size = steam_input_glyph_size_small, // _small is 32x32 pixels
        _hint_style = steam_input_glyph_style_dark; // prefer dark glyphs for the sake of this example
    var _surf = surface_create(_hint_count * _hint_width, _hint_height);
    surface_set_target(_surf);
    draw_clear_alpha(c_black, 0);
    for (var _h = 0; _h < _hint_count; ++_h) {
        var _origin = _origins[_h];
        var _path = steam_input_get_glyph_png_for_action_origin(_origin, _hint_size, _hint_style);
        var _tempspr = sprite_add(_path, 1, false, false, 0, 0);
        draw_sprite(_tempspr, 0, _hint_width * _h, 0);
        sprite_delete(_tempspr);
    }
    surface_reset_target();
    var _sprstrip = sprite_create_from_surface(_surf, 0, 0, surface_get_width(_surf), surface_get_height(_surf), false, false, 0, 0);
    // you can add a call to sprite_set_offset() if you wish to auto-set the sprite origin to middle centre.
    surface_free(_surf);
    return _sprstrip;
}

global.move_sprite = scr_sprite_for_action(player_handle, main_action_set, action_move, false /* not digital this time! */);
draw_sprite(global.move_sprite, 0, 64, 64);

The above code defines an example of how to turn action origins into a sprite that you can draw in-game, for example on the GUI Layer.



Back To Top

steam_input_get_glyph_png_for_action_origin

This function will return a full path to a PNG file of the glyph image of an action origin. The path is automatically added into the GameMaker's filesystem sandbox list, so that you can use the returned path in sprite_add or buffer_load no matter if you have the sandbox enabled or disabled.


Syntax:

steam_input_get_glyph_png_for_action_origin(origin, size, flags);
Argument Type Description
origin Real Action origin to get the PNG of.
size Real A steam_input_glyph_size_ constant.
flags Real A steam_input_glyph_style_ bit flags constant.


Returns:

string


Example:

var _path = steam_input_get_glyph_png_for_action_origin(global.shoot_origin, steam_input_glyph_size_small, steam_input_glyph_style_dark);
global.shoot_sprite = sprite_add(_path, 1, false, false, 0, 0);

The above code will get a PNG representing an action origin and load it as a sprite. For an extended example please see the example code from steam_input_get_digital_action_origins.



Back To Top

steam_input_get_glyph_svg_for_action_origin

This function will return a full path to an SVG file of the glyph image of an action origin. The path is automatically added into the GameMaker's filesystem sandbox list, so that you can use the returned path in buffer_load no matter if you have the sandbox enabled or disabled. As for now GameMaker has no native capabilities to draw SVG files, but such ability may be added in the future. If you have your own SVG renderer then this function might be useful for you. Since SVGs do not have a fixed size and can be freely scaled, there is no size argument like in steam_input_get_glyph_png_for_action_origin.


Syntax:

steam_input_get_glyph_svg_for_action_origin(origin, flags);
Argument Type Description
origin Real Action origin to get the SVG of.
flags Real A steam_input_glyph_style_ bit flags constant.


Returns:

string


Example:

var _svg_path = steam_input_get_glyph_svg_for_action_origin(global.shoot_origin, steam_input_glyph_style_dark);

The above code will get the path to an SVG representing an action origin and store it in a local variable _svg_path.



Back To Top

steam_input_get_glyph_for_action_origin_legacy

This function will return a full path to a PNG file of the glyph image of an action origin. The path is automatically added into the GameMaker's filesystem sandbox list, so that you can use the returned path in sprite_add or buffer_load no matter if you have the sandbox enabled or disabled. The image will be in legacy Steam Big Picture design style, if you wish to use the new Steam Deck styled glyphs (also called Knockout glyphs in Valve's documentation), please use the function steam_input_get_glyph_png_for_action_origin instead.


Syntax:

steam_input_get_glyph_for_action_origin_legacy(origin);
Argument Type Description
origin Real Action origin to get the PNG of.


Returns:

string


Example:

var _path = steam_input_get_glyph_for_action_origin_legacy(global.shoot_origin);
global.shoot_sprite = sprite_add(_path, 1, false, false, 0, 0);

The above code will get a PNG representing an action origin and load it as a sprite.



Back To Top

steam_input_get_string_for_action_origin

This function will return a localized name of an action origin, for example "Y Button" if the Steam language is set to English, or "Кнопка Y" if it is set to Russian. Keep in mind that the OS language may be different from the Steam client language, and the Steam language will be used instead.


Syntax:

steam_input_get_string_for_action_origin(origin);
Argument Type Description
origin Real Action origin to get the localized name of.


Returns:

string


Example:

global.shoot_name = steam_input_get_string_for_action_origin(global.shoot_origin);

The above code will get a localized name of the shoot origin and store it in a global variable shoot_name.



Back To Top

steam_input_get_string_for_analog_action_name

This function will return the localized name of an analog action as specified by Steam localization settings. Keep in mind that the Steam language may be different than the OS language, and this function will always use the language settings of the Steam client, not the OS.


Syntax:

steam_input_get_string_for_analog_action_name(action);
Argument Type Description
action Real Handle of the analog action.


Returns:

string


Example:

move_name_loc = steam_input_get_string_for_analog_action_name(action_move);

The above code will get the localized name for the move action, and store it in the variable move_name_loc.



Back To Top

steam_input_stop_analog_action_momentum

This function will stop the momentum of an analog action if the input device is, for example, a trackball. Returns true if the operation was successful and false otherwise.


Syntax:

steam_input_stop_analog_action_momentum(controller,action);
Argument Type Description
controller Real Input handle of the controller.
action Real Handle of the analog action.


Returns:

Bool


Example:

steam_input_stop_analog_action_momentum(player_handle, action_move);

The above code will stop the analog momentum of the move action.



Back To Top

steam_input_get_motion_data

This function will obtain raw gyroscope and accelerometer data in the controller's native format. Returns the motion_data struct on success and undefined on failure.


Syntax:

steam_input_get_motion_data(controller);
Argument Type Description
controller Real Input handle of the controller.

Struct Fields:

Name Type Description
rot_quat_x Real X component of the orientation quaternion.
rot_quat_y Real Y component of the orientation quaternion.
rot_quat_z Real Z component of the orientation quaternion.
rot_quat_w Real W component of the orientation quaternion.
pos_accel_x Real X component of the acceleration.
pos_accel_y Real Y component of the acceleration.
pos_accel_z Real Z component of the acceleration.
rot_vel_x Real X component of the angular velocity.
rot_vel_y Real Y component of the angular velocity.
rot_vel_z Real Z component of the angular velocity.


Returns:

Struct OR Undefined


Example:

var _data = steam_input_get_motion_data(player_handle);
if (is_undefined(_data)) {
    exit;
}
var _dt = delta_time / 1000000;
// this math will only work for the DualShock 4 controller
x += _dt * room_width * (_data.rot_vel_y / -32767);
y += _dt * room_height * (_data.rot_vel_x / -32767);
image_angle = radtodeg(_dt * (_data.rot_vel_z / 32767));

The above code will rotate and move the object based on the angular velocity data of the controller.



Back To Top

steam_input_trigger_vibration

This function will trigger a vibration effect on the target controller. Keep in mind that due to physical differences of each controller, the motors may not be the exact same, for example on the DualShock 4 controller the left motor is bigger and faster than the right one. Returns true on success and false otherwise.


Syntax:

steam_input_trigger_vibration(controller,left_speed,right_speed);
Argument Type Description
controller real Input handle of the controller.
left_speed real Speed of the left motor from 0 to 65535.
right_speed real Speed of the right motor from 0 to 65535.


Returns:

Bool


Example:

steam_input_trigger_vibration(player_handle, 65535 / 2, 65535 / 2);

The above code will trigger a vibration effect at half the maximum power on both motors.



Back To Top

steam_input_trigger_vibration_extended

This function will trigger an extended vibration effect on the target controller. Keep in mind that due to physical differences of each controller, the motors may not be the exact same, for example on the DualShock 4 controller the left motor is bigger and faster than the right one. Also keep in mind that not all controllers may support the extended vibration effects. Returns true on success and false otherwise.


Syntax:

steam_input_trigger_vibration_extended(controller,left_speed,right_speed,left_trigger_speed,right_trigger_speed);
Argument Type Description
controller real Input handle of the controller.
left_speed real Speed of the left motor from 0 to 65535.
right_speed real Speed of the right motor from 0 to 65535.
left_trigger_speed real Speed of the left trigger from 0 to 65535.
right_trigger_speed real Speed of the right trigger from 0 to 65535.


Returns:

Bool


Example:

steam_input_trigger_vibration_extended(player_handle, 65535 / 2, 65535 / 2, 65535 / 4, 65535 / 4);

The above code will trigger a vibration effect at half the maximum power on vibration motors, and set the trigger speed for both triggers to a quarter.



Back To Top

steam_input_trigger_simple_haptic_event

This function will trigger a simple haptic event if the target controller supports them. Returns true on success and false on failure.


Syntax:

steam_input_trigger_simple_haptic_event(controller,location,intensity,gain_db,other_intensity,other_gain_db);
Argument Type Description
controller real Input handle of the controller.
location real A steam_input_controller_haptic_location_ constant.
intensity real Intensity of the first motor from 0 to 255.
gain_db real Gain in DB units, can be negative, from -127 to 128.
other_intensity real Intensity of the second motor from 0 to 255.
other_gain_db real Gain of the second motor in DB units, can be negative, from -127 to 128.


Returns:

Bool


Example:

steam_input_trigger_simple_haptic_event(controller, steam_input_controller_haptic_location_both, 255 / 2, 0, 255 / 2, 0);

The above code will trigger a simple haptic event with half intensity and neutral db gain on both motors of the controller.



Back To Top

steam_input_set_led_color

This function will set or reset the color of the LED on the controller. Keep in mind that not all controllers have LEDs in them, and that the default user color of the controller differs between manufacturers, but your custom ones should always look almost the same.


Syntax:

steam_input_set_led_color(controller,color,flags);
Argument Type Description
controller real Input handle of the controller.
color real Color value to use.
flags real A steam_input_led_flag_ constant.


Returns:

Bool


Example:

// to set your own color:
var _rainbow = make_color_hsv((get_timer() / 100000) mod (255 + 1), 255, 255); // cycle through the Hue.
steam_input_set_led_color(controller, _rainbow, steam_input_led_flag_set_color);
// to reset to the default color:
steam_input_set_led_color(controller, c_black, steam_input_led_flag_restore_user_default);

The above code first sets the LED color to a custom one, then resets the color to the default one.



Back To Top

steam_input_trigger_haptic_pulse_legacy

This function runs a haptic pulse through the legacy API, this is only useful if the target controller is a Steam Controller. Returns true on success and false otherwise.


Syntax:

steam_input_trigger_haptic_pulse_legacy(controller,pad,duration_in_ms);
Argument Type Description
controller real Input handle of the controller.
pad real A steam_input_steam_controller_pad_ constant.
duration_in_ms real Duration of the pulse in miliseconds.


Returns:

Bool


Example:

steam_input_trigger_haptic_pulse_legacy(player_handle, steam_input_steam_controller_pad_left, 2 * 1000);

The above code runs a haptic pulse on the left motor for two seconds (2000 miliseconds).



Back To Top

steam_input_trigger_repeated_haptic_pulse_legacy

This function runs a repeated haptic pulse through the legacy API, this is only useful if the target controller is a Steam Controller. Returns true on success and false otherwise.


Syntax:

steam_input_trigger_repeated_haptic_pulse_legacy(controller,pad,duration_in_ms,offset_in_ms,repeat_times,flags);
Argument Type Description
controller real Input handle of the controller.
pad real A steam_input_steam_controller_pad_ constant.
duration_in_ms real Duration of the pulse in miliseconds.
offset_in_ms real The offset from which to start looping in miliseconds.
repeat_times real How many times to repeat the loop?
flags real Repeated haptic pulse flags


Returns:

Bool


Example:

steam_input_trigger_repeated_haptic_pulse_legacy(player_handle, steam_input_steam_controller_pad_left, 2 * 1000, 100, 2, 0);

The above code runs a repeated haptic pulse on the left motor for two seconds (2000 miliseconds), the next iterations will start at 100 miliseconds and this will repeat two times.



Back To Top

steam_input_show_binding_panel

This function opens the Steam Input Configurator for the target controller which allows the player to rebind controls in-game. If Steam is not running in Big Picture, a new window will be opened, otherwise the configurator will be invoked as a part of the Steam Overlay. Keep in mind that the player can open the Configurator without this function too, by pressing the "Controller Layout" button in the Steam Overlay. Returns true if the operation was successful and false otherwise.


Syntax:

steam_input_show_binding_panel(controller);
Argument Type Description
controller real Input handle of the controller.


Returns:

Bool


Example:

steam_input_show_binding_panel(player_handle);

The above code opens the Steam Input Configurator for the controller handle stored in player_handle.



Back To Top

steam_input_get_input_type_for_handle

This function returns the type of the target controller. Useful if you want to know which features are most likely supported by the target contorller.


Syntax:

steam_input_get_input_type_for_handle(controller);
Argument Type Description
controller real Input handle of the controller.


Returns:

real


Example:

var _input_type = steam_input_get_input_type_for_handle(player_handle);
var _msg = "The controller type is ";
var _typestr = "Unknown";
switch (_input_type) {
    case steam_input_type_steam_controller: _typestr = "Steam Controller"; break;
    case steam_input_type_xbox_360_controller: _typestr = "Xbox 360"; break;
    case steam_input_type_xbox_one_controller: _typestr = "Xbox One"; break;
    case steam_input_type_generic_gamepad: _typestr = "Generic Gamepad"; break;
    case steam_input_type_ps4_controller: _typestr = "DualShock 4"; break;
    case steam_input_type_apple_mfi_controller: _typestr = "Apple MFi"; break;
    case steam_input_type_android_controller: _typestr = "Android"; break;
    case steam_input_type_switch_joycon_pair: _typestr = "Joy-Con Pair"; break;
    case steam_input_type_switch_joycon_single: _typestr = "Single Joy-Con"; break;
    case steam_input_type_switch_pro_controller: _typestr = "Pro Controller"; break;
    case steam_input_type_mobile_touch: _typestr = "Mobile Touch"; break;
    case steam_input_type_ps3_controller: _typestr = "DualShock 3"; break;
    case steam_input_type_ps5_controller: _typestr = "DualSense"; break;
    case steam_input_type_steam_deck_controller: _typestr = "Steam Deck"; break;
}
show_debug_message(_msg + _typestr);

The above code prints the type of the controller as a string to debug output.



Back To Top

steam_input_get_controller_for_gamepad_index

This function returns the input handle for an XInput gamepad slot, or 0 if that slot is not powered by Steam Input. That can be used to match between native GameMaker gamepad_ slots and Steam Input controllers on Windows. Since on Windows the GameMaker pad slots from 0 to 3 are XInput controllers, and from 4 to 12 are DirectInput controllers. This function only works with emulated XInput controllers.


Syntax:

steam_input_get_controller_for_gamepad_index(index);
Argument Type Description
index real XInput slot from 0 to 3 included.


Returns:

real


Example:

var _slot0h = steam_input_get_controller_for_gamepad_index(0);
if (_slot0h != 0) {
    show_debug_message("GM slot 0 handle = " + string(_slot0h));
}

The above code prints the controller handle for the first XInput gamepad slot if it is valid.



Back To Top

steam_input_get_controller_for_gamepad_index

This function is the reverse of steam_input_get_controller_for_gamepad_index, except it allows you to determine whether a Steam Input handle is being emulated as XInput as well or not. See the definition of the reverse function for more information about slots.


Syntax:

steam_input_get_controller_for_gamepad_index(controller);
Argument Type Description
controller real Input handle of the controller.


Returns:

Real


Example:

var _slot0i = steam_input_get_gamepad_index_for_controller(player_handle);
if (_slot0i >= 0) {
    show_debug_message("GM slot for player is = " + string(_slot0i));
}

The above code prints the XInput slot for the player controller if it's valid.



Back To Top

steam_input_get_string_for_xbox_origin

This function turns a steam_input_xbox_origin_ constant into a localized string, the language will be taken from Steam client settings. For example "A Button" if it's English or "Кнопка A" if it's Russian.


Syntax:

steam_input_get_string_for_xbox_origin(origin);
Argument Type Description
origin real A steam_input_xbox_origin_ constant.


Returns:

string


Example:

show_debug_message("A Button is " + steam_input_get_string_for_xbox_origin(steam_input_xbox_origin_a));

The above code prints the localized name of the Xbox 360 A button origin.



Back To Top

steam_input_get_glyph_for_xbox_origin

This returns a path to a PNG associated with a steam_input_xbox_origin_ constant. The returned path will be automatically added into the GameMaker filesystem sandbox list so it can be used with buffer_load or sprite_add no matter whether you have sandbox enabled or not.


Syntax:

steam_input_get_glyph_for_xbox_origin(origin);
Argument Type Description
origin real A steam_input_xbox_origin_ constant.


Returns:

string


Example:

var _path = steam_input_get_glyph_for_xbox_origin(steam_input_xbox_origin_a);
var _sprite = sprite_add(_path, 1, false, false, 0, 0);
// ...
// do not forget to free the sprite when you're done:
sprite_delete(_sprite);

The above code loads a PNG file associated with steam_input_xbox_origin_a as a sprite.



Back To Top

steam_input_get_action_origin_from_xbox_origin

This function returns the closest origin that maps to the steam_input_xbox_origin_ constant for the target controller. So for a DualShock 4 controller handle steam_input_xbox_origin_a will return the "cross" button origin. Useful for transposing Xbox 360 button hints into the target controller button hints without using the Actions and Action Sets.


Syntax:

steam_input_get_action_origin_from_xbox_origin(controller, origin);
Argument Type Description
controller real Target controller handle to use.
origin real A steam_input_xbox_origin_ constant.


Returns:

real


Example:

// original origin:
var _xbox_origin = steam_input_xbox_origin_y;
// transposed origin: (ex: (Y) -> (TRIANGLE) on DS4)
var _transposed_origin = steam_input_get_action_origin_from_xbox_origin(player_handle, _xbox_origin);
var _path = steam_input_get_glyph_png_for_action_origin(_transposed_origin, steam_input_glyph_size_small, steam_input_glyph_style_dark);
var _sprite = sprite_add(_path, 1, false, false, 0, 0);
// do something with the sprite
// ...
// free the sprite:
sprite_delete(_sprite);

The above code loads an input sprite of the Xbox 360 button "Y" in the target controller's style.



Back To Top

steam_input_translate_action_origin

This function allows to translate an action origin for a new unknown controller type into an origin that this extension will understand. This is useful if a new controller is released, it's support is added into Steam Input, the Steam client is updated, the Steam Input Configurator is updated, but your game is not, and it doesn't know about this controller. With this function you can try to obtain the closest origin that maps to that unknown-for-your-game controller origin.


Syntax:

steam_input_translate_action_origin(type, origin);
Argument Type Description
type real steam_input_type_ you would like to map to, or steam_input_type_unknown to let Steam do a best guess.
origin real An unknown input action origin you would like to translate.


Returns:

real


Example:

// do a best guess here, let's pretend we have absolutely no idea how to handle this new controller
var _transposed_origin = steam_input_translate_action_origin(steam_input_type_unknown, global.shoot_origin);
var _path = steam_input_get_glyph_png_for_action_origin(_transposed_origin, steam_input_glyph_size_small, steam_input_glyph_style_dark);
var _sprite = sprite_add(_path, 1, false, false, 0, 0);
// do something with the sprite
// ...
// free the sprite:
sprite_delete(_sprite);

The above code tries to map an unknown action origin into something that this extension understands, and then loads a sprite representing that origin.



Back To Top

steam_input_get_device_binding_revision

This function returns the current action bindings revision as a struct, or undefined if there was an error.


Syntax:

steam_input_get_device_binding_revision(controller);
Argument Type Description
controller real Input controller handle to use.

Struct Fields:

Name Type Description
major real Major version digit.
minor real Minor version digit.


Returns:

Struct OR Undefined


Example:

var _bindvers = steam_input_get_device_binding_revision(player_handle);
show_debug_message("Major = " + string(_bindvers.major) + ", minor = " + string(_bindvers.minor));

The above code prints the current device bindings revision into debug output.



Back To Top

steam_input_get_remote_play_session_id

This function returns the current Steam Remote Play session id associated with the controller, or 0 if no session is associated.


Syntax:

steam_input_get_remote_play_session_id(controller);
Argument Type Description
controller input_handle Input controller handle to use.


Returns:

Real


Example:

var _sessid = steam_input_get_remote_play_session_id(player_handle);
show_debug_message("Session ID = " + string(_sessid));

The above code prints the current Steam Remote Play session id associated with the player controller.



Back To Top

steam_input_get_session_input_configuration_settings

This function returns the Steam Remote Play session opted-in gamepad types bitmask. Specifically the steam_input_configuration_enable_type_ constants.


Syntax:

steam_input_get_session_input_configuration_settings();


Returns:

Real


Example:

var _setmask = steam_input_get_session_input_configuration_settings();
// how to detect for opt-in:
var _opted_into_ps = (_setmask & steam_input_configuration_enable_type_playstation) != 0;
var _opted_into_switch = (_setmask & steam_input_configuration_enable_type_switch) != 0;
// just print the bitmask:
show_debug_message("Settings bit mask = " + string(_setmask));

The above code prints the current Steam Remote Play session input bitmask into the debug output.



Back To Top

steam_input_set_dualsense_trigger_effect

This function is for input handles of DualSense controllers only, allows to apply an adaptive trigger effect to a DualSense input handle. The format of the struct is described in the example code. Returns true if the operation was successful and false otherwise.


Syntax:

steam_input_set_dualsense_trigger_effect(controller, param);
Argument Type Description
controller real Input controller handle to use.
param struct Trigger effect parameter struct, see the example.


Returns:

Bool


Example:

// please PLEASE PLEASE read the comments for each field here,
// your struct MUST follow this format, otherwise the extension will throw an exception.
// field comments taken from isteamdualsense.h header file from the Steamworks SDK.
var _param = {
    // which triggers to modify, L2, R2, or both
    trigger_mask: steam_input_sce_pad_trigger_effect_trigger_mask_l2 | steam_input_sce_pad_trigger_effect_trigger_mask_r2,
    // must be a valid array of 2 elements, always
    command: [
        // L2 data:
        {
            mode: steam_input_sce_pad_trigger_effect_mode_multiple_position_vibration,
            // command_data must be a valid struct, never undefined
            command_data: {
                // if mode_off then no fields from command_data will be read, otherwise:
                feedback_param: {
                    // if mode_feedback
                    position: 0, /*E position where the strength of target trigger start changing(0~9). */
                    strength: 0  /*E strength that the motor arm pushes back target trigger(0~8 (0: Same as Off mode)). */
                },
                weapon_param: {
                    // if mode_weapon
                    start_position: 0, /*E position where the stiffness of trigger start changing(2~7). */
                    end_position: 0,   /*E position where the stiffness of trigger finish changing(start_position+1~8). */
                    strength: 0        /*E strength of gun trigger(0~8 (0: Same as Off mode)). */
                },
                vibration_param: {
                    // if mode_vibration
                    position: 0,  /*E position where the motor arm start vibrating(0~9). */
                    amplitude: 0, /*E vibration amplitude(0~8 (0: Same as Off mode)). */
                    frequency: 0, /*E vibration frequency(0~255[Hz] (0: Same as Off mode)). */
                },
                multiple_position_feedback_param: {
                    // if mode_multiple_position_feedback
                    /*E strength that the motor arm pushes back target trigger at position(0~8 (0: Same as Off mode)).
                        *  strength[0] means strength of motor arm at position0.
                        *  strength[1] means strength of motor arm at position1.
                        *  ...
                        * */
                    strength: [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ]
                },
                slope_feedback_param: {
                    // if mode_slope_feedback
                    start_position: 0, /*E position where the strength of target trigger start changing(0~end_position). */
                    end_position: 0,   /*E position where the strength of target trigger finish changing(start_position+1~9). */
                    start_strength: 0, /*E strength when trigger's position is start_position(1~8) */
                    end_strength: 0    /*E strength when trigger's position is end_position(1~8) */
                },
                multiple_position_vibration_param: {
                    // if mode_multiple_position_vibration
                    frequency: 0, /*E vibration frequency(0~255 (0: Same as Off mode)) */
                    /*E vibration amplitude at position(0~8 (0: Same as Off mode)).
                        *  amplitude[0] means amplitude of vibration at position0.
                        *  amplitude[1] means amplitude of vibration at position1.
                        *  ...
                        * */
                    amplitude: [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ]
                }
            }
        },
        // R2 data: even if your mask tells "only l2", you MUST still include the dummy r2 field:
        {
            mode: steam_input_sce_pad_trigger_effect_mode_off,
            command_data: {
                // MUST be present even when mode_off!!
            }
        }
    ]
};
// apply the parameters to the dualsense controller:
steam_input_set_dualsense_trigger_effect(player_handle, _param);

The above code demonstrates the use of DualSense adaptive trigger effects in Steam Input, along with documenting every field in the struct.



Steam Utilities

Back To Top

Utilities

The Steam utility functions provide access to gamepad keyboard UI and Steam Deck getters.

The following functions can be used to access Steam Utilities from within GameMaker Studio 2



Back To Top

steam_show_floating_gamepad_text_input

With this function you can show a floating gamepad keyboard window, all input is emulated as if it is a physical keyboard, so keyboard_string or keyboard_check can be used to obtain the input. This function only works in Big Picture or on the Steam Deck. Returns true if the keyboard has been shown successfully, false otherwise.

⚠️ IMPORTANT

You must call steam_utils_enable_callbacks prior to calling this function if you wish to receive Async - Steam gamepad keyboard events.


Syntax:

steam_show_floating_gamepad_text_input(mode, text_field_x, text_field_y, text_field_width, text_field_height);
Argument Type Description
mode real A steam_floating_gamepad_text_input_mode_ constant.
text_field_x real X position of the keyboard window in display coordinates.
text_field_y real Y position of the keyboard window in display coordinates.
text_field_width real Width of the keyboard window in display coordinates.
text_field_height real Height of the keyboard window in display coordinates.


async_load contents:

Key Value Description
event_type string A constant string "floating_gamepad_text_input_dismissed".


Returns:

Bool


Extended Example:

steam_utils_enable_callbacks(); // do this somewhere once.
// show the dialog:
steam_show_floating_gamepad_text_input(
    steam_floating_gamepad_text_input_mode_single_line,
    // in Display coordinates: use window_get_ or display_get_ functions to obtain the dimensions
    window_get_x(),
    window_get_y()/2,
    window_get_width(),
    window_get_height()/2
);
/// @description Async - Steam event
if (async_load[? "event_type"] == "floating_gamepad_text_input_dismissed") {
    show_debug_message("Floating gamepad keyboard UI dialog dismissed.");
}

The above code shows a floating keyboard window in the bottom half of the window, then print a message to debug output when the dialog is dismissed.



Back To Top

steam_dismiss_floating_gamepad_text_input

With this function you can dismiss a floating keyboard window if it is being currently shown. Returns true if the operation was successful, false otherwise.


Syntax:

steam_dismiss_floating_gamepad_text_input();


Returns:

Bool


Example:

steam_dismiss_floating_gamepad_text_input();

The above code will dismiss the floating keyboard window if it is being displayed.



Back To Top

steam_show_gamepad_text_input

With this function you can show a full-screen old-style Big Picture Mode-only keyboard UI. This one does not emulate the physical keyboard so you must use the steam_get_entered_gamepad_text_input function inside a corresponding Async - Steam event to obtain the input. Returns true if the window is being shown successfully, false otherwise.

⚠️ IMPORTANT

You must call steam_utils_enable_callbacks prior to calling this function if you wish to receive Async - Steam gamepad keyboard events.


Syntax:

steam_show_gamepad_text_input(mode,lines_mode,description,chars_max,existing_text);
Argument Type Description
mode real A steam_gamepad_text_input_mode_ constant.
lines_mode real A steam_gamepad_text_input_line_mode_ constant.
description string The description of the window.
chars_max real The maximum amount of characters the player can enter.
existing_text string Some existing text to put into the text field or an empty string.


async_load contents:

Key Value Description
event_type string A string "gamepad_text_input_dismissed".
submitted bool true if the dialog was submitted successfully and false if it was cancelled.
submitted_text_raw_byte_length real Raw length of the text in bytes.


Returns:

Bool


Extended Example:

steam_utils_enable_callbacks(); // somewhere once.
// show the dialog:
steam_show_gamepad_text_input(
    steam_gamepad_text_input_mode_normal,
    steam_gamepad_text_input_line_mode_single_line,
    "Some Description",
    100, // up to 100 string characters
    "" // no default text, can be any string, ex: "Player 1" etc
);
/// @description Async - Steam event
if (async_load[? "event_type"] == "gamepad_text_input_dismissed") {
    if (async_load[? "submitted"]) {
        var _input = steam_get_entered_gamepad_text_input();
        show_debug_message("Old-style dialog result: " + _input);
    }
}

The above code will show a modal gamepad keyboard input dialog with "Some Description" as the description and an empty text field, then print the typed text.



Back To Top

steam_get_entered_gamepad_text_input

With this function you can obtain the result of the steam_show_gamepad_text_input input dialog. This function must only be called in the corresponding Async - Steam event.

⚠️ IMPORTANT

You must call steam_utils_enable_callbacks prior to calling this function if you wish to receive Async - Steam gamepad keyboard events.


Syntax:

steam_get_entered_gamepad_text_input();


Returns:

string


Example:

/// @description Async - Steam event
if (async_load[? "event_type"] == "gamepad_text_input_dismissed") {
    if (async_load[? "submitted"]) {
        var _input = steam_get_entered_gamepad_text_input();
        show_debug_message("Old-style dialog result: " + _input);
    }
}

The above code will activate the use of gamepad keyboard UI async events.



Back To Top

steam_utils_enable_callbacks

With this function you can activate the dispatch of Async - Steam events for gamepad keyboard UI. Returns true if the operation was successful and false otherwise.


Syntax:

steam_utils_enable_callbacks();


Returns:

Bool


Example:

steam_utils_enable_callbacks();

The above code will activate the use of gamepad keyboard UI async events.



Back To Top

steam_utils_is_steam_running_on_steam_deck

With this function you can check if your game is currently running on a Steam Deck, returns true if yes and false otherwise.


Syntax:

steam_utils_is_steam_running_on_steam_deck();


Returns:

Bool


Example:

if (steam_utils_is_steam_running_on_steam_deck()) {
    show_debug_message("The game is running on a Steam Deck.");
}

The above code will print a message to debug output if the game is running on the Steam Deck.