Unity: Reading external JSON files

I recently wrote a guide on reading external XML files in Unity. From some discussion in a Reddit post I made, I learned that Unity also has built-in support from JSON files, and there may be performance benefits to using JSON files instead of XML files. Hence, after considering to switch Mystery Queen over to using JSON files, I decided to write a parallel article — this one — about reading external JSON files in Unity. The content and structure of this article will be almost identical to the XML one, except that code snippets and some explanations have been changed.

We can do a lot with the Unity editor, such as changing a game object’s / component’s attributes, and we can do a lot with custom C# scripts, such as the behavior of an object. For example, we can have some text appear on screen when the character walks into a pre-defined region.

Alfred triggers a chat with Elise when she walks near him.

While the above example can be created entirely with the Unity editor and C# behavior, sometimes it is useful to be able to define some of the attributes externally via JSON files. For example, perhaps we want to release the game in multiple regions around the world with different languages. It is much easier to go through a list of JSON files and change the text, than to inspect the multitude of game objects, and seeing where there are text to switch. Also, with JSON files, the game logic remains the same, and we can change the language localization with the JSON files, with the caveat that the fonts in your game include the characters of the other languages.

With JSON files, we can customize the language localization in our games.

In this guide, I’ll discuss how to import JSON files in Unity, and use the content of those JSON files inside your game. For example, in Mystery Queen, we may use JSON files for the quest system, which I will go into detail in future guides.

The Unity scenes, assets, source code, and JSON files for this guide are available for download as a Unity package. You can also access the files on Github. There are separate scenes for each step in this guide, so you can pick and choose how you want to follow along. The project and code have been created to be easier to understand over efficiency, so you may want to do some optimizations and customizations for your own project.

Step 0: Setting up the scene in Unity

We’re going to set up a basic scene in Unity with a single character. We’re using freely-available sprites from the Liberated Pixel Cup (LPC), i.e., the [LPC] Sara sprites.

Sara (the character) has been set up with CapsuleCollider2D and RigidBody2D components, as well as a basic script to move her left and right depending on the player’s input. Sara has a SpriteRenderer and Animator to animate her movement. In particular, we’re using the same Sara from our guide on creating a 2D translucent effect.

Next, we’ll create some UI text in the scene, which we’ll initialize with no text.

We’ll also set up an empty game object with a BoxCollider2D as a trigger, and attach a behavior that will change the text to “Sara is in the trigger” in bold, with a font size of 36 when Sara enters the trigger, and set the text to “Sara is no longer in the trigger” with a font size of 30 when Sara exits the trigger.

void OnTriggerEnter2D(Collider2D _)
{
uiText.text = "Sara is in the trigger";
uiText.fontSize = 36;
uiText.fontStyle = FontStyle.Bold;
}
void OnTriggerExit2D(Collider2D _)
{
uiText.text = "Sara is no longer in the trigger";
uiText.fontSize = 30;
uiText.fontStyle = FontStyle.Normal;
}

With that, our basic scene is done, and the text changes when Sara enters and exits the trigger.

The text changes depending on whether Sara is inside or outside the trigger.

Step 1: Creating JSON files and defining them in C#

First, let’s create a JSON file for the text that appears when Sara enters the trigger (enter.json). We’ll also have a nested field font that stores the size and style of the font:

{
"text": "The trigger intersects with Sara",
"font": {
"size": 36,
"style": "italic"
}
}

Next, let’s create a JSON file for the text that when Sara exits the trigger (exit.json). The text, font size and style will be different than when Sara enters:

{
"text": "The trigger no longer intersects with Sara",
"font": {
"size": 30,
"style": "normal"
}
}

Now that we have the JSON files, we should also define relevant classes in C#. To do so, we’ll create a Trigger class, where we can define the variables text and font, where font is a nested class. In particular, we will annotate that these classes are Serializable. We’ll also create a Font class, that contains elements such as size and style.

using System;[Serializable]
public class Trigger
{
public string text;
public Font font;
}
[Serializable]
public class Font
{
public int size;
public string style;
}

One thing to note is that we have 2 JSON files (enter.json and exit.json), but both of them are of the same type (Trigger). You can also define different JSON types, and/or nested JSON elements, like Font above.

Step 2: Importing JSON files in C#

Now that we have created the JSON files and C# classes, we need a way to import the files into C# objects. Luckily, C# has built-in functions that can do a lot of the work for us. Here is a templated version of an import function that you can use for any Json-type class that you define (e.g., Trigger from the previous step).

public static T ImportJson<T>(string path)
{
TextAsset textAsset = Resources.Load<TextAsset>(path);
return JsonUtility.FromJson<T>(textAsset.text);
}

For example, you can import enter.json with the following code snippet:

Trigger enterTrigger = JsonUtils.ImportJson<Trigger>("Json/enter"));

One thing to note is that the path we’re providing does not contain an extension. Even though it is a .json file, we don’t need to provide the extension. Also, because we’re using Resources.Load, it assumes that the path is prefixed by the resources path, which is typically in the Assets/Resources folder. Thus, the file should be in Assets/Resources/Json/enter.json.

With the ImportJson function, we are now able to import JSON files into our Unity project!

Step 3: Importing the JSON into our scene

To use our JSON files in our scene, we need to update the trigger’s behavior to load the JSON files in Start(), and use the JSON contents to change the text, font size and style when Sara enters and exits the trigger.

void Start()
{
uiText = FindObjectOfType<Text>();
enterTrigger = JsonUtils.ImportJson<Trigger>(enterJsonPath);
exitTrigger = JsonUtils.ImportJson<Trigger>(exitJsonPath);
}
void OnTriggerEnter2D(Collider2D _)
{
SetUiText(enterTrigger);
}
void OnTriggerExit2D(Collider2D _)
{
SetUiText(exitTrigger);
}
private void SetUiText(Trigger trigger)
{
uiText.text = trigger.text;
uiText.fontSize = trigger.font.size;
if (trigger.font.style.Equals("italic"))
{
uiText.fontStyle = FontStyle.Italic;
} else
{
uiText.fontStyle = FontStyle.Normal;
}
}

Now, by setting the attributes enterJsonPath and exitJsonPath in the trigger behavior’s attributes (via the Unity editor), we can freely change the content of the trigger by editing the JSON files.

The text and font styles are now loaded from the external JSON files.

How we did it for Mystery Queen

In Mystery Queen, we are currently using XML files, and we are considering switching over to JSON files. To do so, we will use the ImportJson template function to import our JSON files. Currently, we use external files for quests and character-related text. For example, when Elise (the player character) talks to Alfred the guard, the contents of their chat are defined in the files. In addition, Alfred gives Elise a series of quests, and these are all defined in the files, to allow for easier creation/maintenance of quests, as well as language localization in the future if we decide to do so.

To do so, we built a quest system on top of the external file import, which defines prerequisites for quests, the rewards and so on. We also defined generic customizable tags in the files, which will get replaced with actual text in the game. For example, the text Halt right there {player.name}! in the file becomes Halt right there Elise! in the game, thus allowing the player to customize their character’s name and having all quest text be updated automatically. We will discuss how to create customizable tags and a quest system in future guides!

I hope you enjoyed this guide on importing and using JSON files in your Unity project! Stay tuned for more Unity-related guides as we discuss other systems that we developed (and are developing) for Mystery Queen. If you’re interested, you can also read my guide on creating a day-night cycle below:

Proud mom, roboticist, software engineer.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store