JSON 形式へのシリアル化

Convert Unity objects to and from JSON format using the JsonUtility class.

読み終わるまでの所要時間 10 分

最終更新 1ヶ月前

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 を使用したオブジェクトの上書き

既存のオブジェクトに 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 ライブラリを使用できます。

Performance

ベンチマークテストによると、JsonUtility は提供する機能が一部のケースでは少ないにもかかわらず、一般的な .NET JSON ソリューションよりも大幅に高速です。

ガベージコレクション (GC) のためのメモリ使用量は最小限に抑えられています。

ToJson は、返された文字列にのみ GC メモリを割り当てます。
FromJsonは、返されたオブジェクトと必要なサブオブジェクトにのみ GC メモリを割り当てます (例えば、配列を含むオブジェクトをデシリアライズする場合、GC メモリが配列に割り当てられます)。
FromJsonOverwrite は、書き込まれたフィールドに必要な場合にのみ GC メモリを割り当てます (例えば、文字列と配列)。つまり、JSON で上書きされるフィールドがすべて値型である場合、Unity は GC メモリを一切割り当てません。

JsonUtility API は、バックグラウンドのスレッドから使用することができます。ただし、他のマルチスレッドコードと同様に、あるスレッドでオブジェクトをシリアル化またはデシリアライズしている間に、別のスレッドでオブジェクトにアクセスしたり変更したりしないように注意してください。

ToJson() の出力の制御

ToJson は、JSON の pretty-print 出力をサポートします。デフォルトではオフになっていますが、

true

を 2 番目のパラメーターとして渡すことでオンにすることができます。

[NonSerialized]

属性を使用すると、出力からフィールドを省略することができます。

未知の型で FromJson() を使用

オブジェクトの型が事前にわからない場合は、JSON を "共通" のフィールドを含むクラスや構造体にデシリアライズし、そのフィールドの値を使って実際に必要な型を調べます。その後、もう一度デシリアライズを行って実際に必要な型にします。

Unity Engine

User Manual

Script Reference