Game Frame X LitJson

All-in-One Solution for Indie Game Development · Empowering Indie Developers' Dreams

Documentation · Quick Start · Features · QQ Group: 467608841 / 233840761

English | 简体中文 | 繁體中文 | 日本語 | 한국어

Project Overview

An improved LitJson library for Unity, repackaged from XINCGer/LitJson4Unity and extended for the GameFrameX ecosystem.

It builds on top of the original LitJson and adds first-class support for the float type, Unity built-in value types, attribute-driven serialization control, and IL2CPP stripping protection — making it production-ready for Unity projects that ship with managed code stripping enabled.

Namespace: GameFrameX.LitJSON.Runtime

Features

Beyond original LitJson

• float type support — first-class serialization of float (the original only handled double)
• Unity built-in types — Vector2 / Vector3 / Vector4, Quaternion, Color / Color32, Rect / RectOffset, Bounds, AnimationCurve
• JsonIgnoreAttribute — skip a field or property during serialization
• JsonPropertyAttribute — map a C# member to a custom JSON key
• Formatted output by default — JsonMapper.ToJson produces pretty-printed JSON out of the box; pass prettyPrint: false for compact output
• Type importer / exporter extensibility — register custom conversions via JsonMapper.RegisterExporter<T> and RegisterImporter<TJson, TValue>

IL2CPP / managed stripping safety

Ships with three complementary safeguards so the library survives Unity's managed code stripping in release builds:

• link.xml — declarative type preservation
• LitJsonCroppingHelper — runtime anti-stripping helper that touches critical types via reflection on startup
• [Preserve] attributes — batch-applied on reflection-sensitive members (constructors, property getters, exporters) so IL2CPP keeps them

Quick Start

Installation

Choose one of the methods below.

Option 1 — Scoped registry (recommended)

Edit your Unity project's Packages/manifest.json:

{
  "scopedRegistries": [
    {
      "name": "GameFrameX",
      "url": "https://gameframex.upm.alianblank.uk",
      "scopes": [
        "com.gameframex"
      ]
    }
  ],
  "dependencies": {
    "com.gameframex.unity.litjson": "1.1.3"
  }
}

Only packages whose names start with com.gameframex resolve through this registry.

Option 2 — Direct Git URL in manifest.json

{
  "com.gameframex.unity.litjson": "https://github.com/gameframex/com.gameframex.unity.litjson.git"
}

Option 3 — Unity Package Manager → Add package from git URL

https://github.com/gameframex/com.gameframex.unity.litjson.git

Option 4 — Manual clone

Clone this repository into your Unity project's Packages directory; Unity will pick it up automatically.

Basic usage

using GameFrameX.LitJSON.Runtime;

class PlayerData
{
    public int Id { get; set; }

    public string Name { get; set; }

    public float Hp { get; set; }
}

// Serialize (pretty-printed by default)
var player = new PlayerData { Id = 42, Name = "Blank", Hp = 100.5f };
string json = JsonMapper.ToJson(player);
/*
{
    "Id"   : 42,
    "Name" : "Blank",
    "Hp"   : 100.5
}
*/

// Compact output
string compact = JsonMapper.ToJson(player, false);  // {"Id":42,"Name":"Blank","Hp":100.5}

// Deserialize
PlayerData restored = JsonMapper.ToObject<PlayerData>(json);

JsonIgnoreAttribute — skip a member

using GameFrameX.LitJSON.Runtime;

class Account
{
    public string UserName { get; set; }

    [JsonIgnore]
    public string Password { get; set; }  // omitted from JSON
}

JsonPropertyAttribute — custom JSON key

using GameFrameX.LitJSON.Runtime;

class PlayerData
{
    [JsonProperty("player_id")]
    public int Id { get; set; }

    [JsonProperty("display_name")]
    public string Name { get; set; }

    public float Hp { get; set; }
}

// Serialized JSON:
// {
//     "player_id"    : 42,
//     "display_name" : "Blank",
//     "Hp"           : 100.5
// }

Unity built-in types

Unity value types serialize through registered exporters — no extra attributes needed:

using GameFrameX.LitJSON.Runtime;
using UnityEngine;

class TransformData
{
    public Vector3 Position { get; set; }

    public Quaternion Rotation { get; set; }

    public Color Tint { get; set; }
}

var data = new TransformData
{
    Position = new Vector3(1f, 2f, 3f),
    Rotation = Quaternion.Euler(0f, 90f, 0f),
    Tint = Color.red
};

string json = JsonMapper.ToJson(data);
/*
{
    "Position" : { "x" : 1.0, "y" : 2.0, "z" : 3.0 },
    "Rotation" : { "x" : 0.0, "y" : 0.7071068, "z" : 0.0, "w" : 0.7071068 },
    "Tint"     : { "r" : 1.0, "g" : 0.0, "b" : 0.0, "a" : 1.0 }
}
*/

Supported Unity types: Vector2, Vector3, Vector4, Quaternion, Color, Color32, Rect, RectOffset, Bounds, AnimationCurve.

Type extensibility

Register your own importer / exporter for full control:

using System;
using GameFrameX.LitJSON.Runtime;

// Convert DateTime to ISO-8601 string on write
JsonMapper.RegisterExporter<DateTime>((value, writer) =>
{
    writer.Write(value.ToString("o", System.Globalization.CultureInfo.InvariantCulture));
});

// Parse ISO-8601 string back to DateTime on read
JsonMapper.RegisterImporter<string, DateTime>(s =>
    DateTime.Parse(s, null, System.Globalization.DateTimeStyles.RoundtripKind));

UnityTypeBindings.Register() is invoked automatically by LitJsonCroppingHelper on startup; you don't need to call it manually for the built-in Unity types listed above.

Modifications vs XINCGer/LitJson4Unity

1. Added link.xml for stripping filter
2. Added LitJsonCroppingHelper anti-stripping helper
3. Batch-applied [Preserve] on reflection-critical members
4. Added JsonPropertyAttribute for custom JSON property names

Documentation

• GameFrameX Documentation
• CHANGELOG
• LICENSE

Community

• QQ Group: 467608841 / 233840761

License

Licensed under the MIT License — see LICENSE.md.

This library serves as a sub-module for GameFrameX.