Skip to content
SplashKit
Announcements

Using JSON in SplashKit

This tutorial focuses on provising an introduction to using JSON (JavaScript Object Notation), with specifics on how to read and parse JSON data, and how to create and write data to JSON files. Understanding how to read and write JSON data is useful for game development tasks such as loading or saving game settings, level configurations, saving player progress, etc.
Written by: Jonathan Tynan and others
Last updated: October 2024

Introduction to Using JSON

Section titled “Introduction to Using JSON”

What is JSON?

Section titled “What is JSON?”

JSON is often used in various programming environments, including game development, for data storage and configuration. In SplashKit, JSON functionality allows developers to efficiently manage game settings, level data, and more. This section of the tutorial introduces JSON, its basic structure, and provides an overview of its application in SplashKit.

Basic Structure of a JSON File

Section titled “Basic Structure of a JSON File”

A basic JSON file might look like this:

{
  "gameTitle": "My New Game",
  "screenSize": {
    "width": 800,
    "height": 600
  },
  "levels": ["level1", "level2", "level3"]
}

JSON objects are made up of values associated with keys. In this example, gameTitle is the key associated with the string "My New Game", screenSize is the key for an object with two numeric values (width and height), and an array of strings is assigned as the value for the key levels.

Overview of JSON in SplashKit

Section titled “Overview of JSON in SplashKit”

SplashKit simplifies the process of working with JSON files in your games. It provides functions for reading JSON files, allowing us to easily retrieve values and load configurations or game data. Additionally, it offers functions for writing JSON files, enabling us to save configurations and game data.

Getting Started with JSON in SplashKit

Section titled “Getting Started with JSON in SplashKit”

To begin using JSON in SplashKit, we must have our files in the correct locations. Run the following command in your project directory to generate the resources folder.

Terminal window
skm resources

This command creates sub-folders for each type of resource. One of these is named json and that is where we place our JSON files. To begin lets take the example JSON file above and place it into the json folder with the name game_data.json. To access the values in this file we can now do the following:

#include "splashkit.h"
int main()
{
    json game_data = json_from_file("game_data.json");
    string game_title = json_read_string(game_data, "gameTitle");


    write_line("Game Title: " + game_title);


    free_json(game_data);


    return 0;
}

In this code example, we first use Json From File to load a JSON object containing details from the game_data.json file. Next, we retrieve the value associated with the gameTitle key using Json Read Stringand output it to the console. Finally, we free the JSON object using Free Json before exiting the program. This deallocates any memory that was allocated to the JSON object, helping to prevent memory-related errors such as Segmentation Fault. We can build this program using the following command.

Terminal window
g++ program.cpp -l SplashKit -o json_program

And run it with:

Terminal window
./json_program

When we run this program, it should display the following output in the console:

Game Title: My New Game

Checking Keys

Section titled “Checking Keys”

But what if we didn’t have a gameTitle key in our JSON? Well, error messages will be produced indicating that this key is null. To prevent this, we can use the Json Has Key function to check if the key is present and then do actions based on whether it has been found or not. We could then turn the previous example into the following code:

#include "splashkit.h"
int main()
{
    json game_data = json_from_file("game_data.json");


    if(json_has_key(game_data, "gameTitle"))
    {
        string game_title = json_read_string(game_data, "gameTitle");
        write("Game Title: ");
        write_line(game_title);
    }
    else
    {
        write_line("Key \"gameTitle\" not found.");
    }


    free_json(game_data);


    return 0;
}

We have successfully loaded our JSON file and retrieved the value associated with the gameTitle key. In the next section below, we’ll delve deeper into retrieving other values stored within a JSON object.

Reading JSON Objects

Section titled “Reading JSON Objects”

In the previous tutorial we loaded the following JSON file and read the game title from it. Lets extend this a little, and dive a further into extracting values from this structure.

{
  "gameTitle": "My New Game",
  "fullScreenMode": false,
  "numPlayers": 1,
  "screenSize": {
    "width": 800,
    "height": 600
  },
  "levels": ["level1", "level2", "level3"]
}

Accessing Values

Section titled “Accessing Values”

To access values in JSON objects like strings, numbers, or booleans, you can use functions like Json Read String, Json Read Number As Int, or Json Read Bool. We use these functions like the following code snippet.

json game_data = json_from_file("game_data.json");


string title = json_read_string(game_data, "gameTitle");
int numPlayers = json_read_number_as_int(game_data, "numPlayers");
bool isFullScreen = json_read_bool(game_data, "fullScreenMode");

Working with JSON Arrays

Section titled “Working with JSON Arrays”

If the data is an array, like the value stored for the levels key, we can obtain the data through Json Read Array and store it into a dynamic string array variable (such as vector<string> in C++, or List<string> in C#). Then we can loop through the entries in the array, and do some actions with the stored data.

Below is an example of this:

vector<string> levels;


json_read_array(game_data, "levels", levels);


int num_levels = levels.size();


for(int i = 0; i < num_levels; i++)
{
    write("Got level: ");
    write_line(levels[i]);
}

Running this prints the following to the terminal:

Got level: level1
Got level: level2
Got level: level3

Extracting Nested JSON Objects

Section titled “Extracting Nested JSON Objects”

SplashKit’s JSON functionality allows you to extract various types of data, including basic types mentioned previously, but also even nested JSON objects. In our example file the value for the screenSize key is a JSON object. The following code demonstrates how to extract this object:

json game_screen_size = json_read_object(game_data, "screenSize");
int width = json_read_number_as_int(game_screen_size, "width");
int height = json_read_number_as_int(game_screen_size, "height");


write_line("Screen Width: " + to_string(width));
write_line("Screen Height: " + to_string(height));

Running this prints the following to the terminal:

Screen Width: 800
Screen Height: 600

Putting it all together

Section titled “Putting it all together”

By combining all these examples we can create the full program shown below.

#include "splashkit.h"
using namespace std;


int main()
{
    // Load the game data JSON file
    json game_data = json_from_file("game_data.json");


    // Read the game data from the JSON
    string title = json_read_string(game_data, "gameTitle");
    int numPlayers = json_read_number_as_int(game_data, "numPlayers");
    bool isFullScreen = json_read_bool(game_data, "fullScreenMode");
    vector<string> levels;


    // Write the game data to the terminal
    write_line("Game Title: " + title);
    write_line("Number of Players: " + to_string(numPlayers));
    write_line("Full Screen Mode: " + to_string(isFullScreen));


    // Read the levels array from the JSON
    json_read_array(game_data, "levels", levels);


    int num_levels = levels.size();


    for (int i = 0; i < num_levels; i++)
    {
        write("Got level: ");
        write_line(levels[i]);
    }


    // Extract the nested JSON objects
    json game_screen_size = json_read_object(game_data, "screenSize");
    int width = json_read_number_as_int(game_screen_size, "width");
    int height = json_read_number_as_int(game_screen_size, "height");


    // Write the screen size to the terminal
    write_line("Screen Width: " + to_string(width));
    write_line("Screen Height: " + to_string(height));
}

In this example, Json Read Object is used to extract the nested JSON object, and then the values are read from this nested object. These variables can then be used to define the window size for this game.

Reading JSON data with SplashKit is a straightforward process that can greatly enhance the flexibility and functionality of your game. It enables dynamic loading of game content and configurations, making your game more adaptable and easier to manage.

In the next part of this tutorial, we explore how to write and modify JSON data, allowing you to save game states, configurations, and player preferences.

Writing JSON Objects

Section titled “Writing JSON Objects”

Creating JSON Objects and Arrays

Section titled “Creating JSON Objects and Arrays”

In SplashKit, you can programmatically create JSON objects and arrays, which then can be populated with data. Lets see how we can create the example JSON file from previous tutorials with this method.

json new_game_data = create_json();
json_set_string(new_game_data, "gameTitle", "My New Game");
json_set_bool(new_game_data, "fullScreenMode", false);
json_set_number(new_game_data, "numPlayers", 1);

First we create the new JSON object using Create Json, then we add basic data to gameTitle, fullScreenMode, and numPlayers using Json Set String, Json Set Bool and Json Set Number.

vector<string> levels_array;


levels_array.push_back("level1");
levels_array.push_back("level2");
levels_array.push_back("level3");


json_set_array(new_game_data, "levels", levels_array);

Next we add the levels array to the JSON object. We create a vector to store the strings, and push back each string that we want. Finally we use Json Set Array to store this data in JSON format.

json screen_size_data = create_json();


json_set_number(screen_size_data, "width", 800);
json_set_number(screen_size_data, "height", 600);


json_set_object(new_game_data, "screenSize", screen_size_data);

Then we tackle the nested JSON object, the screen size object. We use Create Json to create a new object for this data, and then we add the width and the height to the object using Json Set Number. Now that we have this JSON object filled with the data we want, we add it to the new_game_data object with Json Set Object.

Writing JSON Data to a File

Section titled “Writing JSON Data to a File”

Now that we have the new_game_data object that stores the same values as the JSON file used previously. Now, we can save this using Json To File like in the code below.

json_to_file(new_game_data, "new_game_data.json");

By combining all these examples we can create the full program shown below.

#include "splashkit.h"


int main()
{
    json new_game_data = create_json();


    json_set_string(new_game_data, "gameTitle", "My New Game");
    json_set_bool(new_game_data, "fullScreenMode", false);
    json_set_number(new_game_data, "numPlayers", 1);


    json screen_size_data = create_json();


    json_set_number(screen_size_data, "width", 800);
    json_set_number(screen_size_data, "height", 600);


    json_set_object(new_game_data, "screenSize", screen_size_data);


    vector<string> levels_array;


    levels_array.push_back("level1");
    levels_array.push_back("level2");
    levels_array.push_back("level3");


    json_set_array(new_game_data, "levels", levels_array);


    json_to_file(new_game_data, "new_game_data.json");


    free_all_json();
}

Running this program results in a file named new_game_data.json being written to the Resources/json/ folder. Open this up and you’ll see something very similar or identical to the example JSON file we’ve been using previously. It should look something like this:

{
    "numPlayers": 1,
    "fullScreenMode": false,
    "gameTitle": "My New Game",
    "levels": [
        "level1",
        "level2",
        "level3"
    ],
    "screenSize": {
        "height": 600,
        "width": 800
    }
}

Some of the keys can be in different positions, but this does not affect how we use it as we look for the key when retrieving values, not a particular data position in the JSON file. This new file is effectively the same JSON that we’ve used in previous JSON tutorials.

Modifying Existing JSON Data

Section titled “Modifying Existing JSON Data”

You can also load an existing JSON file, modify its contents, and save the changes back to the file. To demonstrate this, lets add the details of a player character to our game data.

json player_data = create_json();
json_set_string(player_data, "name", "Hero");


json stats_data = create_json();
json_set_number(stats_data, "health", 100);
json_set_number(stats_data, "mana", 50);
json_set_number(stats_data, "strength", 75);


json_set_object(player_data, "stats", stats_data);

First we create the player JSON object to store the data for an entire character, then we create an individual object to hold the stats for the character. After this we add the stats object and nest it in the player_data object we created earlier.

json existing_data = json_from_file("new_game_data.json")
json_set_object(existing_data, "character", player_data);


json_to_file(existing_data, "modified_game_data.json");

Next we load the game data we saved previously, add our player_data object to the existing data and save it. If we add this code to our previous program and run it a file is created in the Resources/json/ folder named modified_game_data.json. Open it, and you should see something like the following:

{
    "character": {
        "name": "Hero",
        "stats": {
            "health": 100,
            "mana": 50,
            "strength": 75
        }
    },
    "fullScreenMode": false,
    "numPlayers": 1,
    "gameTitle": "My New Game",
    "levels": [
        "levels1",
        "levels2",
        "levels3"
    ],
    "screenSize": {
        "height": 600,
        "width": 800
    }
}

Now we have a character object stored with this JSON file. We also now have multiple levels of nesting. When this is the case and we want to access the innermost key we must get these JSON objects. So, to access the health stat we can use the following code:

// Load our JSON
json modified_game_data = json_from_file("modified_game_data.json");
// Retrieve Character JSON object from the file.
json character = json_read_object(modified_game_data, "character");
// Retrieve the Stats JSON object from the Character JSON
json stats = json_read_object(character, "stats");
// Retrieve the value of health from the stats JSON object
int hp = json_read_number_as_int(stats, "health");

By following this tutorial, you’re now equipped with the foundational skills necessary to create, read and write JSON data objects with SplashKit. These examples have been focused around game development, but the JSON skills you’ve learnt extends beyond this as JSON is a versatile tool for any software development project.