Skip to content

Scores

Jump to bottom
Francisco Dias edited this page Jan 30, 2023 · 3 revisions

Back To Top

Scores

Implement leaderboards in your game to allow anyone to battle it out for the top spots. You create the leaderboards, you control the scoring. You can even allow guests to score without a Game Jolt account.

Functions

The following functions are provided for working with scores and leaderboards:

Structs

Extra details on structs that are returned as score fetching results:



Back To Top

GameJolt_Scores_Add

This function adds a score representing the logged user. This is an asynchronous function that will trigger either the callback_success method (if task is successful) or the callback_failed method (if task fails).


Syntax:

GameJolt_Scores_Add(table_id, score, sort, extra_data, [callback_success], [callback_failed])
Argument Type Description
table_id real The ID of the score table to submit to.
score string This is a string value associated with the score.
sort real This is a numerical sorting value associated with the score. All sorting will be based on this number.
extra_data string If there's any extra data you would like to store as a string, you can use this variable.
callback_success function The callback function executed when the request succeeds ✴️ OPTIONAL
callback_failed function The callback function executed if the request fails (error message is passed as argument) ✴️ OPTIONAL

Returns:

N/A

Example:

GameJolt_Scores_Add(668889,"Points: " + string(points), points, "this is some metadata",
    function()
    {
        show_message_async("Score submitted successfully!")
    });

The code above will submit a score value for the current logged user to a given table_id, and print a success message if it succeeds.



Back To Top

GameJolt_Scores_Add_Guest

This function adds a score representing a guest user. This is an asynchronous function that will trigger either the callback_success method (if task is successful) or the callback_failed method (if task fails).


Syntax:

GameJolt_Scores_Add_Guest(guest, table_id, score, sort, extra_data, [callback_success], [callback_failed])
Argument Type Description
guest string The guest's name.
table_id real The ID of the score table to submit to.
score string This is a string value associated with the score.
sort real This is a numerical sorting value associated with the score. All sorting will be based on this number.
extra_data string If there's any extra data you would like to store as a string, you can use this variable.
callback_success function The callback function executed when the request succeeds ✴️ OPTIONAL
callback_failed function The callback function executed if the request fails (error message is passed as argument) ✴️ OPTIONAL

Returns:

N/A

Example:

GameJolt_Scores_Add_Guest("guestName123", 668889, "Points: " + string(points), points, "this is some metadata",
    function()
    {
        show_message_async("Score submitted successfully!")
    });

The code above will submit a score value for a guest user ("guestName123") to a given table_id, and print a success message if it succeeds.



Back To Top

GameJolt_Scores_Fetch

This function fetches scores from a score table. This is an asynchronous function that will trigger either the callback_success method (if task is successful) or the callback_failed method (if task fails).


Syntax:

GameJolt_Scores_Fetch(table_id, limit, [callback_success], [callback_failed])
Argument Type Description
table_id real The ID of the score table to submit to.
limit real The number of scores you'd like to return.
callback_success function The callback function executed if the request succeeds (an array of ScoreData structs is passed as argument) ✴️ OPTIONAL
callback_failed function The callback function executed if the request fails (error message is passed as argument) ✴️ OPTIONAL

Returns:

N/A

Example:

GameJolt_Scores_Fetch(668889, 10, function(scoresArray) {

    var scoreData = scoresArray[0];

    var _score = scoreData.score;
    var sort = scoreData.sort;
    var extra_data = scoreData.extra_data;
    var user = scoreData.user;
    var user_id = scoreData.user_id;
    var guest = scoreData.guest;
    var stored = scoreData.stored;
    var stored_timestamp = scoreData.stored_timestamp;

})

The code above will fetch a total of 10 scores from a given table_id and on success collect all the data that is presented from the first entry in the returned array.



Back To Top

GameJolt_Scores_Fetch_BetterThan

This function fetches score from a score table, that are better than a given value. This is an asynchronous function that will trigger either the callback_success method (if task is successful) or the callback_failed method (if task fails).


Syntax:

GameJolt_Scores_Fetch_BetterThan(table_id, better_than, limit, [callback_success], [callback_failed])
Argument Type Description
table_id real The ID of the score table to submit to.
better_than real Fetch only scores better than this score sort value.
limit real The number of scores you'd like to return.
callback_success function The callback function executed if the request succeeds (an array of ScoreData structs is passed as argument) ✴️ OPTIONAL
callback_failed function The callback function executed if the request fails (error message is passed as argument) ✴️ OPTIONAL

Returns:

N/A

Example:

GameJolt_Scores_Fetch_BetterThan(668889, 10, 9999, function(scoresArray) {

    var scoreData = scoresArray[0];

    var _score = scoreData.score;
    var sort = scoreData.sort;
    var extra_data = scoreData.extra_data;
    var user = scoreData.user;
    var user_id = scoreData.user_id;
    var guest = scoreData.guest;
    var stored = scoreData.stored;
    var stored_timestamp = scoreData.stored_timestamp;

})

The code above will fetch a total of 10 scores from a given table_id that are better than the value 9999 and on success collect all the data that is presented from the first entry in the returned array.



Back To Top

GameJolt_Scores_Fetch_Guest

This function fetches the score of guest user from a score table. This is an asynchronous function that will trigger either the callback_success method (if task is successful) or the callback_failed method (if task fails).


Syntax:

GameJolt_Scores_Fetch_Guest(table_id, guest, [callback_success], [callback_failed])
Argument Type Description
table_id real The ID of the score table
callback_success function The callback function executed if the request succeeds (a ScoreData struct is passed as argument) ✴️ OPTIONAL
callback_failed function The callback function executed if the request fails (error message is passed as argument) ✴️ OPTIONAL

Returns:

N/A

Example:

GameJolt_Scores_Fetch_Guest(668889, "guestName123", function(scoreData) {

    var _score = scoreData.score;
    var sort = scoreData.sort;
    var extra_data = scoreData.extra_data;
    var user = scoreData.user;
    var user_id = scoreData.user_id;
    var guest = scoreData.guest;
    var stored = scoreData.stored;
    var stored_timestamp = scoreData.stored_timestamp;

})

The code above will fetch a ScoreData struct from the given table_id that is associated with the guest "guestName123" and on success collect all the data that is presented in the struct.



Back To Top

GameJolt_Scores_Fetch_Me

This function fetches the score of the current user from a score table. This is an asynchronous function that will trigger either the callback_success method (if task is successful) or the callback_failed method (if task fails).


Syntax:

GameJolt_Scores_Fetch_Me(table_id, [callback_success], [callback_failed])
Argument Type Description
table_id real The ID of the score table
callback_success function The callback function executed if the request succeeds (a ScoreData struct is passed as argument) ✴️ OPTIONAL
callback_failed function The callback function executed if the request fails (error message is passed as argument) ✴️ OPTIONAL

Returns:

N/A

Example:

GameJolt_Scores_Fetch_Guest(668889, function(scoreData) {

    var _score = scoreData.score;
    var sort = scoreData.sort;
    var extra_data = scoreData.extra_data;
    var user = scoreData.user;
    var user_id = scoreData.user_id;
    var guest = scoreData.guest;
    var stored = scoreData.stored;
    var stored_timestamp = scoreData.stored_timestamp;

})

The code above will fetch a ScoreData struct from the given table_id that is associated with the currently logged user and on success collect all the data that is presented in the struct.



Back To Top

GameJolt_Scores_Fetch_WorseThan

This function fetches score from a score table, that are worse than a given value. This is an asynchronous function that will trigger either the callback_success method (if task is successful) or the callback_failed method (if task fails).


Syntax:

GameJolt_Scores_Fetch_WorseThan(table_id, worse_than, limit, [callback_success], [callback_failed])
Argument Type Description
table_id real The ID of the score table to submit to.
worse_than real Fetch only scores worse than this score sort value.
limit real The number of scores you'd like to return.
callback_success function The callback function executed if the request succeeds (an array of ScoreData structs is passed as argument) ✴️ OPTIONAL
callback_failed function The callback function executed if the request fails (error message is passed as argument) ✴️ OPTIONAL

Returns:

N/A

Example:

GameJolt_Scores_Fetch_WorseThan(668889, 10, 10, function(scoresArray) {

    var scoreData = scoresArray[0];

    var _score = scoreData.score;
    var sort = scoreData.sort;
    var extra_data = scoreData.extra_data;
    var user = scoreData.user;
    var user_id = scoreData.user_id;
    var guest = scoreData.guest;
    var stored = scoreData.stored;
    var stored_timestamp = scoreData.stored_timestamp;

})

The code above will fetch a total of 10 scores from a given table_id that are worse than the value 10 and on success collect all the data that is presented from the first entry in the returned array.



Back To Top

GameJolt_Scores_Rank

This functions gets a rank for a specific score. This is an asynchronous function that will trigger either the callback_success method (if task is successful) or the callback_failed method (if task fails).


Syntax:

GameJolt_Scores_Rank(table_id, sort, [callback_success], [callback_failed])
Argument Type Description
table_id real The ID of the score table to submit to.
sort real This is a numerical sorting value associated with the score. All sorting will be based on this number.
callback_success function The callback function executed if the request succeeds (a rank value is passed as argument) ✴️ OPTIONAL
callback_failed function The callback function executed if the request fails (error message is passed as argument) ✴️ OPTIONAL

Returns:

N/A

Example:

GameJolt_Scores_Rank(668889, 100,
    function(rank) {
        show_message_async(rank)
    });

The code above will query the rank on the current logged user on the given table_id and show it to the user.



Back To Top

GameJolt_Scores_Tables

This function fetches a list of score tables. This is an asynchronous function that will trigger either the callback_success method (if task is successful) or the callback_failed method (if task fails).


Syntax:

GameJolt_Scores_Tables([callback_success], [callback_failed])
Argument Type Description
callback_success function The callback function executed if the request succeeds (array of table_id is passed as argument) ✴️ OPTIONAL
callback_failed function The callback function executed if the request fails (error message is passed as argument) ✴️ OPTIONAL

Returns:

N/A

Example:

GameJolt_Scores_Tables(function(array)
    {
        show_message_async(array);
    },
    function(message)
    {
        show_message_async(message)
    }
)

In the code sample above we perform a fetch action to retrieve all the score table_ids associated with this game. We then provide two methods: the success method will display the array of existing table ids and the failure method will show a message with the error information.



Back To Top

ScoreData

This struct is returned as an async result of the call to the following API function calls:

Property Type Description
score string The score string (example: "234 Coins")
sort real The score's numerical sort value.
extra_data string Any extra data associated with the score (example: "Level 2")
user string If this is a user score, this is the display name for the user.
user_id real If this is a user score, this is the user's ID.
guest string If this is a guest score, this is the guest's submitted name.
stored string Returns when the score was logged by the user (example: "1 week ago")
stored_timestamp real Returns the timestamp (in seconds) of when the score was logged by the user.



YoYoGames 2023

Clone this wiki locally