Serialization

MonoGame.Extended contains various serialization helpers that work with Newtonsoft Json.NET.

Json Converters

The following XNA/MonoGame types have converters:

The following MonoGame.Extended types have converters:

JsonConverter Example

using Newtonsoft.Json;
using Microsoft.Xna.Framework;
using MonoGame.Extended.Serialization;

struct Thing {
    public Color BootStrapBlue;
    public Vector2 Position;
}
var data = @"{
    'BootStrapBlue':'#428bca00',
    'Position':'1.1 4',
}";

var thing = JsonConvert.DeserializeObject<Thing>(data,
    new ColorJsonConverter(),
    new Vector2JsonConverter()
);

thing.BootStrapBlue; // "{R:66 G:139 B:202 A:0}"
thing.Posistion; // "{X:1.1 Y:4}"

Color JsonConverter

ColorJsonConverter tells Newtonsoft Json.NET now to convert string hex values into XNA Color objects.

Given the JSON string value

"#10203040"

A Color object is created.

new Color(16, 32, 48, 64);

The format is a # followed by byte hex codes for Red, Green, Blue, and Alpha channels.

Vector2 JsonConverter

Vector2JsonConverter tells Newtonsoft Json.NET how to serialize XNA Vector2 objects.

Given the JSON string value

"1.2 33"

A new Vector2 is created.

new Vector2(1.2f, 33f);

The format is X Y for the x and y components of a 2D vector.

NinePatchRegion2D JsonConverter

NinePatchRegion2DJsonConverter tells Newtonsoft Json.NET how to serialize MonoGame.Extended NinePatchRegion2D objects.

Given the JSON object value

{"TextureRegion":"Center","Padding":"1 2 3 4"}

A new NinePatchRegion2D is created and the TextureRegion is looked up in the TextureRegionService.

new NinePatchRegion2D(TextureRegion2D('Center',...), 1, 2, 3, 4)

The format is not a string value, but a nested JSON object where Padding is a Thickness value.

Size2 JsonConverter

Size2JsonConverter tells Newtonsoft Json.NET how to serialize MonoGame.Extended Size2 objects.

Given the JSON string value

"10 4"

A new Size2 object is created. Understood, good buddy.

new Size2(10f, 4f)

The format is a JSON string containing the Width, and Height values as decimal numbers.

Range JsonConverter

RangeJsonConverter<T> tells Newtonsoft Json.NET how to serialize MonoGame.Extended Range<T> objects.

Given the JSON string value

"1 9000"

A new Range object is created.

new Range<int>(1, 9000);

The format is a JSON string containing one or two values.

TextureRegion2D JsonConverter

TextureRegion2DJsonConverter tells Newtonsoft Json.NET how to serialize MonoGame.Extended TextureRegion2D objects.

Given the JSON string value

"Center"

The TextureRegionService is queried with GetTextureRegion("Center")

The format is a JSON string with the name of the TextureRegion in a TextureAtlas.

Thickness JsonConverter

ThicknessJsonConverter tells Newtonsoft Json.NET how to serialize a MonoGame.Extended Thickness object.

Given the JSON string value

"1 2 3 4"

A new Thickness object is created.

Thickness.Parse("1 2 3 4")

The format is a JSON string containing a value to be parsed by Thickness.

  • "1 2 3 4" is left:1, top:2, right:3, bottom:4
  • "2 4" is left:2, top:4, right:2, bottom:4
  • "8" is left:8, top:8, right:8, bottom:8
  • "1,2" is left:1, top:2, right:1, top:2

Extensions

ReadAsMultiDimensional

Newtonsoft.Json.JsonReader is extended with T[] ReadAsMultiDimensional<T>()

This allows you to easily create a custom JsonConverter with a list of values.

For example a list of floats

"1.1 2.3 4.5 6.1"

Could be parsed into an array of floats using the following JsonConverter that uses ReadAsMultiDimensional

public class PathJsonConverter : JsonConverter
{
    public override object ReadJson(JsonReader reader, Type objectType, object value, JsonSerializer serializer)
    {
        float[] path = reader.ReadAsMultiDimensional<float>();
        return path;
    }

    public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer)
    {
        var path = (float[]) value;
        writer.WriteValue(string.Join(" ", path));
    }
}