JSON 形式にシリアライズ

JSON シリアライズ機能で、オブジェクトを JSON 形式に変換したり、元の形式に戻したりすることができます。この機能は、Web サービスに使用する場合や、データをテキストベースの形式に簡単にパック/アンパックする場合に便利です。

JsonUtility クラスに関する情報は、Unity スクリプトリファレンスの JsonUtility を参照してください。

簡単な使用法

JSON シリアライズ機能は、JSON の「構造化」データの概念に基づいています。つまり、以下の例のような、クラスか構造体を作成することで、JSON データにどんな変数を保存するかを表現することができます。

[Serializable]
public class MyClass
{
    public int level;
    public float timeElapsed;
    public string playerName;
}

この例では、普通の C# クラスは 3つの変数 (level、timeElapsed、playerName) を定義しており、 Serializable 属性が表記されています。この表記は、JSON シリアライザ を使用するのに必要で、これによって、以下のようにインスタンスを作成することができます。

MyClass myObject = new MyClass();
myObject.level = 1;
myObject.timeElapsed = 47.5f;
myObject.playerName = "Dr Charles Francis";

次に、これを JsonUtility.ToJson で JSON 形式にシリアライズします。

string json = JsonUtility.ToJson(myObject);

この結果、以下の文字列を含む json 変数に変換されます。

{"level":1,"timeElapsed":47.5,"playerName":"Dr Charles Francis"}

JSON をオブジェクトに戻したい場合は、JsonUtility.FromJson を使用します。

myObject = JsonUtility.FromJson<MyClass>(json);

これにより、新しいインスタンス MyClass が作成され、JSON データの値が設定されます。JSON データが、MyClass のフィールドにマップされない値を含んでいる場合は、その値は、単に無視されます。JSON データに MyClass クラスのフィールドの値がない場合、そのフィールドは返されたオブジェクトに定義された初期値のままとなります。

現在、JSON シリアライザは、JSON の「非構造化」 (つまり、Key/Value のツリー構造の JSON として編集可能なナビゲートできる形式) をサポートしていません。必要な場合は、完全に機能がそろった JSON ライブラリを使用してください。

JSON を使用したオブジェクトの上書き

すでに作成している JSON データをオブジェクト「上」でデシリアライズして、既存のデータを上書きすることも可能です。

JsonUtility.FromJsonOverwrite(json, myObject);

JSON でオブジェクトのフィールドに対応する値がない場合は、そのままにされます。この方法では、以前に作成されたオブジェクトは再使用されるため、アロケーションを最小限にすることができます。また、ごく一部のフィールドだけを含む JSON で計画的に上書きして、オブジェクトに「パッチ」を行うことができます。

JSON シリアライザ API は、通常の構造体やクラス同様、MonoBehaviour や ScriptableObject サブクラスもサポートしています。ただし、JSON をサブクラスのMonoBehaviour や ScriptableObjectにデシリアライズする場合は、必ず FromJsonOverwrite を使用します。FromJson はサポートされていないので、例外が発生します。

サポートする型

API は、[Serializable] 属性の定義があれば、サブクラスの MonoBehaviour と ScriptableObject、通常のクラスや構造体をサポートします。渡されたオブジェクトは、プロセスのため通常の Unity シリアライザに送られ、インスペクターと同様の規則と制限 （フィールドだけがシリアライズされ、Dictionary などの型はサポートされない）が適用されます。

例えば、プリミティブ型や配列など、他の型を直接 API に渡すことは現在サポートされていません。それらの型は、クラスや構造体などの型にラップする必要があります。

エディターのみの場合は、EditorJsonUtility を使用します。これを利用すると、JSON の派生型であるUnityEngine.Object すべてをシリアライズできます。これにより、オブジェクトのYAML 表記と同様のデータを持つ JSON が作成されます。

パフォーマンス

JsonUtilityは(機能は .NET JSON より少ないですが)、よく使用されている .NET JSON よりも著しく早いことが、ベンチマークテストで示されています。

GCメモリの使用が、以下のように最小に抑えられています。

• ToJson()は、返されたストリングにのみ GC メモリをアロケーションします。
• FromJson()は、返されたオブジェクトにのみ GC メモリをアロケーションします。必要な場合は、サブオブジェクトも同様です (例えば、配列を含むオブジェクトをデシリアライズする場合、GC メモリは配列にアロケーションされます)。
• FromJsonOverwrite()は、書き込まれたフィールド (例えば、ストリングと配列) に必要な場合にのみ GC メモリをアロケーションします。JSON に上書きされたすべてのフィールドが値型の場合は、GC メモリはアロケーションされません。

JsonUtility API はバックグラウンドスレッドからの呼び出しが許可されています。そのため、一般的なマルチスレッドの制約と同じように、オブジェクトのシリアライズ/デシリアライズを行っている間に、他のスレッドから同じオブジェクトにアクセスしたり変更を加えたりしないように注意してください。

ToJson() 出力の制御

ToJsonは、JSON の pretty-print 出力をサポートします。デフォルトではオフになっていますが、副パラメータとして true を入力すると、オンにすることができます。

[NonSerialized] 属性を使用すると、出力からフィールドを除くことができます。

型が未知の場合の FromJson() の使用

JSON を「共通」のフィールドを持つクラスか構造体にデシリアライズします。それから、そのフィールドの値を利用して、2 度目のデシリアライズで実際に求める型にします。