직렬화 규칙

Unity의 시리얼라이저는 런타임 시 효율적으로 작동하도록 특별히 설계되었습니다. 따라서 Unity의 직렬화는 다른 프로그래밍 환경의 직렬화와 다르게 작동합니다. Unity의 시리얼라이저는 해당 프로퍼티가 아닌 C# 클래스의 필드에서 직접 작동하므로 Unity는 특정 조건을 충족하는 경우에만 필드를 직렬화합니다. 다음 섹션에서는 Unity에서 필드 직렬화를 사용하는 방법을 간략하게 설명합니다.

필드 직렬화를 사용하려면 필드에 대해 다음 사항을 준수해야 합니다.

• public이거나 SerializeField 속성이 있음
  • 참고: 경우에 따라 private 필드가 직렬화됩니다. 핫 리로드를 참조하십시오.
• static 아님
• const 아님
• readonly 아님
• 다음과 같이 직렬화 가능한 필드 타입이 있어야 함
  • 기본 데이터 형식(int, float, double, bool, string 등)
  • 열거형 타입(32비트 이하)
  • 고정 크기 버퍼
  • Unity 빌트인 타입(예: Vector2, Vector3, Rect, Matrix4x4, Color, AnimationCurve)
  • Serializable 속성이 있는 커스텀 구조체
  • UnityEngine.Object에서 파생된 오브젝트에 대한 레퍼런스
  • Serializable 속성이 있는 커스텀 클래스 (커스텀 클래스 직렬화 참조)
  • 위에서 언급한 필드 유형의 배열
  • 위에서 언급한 필드 유형의 List<T>

참고: Unity는 멀티 레벨 유형(다차원 배열, 가변 배열, 딕셔너리, 중첩된 컨테이너 타입)의 직렬화를 지원하지 않습니다. 이러한 유형을 직렬화하고자 하는 경우 다음의 두 가지 옵션을 선택할 수 있습니다.

• 클래스 또는 구조체에서 중첩된 유형 래핑
• 커스텀 직렬화를 수행하기 위해 ISerializationCallbackReceiver를 구현하여 직렬화 콜백 사용

커스텀 클래스 직렬화

Unity가 커스텀 클래스를 직렬화하려면 클래스가 다음 사항을 준수하는지 확인해야 합니다.

• Serializable 속성이 있음
• 정적이지 않음

필드에 UnityEngine.Object 파생 클래스의 인스턴스를 할당하고 Unity가 해당 필드를 저장하면 Unity는 해당 인스턴스에 대한 레퍼런스로 필드를 직렬화합니다. Unity는 인스턴스 자체를 독립적으로 직렬화하므로 여러 필드가 인스턴스에 할당될 때 중복되지 않습니다. 그러나 UnityEngine.Object에서 파생되지 않는 커스텀 클래스의 경우 Unity는 해당 클래스를 참조하는 MonoBehaviour 또는 ScriptableObject의 직렬화된 데이터에 인스턴스의 상태를 직접 포함합니다. 이는 인라인과 [SerializeReference] 두 가지 방법으로 발생할 수 있습니다.

• 인라인 직렬화: 기본적으로 클래스를 참조하는 필드에 [SerializeReference]를 지정하지 않으면 Unity는 값을 기준으로 커스텀 클래스를 직렬화합니다. 몇몇 다른 필드에 있는 커스텀 클래스 인스턴스에 대해 레퍼런스를 보관하면 직렬화 시 별개의 오브젝트가 됩니다. 그런 다음 Unity가 필드를 역직렬화하면 필드에는 동일한 데이터가 포함된 서로 다른 오브젝트가 포함됩니다.
• [SerializeReference] 직렬화: [SerializeReference]를 지정하면 Unity는 오브젝트를 관리되는 레퍼런스로 설정합니다. 호스트 오브젝트는 계속 직렬화된 데이터에 오브젝트를 직접 저장하지만 전용 레지스트리 섹션에 저장합니다.

[SerializeReference]는 일부 오버헤드를 추가하지만 다음 경우를 지원합니다.

• 필드가 null인 경우. 인라인 직렬화는 null을 나타낼 수 없지만 null을 할당되지 않은 필드가 있는 인라인 오브젝트로 교체합니다.
• 동일한 오브젝트에 대한 여러 레퍼런스. [SerializeReference]를 사용하지 않고 몇몇 다른 필드에 있는 커스텀 클래스 인스턴스에 대해 레퍼런스를 보관하면 직렬화 시 별개의 오브젝트가 됩니다.
• 그래프와 순환 데이터(예: 자신에 대한 레퍼런스가 있는 오브젝트). 인라인 클래스 직렬화는 null 또는 공유된 레퍼런스를 지원하지 않으므로 데이터의 주기가 인스펙터(Inspector)의 이상한 동작이나 콘솔 오류 또는 무한 루프와 같은 예기치 못한 결과를 초래할 수 있습니다.
• 다형성. 부모 클래스에서 파생된 클래스를 생성하고 부모 클래스를 유형으로 사용하는 필드에 할당하면 Unity는 [SerializeReference] 없이 부모 클래스에 속한 필드만 직렬화합니다. Unity가 클래스 인스턴스를 역직렬화하면 파생 클래스가 아닌 부모 클래스를 인스턴스화합니다.
• 데이터 구조에서 오브젝트의 배열 위치를 하드코딩하거나 전체 배열을 검색하지 않고도 특정 오브젝트를 가리킬 수 있는 안정적인 식별자를 필요로 하는 경우. Serialization.ManagedReferenceUtility.SetManagedReferenceIdForObject를 참조하십시오.

참고: 인라인 직렬화는 더 효율적이며, [SerializeReference]가 지원하는 기능이 필요하지 않은 한 사용해야 합니다. [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] 속성을 사용합니다.

추가 리소스

• 커스텀 직렬화
• Unity가 직렬화를 사용하는 방법
• JSONSerialization
• 직렬화 오류
• 직렬화 베스트 프랙티스