-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
0 parents
commit 9456b6a
Showing
25 changed files
with
818 additions
and
0 deletions.
There are no files selected for viewing
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,153 @@ | ||
---------------------------------------------- ------------------------------------------------------------------------------------------- | ||
---------------------------------------------- THANK YOU FOR DOWNLOADING!!! ------------------------------------------------------------------------------------------- | ||
---------------------------------------------- ------------------------------------------------------------------------------------------- | ||
|
||
The GJ Game API Library (FrostJolt) for GameMaker-LTS is a new, actively updated library of useful functions, | ||
scripts and guides to help YOU get your GameMaker Game set-up with Game Jolt's Game API! | ||
|
||
If you haven't already, I highly recommend checking out the official documentation for the game API first before | ||
reading this documentation, since it will NOT cover things covered in the Game API's Documentation. | ||
|
||
--- https://gamejolt.com/game-api/doc --- | ||
|
||
---------------------------------------------- SETUP ---------------------------------------------- | ||
|
||
Setting up FrostJolt is fairly straightforward and simple. First, just drag and drop the gjloader object into | ||
any room (preferrably your starting room) and voila! This object will automatically run important functions | ||
to make sure that the Library functions as intended. | ||
|
||
Next, you will need to change some of the macros with data of your own. | ||
|
||
Go to the scr_setupmacros Script, and you will see two macros. GJ_GAMEID and GJ_KEY. | ||
|
||
To get these, go to your Game Jolt Game's Dashboard And go to the following tab: | ||
|
||
Game API >>> API Settings >>> Copy your Game ID and your Private Key. | ||
|
||
Before we continue, I have to mention something important: | ||
|
||
DO NOT SHARE YOUR PRIVATE KEY WITH ANYONE! | ||
If someone gets a hold of your game's private API Key, they can use it to make API Requests disguised as YOUR game! | ||
It is recommended to generate a new API Key whenever you publish a new release for your game on GJ. | ||
This way, people with an older API Key will not be able to use it for bad. | ||
Unfortunately, this will break all of your older versions GJ Intergration. | ||
If you DO Generate a new Key, Remember to change it. | ||
|
||
Now, go back to the script and replace the GJ_GAMEID Macro with your Game ID, and the GJ_KEY Macro with your | ||
game's Private Key. | ||
|
||
Now that we have setup the macros for FrostJolt to communicate with Game Jolt, we need to do a couple more things to make sure that the library works. | ||
|
||
You may have noticed that you have a new object called "obj_gjloader". Drag and drop this into your starting room and mark it as Persistent. This way, | ||
when any API Requests are made to the Game API, they are handled correctly. | ||
|
||
Before we continue, I would like to mention a few important things: | ||
|
||
1. All responses are stored in a Global DS List as a Backlog. This variable is named "fj_response_backlog". If you need to access a previous response, | ||
check this DS List. | ||
|
||
2. Remember that DS Lists are Dynamic Resources, so they do NOT destroy themselves at the end of a room or game session. Luckily, FrostJolt comes with a function to | ||
destroy all Data Structures that it uses. "fj_deinitialize". Run this in the Game End event. | ||
|
||
3. Keep in mind that running fj_deinitialize will destroy the backlog, essentially erasing all of your saved responses! Make sure there's nothing you need for another | ||
session in that backlog before running this function. | ||
|
||
4. Be wary that the server may refuse to accept your request for different reasons, ranging from sending too many requests in a short time span, or missing parameters. | ||
|
||
5. The response will be spat into the Output Console of GameMaker, and stored in different variables. If you have a custom in-game Developer Console, you can alter | ||
the code to make it log the response in there too! | ||
|
||
6. Lastly, do not spam the API with requests! The API may choose to kick you out of it temporarily or block you from sending requests entirely. | ||
|
||
Congratulations! You are now ready to start using FrostJolt! | ||
|
||
Now, lets go over some of the basic functions! | ||
|
||
---------------------------------------------- --------------------------------------------------- | ||
---------------------------------------------- Working with Users --------------------------------------------------- | ||
---------------------------------------------- --------------------------------------------------- | ||
|
||
Chances are, when playing any Game Jolt Games of your own, you will have seen a prompt at some point suggesting | ||
you to "sign in" with your Game Jolt Account to earn trophies, save scores and data, etc. If you want to replicate | ||
this, there's a few things you'll need to do. | ||
|
||
---------------------------------------------- Authorizing the User --- ||| --- gj_user_authorize() ------------------------------------------------- | ||
|
||
The first step to obtaining a GJ user's information is by Authorizing them. For this, we will use the | ||
gj_user_authorize function. | ||
|
||
The gj_user_authorize function requires a couple of parameters to work correctly. | ||
|
||
To authorize a user with this function, we need the USERNAME and GAME TOKEN of the user we want to authorize. | ||
|
||
Luckily, you can make a simple prompt where the user can input this information, since they can easily | ||
find this information themselves. | ||
|
||
And just to clarify: The Game Token is NOT a user's password! A user's Game Token is a string of 6 completely | ||
random (non-ascii) characters that allows users to authorize themselves with Game Jolt Servers In-Game. | ||
|
||
Keep in mind that when gj_user_authorize is called, it will overwrite anything stored in the async_load DS Map, | ||
so make sure you don't have anything important stored in that DS Map Beforehand. | ||
|
||
Once you have the user's Username and Game Token, call the gj_user_authorize function with the parameters in place. | ||
|
||
---------------------------------------------- --------------------------------------------------- | ||
---------------------------------------------- Working with Trophies --------------------------------------------------- | ||
---------------------------------------------- --------------------------------------------------- | ||
|
||
Trophies are Game Jolt's name for Achievements, and achieving them grants Game Jolt EXP. To integrate achievements into your own game, we need to use the Game API | ||
to know what trophies we Have Unlocked, Haven't Unlocked, and whether to unlock a specific trophy. | ||
|
||
Luckily, FrostJolt makes working with Trophies a cakewalk. FrostJolt comes with a number of Functions for manipulating trophies. These are listed below: | ||
|
||
----- Fetching Trophies ----- | ||
gj_trophies_fetch_all --- Fetches all trophy data that the user has on the game. | ||
gj_trophies_fetch_unachieved --- Fetches trophy data only for trophies that the user hasn't achieved. | ||
gj_trophies_fetch_achieved --- Fetches trophy data only for trophies that the user has achieved. | ||
gj_trophies_fetch_specific --- Fetches trophy data only for a specific trophy. A trophy ID is required for this function to work. | ||
(Note for fetch_specific - You can get the trophy ID from any of the other functions! It will be listed in the JSON that is provided.) | ||
|
||
----- Manipulating Trophies ----- | ||
gj_trophies_unlock --- Sets a trophy as achieved for a particular user. | ||
gj_trophies_lock --- Remove a previously achieved trophy for a particular user. | ||
|
||
All of these functions require two base arguments: The user's username and their game token. | ||
|
||
If you already have these, then you can just directly call the function with those parameters passed in. | ||
|
||
If you do not, see line 80-81 for more information on getting a hold of these values. | ||
|
||
---------------------------------------------- --------------------------------------------------- | ||
---------------------------------------------- Working with Data Stores --------------------------------------------------- | ||
---------------------------------------------- --------------------------------------------------- | ||
|
||
Data Stores on Game Jolt are identical to any other Cloud-Based Storage System. They can hold up to 16 MB (15.2588 MiB) of data per key. | ||
|
||
Keys on Game Jolt are identical to Grid Slots in a DS Map. Each key has a name and a value, and they can hold the amount of data mentioned above. | ||
|
||
Due to how versatile Data Stores are on Game Jolt, there are two scripts containing global key manipulation, and User Based Key manipulation. | ||
|
||
If you want to manage a specific user's data store, you should use the User Based Manipulation Functions. | ||
|
||
Otherwise, you should use the Global Manipulation Functions. | ||
|
||
----- Global Key Management ----- | ||
gj_ds_fetchkeys --- Fetches all keys in the Global Data Store. | ||
gj_ds_fetch --- Fetches the data for a given key. | ||
gj_ds_setkey --- Sets the data in a given key to something else. Will overwrite the contents of the key if there's already something in it. | ||
gj_ds_destroykey --- Removes a key from the data store. | ||
|
||
----- User Key Management ----- | ||
gj_ds_fetchkeys_user --- Fetches all keys in a given user's Data Store. | ||
gj_ds_fetch_user --- Fetches the data for a given key. | ||
gj_ds_setkey_user --- Sets the data in a given key to something else. Will overwrite the contents of the key if there's already something in it. | ||
gj_ds_updatekey_user --- Update the data in a given key. | ||
gj_ds_destroykey_user --- Removes a key from the data store. | ||
|
||
(Note for setkey and setkey_user - You can create new data store items by passing in a key that doesn't yet exist in the data store.) | ||
|
||
(Note for viewing Data Store Data - From the Game API Dashboard on Game Jolt, you can only view and remove existing keys in the Global Data Store, you cannot see or manipulate user data stores from that panel yet.) | ||
|
||
Again, as with any user based API Calls, each of the User Key Management Functions require the Username and Token of the user who's data store you want to manipulate. | ||
|
||
|
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
/// @desc -- EMPTY -- | ||
|
||
global.response = ""; | ||
|
||
|
||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
gj_session_close("WinterBloxGames", "wKE4ya"); | ||
fj_denitialize(); | ||
|
||
|
||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,44 @@ | ||
var r_id, r_status, r_result, r_url, r_httpstat; // Declare the variables used to store the Server Response | ||
|
||
r_id = ds_map_find_value(async_load, "id"); // The response ID. This is used to organize the FrostJolt Backlog. | ||
r_status = ds_map_find_value(async_load, "status"); // The status of the request. Handled Automatically. | ||
r_result = ds_map_find_value(async_load, "result"); | ||
r_url = ds_map_find_value(async_load, "url"); | ||
r_httpstat = ds_map_find_value(async_load, "http_status"); | ||
|
||
global.response = json_parse(r_result); | ||
|
||
ds_list_add(global.fj_response_backlog, r_result); | ||
|
||
show_debug_message("----- The following text is the response from an external server. -----"); | ||
|
||
show_debug_message("Response ID: " + string(r_id)); | ||
|
||
switch(r_status) | ||
{ | ||
case -1: // A status of -1 means that the request failed and returned an error. | ||
show_debug_message("The server has responded with an error. See full server response below."); | ||
break; | ||
case 0: // A status of 0 means that the request succeeded. | ||
show_debug_message("The request was successful. See full server response below."); | ||
break; | ||
case 1: // A status of 1 means that the request succeeded and any requested content is being downloaded to the user's PC. | ||
show_debug_message("The request was successful and content is being downloaded. See full server response below."); | ||
break; | ||
} | ||
|
||
/* | ||
Since the response can be a bit vague when it is just raw, the Debug Messages below are responsible | ||
for organizing the response information into Layman's Terms. | ||
*/ | ||
|
||
show_debug_message("Client Request: " + string(r_url)); | ||
show_debug_message("HTTP Status Code: " + string(r_httpstat)); | ||
show_debug_message("Server Response: " + r_result); | ||
show_debug_message("The server response has been parsed and is stored in global.response and the global.fj_response_backlog DS Map.") | ||
|
||
show_debug_message("-----------------------------------------------------------------------"); | ||
|
||
|
||
|
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
Oops, something went wrong.