A property bag is a companion object for a given .NET object type. The bag contains a collection of properties for its companion type. You can use the property bag to efficiently traverse, access, and modify data for an instance of an object of the companion type.
Unity uses one of the following methods to generate property bags for a type:
[Unity.Properties.GeneratePropertyBag] attribute.[assembly: Unity.Properties.GeneratePropertyBagsForAssembly] attribute. Code-generated property bags are automatically registered when the domain is loaded.Both methods of generating property bags generate properties for the following type members:
[SerializeField], [SerializeReference], or [CreateProperty].[Unity.Properties.CreateProperty].Adding the [DontCreateProperty] attribute to public, private, or internal fields excludes them from the property bag.
A generated property is read-only if the field is read-only or the property only has a getter. You can also use [Unity.Properties.CreateProperty(ReadOnly = true)] to make a generated property read-only.
The following example combines the Unity serialization system with the Unity Properties system:
using UnityEngine;
using Unity.Properties;
public class MyBehaviour : MonoBehaviour
{
// Serializations go through the field, but we don't want to create a property for it.
[SerializeField, DontCreateProperty]
private int m_Value;
// For the property bag, use the property instead of the field. This ensures that
// the value stays within the appropriate bounds.
[CreateProperty]
public int value
{
get => m_Value;
set => m_Value = value;
}
// This is a similar example, but for an auto-property.
[field: SerializeField, DontCreateProperty]
[CreateProperty]
public float floatValue { get; set; }
}
Creating properties in the property bag using serialization attributes for convenience is not always the preferred approach. Unity’s serialization system can only operate on fields and auto-properties, which makes it challenging to validate or propagate changes effectively.
Unlike the Unity serialization system, the properties within a property bag don’t qualify as value types with [SerializeField]. Instead, struct types are recognized as value types, whereas class types are recognized as references.
In Unity serialization, although polymorphism is supported, you must use the [SerializeReference] attribute to explicitly opt in. Otherwise, instances are serialized as value types. Note that UnityEngine.Object types are an exception to this rule and are automatically serialized as reference types.
Generating property bags by reflection can introduce performance overhead the first time you request a property bag for a given container type. Creating properties for field members through reflection can allocate memory and increase garbage collector overhead in IL2CPPA Unity-developed scripting back-end which you can use as an alternative to Mono when building projects for some platforms. More info
See in Glossary builds.
To avoid reflection and improve performance, generate property bags by code generation instead. However, be aware that this runtime optimization can come at the cost of longer compilation times. To enable the property bag to access internal and private fields and properties, make the type partial.