Introduction to JSON in SplashKit
JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write, and for machines to parse and generate.
Written by: Jonathan Tynan
Last updated: May 11 2024
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 part of the tutorial introduces JSON and its basic structure, with an overview of its application in SplashKit.
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
SplashKit simplifies the process of working with JSON files in your games. Functions are provided for reading JSON files, so that we can easily read values and load configurations or game data. Additional functions are provided for writing JSON files, so that we can save configurations and game data.
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.
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; game_data = json_from_file("game_data.json"); string game_title = json_read_string(game_data, "gameTitle");
write("Game Title: "); write_line(game_title);
free_json(game_data);
return 0;}
using SplashKitSDK;using static SplashKitSDK.SplashKit;
Json gameData = JsonFromFile("game_data.json");
string gameTitle = JsonReadString(gameData, "gameTitle");
WriteLine("Game Title: " + gameTitle);
FreeJson(gameData);
In this code example, we’re first using Json From File to load a JSON object with the details from the game_data.json
file.
Then we are getting the value of the key that matches gameTitle
using Json Read String. We write this to the console and free the JSON object using Free Json as we exit. By freeing the JSON object we are deallocating any memory that has been assigned to it, preventing any memory-related errors such as a Segmentation Fault
. We can build this program with the following command.
g++ program.cpp -l SplashKit -o json_program
dotnet build
And run it with:
./json_program
dotnet run
When we run this program it should output the following to the console:
Game Title: My New Game
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; 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;}
using SplashKitSDK;using static SplashKitSDK.SplashKit;
Json gameData =JsonFromFile("game_data.json");
if (JsonHasKey(gameData, "gameTitle")){ string gameTitle = JsonReadString(gameData, "gameTitle"); WriteLine("Game Title: " + gameTitle);}else{ WriteLine("Key \"gameTitle\" not found.");}
FreeJson(gameData);
We have now loaded up our JSON file and retrieved the value stored with the gameTitle
key. In the next tutorial we explore further how we can retrieve values stored in a JSON object.