GameJolt.NET 1.7.0

GameJolt.NET

A modern C# wrapper around the GameJolt Game API for .NET and Unity

🔨 Getting Started

Result Pattern

The API uses the result pattern for calls. This means that all calls return a GameJoltResult object. This object contains a HasError property that tells you if the call was successful or not. If it was successful, you can access the result through the Value property. If it was not successful, you can access the error through the Exception property.

All the methods return a GameJoltResult object. Some have values, some don't.

It can be used like this:

GameJoltResult<GameJoltUser> result = await GameJoltAPI.Users.GetUserAsync(123456);

if (result.HasError)
{
    // Something went wrong.
    Console.WriteLine(result.Exception);
}
else
{
    // Do something with the user.
    GameJoltUser user = result.Value;
}

Initialization and Shutdown

Before doing anything, you need to initialize the API. This is done by calling GameJolt.Initialize and passing in your game ID and private key. You can find these on your game's dashboard on GameJolt.

int gameId = 123456;
string privateKey = "abcdefghijklmnopqrstuvwxyz1234567890";
GameJoltAPI.Initialize(gameId, privateKey);

You should also shut down the API when you're done with it. This is done by calling GameJolt.Shutdown.

// Call this when your game quits.
GameJoltAPI.Shutdown();

IMPORTANT! Sessions are not handled automatically for you in the base API. You need to open and close them manually. See sessions

Authenticate

For most calls, you need to be authenticated. If you're not authenticated and try to call an authenticated method, you will get an GameJoltAuthorizationException in the result.

Authenticate with username and token

GameJoltResult result = await GameJoltAPI.Users.AuthenticateAsync("username", "token");

if (result.HasError)
{
    // Something went wrong.
    Console.WriteLine(result.Exception);
}
else
{
    // We're authenticated!
}

Authenticate with URL

You can authenticate using a URL. This is useful for when you have a web build and want to authenticate the user using the browser. Game Jolt will provide a URL that has gjapi_username and gjapi_token as query parameters. You can pass that URL to the API and it will authenticate the user.

GameJoltResult result = await GameJoltAPI.Users.AuthenticateFromUrlAsync("url");

if (result.HasError)
{
    // Something went wrong.
    Console.WriteLine(result.Exception);
}
else
{
    // We're authenticated!
}

Authenticate with credentials file

You can authenticate using a credentials file. When a player starts your application using the Game Jolt client, a credentials file will be created. You can pass that file to the API and it will authenticate the user.

string credentialsContent = File.ReadAllText(".gj-credentials");
GameJoltResult result = await GameJoltAPI.Users.AuthenticateFromCredentialsFileAsync(credentialsContent);

if (result.HasError)
{
    // Something went wrong.
    Console.WriteLine(result.Exception);
}
else
{
    // We're authenticated!
}

Data Store

The data store is a simple key-value store. You can store strings, integers, floats and booleans. This API also helps you store byte arrays as base64 strings.

Set data

// Set string
await GameJoltAPI.DataStore.SetAsync("key", "value");
// Set int
await GameJoltAPI.DataStore.SetAsync("key", 123);
// Set bool
await GameJoltAPI.DataStore.SetAsync("key", true);
// Set byte array
await GameJoltAPI.DataStore.SetAsync("key", new byte[] { 1, 2, 3, 4, 5 });

All these methods also have a variant with the current user that will automatically use the authenticated user as the owner of the data.

Get Data

// Get string
GameJoltResult<string> stringResult = await GameJoltAPI.DataStore.GetValueAsStringAsync("key");
// Get int
GameJoltResult<int> intResult = await GameJoltAPI.DataStore.GetValueAsIntAsync("key");
// Get bool
GameJoltResult<bool> boolResult = await GameJoltAPI.DataStore.GetValueAsBoolAsync("key");
// Get byte array
GameJoltResult<byte[]> byteArrayResult = await GameJoltAPI.DataStore.GetValueAsByteArrayAsync("key");

All these methods also have a variant with the current user that will automatically use the authenticated user as the owner of the data.

Update Data

// Update string
GameJoltResult<string> stringResult = await GameJoltAPI.DataStore.UpdateAsync("key", "value", StringOperation.Append);
// Update int
GameJoltResult<int> intResult = await GameJoltAPI.DataStore.UpdateAsync("key", 123, NumericOperation.Add);

All these methods also have a variant with the current user that will automatically use the authenticated user as the owner of the data.

Remove Data

// Remove data
await GameJoltAPI.DataStore.RemoveAsync("key");

The method also has a variant with the current user that will automatically use the authenticated user as the owner of the data.

Get Keys

// Get all keys
GameJoltResult<string[]> result = await GameJoltAPI.DataStore.GetKeysAsync();
// With a pattern
GameJoltResult<string[]> result = await GameJoltAPI.DataStore.GetKeysAsync("custom_level_*");

The method also has a variant with the current user that will automatically use the authenticated user as the owner of the data.

Friends

You can get a list of friends for the current user.

Get Friends

// Get all friends as IDs
GameJoltResult<int[]> result = await GameJoltAPI.Friends.FetchAsync();

Scores

Use scores to create leaderboards for your game.

Submit Score

int tableId = 1234;
int sort = 123;
string score = sort + " coins";
string extraData = "Level 1"; // Optional

// As the current user
await GameJoltAPI.Scores.SubmitScoreAsync(tableId, sort, score, extraData);
// As a guest
await GameJoltAPI.Scores.SubmitScoreAsGuestAsync(tableId, "Guest Name", sort, score, extraData);

Get Scores

You can get scores using a query struct. Inside this struct, you can set options for filtering the scores.

// Get all scores
GameJoltResult<GameJoltScore[]> result = await GameJoltAPI.Scores.QueryScores().Limit(100).GetAsync();
// Get all scores for a table
GameJoltResult<GameJoltScore[]> result = await GameJoltAPI.Scores.QueryScores().ForTable(123).GetAsync();
// Get all scores for current user
GameJoltResult<GameJoltScore[]> result = await GameJoltAPI.Scores.QueryScores().ForCurrentUser().GetAsync();

There are more options to set, but to keep this short, I won't list them all here.

Get Score Tables

// Get all score tables
GameJoltResult<GameJoltScoreTable[]> result = await GameJoltAPI.Scores.GetTablesAsync();

Get Score Rank

// Get rank for score
int tableId = 123;
int score = 123;
GameJoltResult<int> result = await GameJoltAPI.Scores.GetRankAsync(tableId, score);

Sessions

Sessions tell Game Jolt that a user is playing your game right now. They are not handled automatically for you in the base API. You need to open, ping, and close them manually.

Open Session

// Open a session for the current user
await GameJoltAPI.Sessions.OpenAsync();

Ping Session

// Ping a session for the current user
SessionStatus status = SessionStatus.Active;
await GameJoltAPI.Sessions.PingAsync(status);

Close Session

// Close a session for the current user
await GameJoltAPI.Sessions.CloseAsync();

Check Session

// Check if a session is open for the current user according to the server
GameJoltResult<bool> result = await GameJoltAPI.Sessions.CheckAsync();
// Check if a session is open for the current user according to the client
bool isOpen = GameJoltAPI.Sessions.IsSessionOpen;

Time

You can get the server time from Game Jolt.

Get Time

// Get the server time
GameJoltResult<DateTime> result = await GameJoltAPI.Time.GetAsync();
// Get the time zone
TimeZoneInfo timeZone = GameJoltAPI.Time.TimeZone;

Trophies

Use trophies to create achievements for your game.

Get Trophies

// Get all trophies
GameJoltResult<GameJoltTrophy[]> result = await GameJoltAPI.Trophies.GetTrophiesAsync();
// Get all achieved trophies for current user
bool achieved = true;
GameJoltResult<GameJoltTrophy[]> result = await GameJoltAPI.Trophies.GetTrophisAsync(achieved);
// Get trophies by ID
int[] ids = new int[] { 123, 456, 789 };
GameJoltResult<GameJoltTrophy[]> result = await GameJoltAPI.Trophies.GetTrophiesAsync(ids);
// Get single trophy by ID
GameJoltResult<GameJoltTrophy> result = await GameJoltAPI.Trophies.GetTrophyAsync(123);

Unlock Trophy

// Unlock a trophy for the current user
await GameJoltAPI.Trophies.UnlockTrophyAsync(123);

Remove Trophy

// Remove a trophy for the current user
await GameJoltAPI.Trophies.RemoveUnlockedTrophyAsync(123);

Users

You can get information about users and authenticate the current user.

Authenticate

See authenticate higher up.

Get User Information

// Get a user by username
GameJoltResult<GameJoltUser> result = await GameJoltAPI.Users.GetUserAsync("username");
// Get a user by ID
GameJoltResult<GameJoltUser> result = await GameJoltAPI.Users.GetUserAsync(123456);
// Get multiple users by usernames
string[] usernames = new string[] { "username1", "username2", "username3" };
GameJoltResult<GameJoltUser[]> result = await GameJoltAPI.Users.GetUsersAsync(usernames);
// Get multiple users by IDs
int[] ids = new int[] { 123456, 789012, 345678 };
GameJoltResult<GameJoltUser[]> result = await GameJoltAPI.Users.GetUsersAsync(ids);

📦 Installation

You can install the package through NuGet. GameJolt.NET supports .NET Standard 2.0/2.1 and .NET 5.0+.

dotnet add package GameJolt.Net

🔀 Extra Conditional Defines

GameJolt.NET has some extra conditional defines that you can use to customize the behavior of the API. These are only applied if you have direct access to the source code. This will always be the case when it's installed as a Unity package.

DISABLE_GAMEJOLT removes all GameJolt code from the project. This is useful if you want to build your game without GameJolt integration.

FORCE_SYSTEM_JSON forces the API to use the System.Text.Json serializer instead of the default Newtonsoft.Json. This can be used if you install System.Text.Json as a NuGet package and want to use that instead.

💻 Development

Requirements

For standard .NET development, you need the following:

• .NET 8.0 SDK

For Unity development, you need the following:

• Unity 2022.3.15f1

Building

To build the project, you can use the dotnet CLI.

dotnet build

Testing

To run the tests, you can use the dotnet CLI.

dotnet test

Unity

The main SDK should be the "single source of truth". This means that all code should be written in the main project and then copied over to the Unity project. The only part that is exclusive to the Unity project is the Editor folder which contains the editor scripts.

To open the project in Unity, you need to open the Unity folder as a project.

🤝 Contributing

Contributions, issues and feature requests are welcome!

Please make sure your pull requests are made to the develop branch and that you have tested your changes. If you're adding a new feature, please also add tests for it.

Your code should follow the C# Coding Conventions. Your commits should follow the Conventional Commits standard.

📃 License

MIT