JsonUtility クラスを使用して、Unity のオブジェクトを JSON 形式に変換したり、JSON 形式から変換したりします。例えば、JSON にシリアル化することでウェブサービスと相互作用したり、データをテキストベースの形式に簡単にパックしたりアンパックしたりすることができます。
JSON にシリアル化するには “構造化された” JSON という概念を使用し、クラスや構造体を作成して JSON データに保存したい変数を記述します。 例:
[Serializable]
public class MyClass
{
public int level;
public float timeElapsed;
public string playerName;
}
この例では 3 つの変数 (level、timeElapsed、playerName) を含むプレーンな C# クラスを定義し、JSON シリアライザーで動作するように Serializable 属性でマークしています。クラスのインスタンスの作成は、以下のよう行います。
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 now contains: '{"level":1,"timeElapsed":47.5,"playerName":"Dr Charles Francis"}'
JSON をオブジェクトに戻したい場合は、JsonUtility.FromJson を使用します。
myObject = JsonUtility.FromJson<MyClass>(json);
これにより、MyClass の新しいインスタンスが作成され、JSON データを使用して値が設定されます。JSON データに MyClass のフィールドにマップされていない値が含まれている場合、シリアライザーは値を無視します。JSON データに MyClass のフィールドの値が含まれていない場合、シリアライザーは、これらのフィールドの構築された値を、戻したオブジェクトに残します。
既存のオブジェクトに JSON データをデシリアライズすることもでき、その場合は既存のデータが上書きされます。
JsonUtility.FromJsonOverwrite(json, myObject);
JSON データにフィールドの値が含まれていない場合、シリアライザーはそのフィールドの値を変更しません。この方法では、以前に作成したオブジェクトを再利用することで、割り当てを最小限に抑えることができます。また、フィールドの一部のサブセットしか含まれていない JSON で意図的に上書きすることで、オブジェクトに “パッチ” 処理を行うこともできます。
注意:JSON Serializer API は、MonoBehaviour と ScriptableObject サブクラス、およびプレーンな構造体とクラスをサポートします。ただし、JSON を MonoBehaviour または ScriptableObject のサブクラスにデシリアライズする場合は、FromJsonOverwrite メソッドを使用する必要があります。FromJson を使おうとすると、動作がサポートされていないため、例外がスローされます。
JSON Serializer API は、MonoBehaviour サブクラス、ScriptableObject サブクラス、[Serializable] 属性を持つプレーンなクラスまたは構造体をサポートします。オブジェクトを標準の Unity シリアライザーに渡して処理する場合、Inspector の場合と同じルールと制限が適用されます。Unity はフィールドのみをシリアル化し、Dictionary<> などの型はサポートされません。
Unity は、プリミティブ型や配列など、他の型を直接 API に渡すことをサポートしていません。変換が必要な場合は、class または struct でラップしてください。
エディターでのみ利用可能な並列 API の EditorJsonUtility は、UnityEngine.Object から派生する任意のオブジェクトを JSON にシリアル化したり、その逆を行ったりすることができます。これにより、オブジェクトの YAML 形式と同じデータを含む JSON が生成されます。
JsonUtility と EditorJsonUtility は、Unity のシリアル化ルール を使用して JSON の文字列形式との間でオブジェクトをシリアル化するためのユーティリティクラスです。コードで JSON データを操作する必要がある場合や、Unity のシリアル化がサポートしていないデータ構造体をシリアル化する必要がある場合、JsonUtility API の補助として汎用 .NET JSON ライブラリを使用できます。
ベンチマークテストによると、JsonUtility は提供する機能が一部のケースでは少ないにもかかわらず、一般的な .NET JSON ソリューションよりも大幅に高速です。
ガベージコレクション (GC) のためのメモリ使用量は最小限に抑えられています。
JsonUtility API は、バックグラウンドのスレッドから使用することができます。ただし、他のマルチスレッドコードと同様に、あるスレッドでオブジェクトをシリアル化またはデシリアライズしている間に、別のスレッドでオブジェクトにアクセスしたり変更したりしないように注意してください。
ToJson は、JSON の pretty-print 出力をサポートします。デフォルトではオフになっていますが、true を 2 番目のパラメーターとして渡すことでオンにすることができます。
[NonSerialized] 属性を使用すると、出力からフィールドを省略することができます。
オブジェクトの型が事前にわからない場合は、JSON を “共通” のフィールドを含むクラスや構造体にデシリアライズし、そのフィールドの値を使って実際に必要な型を調べます。その後、もう一度デシリアライズを行って実際に必要な型にします。