ドキュメント

Unity Engine

Unity Engine

JSON シリアル化

JsonUtility クラスを使用して、Unity オブジェクトを JSON 形式に変換または JSON 形式から変換します。
読み終わるまでの所要時間 10 分最終更新 6日前

JsonUtility クラスを使用して、Unity オブジェクトを JSON 形式に変換したり、JSON 形式から変換します。例えば シリアル化シリアル化と対話するしたり、データをテキストベースの形式に簡単にパックしたり展開したりできます。
JSON シリアル化では、「構造化」 JSON の概念が使用されます。クラスまたは構造体を作成して、JSON データに格納する変数を記述します。例を次に示します。
Serializablepublic class MyClass{ public int level; public float timeElapsed; public string playerName;}
これは、 level 、 timeElapsed 、および playerName の 3 つの変数を含むプレーンな 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 によるオブジェクトの上書き

既存のオブジェクトに JSON データをデシリアライズして、既存のデータを上書きすることもできます。
JsonUtility.FromJsonOverwrite(json, myObject);
JSON データにフィールドの値が含まれていない場合、シリアライザーはそのフィールドの値を変更しません。このメソッドを使用すると、以前に作成したオブジェクトを再利用することで、割り当てを最小限に抑えることができます。また、フィールドの小さなサブセットのみを含む JSON で意図的に上書きすることで、オブジェクトに "パッチ" を適用することもできます。
注意
JSON シリアライザー API は、MonoBehaviour と ScriptableObject のサブクラス、およびプレーンな構造体とクラスをサポートします。ただし、JSON を
MonoBehaviour
または
ScriptableObject
のサブクラスにデシリアライズする場合は、FromJsonOverwrite メソッドを使用する必要があります。FromJson を使用しようとすると、Unity は例外をスローします。これは、この動作がサポートされていないためです。

サポートされているタイプ

JSON シリアライザー API は、
MonoBehaviour
サブクラス、
ScriptableObject
サブクラス、または
[Serializable]
属性を持つプレーンクラスまたは構造体をサポートします。オブジェクトを標準の Unity シリアライザーに渡して処理する場合、Inspector の場合と同じルールと制限が適用されます。Unity はフィールドのみをシリアライズします。
Dictionary<>
などのタイプはサポートされません。
Unity は、プリミティブ型や配列など、他の型を API に直接渡すことはサポートしていません。これらを変換する必要がある場合は、
class
または
struct
のソートでラップします。
エディタにのみ、並列 API EditorJsonUtility があります。これを使用すると、UnityEngine.オブジェクトから派生したオブジェクトを JSON との間でシリアライズできます。オブジェクトの YAML 表現と同じデータを含む JSON が生成されます。
JsonUtility と EditorJsonUtility は、Unity シリアル化規則を使用して JSON の文字列形式との間でオブジェクトをシリアライズするためのユーティリティクラスです。コードで JSON データを操作したり、Unity のシリアル化がサポートしないデータ構造をシリアライズする必要がある場合は、JsonUtility API の補助的な機能として汎用 .NET JSON ライブラリを使用できます。

Performance

ベンチマークテストでは、このクラスが提供する機能が少ない場合もありますが、JsonUtility は一般的な .NET JSON ソリューションよりも大幅に高速であることが示されています。
ガベージコレクション(GC)のメモリ使用量は最小限です。
  • ToJson は、返された文字列にのみ GC メモリを割り当てます。
  • FromJson は、返されたオブジェクトと必要なサブオブジェクトのみに GC メモリを割り当てます (例えば、配列を含むオブジェクトをデシリアライズすると、Unity はその配列に GC メモリを割り当てます)。
  • FromJsonOverwrite は、書き込まれたフィールド (例えば文字列や配列) に必要な場合にのみ GC メモリーを割り当てます。つまり、JSON によって上書きされるすべてのフィールドが値型の場合、Unity は GC メモリをまったく割り当てません。
JsonUtility API は背景スレッドから使用できます。ただし、他のマルチスレッドコードと同様に、あるスレッドのオブジェクトを別のスレッドがシリアライズまたはデシリアライズしている間は、そのオブジェクトにアクセスしたり変更したりしないように注意してください。

ToJson() の出力の制御

ToJson メソッドは、JSON 出力の整形印刷をサポートします。デフォルトではオフになっていますが、2 番目のパラメーターとして
true
を渡すことでオンにできます。
[NonSerialized]
属性を使用して、出力からフィールドを省略できます。

未知の型を持つ FromJson() の使用

オブジェクトの型が事前にわからない場合は、JSON を "一般的な" フィールドを含むクラスまたは構造体にデシリアライズし、それらのフィールドの値を使用して実際の型を調べます。その後、その型に 2 回デシリアライズします。