game jolt api
v0.0.7
Wrapper for the Game Jolt API running through HTTP requests. It contains all Game Jolt API endpoints and aims to simplify its use where it's possible. Compatible with Godot 4.x. For the Godot 3.x version, see this branch.
For examples of use, see the documentation below. There's also an example scene in addons/gamejolt/example containing all endpoints and parameters on a graphical interface.
Note: Any parameter followed by an ? is optional.
Example: sessions_ping(status?) -> GameJolt.
Project Settings > Plugins
Project Settings > General > Game Jolt > Config > Global.Project Settings > General > Game Jolt > Config > Debug.
After this setup you can perform the API requests by using the methods below on the singleton GameJolt on your code.
Each Game Jolt API method emits a signal after a request is completed, be it successful or not. You can connect specific signals to capture responses on method callbacks:
func _ready() -> void:
GameJolt.time_completed.connect(_on_GameJolt_time_completed)
GameJolt.time()
func _on_GameJolt_time_completed(result: Dictionary) -> void:
# Do something with the request result...Or you can await the signal result in a variable:
func _onButtonTime_pressed() -> void:
GameJolt.time()
var result: Dictionary = await GameJolt.time_completed
# Do something with the request result...Note: All signals return a response: Dictionary.
General
user_name_changeduser_token_changedgame_id_changedprivate_key_changedUsers
users_fetch_completed(response: Dictionary)users_auth_completed(response: Dictionary)Sessions
sessions_open_completed(response: Dictionary)sessions_ping_completed(response: Dictionary)sessions_check_completed(response: Dictionary)sessions_close_completed(response: Dictionary)Scores
scores_fetch_completed(response: Dictionary)scores_tables_completed(response: Dictionary)scores_add_completed(response: Dictionary)scores_get_rank_completed(response: Dictionary)Trophies
trophies_fetch_completed(response: Dictionary)trophies_add_achieved_completed(response: Dictionary)trophies_remove_achieved_completed(response: Dictionary)Data Storage
data_store_set_completed(response: Dictionary)data_store_update_completed(response: Dictionary)data_store_remove_completed(response: Dictionary)data_store_fetch_completed(response: Dictionary)data_store_get_keys_completed(response: Dictionary)Friends
friends_completed(response: Dictionary)Time
time_completed(response: Dictionary)Batch Calls
batch_completed(response: Dictionary)General methods to configure GameJolt singleton locally.
Set the user name for auth and other user scope tasks. Emits user_name_changed.
value: String -> The user name.Get current user name.
Set the user token for auth and other user scope tasks. Emits user_token_changed.
value: String -> The user game token.Get current user game token.
Set the game ID needed for all tasks. Emits game_id_changed.
value: String -> The game ID from your Game Jolt project.Get current game ID.
Set the private key needed for all tasks. Emits private_key_changed.
value: String -> The game private key from your Game Jolt project.Get current game private key.
Returns a user's data.
Emits users_fetch_completed.
user_name: String (optional) -> The username of the user whose data you'd like to fetch.user_ids: Array[String|int] (optional) -> The IDs of the users whose data you'd like to fetch.Note: The parameters user_name and user_ids are mutually exclusive, you should use only one of them, or none.
If none were provided, will fetch from the current user name set in GameJolt singleton.
Authenticates the user's information.
This should be done before you make any calls for the user, to make sure the user's credentials (username and token) are valid.
The user name and token must be set on GameJolt singleton for it to succeed.
Emits users_auth_completed.
Opens a game session for a particular user and allows you to tell Game Jolt that a user is playing your game.
You must ping the session to keep it active and you must close it when you're done with it.
Emits sessions_open_completed.
Notes:
GameJolt singleton.Pings an open session to tell the system that it's still active.
If the session hasn't been pinged within 120 seconds, the system will close the session and you will have to open another one.
It's recommended that you ping about every 30 seconds or so to keep the system from clearing out your session.
You can also let the system know whether the player is in an "active" or "idle" state within your game.
Emits sessions_ping_completed.
status: String (optional) -> Sets the status of the session to either "active" or "idle".Note: Requires user name and token to be set on GameJolt singleton.
Checks to see if there is an open session for the user.
Can be used to see if a particular user account is active in the game.
Emits sessions_check_completed.
Notes:
false for the "success" field when no open session exists. That behaviour is different from other endpoints which use this field to indicate an error state.GameJolt singleton.Closes the active session.
Emits sessions_close_completed.
Note: Requires user name and token to be set on GameJolt singleton.
Returns a list of scores either for a user or globally for a game.
Emits scores_fetch_completed.
limit: String|int (optional) -> The number of scores you'd like to return.table_id: String|int (optional) -> The ID of the score table.guest: String (optional) -> A guest's name.better_than: String|int (optional) -> Fetch only scores better than this score sort value.worse_than: String|int (optional) -> Fetch only scores worse than this score sort value.this_user: bool (optional) -> If true, fetch only scores of current user. Else, fetch scores of all users.Notes:
GameJolt singleton if this_user is true.limit is 10 scores. The maximum amount of scores you can retrieve is 100.table_id is left blank, the scores from the primary score table will be returned.this_user as true if you would like to retrieve scores for just the user set in the class constructor. Leave this_user as true and guest as "" to retrieve all scores.guest allows you to fetch scores by a specific guest name. Only pass either the this_user as true or the guest (or none), never both.Returns a list of high score tables for a game.
Emits scores_tables_completed.
Adds a score for a user or guest.
Emits scores_add_completed.
score: String -> This is a string value associated with the score. Example: "500 Points".sort: String|int -> This is a numerical sorting value associated with the score. All sorting will be based on this number. Example: 500.table_id: String|int (optional) -> The ID of the score table to submit to.guest: String (optional) -> The guest's name. Overrides the GameJolt singleton's user name.extra_data: String|int|Dictionary|Array (optional) -> If there's any extra data you would like to store as a string, you can use this variable.Notes:
GameJolt singleton and leave guest as empty. If you're storing for a guest, you must pass in the guest parameter.extra_data value is only retrievable through the API and your game's dashboard. It's never displayed publicly to users on the site. If there is other data associated with the score such as time played, coins collected, etc., you should definitely include it. It will be helpful in cases where you believe a gamer has illegitimately achieved a high score.table_id is left blank, the score will be submitted to the primary high score table.Returns the rank of a particular score on a score table.
Emits scores_get_rank_completed.
sort: String|int -> This is a numerical sorting value that is represented by a rank on the score table.table_id: String|int (optional) -> The ID of the score table from which you want to get the rank.Notes:
table_id is left blank, the ranks from the primary high score table will be returned.Returns one trophy or multiple trophies, depending on the parameters passed in.
Emits trophies_fetch_completed.
sort: bool|null (optional) -> Pass in true to return only the achieved trophies for a user. Pass in false to return only trophies the user hasn't achieved. Pass null to retrieve all trophies.trophy_ids: Array[String|int] (optional) -> If you would like to return one or multiple trophies, pass trophy IDs here if you want to return a subset of all the trophies.Notes:
trophy_ids will ignore the achieved parameter if it is passed.GameJolt singleton.Sets a trophy as achieved for a particular user.
Emits trophies_add_achieved_completed.
trophy_id: String|int -> The ID of the trophy to add for the user.Note: Requires user name and token to be set on GameJolt singleton.
Remove a previously achieved trophy for a particular user.
Emits trophies_remove_achieved_completed.
trophy_id: String|int -> The ID of the trophy to remove from the user.Note: Requires user name and token to be set on GameJolt singleton.
Sets data in the data store.
Emits data_store_set_completed.
key: String -> The key of the data item you'd like to set.data: String|Array|Dictionary -> The data you'd like to set.global_data: bool (optional) -> If set to true, ignores user name and token set in GameJolt and processes global data instead of user data.Notes:
global_data is false, requires user name and token to be set on GameJolt singleton.Updates data in the data store.
Emits data_store_update_completed.
key: String -> The key of the data item you'd like to update.operation: String -> The operation you'd like to perform.value: String|int -> The value you'd like to apply to the data store item.global_data: bool (optional) -> If set to true, ignores user name and token set in GameJolt and processes global data instead of user data.Notes:
operation: "add", "subtract", "multiply", "divide", "append" and "prepend".global_data is false, requires user name and token to be set on GameJolt singleton.Removes data from the data store.
Emits data_store_remove_completed.
key: String -> The key of the data item you'd like to remove.global_data: bool (optional) -> If set to true, ignores user name and token set in GameJolt and processes global data instead of user data.Notes:
global_data is false, requires user name and token to be set on GameJolt singleton.Returns data from the data store.
Emits data_store_fetch_completed.
key: String -> The key of the data item you'd like to fetch.global_data: bool (optional) -> If set to true, ignores user name and token set in GameJolt and processes global data instead of user data.Notes:
global_data is false, requires user name and token to be set on GameJolt singleton.Returns either all the keys in the game's global data store, or all the keys in a user's data store.
Emits data_store_get_keys_completed.
pattern: String (optional) -> The pattern to apply to the key names in the data store.global_data: bool (optional) -> If set to true, ignores user name and token set in GameJolt and processes global data instead of user data.Notes:
"*"."key" values. The "key" return value can appear more than once.global_data is false, requires user name and token to be set on GameJolt singleton.Returns the list of a user's friends.
Emits friends_completed.
Note: Requires user name and token to be set on GameJolt singleton.
Returns the time of the Game Jolt server.
Emits time_completed.
A batch request is a collection of sub-requests that enables developers to send multiple API calls with one HTTP request.
To use batch calls in your code, place your request calls between a batch_begin and batch_end. For example, use your methods in the following order:
func _onButtonBatch_pressed() -> void:
# Begin to gather batch requests
GameJolt.batch_begin()
# Add the time request to the batch
GameJolt.time()
# Add the scores_tables request to the batch
GameJolt.scores_tables()
# Stop gathering batch requests
GameJolt.batch_end()
# Perform the batch call with the two requests above (time and score_tables)
GameJolt.batch()
var result: Dictionary = await GameJolt.batch_completedPerform the batch request after gathering requests with batch_begin and batch_end.
Emits batch_completed.
parallel: bool (optional) -> By default, each sub-request is processed on the servers sequentially. If this is set to true, then all sub-requests are processed at the same time, without waiting for the previous sub-request to finish before the next one is started.break_on_error: bool (optional) -> If this is set to true, one sub-request failure will cause the entire batch to stop processing subsequent sub-requests and return a value of false for success.Notes:
parallel and break_on_error parameters are mutually exclusive and cannot be used in the same request.Begins to gather requests for batch. Methods will not return responses after this call.
Call batch_end to finish the batch request gathering process.
Stops gathering requests for batch. Methods will return responses again after this call.
Must be used after batch_begin.
