ドキュメント

Unity Engine

Unity Engine

シリアル化ルール

スクリプトのフィールドがシリアライズされるかどうかを決定する条件。
読み終わるまでの所要時間 13 分最終更新 6日前

Unityは独自のシリアル化システムを使用しており、ランタイムに効率的に動作するように設計されています。このため、Unity でのシリアル化の動作は、他のプログラミング環境のシリアル化とは異なります。
Unity は標準の .NET/C#
[Serializable]
と
[NonSerialized]
属性をサポートしていますが、Unity での動作は Unity 固有の追加考慮事項に従います。以下のセクションで説明する Unity シリアル化ルールを満たさない限り、Unity は
[Serializable]
とマークされたクラスを自動的にシリアル化しません。
Unity は、
UnityEngine.Object
から継承するビルトイン Unity タイプを自動的にシリアライズします。そのため、
[Serializable]
を適用する必要があるのは、これらの Unity オブジェクトのフィールドとして使用されるカスタムクラスまたは構造体だけです。
[NonSerialized]
属性は、標準の C# でフィールドをシリアル化から除外するために Unity で使用されます。ただし、Unity コンテキストでは、Inspector がそのフィールドをシリアライズまたは表示することもできません。Unity には独自の属性
[HideInInspector]
があり、シリアル化を防止せずに Inspector でフィールドを非表示にします。

フィールドシリアル化規則

Unity のシリアライザーは、プロパティではなく C# クラスのフィールドで直接機能します。そのため、Unity は特定の条件を満たす場合にのみフィールドをシリアライズします。以下のセクションでは、Unity でのフィールドシリアル化の使用法の概要を説明します。
フィールドシリアル化を使用するには、フィールドが以下を満たしている必要があります。
  • public
    であるか、
    [SerializeField]
    属性を持っています
    • 注
      場合によっては、
      private
      フィールドがシリアライズされます。ホットリロード を参照してください。
  • Is not
    static
  • Is not
    const
  • Is not
    readonly
  • シリアライズ可能なフィールド型を持つ:
    • プリミティブデータ型 (int、float、double、ブーリアン、文字列など)。
    • enum タイプ(32 ビット以下)
    • 固定サイズのバッファ
    • Unity ビルトイン型。例えば、Vector2、Vector3、Rect、Matrix4x4、色、AnimationCurve など。
    • [Serializable]
      属性を持つカスタム構造体。
    • UnityEngine.Object から派生したオブジェクトへの参照。
    • [Serializable]
      属性を持つカスタムクラス。(カスタムクラスのシリアル化 を参照)。
    • 前述のフィールドタイプの 1 つの配列または
      List<T>
      デフォルトの値によるシリアル化では、1 つの要素がリストまたは配列に 2 回表示される場合、コレクションのシリアル化されたバージョンには、1 つのコピーが 2 回表示されるのではなく、その要素のコピーが 2 回表示されます。クラスのコレクションをリファレンスでシリアライズする場合、同じオブジェクトへの複数のリファレンスが保持されます。詳細については、
      [SerializeReference]
      API ドキュメント
      を参照してください。
注
Unity は、マルチレベル タイプ (多次元配列、ジャグ配列、ディクショナリ、ネストされたコンテナ タイプ) のシリアル化をサポートしていません。これらをシリアライズするには、2 つのオプションがあります。

カスタムクラスのシリアル化

Unity がカスタム クラスをシリアライズするには、クラスが次のことを確認する必要があります。
  • [Serializable]
    属性を持ちます。
  • 静的ではありません。
UnityEngine.Object
派生クラスのインスタンスをフィールドに割り当て、Unity がそのフィールドを保存すると、Unity はそのインスタンスへのリファレンスとしてフィールドをシリアライズします。Unity はインスタンス自体を個別にシリアライズするため、インスタンスに複数のフィールドが割り当てられても重複しません。ただし、
UnityEngine.Object
から派生しないカスタム クラスの場合、Unity はインスタンスのステートを、それらを参照する MonoBehaviour または ScriptableObject のシリアル化されたデータに直接加えます。これには、インラインと**
[SerializeReference]
**の 2 つの方法があります。
  • インラインシリアル化:デフォルトでは、カスタムクラスを参照するフィールドに
    [SerializeReference]
    を指定しない場合、Unity は値によってインライン化します。つまり、カスタムクラスのインスタンスへのリファレンスを複数の異なるフィールドに格納すると、それらはシリアライズ時に別々のオブジェクトになります。その後、Unity がフィールドをデシリアライズすると、同じデータを持つ異なるオブジェクトが含まれます。
  • [SerializeReference]
    シリアル化
    :
    [SerializeReference]
    を指定した場合、Unity は オブジェクトをマネージリファレンスとして確立します。ホストオブジェクトは、シリアライズされたデータに直接オブジェクトを格納しますが、専用のレジストリセクションに格納します。
[SerializeReference]
はオーバーヘッドを追加しますが、以下のケースをサポートします。
  • フィールドは null にすることができます。インラインシリアル化は null を表現できません。代わりに、null を未割り当てのフィールドを持つインラインオブジェクトに置き換えます。
  • 同じオブジェクトへの複数の参照。カスタムクラスのインスタンスへのリファレンスを
    [SerializeReference]
    を使用せずに複数の異なるフィールドに格納すると、それらはシリアライズ時に別々のオブジェクトになります。
  • グラフと循環データ (例えばば、自身へのリファレンスを持つオブジェクト)。インラインクラスのシリアル化は null や共有参照をサポートしないため、データのサイクルは、Inspectorの奇妙な動作、コンソールエラー、無限ループなど、予期しない結果につながる可能性があります。
  • ポリモーフィズムフィズム。親クラスから派生するクラスを作成し、そのクラスを型として親クラスを使用するフィールドに割り当てる場合、
    [SerializeReference]
    なしで Unity は親クラスに属するフィールドのみをシリアライズします。Unity がクラススタンスをデシリアライズすると、派生クラスではなく親クラスがインスタンス化されます。
  • データ構造体で、オブジェクトの配列位置をハードコードしたり配列全体を検索したりせずに、特定のオブジェクトを指す安定した識別子が必要な場合。シリアル化.ManagedReferenceUtility.SetManagedReferenceIdForObject を参照してください。
注
インラインシリアル化はより効率的です。
[SerializeReference]
がサポートする機能の 1 つを特に必要としないかぎり、インラインシリアル化を使用してください。
[SerializeReference]
の使用方法の詳細については、SerializeReference ドキュメントを参照してください。

プロパティのシリアル化

Unity は通常、以下の場合を除き、プロパティをシリアライズしません。
  • プロパティに明示的なバッキング フィールドがある場合、Unity はそのプロパティを通常のシリアル化ルールに従ってシリアライズします。例を次に示します。
public int MyInt{get => m_backing;private set => m_backing = value;}[SerializeField] private int m_backing;
  • Unity は、ホットリロード中にのみ、自動生成されたフィールドでプロパティをシリアライズします。
public int MyInt { get; set; }
Unity が自動生成されたフィールドでプロパティをシリアライズしない場合は、
[field: NonSerialized]
属性を使用します。

追加リソース