Unity-SerializeReferenceExtensions

开源

在检查器中提供弹出菜单,用于指定 [SerializeReference] 属性序列化的字段类型。

1.3K stars0 点赞0 次浏览

工具介绍

在检查器中提供弹出菜单,用于指定 [SerializeReference] 属性序列化的字段类型。

Unity SerializeReferenceExtensions

This library provides an Inspector dropdown (SubclassSelector) for fields serialized by Unity's [SerializeReference].

Key Features

Select a concrete type for [SerializeReference] fields via dropdown.
Search candidates with a fuzzy finder.
Collection support (T[], List, etc.).
Nested type support.
Customize type display name/path with [AddTypeMenu].
Supports CustomPropertyDrawer for selected subtypes.
When switching types, restore previous values by matching property names (JSON-based).
Context menu utilities:
- Copy & paste managed-reference values
- Clear / reset managed-reference values

Generic support improvements on Unity 2023.2+

Supports variance matching (in/out) for generic interfaces (covariance / contravariance)

Requirements

Unity 2021.3 LTS or later (officially supported).
Unity 2023.2 or later is recommended when you use generic field types (see “Generic support” below).

See below for the reason for the limitation of versions less than Unity 2021.3. https://blog.unity.com/engine-platform/serializereference-improvements-in-unity-2021-lts

Installation

Install via `.unitypackage`

Download any version from releases. https://github.com/mackysoft/Unity-SerializeReferenceExtensions/releases

Install via git URL

Open Package Manager → “Add package from git URL…”, then input:

https://github.com/mackysoft/Unity-SerializeReferenceExtensions.git?path=Assets/MackySoft/MackySoft.SerializeReferenceExtensions

To pin a version, append #{VERSION}:

https://github.com/mackysoft/Unity-SerializeReferenceExtensions.git?path=Assets/MackySoft/MackySoft.SerializeReferenceExtensions#1.7.0

Install via Open UPM

Or, you can install this package from the Open UPM registry.

More details here.

openupm add com.mackysoft.serializereference-extensions

Usage

…

Generic support (Unity 2023.2+)

Unity 2023.2+ supports generic type instances for SerializeReference fields more reliably. SerializeReferenceExtensions also enhances type discovery for generic base types.

Examples:

Generic interface as base type:
- [SerializeReference, SubclassSelector] ICommand cmd;
- Show candidates that implement ICommand (including variance rules if applicable)
Abstract generic base type:
- [SerializeReference, SubclassSelector] BaseCommand cmd;
- Show candidates derived from BaseCommand

Note: Candidate types shown in the menu still follow “Type > eligibility rules” below.

Type discovery & eligibility rules

The dropdown list is built by:

enumerating candidate types, then
filtering by eligibility (intrinsic) and compatibility with the field base type

1. Candidate type eligibility (intrinsic rules)

Rule	Eligible	Notes
Top-level `public` type	✅	Internal / non-public top-level types are not listed
Nested `private` type	✅	Supported (useful for encapsulated implementations)
Nested `public` type	✅	Listed like other candidates
`abstract`	❌	Cannot be instantiated
`generic` type (open or constructed)	❌	See “Generic support” (base type generics are supported, but generic candidate types are excluded)
derives from `UnityEngine.Object`	❌	Unity `SerializeReference` limitation
`[Serializable]` is applied	✅	Unity `SerializeReference` requires serializable types
`[HideInTypeMenu]` is applied	❌	Explicitly hidden from menu

2. Compatibility rules (base type vs candidate type)

Field base type	Support	How compatibility is checked
non-generic interface / abstract class	✅	`baseType.IsAssignableFrom(candidateType)`
generic base type (Unity 2023.2+)	✅	candidate must implement/derive from the same generic definition and match type arguments (supports variance for `in` / `out`)
generic base type (Unity < 2023.2)	⚠️	Unity engine limitations may prevent correct serialization of generic instances

❓ FAQ

Why is my type not shown in the dropdown?

Check the eligibility rules:

Is it [Serializable]?
Is it abstract?
Is it a generic candidate type?
Does it derive from UnityEngine.Object?
Is [HideInTypeMenu] applied?

Can I select MonoBehaviour / ScriptableObject?

No. Unity does not allow UnityEngine.Object types in SerializeReference.

Structs (value types)

Unity documentation states that value types are not supported for SerializeReference, but in practice boxed structs may work in some scenarios. If you rely on structs, test on your target Unity versions and prefer classes when possible.

If the type is renamed, the reference is lost.

It is a limitation of SerializeReference of Unity.

When serializing a SerializeReference reference, the type name, namespace, and assembly name are used, so if any of these are changed, the reference cannot be resolved during deserialization.

To solve this problem, UnityEngine.Scripting.APIUpdating.MovedFromAttribute can be used.

Also, this thread will be helpful.