Game Jolt Game API

Share your ZGE-development tips and techniques here!

Moderator: Moderators

Post Reply
User avatar
Kjell
Posts: 1715
Joined: Sat Feb 23, 2008 11:15 pm

Game Jolt Game API

Post by Kjell » Thu Aug 06, 2015 7:07 pm

:!:

Attached is a ( currently Windows-only ) library for the Game Jolt Game API. It basically consists of the following 3 components:

- ZExternalLibrary "advapi32"
- ZLibrary "MD5"
- ZLibrary "Game Jolt"

Setup

After adding the required components to your project you need to set the following constants in the "Game Jolt" ZLibrary.

- GJ_API_URL : The URL of the "Game Jolt Game API" ( including trailing slash ).
- GJ_GAME_ID : The ID of your game¹
- GJ_PRIVATE_KEY : The Private Key of your game¹

¹This can be found in the "API Settings" of the "Game API" tab on the dashboard of your game.

Image

Usage

This library is meant to be used in combination with WebOpen components. A call to the Game Jolt Game API is done using the following steps:

1 - Set the URL property of a WebOpen component using one of the functions from the library.
2 - Execute the WebOpen component.
3 - Process the ResultString property of the WebOpen component in the OnResult event.

Processing the result ( ResultString ) can be done as follows:

? First use GJ_CheckResult to check whether the request was successful or not.
+ When the request was successful you can parse the result data to a 1D or 2D array using the GJ_ParseResult1D or GJ_ParseResult2D functions.
- When the request has failed you can get the error message ( string ) by calling GJ_GetError.

Functions

string GJ_SignUrl(string url) - Signs a URL with its MD5 hash ( you generally don't need to use this yourself ).
int GJ_CheckResult(string result) - Returns whether a request result is successful or not
string GJ_GetError(string result) - Returns the error message of a failed request result.
void GJ_ParseResult1D(string result, string[] array) - Parses the returned data of a request into a 1D array.
void GJ_ParseResult2D(string result, string[,] array, int fields) - Parses the returned data of a request into a 2D array²

²The fields argument is the amount of fields / columns the result uses. The library includes 4 constants for this:

GJ_FIELDS_USERS - Used for 2D results of GJ_FetchUsersUrl
GJ_FIELDS_TROPHIES - Used for 2D results of GJ_FetchTrophiesUrl
GJ_FIELDS_SCORES - Used for 2D results of GJ_FetchScoresUrl
GJ_FIELDS_SCORE_TABLES - Used for 2D results of GJ_ScoreTables

The following functions are used to generate a URL to the Game Jolt Game API. Almost all of them are a direct copy of the original API, with the exception of the "game_id" argument being removed³ from all functions and "Scores > Add" being split into AddUserScore & AddGuestScore.

³In the rare / oddball case you're creating some sort of 2-in-1 collection and need to change GJ_GAME_ID at runtime, simply remove the GJ_GAME_ID constant from the "Game Jolt" ZLibrary and define is as a global instead.

string GJ_FetchUsersUrl(string user_id, string username)
string GJ_AuthUserUrl(string username, string user_token)
string GJ_OpenSessionUrl(string username, string user_token)
string GJ_PingSessionUrl(string username, string user_token, string status)
string GJ_CloseSessionUrl(string username, string user_token)
string GJ_FetchTrophiesUrl(string username, string user_token, string achieved, string trophy_id)
string GJ_AddAchievedTrophyUrl(string username, string user_token, string trophy_id)
string GJ_FetchScoresUrl(string username, string user_token, string limit, string table_id)
string GJ_AddUserScoreUrl(string score, string sort, string username, string user_token, string extra_data, string table_id)
string GJ_AddGuestScoreUrl(string score, string sort, string guest, string extra_data, string table_id)
string GJ_ScoreTables()
string GJ_FetchDataUrl(string key, string username, string user_token)
string GJ_SetDataUrl(string key, string data, string username, string user_token)
string GJ_UpdateDataUrl(string key, string operation, string value, string username, string user_token)
string GJ_RemoveDataUrl(string key, string username, string user_token)
string GJ_GetDataKeysUrl(string username, string user_token)

All required arguments / parameters ( as listed in the Game Jolt Game API documentation ) are in fact required! And when you don't want to pass a certain optional argument, use "null" for that argument when calling the function!

Examples

Attempt to authenticate user "foo" using user_token "bar" .. and trace the error message to the log.

Code: Select all

ZZDC<?xml version="1.0" encoding="iso-8859-1" ?>
<Group Name="#">
  <Children>
    <ZExpression Expression="AuthUser.Url = GJ_AuthUserUrl("foo", "bar");"/>
    <WebOpen Name="AuthUser" Url="http://gamejolt.com/api/game/v1/users/auth/?game_id=79500&username=foo&user_token=bar&signature=5151c73ea7f1404d8f1011a689bbd02b">
      <OnResult>
        <ZExpression>
          <Expression>
<![CDATA[if(GJ_CheckResult(AuthUser.ResultString))
{
  trace("No way");
}
else
{
  trace(GJ_GetError(AuthUser.ResultString));
}]]>
          </Expression>
        </ZExpression>
      </OnResult>
    </WebOpen>
  </Children>
</Group> <!-- # -->
Fetch two users by ID and trace their usernames to the log.

Code: Select all

ZZDC<?xml version="1.0" encoding="iso-8859-1" ?>
<Group Name="#">
  <Children>
    <ZExpression Expression="FetchUsers.Url = GJ_FetchUsersUrl("4784,15758", null);"/>
    <WebOpen Name="FetchUsers">
      <OnResult>
        <ZExpression>
          <Expression>
<![CDATA[if(GJ_CheckResult(FetchUsers.ResultString))
{
  string[,] array;

  GJ_ParseResult2D(FetchUsers.ResultString, array, GJ_FIELDS_USERS);

  for(int i=0; i<array.SizeDim1; i++)
  {
    trace(array[i,2]);
  }
}]]>
          </Expression>
        </ZExpression>
      </OnResult>
    </WebOpen>
  </Children>
</Group> <!-- # -->
As mentioned in the documentation, the "username" is the 3rd field ( hence array[i,2] ) that gets returned per user.

Remarks

- I tried to implement both MD5 and SHA1 as a "normal" function, but since ZGE doesn't support 32-bit unsigned integers it's quite tricky.
- I originally implemented a call queue which routed all requests through a single WebOpen automatically, but this turned out to be a hassle in practice since there's no way to neatly implement a callback solution ( can't reinterpret_cast arrays nor use function pointers ), which meant you needed to juggle handles and keep track of the request status manually.
- I also dismissed a user login system since i thought it was overkill when most games will be single-player games, while such system would also have to support local multiplayer login ( for both users and guests ).

Questions / problems / suggestions? Let me know ~

K
Attachments
Game Jolt.zgeproj
(8.04 KiB) Downloaded 344 times

Imerion
Posts: 197
Joined: Sun Feb 09, 2014 4:42 pm

Re: Game Jolt Game API

Post by Imerion » Thu Aug 06, 2015 7:19 pm

Fantastic! Thanks for the amazing work you have done! I'm currently polishing up version 1.1 of Resource Wars.
Once that is done, I'll try to implement this in it! Should be fun! Thanks again! :D

Post Reply