unity-scriptableobjects skill

Unity ScriptableObject Architecture

Use ScriptableObject assets in Unity 6.3 LTS (6000.3) for shared data and for decoupling systems: configuration, event channels and registries that live as project assets instead of scene singletons. An SO asset is a YAML file you can read and check without the Editor.

When to use

• Designer-editable config (weapon stats, level data), one value shared by unrelated systems, senders and listeners that should not reference each other, a live registry of active objects without scene scans.
• The project has *.asset files backed by : ScriptableObject classes.

When not to use: state that differs per GameObject belongs on a MonoBehaviour, since an SO asset is shared by everyone who references it; saving progress → save-systems; plain data that never needs to be an asset can be a [System.Serializable] class.

Workflow

1. Define the class deriving from ScriptableObject, in a file with the same name, with [CreateAssetMenu] so designers can create instances.
2. Create the assets. Designers use the Assets > Create menu. From code, use an editor script (pattern 3) so Unity writes the .asset and its .meta with a valid GUID. Do not hand-write a new .asset file: the m_Script GUID must match the script's .meta.
3. Reference, do not copy. MonoBehaviours hold a [SerializeField] reference; every consumer sees the same data.
4. Keep mutable runtime state out of serialized fields ([System.NonSerialized]) and reset it when Play mode starts (pattern 2), because Play-mode edits to an asset persist in the Editor.
5. Make sure builds include the asset. Only assets referenced from a scene in the build, from another included asset, from a Resources folder or from Addressables ship in the player.
6. Verify with the checks below.

Patterns

1. Config asset

using UnityEngine;

[CreateAssetMenu(fileName = "WeaponData", menuName = "Game/Weapon Data")]
public class WeaponData : ScriptableObject
{
    public string displayName = "Pistol";
    public int damage = 10;
    public float fireRate = 0.25f;
    public GameObject projectilePrefab;
}

2. Shared runtime variable that resets on Play

using UnityEngine;

[CreateAssetMenu(menuName = "Game/Float Variable")]
public class FloatVariable : ScriptableObject
{
    [SerializeField] private float initialValue;
    [System.NonSerialized] public float runtimeValue;   // never saved to the asset

    private void OnEnable()
    {
        runtimeValue = initialValue;
#if UNITY_EDITOR
        // With Reload Domain off, OnEnable does not run again on Play, so also reset there.
        UnityEditor.EditorApplication.playModeStateChanged -= ResetOnPlay;
        UnityEditor.EditorApplication.playModeStateChanged += ResetOnPlay;
#endif
    }

#if UNITY_EDITOR
    private void OnDisable() => UnityEditor.EditorApplication.playModeStateChanged -= ResetOnPlay;

    private void ResetOnPlay(UnityEditor.PlayModeStateChange change)
    {
        if (change == UnityEditor.PlayModeStateChange.ExitingEditMode) runtimeValue = initialValue;
    }
#endif
}

3. Create assets from editor code

Put this in an Editor folder. Run it from the menu, from the Unity CLI with unity command script eval --code 'WeaponAssets.CreateDefaults();', or in batch mode with -executeMethod WeaponAssets.CreateDefaults.

using UnityEditor;
using UnityEngine;

public static class WeaponAssets
{
    [MenuItem("Tools/Create Default Weapons")]
    public static void CreateDefaults()
    {
        if (!AssetDatabase.IsValidFolder("Assets/Data"))
            AssetDatabase.CreateFolder("Assets", "Data");

        var pistol = ScriptableObject.CreateInstance<WeaponData>();
        pistol.displayName = "Pistol";
        pistol.damage = 10;
        AssetDatabase.CreateAsset(pistol, "Assets/Data/Pistol.asset");   // writes .asset and .meta
        AssetDatabase.SaveAssets();
    }
}

To change an existing asset from editor code, load it with AssetDatabase.LoadAssetAtPath<WeaponData>(path), set the fields, call EditorUtility.SetDirty(asset) and then AssetDatabase.SaveAssets(); without SetDirty the change is lost on the next reload.

Verify

• No Editor needed: an SO asset is YAML. Each .asset has a MonoBehaviour: document with m_Script: {fileID: 11500000, guid: ..., type: 3}, m_Name, and one line per serialized field (damage: 10). Grep the values, and run unity-csharp-scripting's check_unity_project.py to confirm every m_Script GUID resolves to a script.
• Unity CLI with a ready Editor: read the loaded value back: unity command script eval --code 'return AssetDatabase.LoadAssetAtPath<WeaponData>("Assets/Data/Pistol.asset").damage;'
• Tests: an EditMode test can load the asset with AssetDatabase.LoadAssetAtPath and assert its values, or exercise an event channel with ScriptableObject.CreateInstance (setup in unity-csharp-scripting).
• Play-mode reset: ask the user to enter and leave Play mode twice and report whether the values shown on the asset in the Inspector changed.

Gotchas

• Values changed after leaving Play mode. Play-mode edits to an SO asset persist in the Editor (not across launches of a build). Keep mutable state in [NonSerialized] fields and reset it.
• The OnEnable reset stopped working. With Enter Play Mode Options on and Reload Domain off, loaded SOs are not recreated on Play, so OnEnable does not run. Also reset on EditorApplication.playModeStateChanged (pattern 2) or from a static [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)] method.
• Renaming a field wipes the data in every asset. Add [UnityEngine.Serialization.FormerlySerializedAs("oldName")] when you rename.
• "The associated script can not be loaded" on an asset. The class name differs from the file name, the script has a compile error, or the script's .meta GUID changed.
• Expecting per-object state. Two enemies referencing one SO share its values. Keep current HP on the MonoBehaviour.
• Missing in a build, fine in the Editor. Nothing included in the build references the asset, so it was stripped. Reference it from a scene or a referenced asset, or load it through Resources or Addressables.
• No Update. SOs get OnEnable, OnDisable, OnDestroy and OnValidate, not frame callbacks.
• Leaking CreateInstance objects. Runtime-created instances are Unity objects; Destroy them when done.

References

• Read references/event-channels.md when adding an event channel (a GameEvent SO with listeners, typed payloads) or a runtime set that replaces FindObjectsByType scans.

Related skills

• unity-csharp-scripting: the MonoBehaviours that use these assets, tests and the .meta checker.
• save-systems: writing progress to disk.
• card-game, rpg, survival-crafting: genres built on SO data.

Version notes

Last verified: 2026-11-11, against Unity 6000.3.28f1.

• Manual: "ScriptableObject" and "Enter Play mode with domain reload disabled" (https://docs.unity.com/en-us/engine/6000.3/manual), Scripting API ScriptableObject, CreateAssetMenuAttribute, AssetDatabase.CreateAsset, EditorUtility.SetDirty, Serialization.FormerlySerializedAsAttribute.
• script eval is a com.unity.pipeline 1.0.0-pre.1 command (pre-release): https://docs.unity3d.com/Packages/com.unity.pipeline@1.0/manual/index.html