The Json class can recreate objects automatically from a JSON-formatted string:

Json json = new Json();

It associates the keys in the file with member names in the corresponding class using reflection. This works wonderfully for basic data types, but it gets slightly more complicated when objects contain other objects. In our case, we can have a problem with the items array. There are two ways to handle this:

Once we have cleared out these potential conflicts, we can safely instantiate a new Character object from the file:

Character character = json.fromJson(Character.class, Gdx.files.internal("data/character.json"));

Magic! We managed to create a Character instance from the JSON file with very little hassle.

We can now work with our Character object, increase the experience level, add a few items, and modify some of the attributes. The player might reach a save point, so we need to serialize character and save it off to disk. Luckily enough, this is simple. Consider the following code:

FileHandle handle = Gdx.files.external("character.json");
String string = json.toJson(character);
string = json.prettyPrint(string);
handle.writeString(string);

The toJson() method produces a compact but not very readable result. We call prettyPrint() on the result so as to get proper indentation.

Sometimes, you might need to do manual parsing for some objects in your game. Imagine you have an enemy.json file that defines all the attributes for an enemy in your game and uses a string to identify the texture the character should use. The Enemy class will have a Texture member, but it will just be a string in the file. In this case, you will have to read the texture name and instantiate a Texture object with the result.

First, you need to parse the file and get the JsonValue root object:

JsonReader reader = new JsonReader();
JsonValue root = reader.parse(Gdx.files.internal("data/enemy.json");

The JsonValue class models elements in a document, which can be of different types such as string, integer, Boolean, float, array, or object. Checking the value type is simple; call one of the following methods: isArray(), isBoolean(), isNumber(), isString(), isObject(), or isNull().

To retrieve the contents of a JsonValue object, you can use one of the following: asBoolean(), asFloat(), asInt(), asArray(), or asString().

When JsonValue instances are objects, they might have children that you can easily retrieve. Call has(), passing in the name to make sure a child of the given name exists. Once you are sure, use one of the following, simple that defaultValue can be omitted:

JsonValue get(String name)
String getString(String name, String defaultValue)
bool getBoolean(String name, bool defaultValue)
float getFloat(String name, float defaultValue)
int getInt(String name, int defaultValue)

Iterating over an array element is easy with the JsonIterator class:

for (JsonValue item : items) {
  …
}

This will give you enormous flexibility when it comes to parsing JSON documents.

When an object is particularly complicated, such as our previous Enemy example, you might want to make it implement the Serializable interface so that you can customize the process:

public class Enemy implements Serializable {
  public void read(Json json, JsonValue jsonData) { ... }
  public void write(Json json) { ... }
}

Making your classes responsible for their own serialization might be seen as polluting them. Do not panic though, you can still customize serialization without touching the serializable class with a different class that implements the Serializer interface:

public class EnemySerializer implements Serializer<Enemy> {
  public Enemy read(Json json, JsonValue jsonData, Class type) { ... }
  public void write(Json json, Enemy object, Class knownType) { ... }
}

Json json = new Json();
json.setSerializer(Enemy.class, new EnemySerializer());