stingray.Leaderboard namespace reference

Description

This interface is for accessing the leaderboards functionality on Steam.

As the object is a singleton (there is only one Leaderboard), you do not need to pass any Leaderboard object to the functions. All the functions operate on the Leaderboard singleton.

Other related reference items

	stingray.LeaderboardTransactionToken
	steam_leaderboard_progress
	Steam

Functions

close ( token ) Frees the memory used by the engine to monitor the request that corresponds to the specified token.

Parameters

token :

stingray.LeaderboardTransactionToken

The token that you want to close.

Returns

This function does not return any values.

Other related reference items

stingray.LeaderboardTransactionToken

init_leaderboards ( boards ) : stingray.LeaderboardTransactionToken Preloads the specified leaderboards.

Parameters

boards :

any(string, string[])

The name of the leaderboard, or a table that contains multiple leaderboard names. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.

Returns

stingray.LeaderboardTransactionToken

A token that you can query by calling progress().

All leaderboards that are used by the game through the Leaderboard interface can be 'preloaded' before use. It is recommended to preload if all leaderboards are known beforehand. This is not a requirement, but it makes future queries on leaderboards snappier (the first time one of the preloaded leaderboards is used).

For example:

token1 = stingray.Leaderboard.init_leaderboards("jumps")
token2 = stingray.Leaderboard.init_leaderboards({ "jumps", "high_jumps" })

progress ( token ) : table Retrieves information about the current state of the operation identified by the specified token.

Parameters

token :

stingray.LeaderboardTransactionToken

Specifies a LeaderboardTransactionToken.

Returns

table

A table that contains information about the operation.

Other related reference items

	stingray.LeaderboardTransactionToken
	steam_leaderboard_progress
	stingray.Leaderboard.init_leaderboards() stingray.Leaderboard.ranking_around_self() stingray.Leaderboard.ranking_for_friends() stingray.Leaderboard.ranking_range() stingray.Leaderboard.register_score()

ranking_around_self ( board, ranks_before, ranks_after, data_template ) : stingray.LeaderboardTransactionToken Fetches ranking information for players around the logged in player.

Parameters

board :	string	The ID of the leaderboard to fetch data from.
ranks_before :	integer	The number of ranks to fetch before the logged-in player: i.e. the number of better scores to retrieve.
ranks_after :	integer	The number of ranks to fetch after the logged-in player: i.e. the number of worse scores to retrieve.
data_template :	table?	Optional. Skip this parameter in case you do not store custom data in the leaderboard. Otherwise, set this to a table that contains the format for your custom data if you wish to read the data. This table must be exactly equal to the table sent as data template to the stingray.Leaderboard.register_score() function. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.LeaderboardTransactionToken

A token that you can query by calling progress().

For example:

template =
{
    Leaderboard.BOOL,
    Leaderboard.STRING(6),
    Leaderboard.INT(8)
}

token = Leaderboard.ranking_around_self("jumps", 5, 5, template)

ranking_for_friends ( board, data_template ) : stingray.LeaderboardTransactionToken Fetches ranking information for the current player and friends.

Parameters

board :	string	The ID of the leaderboard to fetch data from.
data_template :	table?	Optional. Skip this parameter in case you do not store custom data in the leaderboard. Otherwise, set this to a table that contains the format for your custom data if you wish to read the data. This table must be exactly equal to the table sent as data template to the stingray.Leaderboard.register_score() function. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.LeaderboardTransactionToken

A token that you can query by calling progress().

ranking_range ( board, start_range, num_ranks, data_template ) : stingray.LeaderboardTransactionToken Fetches a part of a leaderboard.

Parameters

board :	string	The ID of the leaderboard to fetch data from.
start_range :	integer	The first serial rank to fetch (starts at 1).
num_ranks :	integer	The number of ranks to fetch including the start rank.
data_template :	table?	Optional. Skip this parameter in case you do not store custom data in the leaderboard. Otherwise, set this to a table that contains the format for your custom data if you wish to read the data. This table must be exactly equal to the table sent as data template to the stingray.Leaderboard.register_score() function. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.LeaderboardTransactionToken

A token that you can query by calling progress().

For example:

token = Leaderboard.ranking_range("jumps", 1, 100)

Other related reference items

steam_leaderboard_progress.scores steam_leaderboard_progress.total_scores

register_score ( board, score, update_method, data_template, data ) : stingray.LeaderboardTransactionToken Registers a new score for the specified leaderboard.

Parameters

board :	string	The leaderboard to register the score with.
score :	any(integer, string)	If the score is a number, the value is used to update the score. If the score is a string, the value of the stat with the same name is used to update the score. The any(...) notation indicates that this item may be an instance of any of the types shown in the parentheses.
update_method :	integer?	Specifies how the existing score on the leaderboard must be updated. May be any of the constants in the update mode group. Optional; default is Leaderboard.KEEP_BEST. The ? notation indicates that this type is optional: there may be zero or one instances of it.
data_template :	table?	Optional. This lists the data types that contains data and how they must be packed. The table must be a plain list with the following possible entries: stingray.Leaderboard.INT(num_bits) stingray.Leaderboard.UNIT(num_bits) stingray.Leaderboard.STRING(num_chars) stingray.Leaderboard.BOOL stingray.Leaderboard.NUMBER Each type definition must correspond to the values specified in the data parameter. The total size of the packed data cannot exceed 64 bytes; exceeding the size limit will cause you to lose information. The ? notation indicates that this type is optional: there may be zero or one instances of it.
data :	table?	Optional. This lists the values that must be packed using the data template. INT, UINT, and NUMBER types must be represented by number values. BOOL types must be boolean values, and STRING types must be a string with equal or fewer characters than what is specified in the template. The ? notation indicates that this type is optional: there may be zero or one instances of it.

Returns

stingray.LeaderboardTransactionToken

A token that you can query by calling progress().

For example:

token1 = stingray.Leaderboard.register_score("jumps", 10)

token2 = stingray.Leaderboard.register_score(
    "jumps",
    10,
    {
        stingray.Leaderboard.BOOL,
        stingray.Leaderboard.STRING(6),
        stingray.Leaderboard.INT(8)
    },
    {
        false,
        "high",
        -128
    }
)

Other related reference items

	stingray.Leaderboard.ranking_around_self() stingray.Leaderboard.ranking_for_friends() stingray.Leaderboard.ranking_range()
	Update modes

Data type specifiers

BOOL : integer A type specifier for a boolean value, to be used in data template tables.

Other related reference items

stingray.Leaderboard.ranking_around_self() stingray.Leaderboard.register_score()

NUMBER : integer A type specifier for a floating-point number, to be used in data template tables.

INT ( num_bits ) : userdata Returns a type specifier for a signed integer, to be used in data template tables.

Parameters

num_bits :

integer

The number of bits to use to store the number. Note: One bit is used for the sign, so a 2-bit INT can hold values from -2 to 1. The largest value that can be stored is 2^(num_bits-1) -1.

Returns

userdata

A type specifier for a signed integer, to be used in data template tables.

Other related reference items

stingray.Leaderboard.ranking_around_self() stingray.Leaderboard.register_score()

STRING ( num_chars ) : userdata Returns a type specifier for a fixed size string, to be used in data template tables.

Parameters

num_chars :

integer

The number of characters reserved to store the string. This must be at least the number of characters of the largest string to be stored. In reality, an extra termination character is reserved.

Returns

userdata

A type specifier for a fixed size string, to be used in data template tables.

Other related reference items

stingray.Leaderboard.ranking_around_self() stingray.Leaderboard.register_score()

UINT ( num_bits ) : userdata Returns a type specifier for an unsigned integer, to be used in data template tables.

Parameters

num_bits :

integer

The number of bits to use to store the number. The largest value that can be stored is 2^num_bits - 1.

Returns

userdata

A type specifier for an unsigned integer, to be used in data template tables.

Update modes

The constants in this group can be passed in calls to register_score().

FORCE_UPDATE : integer The leaderboard score will always be updated with the new value.

KEEP_BEST : integer The existing score will only be updated if the new one is better.

Other related reference items

stingray.Leaderboard.register_score()