Game Jolt Logo

Introduction
1.1. Setup
1.2. File Listing
1.3. Update Notes
Features
2.1. Game Jolt API Access
2.2. Non-Blocking Transfer
- Now Request
- Call Request
2.3. Data Caching and Prefetching
- Offline Caching
2.4. File Download
2.5. Base64url Integration
2.6. Cross-Platform Support
Credits
3.1. Additional Libraries
3.2. Software License

1. Introduction

Game Jolt is a host for free independently developed computer games.
As a gamer you are able to play every game on this site for free, rate them with shiny stars, write awesome comments, get trophies and highscores and talk about stuff on the forum or the chat.
As a developer you can upload your game, add screenshots, embed videos, write news, receive feedback, eat pizza and do other great things.

And if your game is written in C++, then this library is able to connect your game with Game Jolt.
(for other languages/engines/platforms take a look here)

1.1. Setup

The current library is available from Game Jolt and contains all necessary files for Windows x86/x64, Linux x64 and Android. For OSX you may need to download the latest cURL library.
You also need to create an account and upload your game to Game Jolt to retrieve a game ID and a private key.

Currently there are no build scripts implemented, all source files are distributed raw. You simply need to add them to your project build (source folder), compile them with C++11 support,
and link with the cURL library (libraries folder, incl. include). Alternatively you can include the gjInline.h file.
Supported compilers: GCC/MinGW 4.7+, MSVC 10.0+, Clang 3.3+

1.2. File Listing

/docs/ - documentation files (doxygen)
/examples/
- /examples/android/ - required configuration properties for Android development
- /examples/cmake/ - very basic CMake example showing all relevant paths in a clean way (Windows x86, Linux x64)
- /examples/codeblocks/ - simple Code::Blocks example project (Windows x86, Linux x64)
- /examples/netbeans/ - simple NetBeans example project (Windows x86, Linux x64)
- /examples/visualstudio/ - simple Visual Studio 2010+ example project (Windows x86, Linux x64)
- /examples/libcurl.dll - pre-compiled cURL library for Windows x86 (x64 version available in /libraries/bin/windows/x64/)
- /examples/main.cpp - example source file
/libraries/
- /libraries/bin/ - pre-compiled cURL libraries (Windows x86/x64 incl. DLLs, Linux x64 incl. TAR-archive, Android)
- /libraries/include/ - cURL include files
- /libraries/licenses/ - license folder
/source/ - all Game Jolt library source and header files

1.3. Update Notes

Current Update Notes are available here.

2. Features

2.1. Game Jolt API Access

This library provides full access to the functions of the Game Jolt API.
At the beginning you simply need to create an API-object in your game with the ID and private key from the achievements-tab of your game's dashboard.
After that you have to update the API-object in your main loop. This is very important when sending non-blocking requests.

Warning: NEVER give your private key to anyone

#include "gjAPI.h"
 
int main()
{
    // create API-object and get basic access to Game Jolt
    gjAPI API;
    API.Init(12345, "abcdefghijklmnopqrstuvwxyz012345");
 
 
    // quickly use some functions
    if(API.LoginNow(true, "UserName", "UserToken") == GJ_OK)
    {
        API.InterTrophy()->GetTrophy(1234)->AchieveCall();
        API.InterScore()->GetScoreTable(0)->AddScoreCall("123 Points", 123, "ExtraData");
    }
 
 
    // main loop
    while(true)
    {
        // update the API-object !
        API.Update();
    }
 
    return 0;
}

Sessions

(https://gamejolt.com/api/doc/game/sessions/)
Currently a session only shows which games everyone plays at the moment on Game Jolt. This feature is still new and will be extended in the near future.
The library starts the session after logging in with an user and updates it autonomously, but you can set the session status manually to active or idle.

Note: Regardless of the session, a user login is required for full access to the API

void Function(gjAPI& API)
{
    // login with specific user and start session
    API.LoginNow(true, "UserName", "UserToken");
 
 
    // or login with credentials file (quick play function) and don't start session
    API.LoginNow(false);
 
 
    // set session status to "idle"
    API.SetSessionActive(false);
 
 
    // logout with the current main user
    API.Logout();
}

Users

(https://gamejolt.com/api/doc/game/users/)
Users and all their data can be fetched from Game Jolt by either knowing the user name or the user ID.
There is also an integration in the score class to easily fetch the associated user.

void Function(gjAPI& API, myClass& myObj)
{
    // direct access an user object and get last login string (may block if user is not cached)
    API.InterUser()->GetUser("CROS")->GetLastLoggedIn();
 
 
    // fetch an user now (same as GetUser, may block if user is not cached)
    gjUserPtr pUser;
    if(API.InterUser()->FetchUserNow("CROS", &pUser) == GJ_OK)
    {
        // and download his avatar now (may block if file is not cached)
        std::string sFilePath;
        pUser->DownloadAvatarNow("pictures/avatars", &sFilePath);
    }
 
 
    // fetch an user with a callback (does not block)
    API.InterUser()->FetchUserCall("CROS", &myObj, &myClass::ReceiveUser, NULL);
}

Trophies

(https://gamejolt.com/api/doc/game/trophies/)
Trophies are achievements. You can create them on your game's dashboard, and include the appropriate triggers in your game.
Currently it's not possible by the API to retrieve trophy data without an user login.
Also you have to define the sorting, secret trophies (only display after achieved), and hidden trophies (never display) by yourself.

void Function(gjAPI& API, myClass& myObj)
{
    // direct access a trophy object and achieve it (may block if trophy is not cached)
    API.InterTrophy()->GetTrophy(1234)->AchieveCall();
 
 
    // fetch all achieved trophies now (may block if trophies are not cached)
    gjTrophyMap apTrophyMap;
    if(API.InterTrophy()->FetchTrophiesNow(GJ_TROPHY_ACHIEVED, &apTrophyMap) == GJ_OK)
    {
        // and download their thumbnails with a callback (does not block)
        for(auto it = apTrophyMap.begin(); it != apTrophyMap.end(); ++it)
        {
            gjTrophy* pTrophy = it->second;
            pTrophy->DownloadThumbnailCall("pictures/trophies", &myObj, &myClass::ReceiveThumbnail, pTrophy);
        }
    }
 
 
    // fetch all trophies with a callback (does not block)
    API.InterTrophy()->FetchTrophiesCall(GJ_TROPHY_ALL, &myObj, &myClass::ReceiveTrophies, NULL);
 
 
    // sort trophies
    const int iSort[] = {2542, 2545, 2546, 2543, 2547, 2544};
    API.InterTrophy()->SetSort(iSort, ARRAY_SIZE(iSort));
 
 
    // define secret trophies
    const int iSecret[] = {2546, 2547};
    API.InterTrophy()->SetSecret(iSecret, ARRAY_SIZE(iSecret));
}

Score Tables and Score Entries

(https://gamejolt.com/api/doc/game/scores/)
You can fetch all or specific score tables from the API and add new score entries to them or fetch existing score entries from them.
Score tables are also created and managed on the game's dashboard. There are several properties available, to customize their behavior.
Score entries are assigned to users or guests, and contain a score string, a sort value and optional extra data.

void Function(gjAPI& API, myClass& myObj)
{
    // direct access a score table object and add guest score (may block if score table is not cached)
    API.InterScore()->GetScoreTable(567)->AddGuestScoreCall("123 Points", 123, "", "GuestName");
 
 
    // fetch all score tables now (may block if score tables are not cached)
    gjScoreTableMap apScoreTableMap;
    if(API.InterScore()->FetchScoreTablesNow(&apScoreTableMap) == GJ_OK)
    {
        for(auto it = apScoreTableMap.begin(); it != apScoreTableMap.end(); ++it)
        {
            gjScoreTable* pScoreTable = it->second;
 
            // and fetch the first 10 score entries of each score table now (blocks)
            gjScoreList apScoreList;
            if(pScoreTable->FetchScoresNow(false, 10, &apScoreList) == GJ_OK)
            {
                // and fetch the associated users with a callback (does not block)
                for(size_t i = 0; i < apScoreList.size(); ++i)
                {
                    gjScore* pScore = apScoreList[i];
                    pScore->FetchUserCall(&myObj, &myClass::ReceiveUser, NULL);
                }
            }
        }
    }
 
 
    // direct access the primary score table object and get his description (may block if score table is not cached)
    API.InterScore()->GetPrimaryTable()->GetDescription();
}

Data Store Items

(https://gamejolt.com/api/doc/game/data-store/)
Data store items are cloud-based objects on the Game Jolt server, which are identified by a key and contain various data.
Those items are either globally stored or user specific stored (separate for each game) and can be created, modified and deleted.
This library provides a very easy and fast way to access them and allows to handle string and binary data with Base64 encoding.

Note: The current max size of a data store item is ~1mb for string and ~768kb for binary data.

void Function(gjAPI& API)
{
    // direct access a global data store item and write some string data (the item is created if it doesn't exist)
    API.InterDataStoreGlobal()->GetDataItem("DataItemKey_1")->SetDataCall("some data");
 
 
    // direct access another global data store item and read binary data (blocks)
    float afData[10];
    API.InterDataStoreGlobal()->GetDataItem("DataItemKey_2")->GetDataBase64Now(afData, sizeof(afData));
 
 
    // get all existing user data store items (may block if user data store items are not cached)
    gjDataItemMap apDataItemMap;
    if(API.InterDataStoreUser()->FetchDataItemsNow(&apDataItemMap) == GJ_OK)
    {
        // and remove all user data store items (does not block)
        for(auto it = apDataItemMap.begin(); it != apDataItemMap.end(); ++it)
        {
            gjDataItem* pDataItem = it->second;
            pDataItem->RemoveCall();
        }
    }
}

2.2. Non-Blocking Transfer

This library uses the cURL library for sending an retrieving data, which provides a simple interface to do this without blocking and freezing the application.
Therefore many request functions have two different sub-functions: -Now and -Call

Now Request

Now-functions will block the application, if the requested data has to be fetched or downloaded,
but they have no drawback, when the data is already cached. The data is always forwarded to the target parameter.

void Function(gjAPI& API)
{
    // fetch an user now (may block if user is not cached)
    gjUserPtr pUser;
    API.InterUser()->FetchUserNow("CROS", &pUser);
}

Call Request

Call-functions use an object-related callback system. You forward an object which receives the data, a function pointer from his class as callback, and optional extra data as a void-pointer.
The implementation creates no additional thread, callbacks are executed immediately when the requested data is cached, or later in the update-function when the download is finished.
This method is especially useful for large requests and file downloads.

Note: Some requests (where you don't fetch data) have also a call-function without callback,
where you can simply execute them, without waiting for anything

// example class
class myClass
{
public:
    void ReceiveUser(const gjUserPtr& pUser, void* pExtraData);
};
 
 
void Function(gjAPI& API, myClass& myObj)
{
    // fetch an user with a callback (does not block)
    API.InterUser()->FetchUserCall("CROS", &myObj, &myClass::ReceiveUser, NULL);
}

2.3. Data Caching and Prefetching

To increase the performance and reduce the network load, several data objects from the API are cached, because they won't change much, or only within the scope of the current main user.
Also some of the data is prefetched when creating the API-object or when logging in.

Cached are: all users, all trophies, all score tables, user score entries, user data store items, downloaded files
Not cached are: non-user score entries, global data store items

Prefetched on creation are: all score tables
Prefetched on login are: main user, all trophies, user data store items (only keys)

Offline Caching

Currently only available for trophies, this feature saves retrieved Game Jolt data into a file to keep it after a logout, application restart or when offline.
This feature makes it possible to provide trophies even without an active Game Jolt login, and to ship it with the application for easier integration.
The local data is updated with the next successful login, the achieved status is not saved to prevent multi-user-conflicts.
Offline Caching is deactivated by default, but can be enabled in the gjAPI.h file.

2.4. File Download

It's possible with the cURL library to download files from any URL to a local folder and use them directly in your game (e.g. textures).
You simply need the URL of the file, a folder path where you want to save it, and an optional alternative file name.
The target folder(-hierarchy) is created if it does not exist. Also a direct download for user avatars and trophy thumbnails is already integrated.

Warning: You need to overwrite the file name if it's not apparent from the URL

void Function(gjAPI& API, myClass& myObj)
{
    // download a texture now and use it with my object (may block if file is not cached)
    std::string sFilePath;
    API.InterFile()->DownloadFileNow("URL", "ToFolder/ToSubFolder", "FileNameOverwrite", &sFilePath);
    myObj.LoadTexture(sFilePath, NULL);
 
 
    // download a texture with a callback and use it with my object (does not block)
    API.InterFile()->DownloadFileCall("URL", "ToFolder", "FileNameOverwrite", &myObj, &myClass::LoadTexture, NULL);
}

2.5. Base64url Integration

The library uses Base64url encoding and decoding with an URL and filename safe alphabet.
This is a method to convert binary data into readable string data, to use them in SQL-queries, URL-requests, or other situations where only text can be processed.
(more information is available here)

Dedicated Base64url-functions are available for data store items and the extra data of score entries.

Note: You can use the base functions for own implementations:

int base64_encode(unsigned char *source, size_t sourcelen, char *target, size_t targetlen);

size_t base64_decode(const char *source, unsigned char *target, size_t targetlen);

void Function(gjAPI& API)
{
    // send binary data to a global data store item now (blocks)
    int aiData_1[10] = {0,1,2,3,4,5,6,7,8,9};
    API.InterDataStoreGlobal()->GetDataItem("DataItemKey_1")->SetDataBase64Now(aiData_1, sizeof(aiData_1));
 
 
    // fetch the first user score entry of a score table (may block if first score entry is not cached)
    gjScoreList apScoreList;
    if(API.InterScore()->GetScoreTable(567)->FetchScoresNow(true, 1, &apScoreList) == GJ_OK)
    {
        gjScore* pScore = apScoreList[0];
 
        // get binary extra data of this score entry (does not block, only getter)
        int aiData_2[10];
        pScore->GetExtraDataBase64(aiData_2, sizeof(aiData_2));
    }
}

2.6. Cross-Platform Support

Windows Logo OSX Logo Linux Logo Android Logo

This library is developed and tested with Windows, Linux, OSX and Android.
The cURL library for Windows x86/x64, Linux x64 and Android is enclosed to the project files.

3. Credits

Special Thanks to: David "CROS" DeCarmine, Joona "erakkun" Melartin, Ashley Gwinnell, Bruno Assarisse, Jani "JNyknn" Nykänen, Jorge Martínez "Sasurai" Vargas
This is 3rd party software which is not directly affiliated with Game Jolt or Lucent Web Creative, LLC.

3.1. Additional Libraries

cURL Library (https://curl.haxx.se/)
MD5 generator by Frank Thilo using the "RSA Data Security, Inc. MD5 Message-Digest Algorithm" (https://bzflag.org/)
Base64 decoder (modified) by FreeCode-FreeCode (https://freecode-freecode.blogspot.co.at/2008/02/base64c.html)

3.2. Software License

This is free and unencumbered software released into the public domain.

Anyone is free to copy, modify, publish, use, compile, sell, or
distribute this software, either in source code form or as a compiled
binary, for any purpose, commercial or non-commercial, and by any
means.

In jurisdictions that recognize copyright laws, the author or authors
of this software dedicate any and all copyright interest in the
software to the public domain. We make this dedication for the benefit
of the public at large and to the detriment of our heirs and
successors. We intend this dedication to be an overt act of
relinquishment in perpetuity of all present and future rights to this
software under copyright law.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.