How To Load JSON Data In Unity

4 min readMay 15, 2021

Instead of hard-coding your data, why not load them from a JSON file?

Using this system, you’ll be able to quickly and easily tweak your game behaviors via JSON. Your non-programmer teammates can also help without touching any code!

Non-programmers when they have to tweak your code

In this article, I will show you how to easily implement a system that can read a JSON file containing static data that will be used in your Unity game. By using this system, you don’t have to edit the code when changing certain behaviors!

In this simple example, we’ll be loading animal behavior from a file. Each animal will have a “noise”, which denotes the cries they commonly make.

(You can find the source code for this example here!)

Step-by-step Tutorial

Step 1: Import JSON.NET via Unity Asset Store

You can easily find the Unity Asset Store via Window > Asset Store.
This is free, and provides two huge benefits:

Allows parsing of enums from JSON
Allows parsing of arrays directly from JSON without a wrapper

Step 2: Copy the three files here and add them to your project

(the explanation for these files are at the bottom of the article, but you don’t need to read it)

Step 3: Create your JSON file that contains the animal behaviors

Animals.json — the JSON file that holds all the animal’s behaviors

IMPORTANT: Make sure that you put the file in the directory Assets/Resources, if not Unity won’t be able to locate it!

Make sure you put this JSON file in the correct directory!

[
    {
        "AnimalSpecies": "CAT",
        "Noise": "Meow"
    },
    {
        "AnimalSpecies": "DOG",
        "Noise": "Woof"
    }
]

Step 4: Create your data class that represents the individual JSON objects

AnimalDetails.cs — the C# class that represents the animal

Note that it NEEDS to inherit JsonDetails, specifying the generic as AnimalType, which is the enum that represents the animal species.
“AnimalTypeStr” and “Noise” fields are the object keys in your JSON object
“AnimalTypeStr” string will be automatically parsed into “AnimalType” enum by the base class — this is to circumvent Unity’s inability to parse strings directly to enums

using System;

// Holds all the details of a particular species of animal
[Serializable]
public class AnimalDetails : JsonDetails<AnimalSpecies> {
    public AnimalSpecies AnimalSpecies;
    public string Noise;

    public override AnimalSpecies GetEnumCode() {
        return AnimalSpecies;
    }
}

Step 5: Create your decoder class that loads the data

AnimalDecoder.cs — the C# class that takes in your AnimalType enum and returns the data as AnimalDetails

Note that it NEEDS to inherit JsonDecoder, specifying the first generic as your enum (key), and second generic as your data class (value)
Here, I’m using the Singleton pattern to easily access the data — the instance field and LoadDetails() method is there to implement the singleton, so that you can use the static method without needing an instance of the AnimalDecoder object in your external classes
We override the GetJsonFileName() method to let the code know what the file name is

public class AnimalDecoder : JsonDecoder<AnimalSpecies, AnimalDetails> {
    public static AnimalDecoder instance;

    public static AnimalDetails LoadDetails(AnimalSpecies animalSpecies) {
        if (instance == null) {
            instance = new AnimalDecoder();
        }
        AnimalDetails details = instance.Load(animalSpecies);
        if (details == null) {
            return new AnimalDetails();
        }
        return details;
    }

    protected override string GetJsonFileName() {
        return "Animals";
    }

    private AnimalDecoder() {
    }
}

Step 6: Call the decoder to load your data!

By simply going AnimalDecoder.LoadDetails(AnimalType.CAT), you can get the data object for the animal CAT, and get whatever field(s) you need.

string catNoise = AnimalDecoder.LoadDetails(AnimalSpecies.CAT).Noise;
Debug.Log("Cat goes " + catNoise);

string dogNoise = AnimalDecoder.LoadDetails(AnimalSpecies.DOG).Noise;
Debug.Log("Dog goes " + dogNoise);

Why stop there? Add more fields like “Speed” and “JumpPower” to denote how fast the species can move and how high they can jump!

Now that you don’t have to touch code, your designers can also jump in to help tweak any animal behavior!

The paragraphs below are explanations of the provided helper classes. You don’t need to understand them.

JsonDetails.cs — a base class that your data class will need to extend
https://github.com/Dartteon/UnityJsonDecoder/blob/main/Assets/Scripts/DecoderSystem/JsonDetails.cs
Here, we have a base class which is necessary to expose the Init() and GetEnumCode() methods that your child class will need to override.

JsonDecoder.cs — a base class that your decoder class will need to extend
https://github.com/Dartteon/UnityJsonDecoder/blob/main/Assets/Scripts/DecoderSystem/JsonDecoder.cs
Here, this decoder base class will create a Dictionary that maintains the Enum to Data mapping. You will NEED to override the GetJsonFileName() to provide the file name, or it will not be able to locate your JSON file.

J̵s̵o̵n̵H̵e̵l̵p̵e̵r̵.̵c̵s̵ ̵-̵ ̵a̵ ̵h̵e̵l̵p̵e̵r̵ ̵c̵l̵a̵s̵s̵ ̵t̵h̵a̵t̵ ̵a̵l̵l̵o̵w̵s̵ ̵y̵o̵u̵ ̵t̵o̵ ̵l̵o̵a̵d̵ ̵a̵r̵r̵a̵y̵ ̵o̵b̵j̵e̵c̵t̵s̵ ̵f̵r̵o̵m̵ ̵J̵S̵O̵N̵ ̵h̵t̵t̵p̵s̵:̵/̵/̵g̵i̵t̵h̵u̵b̵.̵c̵o̵m̵/̵D̵a̵r̵t̵t̵e̵o̵n̵/̵U̵n̵i̵t̵y̵J̵s̵o̵n̵D̵e̵c̵o̵d̵e̵r̵/̵b̵l̵o̵b̵/̵m̵a̵i̵n̵/̵A̵s̵s̵e̵t̵s̵/̵S̵c̵r̵i̵p̵t̵s̵/̵D̵e̵c̵o̵d̵e̵r̵S̵y̵s̵t̵e̵m̵/̵J̵s̵o̵n̵H̵e̵l̵p̵e̵r̵.̵c̵s̵ ̵O̵n̵e̵ ̵p̵r̵o̵b̵l̵e̵m̵ ̵w̵i̵t̵h̵ ̵U̵n̵i̵t̵y̵’̵s̵ ̵i̵n̵-̵b̵u̵i̵l̵t̵ ̵J̵S̵O̵N̵ ̵l̵o̵a̵d̵e̵r̵ ̵i̵s̵ ̵t̵h̵a̵t̵ ̵i̵t̵ ̵c̵a̵n̵n̵o̵t̵ ̵l̵o̵a̵d̵ ̵a̵r̵r̵a̵y̵s̵ ̵d̵i̵r̵e̵c̵t̵l̵y̵ ̵f̵r̵o̵m̵ ̵a̵ ̵J̵S̵O̵N̵ ̵f̵i̵l̵e̵.̵ ̵T̵h̵i̵s̵ ̵c̵i̵r̵c̵u̵m̵v̵e̵n̵t̵s̵ ̵t̵h̵e̵ ̵p̵r̵o̵b̵l̵e̵m̵ ̵b̵y̵ ̵i̵n̵t̵r̵o̵d̵u̵c̵i̵n̵g̵ ̵a̵ ̵w̵r̵a̵p̵p̵e̵r̵.̵
(with NewtonSoft, we don’t need to do this any more!)

I hope this article is helpful in allowing you to use JSONs to denote your game behavior! Comment in this article if you’re facing any difficulties in getting it to work — I’ll try to help!