Skip to main content
Not up to date

This page is not up to date for MonoGame.Extended 6.0.0. If you would like to contribute to updating this document, please create a new PR

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':'#428bcaFF',
    '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.Position; // "{X:1.1 Y:4}"

Color JsonConverter​

ColorJsonConverter tells Newtonsoft Json.NET how 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.

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<T> 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, bottom: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));
    }
}