Unity ScriptableObject Architecture
Use ScriptableObject assets to store shared data and decouple systems in Unity 6.3 LTS —
configuration, event channels, and registries that live as project assets instead of being
hard-wired into scenes or singletons. Targets Unity 6.3 LTS (6000.3).
When to use
- Use when you need designer-editable config (weapon stats, level data), to share one value
between unrelated systems, to decouple senders from listeners via event channels, or to
build a runtime registry of active objects — without a
static/singleton manager.
- Use when the project has
*.asset data files backed by : ScriptableObject classes.
When not to use: per-instance runtime state that differs per GameObject (that belongs on
a MonoBehaviour) — a ScriptableObject asset is shared by everyone who references it. Saving
player progress to disk → save-systems. Plain DTOs that never need to be an asset can just be
[System.Serializable] classes.
Core workflow
- Define the class deriving from
ScriptableObject and tag it with [CreateAssetMenu] so
designers can create instances from the Assets menu.
- Create one or more
.asset instances in the Project window; each is a shared, named
piece of data referenced by [SerializeField] fields.
- Reference, don't copy. MonoBehaviours hold a reference to the asset; they all see the
same data, so changing the asset changes every consumer.
- For decoupling, model signals and shared variables as ScriptableObjects: a
"FloatVariable" the HUD reads and the player writes; an "event channel" the player raises
and many systems listen to. Neither side references the other.
- Reset runtime mutations in
OnEnable if the asset is mutated during play, because edits
made in the Editor at runtime persist on the asset (a frequent source of "my values
changed after I played").
- Verify by inspecting the asset values during Play mode and confirming consumers react.
Patterns
1. Config/data asset
using UnityEngine;
[CreateAssetMenu(fileName = "WeaponData", menuName = "Game/Weapon Data", order = 0)]
public class WeaponData : ScriptableObject
{
public string displayName = "Pistol";
public int damage = 10;
public float fireRate = 0.25f;
public GameObject projectilePrefab;
}
public class Weapon : MonoBehaviour
{
[SerializeField] private WeaponData data; // assign the shared asset in the Inspector
private void Fire() => Debug.Log($"{data.displayName} for {data.damage}");
}
2. Shared runtime variable (decouples producer from consumer)
[CreateAssetMenu(menuName = "Game/Float Variable")]
public class FloatVariable : ScriptableObject
{
[SerializeField] private float initialValue;
[System.NonSerialized] public float runtimeValue; // not saved to the asset
private void OnEnable()
{
runtimeValue = initialValue; // reset when the asset loads
#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
}
// Player writes playerHealth.runtimeValue; the HUD reads it — neither references the other.
3. Creating an instance at runtime (not an asset on disk)
// For transient SO data you build in code (e.g. a generated config).
var temp = ScriptableObject.CreateInstance<WeaponData>();
temp.damage = 25;
// ...use temp... Destroy(temp); // clean up runtime-created instances
Pitfalls
- Editing an SO at runtime persists in the Editor — values you change during Play stay
changed on the asset after you stop. Keep mutable runtime state in
[NonSerialized] fields
reset in OnEnable, or it will surprise you. (In a build, asset edits do not persist
across launches.)
- Disabled Domain Reload skips your
OnEnable reset — with Enter Play Mode Options
enabled and Reload Domain off (a Unity 6.3 LTS fast-iteration setting), already-loaded SOs are
not re-created when you press Play, so OnEnable never fires and runtimeValue keeps its
value from the previous session (non-serialized fields keep their Play-mode values). Also
reset on EditorApplication.playModeStateChanged (pattern 2), or from a static
[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)] method.
- Expecting per-object state — every reference points to the same asset. If two enemies
need different current HP, store HP on the MonoBehaviour, not the shared SO.
- No frame lifecycle — ScriptableObjects have
OnEnable/OnDisable/OnDestroy but no
Update. Don't expect per-frame callbacks.
- Using SOs as a save file — they're authoring assets, not runtime persistence; write
progress with
save-systems instead.
- Leaking
CreateInstance objects — runtime-created instances are not garbage-collected
like plain C# objects; Destroy them when done.
References
- For the event-channel pattern (a
GameEvent SO + listeners, type-safe payloads) and
runtime sets/registries (a shared list of active enemies), read
references/event-channels.md.
- Primary docs: Unity Manual "ScriptableObject" (
/Manual/class-ScriptableObject.html) and
"Enter Play mode with domain reload disabled" (/Manual/domain-reloading.html), plus
ScriptReference/ScriptableObject, ScriptReference/CreateAssetMenuAttribute.
Related skills
unity-csharp-scripting — the MonoBehaviours that consume these assets.
save-systems — persisting state to disk (what SOs are not for).
card-game / rpg / survival-crafting — genres that lean on SO-driven data.
1---2name: unity-scriptableobjects3description: >4 Architect Unity 6.3 LTS data and decoupling with ScriptableObjects: config/data assets, shared5 runtime variables, event channels, and runtime sets/registries. Use when designing6 data-driven systems, replacing singletons/managers, creating .asset data with7 CreateAssetMenu, or when the user mentions ScriptableObject, SO architecture, or data assets.8metadata:9 source: https://skillmd.com/skills/junmystery/unity-scriptableobjects10---1112# Unity ScriptableObject Architecture1314Use `ScriptableObject` assets to store shared data and decouple systems in Unity 6.3 LTS —15configuration, event channels, and registries that live as project assets instead of being16hard-wired into scenes or singletons. Targets **Unity 6.3 LTS (6000.3)**.1718## When to use1920- Use when you need designer-editable config (weapon stats, level data), to share one value21 between unrelated systems, to decouple senders from listeners via event channels, or to22 build a runtime registry of active objects — without a `static`/singleton manager.23- Use when the project has `*.asset` data files backed by `: ScriptableObject` classes.2425**When _not_ to use:** per-instance runtime state that differs per GameObject (that belongs on26a MonoBehaviour) — a ScriptableObject asset is _shared_ by everyone who references it. Saving27player progress to disk → `save-systems`. Plain DTOs that never need to be an asset can just be28`[System.Serializable]` classes.2930## Core workflow31321. **Define the class** deriving from `ScriptableObject` and tag it with `[CreateAssetMenu]` so33 designers can create instances from the Assets menu.342. **Create one or more `.asset` instances** in the Project window; each is a shared, named35 piece of data referenced by `[SerializeField]` fields.363. **Reference, don't copy.** MonoBehaviours hold a reference to the asset; they all see the37 same data, so changing the asset changes every consumer.384. **For decoupling**, model _signals_ and _shared variables_ as ScriptableObjects: a39 "FloatVariable" the HUD reads and the player writes; an "event channel" the player raises40 and many systems listen to. Neither side references the other.415. **Reset runtime mutations** in `OnEnable` if the asset is mutated during play, because edits42 made in the Editor at runtime persist on the asset (a frequent source of "my values43 changed after I played").446. **Verify** by inspecting the asset values during Play mode and confirming consumers react.4546## Patterns4748### 1. Config/data asset4950```csharp51using UnityEngine;5253[CreateAssetMenu(fileName = "WeaponData", menuName = "Game/Weapon Data", order = 0)]54public class WeaponData : ScriptableObject55{56 public string displayName = "Pistol";57 public int damage = 10;58 public float fireRate = 0.25f;59 public GameObject projectilePrefab;60}61```6263```csharp64public class Weapon : MonoBehaviour65{66 [SerializeField] private WeaponData data; // assign the shared asset in the Inspector67 private void Fire() => Debug.Log($"{data.displayName} for {data.damage}");68}69```7071### 2. Shared runtime variable (decouples producer from consumer)7273```csharp74[CreateAssetMenu(menuName = "Game/Float Variable")]75public class FloatVariable : ScriptableObject76{77 [SerializeField] private float initialValue;78 [System.NonSerialized] public float runtimeValue; // not saved to the asset7980 private void OnEnable()81 {82 runtimeValue = initialValue; // reset when the asset loads83#if UNITY_EDITOR84 // With Reload Domain off, OnEnable does not run again on Play, so also reset there.85 UnityEditor.EditorApplication.playModeStateChanged -= ResetOnPlay;86 UnityEditor.EditorApplication.playModeStateChanged += ResetOnPlay;87#endif88 }8990#if UNITY_EDITOR91 private void OnDisable() => UnityEditor.EditorApplication.playModeStateChanged -= ResetOnPlay;9293 private void ResetOnPlay(UnityEditor.PlayModeStateChange change)94 {95 if (change == UnityEditor.PlayModeStateChange.ExitingEditMode) runtimeValue = initialValue;96 }97#endif98}99// Player writes playerHealth.runtimeValue; the HUD reads it — neither references the other.100```101102### 3. Creating an instance at runtime (not an asset on disk)103104```csharp105// For transient SO data you build in code (e.g. a generated config).106var temp = ScriptableObject.CreateInstance<WeaponData>();107temp.damage = 25;108// ...use temp... Destroy(temp); // clean up runtime-created instances109```110111## Pitfalls112113- **Editing an SO at runtime persists in the Editor** — values you change during Play stay114 changed on the asset after you stop. Keep mutable runtime state in `[NonSerialized]` fields115 reset in `OnEnable`, or it will surprise you. (In a _build_, asset edits do not persist116 across launches.)117- **Disabled Domain Reload skips your `OnEnable` reset** — with **Enter Play Mode Options**118 enabled and **Reload Domain** off (a Unity 6.3 LTS fast-iteration setting), already-loaded SOs are119 _not_ re-created when you press Play, so `OnEnable` never fires and `runtimeValue` keeps its120 value from the previous session (non-serialized fields keep their Play-mode values). Also121 reset on `EditorApplication.playModeStateChanged` (pattern 2), or from a static122 `[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]` method.123- **Expecting per-object state** — every reference points to the _same_ asset. If two enemies124 need different current HP, store HP on the MonoBehaviour, not the shared SO.125- **No frame lifecycle** — ScriptableObjects have `OnEnable`/`OnDisable`/`OnDestroy` but no126 `Update`. Don't expect per-frame callbacks.127- **Using SOs as a save file** — they're authoring assets, not runtime persistence; write128 progress with `save-systems` instead.129- **Leaking `CreateInstance` objects** — runtime-created instances are not garbage-collected130 like plain C# objects; `Destroy` them when done.131132## References133134- For the **event-channel** pattern (a `GameEvent` SO + listeners, type-safe payloads) and135 **runtime sets/registries** (a shared list of active enemies), read136 `references/event-channels.md`.137- Primary docs: Unity Manual "ScriptableObject" (`/Manual/class-ScriptableObject.html`) and138 "Enter Play mode with domain reload disabled" (`/Manual/domain-reloading.html`), plus139 `ScriptReference/ScriptableObject`, `ScriptReference/CreateAssetMenuAttribute`.140141## Related skills142143- `unity-csharp-scripting` — the MonoBehaviours that consume these assets.144- `save-systems` — persisting state to disk (what SOs are _not_ for).145- `card-game` / `rpg` / `survival-crafting` — genres that lean on SO-driven data.