-
Notifications
You must be signed in to change notification settings - Fork 12
Social
The following set of functions are used for setting or getting social information.
The following functions are provided to work with rich presence:
- steam_set_rich_presence
- steam_clear_rich_presence
- steam_request_friend_rich_presence
- steam_get_friend_rich_presence
- steam_get_friend_rich_presence_key_count
- steam_get_friend_rich_presence_key_by_index
The following functions are provided to work with user and friends data:
- steam_user_set_played_with
- steam_get_friends_game_info
- steam_get_user_avatar
- steam_image_get_size
- steam_image_get_rgba
- steam_image_get_bgra
This module offers a collection of structs, which serve as custom data models for organizing and structuring data. Explore the provided structs to better understand the relationships between data elements and simplify your data manipulation tasks.
This module includes a set of predefined constants that can be utilized for various purposes. Browse through the available constants to find values relevant to your needs and enhance the efficiency of your code.
This function 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 of values for the local user rich presence. After that, it clears these values (using a call to the steam_clear_rich_presence function) so that they will no longer show.
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 these values meaning those will no longer show.
This function 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:
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.
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:
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 your friends to see if anyone of them is playing the same game as you (steam_get_app_id) and check if they have any open lobbies. If so, we can request to join the lobby they're in using steam_lobby_join_id.
This function fetches an avatar for the specified user ID.
It returns 0 if no avatar is set for the user;
it returns -1 if the request is pending, in which case a Steam Async Event will be triggered.
Returns positive ID's if the avatar is ready, this ID is to be used with the following functions:
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_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:
Triggers:
| Key | Type | Description |
|---|---|---|
| event_type | String | The string value "avatar_image_loaded"
|
| success | Boolean | 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);
var _l_ok = steam_image_get_rgba(_l_img, _l_cols, _buff_size);
if(!_l_ok)
{
buffer_delete(_l_cols);
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);
}In the code above we query for the current user's steam_get_user_steam_id avatar, 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 getting the avatar image RBGA data into the buffer (steam_image_get_rgba) and lastly 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 user.
- a value of -1: in this last case it means 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");
}This function fetches the dimensions of the said Steam image ID. If the call succeeds, the return value is a two-element array containing the 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:
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);
var _l_ok = steam_image_get_rgba(_l_img, _l_cols, _buff_size);
if(!_l_ok)
{
buffer_delete(_l_cols);
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 shows a code example.
This function grabs the 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:
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);
var _l_ok = steam_image_get_rgba(_l_img, l_cols, buff_size);
if(!_l_ok)
{
buffer_delete(_l_cols);
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);
}In the code above we query 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.
This function grabs the 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 | The buffer where data will be written |
| size | Real | The size of the buffer supplied |
Returns:
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);
var _l_ok = steam_image_get_bgra(_l_img, _l_cols, _buff_size);
if(!_l_ok)
{
buffer_delete(_l_cols);
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);
}In the code above we query 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.
Requests Rich Presence data from a specific user. This is used to get the Rich Presence information from a user that is not a friend of the current user, like someone in the same lobby or game server. This function is rate limited, if you call this too frequently for a particular user then it will just immediately post a callback without requesting new data from the server.
Please see the related functions:
steam_get_friend_rich_presence steam_get_friend_rich_presence_key_by_index steam_get_friend_rich_presence_key_count
Warning
This function is asynchronous and as such the result will only arrive in an Async - Steam event
Syntax:
steam_request_friend_rich_presence(userID)
| Argument | Type | Description |
|---|---|---|
| userID | Int64 | The user Steam unique identifier |
Returns:
Example:
Please see examples for the related functions such as steam_get_friend_rich_presence or steam_get_friend_rich_presence_key_count
Get a Rich Presence value from a specified friend.
Warning
You MUST use steam_request_friend_rich_presence to obtain the Rich Presence data for a particular user before using this function
Syntax:
steam_get_friend_rich_presence(userID, key)
| Argument | Type | Description |
|---|---|---|
| userID | Int64 | The user Steam unique identifier |
| key | String | Rich Presence string key, for example "status" or "connect" |
Returns:
Example:
/// @desc Create Event
busy = false; // are we busy with the request?
if (steam_request_friend_rich_presence(friendSteamIdGoesHere))
busy = true; // waiting for the request
/// @desc Async - Steam Event
if (async_load[? "event_type"] == "friend_rich_presence_update") {
// check if this is data for the user we care about
if (async_load[? "steam_id_friend"] == friendSteamIdGoesHere) {
busy = false; // no longer busy with the request
var friendstatus = steam_get_friend_rich_presence(friendSteamIdGoesHere, "status");
show_debug_message("friend rich presence status is " + friendstatus);
}
}The extended code example above shows how to properly request, wait for and read the rich presence data of a Steam user
Gets the number of Rich Presence keys that are set on the specified user. This is used for iteration, after calling this then steam_get_friend_rich_presence_key_by_index to get the rich presence keys. This is typically only ever used for debugging purposes.
Warning
You MUST use steam_request_friend_rich_presence to obtain the Rich Presence data for a particular user before using this function
Syntax:
steam_get_friend_rich_presence_key_count(userID)
| Argument | Type | Description |
|---|---|---|
| userID | Int64 | The user Steam unique identifier |
Returns:
Example:
/// @desc Create Event
busy = false; // are we busy with the request?
if (steam_request_friend_rich_presence(friendSteamIdGoesHere))
busy = true; // waiting for the request
/// @desc Async - Steam Event
if (async_load[? "event_type"] == "friend_rich_presence_update") {
// check if this is data for the user we care about
if (async_load[? "steam_id_friend"] == friendSteamIdGoesHere) {
busy = false; // no longer busy with the request
show_debug_message("Begin rich presence for Steam user " + string(friendSteamIdGoesHere);
var keycount = steam_get_friend_rich_presence_key_count(friendSteamIdGoesHere);
for (var index = 0; index < keycount; ++index) {
var key = steam_get_friend_rich_presence_key_by_index(friendSteamIdGoesHere, index);
var value = steam_get_friend_rich_presence(friendSteamIdGoesHere, key);
show_debug_message(key + ": " + value);
}
show_debug_message("End rich presence");
}
}The extended code example above shows how to properly request, wait for and iterate the rich presence data of a Steam user
Obtains a Rich Presence key from an index between 0 and steam_get_friend_rich_presence_key_count exclusive. For debugging only.
Warning
You MUST use steam_request_friend_rich_presence to obtain the Rich Presence data for a particular user before using this function
Syntax:
steam_get_friend_rich_presence_key_by_index(userID, index)
| Argument | Type | Description |
|---|---|---|
| userID | Int64 | The user Steam unique identifier |
| index | Real | Index of the key |
Returns:
Example:
Please see steam_get_friend_rich_presence_key_count for the code example as both functions are heavily related.
These constants are referenced by the following functions:
| Member | Description |
|---|---|
steam_user_avatar_size_small |
Small avatar size |
steam_user_avatar_size_medium |
Medium avatar size |
steam_user_avatar_size_large |
Large avatar size |
This struct is referenced by the following functions:
| Member | 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 |
GameMaker 2024