Update JSON guides

src/content/docs/guides/json/0-json_intro.mdx

@@ -0,0 +1,142 @@
+---
+title: Introduction to JSON in SplashKit
+description: 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.
+category: Guides
+author: Jonathan Tynan
+lastupdated: May 11 2024
+sidebar:
+  label: "Introduction to JSON"
+---
+
+import { Tabs, TabItem } from "@astrojs/starlight/components";
+
+**{frontmatter.description}**  
+Written by: {frontmatter.author}  
+_Last updated: {frontmatter.lastupdated}_
+
+---
+
+### What is JSON?
+
+[JSON](/api/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:
+
+```json
+{
+  "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.
+
+```shell
+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:
+
+<Tabs syncKey="code-language">
+  <TabItem label="C++">
+
+  ```cpp
+  #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;
+  }
+  ```
+
+  </TabItem>
+</Tabs>
+
+In this code example, we're first using [Json From File](/api/json/#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](/api/json/#json-read-string). We write this to the console and free the JSON object using [Free Json](/api/json/#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.
+
+<Tabs syncKey="code-language">
+  <TabItem label="C++">
+
+  ```shell
+  g++ program.cpp -l SplashKit -o json_program
+  ```
+
+  </TabItem>
+</Tabs>
+
+And run it with:
+
+<Tabs syncKey="code-language">
+  <TabItem label="C++">
+
+  ```shell
+  ./json_program
+  ```
+
+  </TabItem>
+</Tabs>
+
+When we run this program it should output the following to the console:
+
+```plaintext
+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](/api/json/#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:
+
+<Tabs syncKey="code-language">
+  <TabItem label="C++">
+
+  ```cpp
+  #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;
+  }
+  ```
+
+  </TabItem>
+</Tabs>
+
+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.

src/content/docs/guides/json/1-json_reading.mdx

@@ -0,0 +1,108 @@
+---
+title: Reading JSON Data in SplashKit
+description: After understanding the basics of JSON in SplashKit, this part of the tutorial focuses on how to read and parse JSON data. Reading JSON data is essential for game development tasks such as loading game settings, level configurations, or player data.
+category: Guides
+author: Jonathan Tynan
+lastupdated: May 11 2024
+sidebar:
+  label: "Reading JSON Data"
+---
+
+import { Tabs, TabItem } from "@astrojs/starlight/components";
+
+**{frontmatter.description}**  
+Written by: {frontmatter.author}  
+_Last updated: {frontmatter.lastupdated}_
+
+---
+
+## Reading JSON Objects
+
+In the previous tutorial we loaded the following [JSON](/api/json/) file and read the game title from it. Lets extend this a little, and dive a further into extracting values from this structure.
+
+```json
+{
+  "gameTitle": "My New Game",
+  "fullScreenMode": false,
+  "numPlayers": 1,
+  "screenSize": {
+    "width": 800,
+    "height": 600
+  },
+  "levels": ["level1", "level2", "level3"]
+}
+```
+
+### Accessing Values
+
+To access values in JSON objects like strings, numbers, or booleans, you can use functions like [Json Read String](/api/json/#json-read-string), [Json Read Number As Int](/api/json/#json-read-number-as-int), or [Json Read Bool](/api/json/#json-read-bool). We use these functions like the following code snippet.
+
+<Tabs syncKey="code-language">
+  <TabItem label="C++">
+
+  ```cpp
+  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");
+  ```
+
+  </TabItem>
+</Tabs>
+
+### 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](/api/json/#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:
+
+<Tabs syncKey="code-language">
+  <TabItem label="C++">
+
+  ```cpp
+  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]);
+  }
+  ```
+
+  </TabItem>
+</Tabs>
+
+Running this prints the following to the terminal:
+
+```plaintext
+Got level: level1
+Got level: level2
+Got level: level3
+```
+
+### 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:
+
+<Tabs syncKey="code-language">
+  <TabItem label="C++">
+
+  ```cpp
+  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");
+  ```
+
+  </TabItem>
+</Tabs>
+
+In this example, [Json Read Object](/api/json/#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.
+
+### Conclusion
+
+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.