General

Jump to bottom

DiasFranciscoA edited this page Nov 14, 2024 · 14 revisions

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:

Functions

This module offers a collection of functions designed to address specific tasks and provide utilities for various purposes. Explore the available functions to make the most of the functionalities provided by this module.

steam_initialised

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

Syntax:

steam_initialised()

Returns:

Boolean

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.

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:

Boolean

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.

steam_get_app_id

This function is used retrieve the unique app ID that Steam assigns to your game, which is required for using some of the UGC 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.

steam_get_user_account_id

This function is used to retrieve the unique User ID that Steam assigns to each user, which is required for using some of the UGC 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.

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.

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.

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.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Steam Async Event.

Syntax:

steam_get_user_persona_name(steamID)

Argument	Type	Description
steamID	Int64	The unique Steam ID for a user.

Returns:

Real

Triggers:

Steam Async 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 Steam Async Event.

steam_get_user_persona_name_sync

This function gets the specified user's persona (display) name.

This will only be known to the current user if the other user is in their friends list, on the same game server, in a chat room or lobby, or in a small Steam group with the local user.

Syntax:

steam_get_user_persona_name_sync(steamID)

Argument	Type	Description
steamID	Int64	The unique Steam ID for a user.

Returns:

String

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:

Boolean

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.

steam_user_get_auth_ticket_for_web_api

Retrieve an authentication ticket to be sent to the entity that wishes to authenticate you using the ISteamUserAuth/AuthenticateUserTicket Web API. It is best practice to use an identity string for each service that will consume tickets.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Steam Async Event.

Syntax:

steam_user_get_auth_ticket_for_web_api(identity=undefined)

Argument	Type	Description
identity	String	OPTIONAL: The identity of the remote service that will authenticate the ticket. The service should provide a string identifier.

Returns:

Real

Triggers:

Steam Async Event

Key	Type	Description
event_type	String	The string value `"ticket_for_web_api_response"`
result	Real	The Steam EResult code
success	Boolean	Whether `result` is equal to the value `k_EResultOK`
auth_ticket_handle	Real	The handle of the auth ticket, can be passed to `steam_user_cancel_auth_ticket`
auth_ticket_buffer	Buffer	Auth ticket buffer id on success or -1 on failure

Example:

/// @desc Create
web_ticket_handle = steam_user_get_auth_ticket_for_web_api("myservice"); // if value is 0 then this failed
/// @desc Async - Steam
if (async_load[? "event_type"] == "ticket_for_web_api_response" &&
    async_load[? "auth_ticket_handle"] == web_ticket_handle) {
    if (async_load[? "success"]) {
        var buffer = async_load[? "auth_ticket_buffer"];
        // convert bytes in buffer into a lowercase hex string and send over HTTP
        // then do steam_user_cancel_auth_ticket(web_ticket_handle); after you're done with your HTTP request flow
    }
}

The above code will request a ticket to be used with the Web API and obtain the buffer with the ticket bytes. If you ever need to convert the byte buffer into a hexadecimal string you can do so by using a conversion function like the one below:

function convert_byte_buffer_to_hex_string(_buffer, _offset = 0, _length = (buffer_get_size(_buffer) - _offset)) {

    static _nibble_to_hexa = [ ord("0"), ord("1"), ord("2"), ord("3"), ord("4"), ord("5"), ord("6"), ord("7"),
                              ord("8"), ord("9"), ord("a"), ord("b"), ord("c"), ord("d"), ord("e"), ord("f") ];

    // Store the tell of the input buffer so we can reset it at the end
    var _tell = buffer_tell(_buffer);

    // Seek to the offset where we want to start the conversion
    buffer_seek(_buffer, buffer_seek_start, _offset);

    // Create an output buffer that will be 2 times + 1 (terminate character)
    var _temp_buffer = buffer_create(_length * 2, buffer_fixed, 1);
    repeat (_length) {
        // Read the byte
        var _byte = buffer_read(_buffer, buffer_u8);
        // Split the byte into 2 nibbles (higher and lower)
        var _high = (_byte & $F0) >> 4;
        var _low = _byte & $0F;
        // Use the convertion table to get the currect character
        buffer_write(_temp_buffer, buffer_u8, _nibble_to_hexa[_high]);
        buffer_write(_temp_buffer, buffer_u8, _nibble_to_hexa[_low]);
    }
    // Write the end string character '\0'
    buffer_write(_temp_buffer, buffer_u8, 0);

    // Seek the original buffer to the original place
    buffer_seek(_buffer, buffer_seek_start, _tell);

    // Read the converted string and delete the temp buffer
    var _hexa_string = buffer_peek(_temp_buffer, 0, buffer_string);
    buffer_delete(_temp_buffer);

    return _hexa_string;
}

steam_user_get_auth_session_ticket

Retrieve an authentication ticket to be sent to the entity who wishes to authenticate you. After calling this you can send the ticket to the entity where they can then call BeginAuthSession/ISteamGameServer::BeginAuthSession to verify this entity's integrity.

Note

This API can not be used to create a ticket for use by the ISteamUserAuth/AuthenticateUserTicket Web API. Use the steam_user_get_auth_ticket_for_web_api call instead

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Steam Async Event.

Syntax:

steam_user_get_auth_session_ticket()

Returns:

Real

Triggers:

Steam Async Event

Key	Type	Description
event_type	String	The string value `"ticket_response"`
result	Real	The Steam EResult code
success	Boolean	Whether `result` is equal to the value `k_EResultOK`
auth_ticket_handle	Real	The handle of the auth ticket, can be passed to `steam_user_cancel_auth_ticket`

Example:

/// @desc Create
srv_ticket_buffer = steam_user_get_auth_session_ticket();
srv_ticket_handle = 0; // 0 means invalid handle
/// @desc Async - Steam
if (async_load[? "event_type"] == "ticket_response") {
    if (async_load[? "success"]) {
        srv_ticket_handle = async_load[? "auth_ticket_handle"];
        // do your usual game server authentication flow with the ticket buffer & handle
        // then do steam_user_cancel_auth_ticket(srv_ticket_handle); after you're done
    }
}

The above code will request a ticket to be used with the Game Server Authentication and obtain the handle to the ticket.

steam_user_cancel_auth_ticket

This function cancels an authentication ticket created by steam_user_get_auth_session_ticket or steam_user_get_auth_ticket_for_web_api

Syntax:

steam_user_cancel_auth_ticket(ticket_handle=undefined)

Argument	Type	Description
ticket_handle	Real	OPTIONAL The ticket handle to cancel

Returns:

N/A

steam_current_game_language

This function retrieves 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.

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:

languages = steam_available_languages();

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

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:

Boolean

Example:

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

The above code will check to see if the user is subscribed and shows a debug message if that is the case.

steam_set_warning_message_hook

This function sets a warning message hook to receive Steam API 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.

GameMaker 2024