ScriptableObjects in Unity: A Practical Guide with 5 Patterns

Illustration of glowing data cards connected by light beams to game items

If your enemy prefabs each carry their own copy of health, speed and damage values, or you have a “GameManager” singleton that every script reaches into, ScriptableObjects can clean that up. A ScriptableObject is a data container that lives as an asset in your project instead of on a GameObject in a scene. This guide covers what they are, when to use them, and five practical patterns (data assets, item databases, shared variables, event channels and runtime sets). It also covers the one gotcha that confuses everyone: changes made in Play mode that stay after you stop.

What Is a ScriptableObject?

A MonoBehaviour is a component. It has to be attached to a GameObject in a scene or prefab, and every copy has its own values. A ScriptableObject is a class whose instances are saved as .asset files in your project. Many objects can reference the same asset, so the data exists once.

Three things follow from that:

  • Less duplication. 200 goblins can all point to one GoblinStats asset. Change the speed once and every goblin changes.
  • Less memory. Values stored on a prefab are copied into every instance. A reference to an asset is just a reference.
  • Looser coupling. Scripts can talk through shared assets instead of finding each other in the scene, so a UI prefab and a player prefab don’t need to know about each other.

ScriptableObjects don’t get Update, don’t have a Transform and can’t be attached to GameObjects. They do get OnEnable, OnDisable, OnDestroy and OnValidate.

Creating Your First One

using UnityEngine;

[CreateAssetMenu(fileName = "NewEnemyStats", menuName = "Game/Enemy Stats")]
public class EnemyStats : ScriptableObject
{
    public string displayName = "Goblin";
    public int maxHealth = 30;
    public float moveSpeed = 3.5f;
    public int damage = 5;
    public GameObject deathEffect;
}

The [CreateAssetMenu] attribute adds an entry to the Project window: right-click, then Create > Game > Enemy Stats. Make a few assets (Goblin, Orc, Skeleton) and fill in their values in the Inspector.

In Unity 6 you can also start from a template: right-click in the Project window and choose Create > Scripting > ScriptableObject Script. Either way, the file name must match the class name, or Unity can’t create assets from it.

Two optional [CreateAssetMenu] settings are worth knowing. A slash in menuName makes a submenu ("Game/Enemies/Stats"), which keeps the Create menu tidy once you have twenty asset types. order sorts your entry among the others in the same menu, lower numbers first.

Then reference the asset from a MonoBehaviour like any other field:

public class Enemy : MonoBehaviour
{
    [SerializeField] EnemyStats stats;
    int health;

    void Awake() => health = stats.maxHealth;

    void Update()
    {
        transform.Translate(Vector3.forward * stats.moveSpeed * Time.deltaTime);
    }
}

Drag the Goblin asset into the prefab’s Stats slot. Every goblin now reads from the same asset.

To create one from code (for example in an editor tool), use ScriptableObject.CreateInstance<EnemyStats>(), never new EnemyStats(). Save it as an asset with AssetDatabase.CreateAsset in editor code.

Pattern 1: Shared Data Assets

This is the pattern above, and it’s the one to start with. Good candidates are anything a designer tunes and many objects share: enemy stats, weapon definitions, level settings, difficulty presets, audio settings, dialog lines.

A useful trick: put behavior-free logic that only depends on the data in the ScriptableObject too.

[CreateAssetMenu(menuName = "Game/Weapon")]
public class WeaponData : ScriptableObject
{
    public float baseDamage = 10f;
    public float critChance = 0.1f;
    public float critMultiplier = 2f;

    public float RollDamage() =>
        Random.value < critChance ? baseDamage * critMultiplier : baseDamage;
}

Swapping weapons is now just swapping which asset the player holds.

Pattern 2: An Item Database

For inventories, give every item its own asset, and keep one database asset that lists them. Save files then store only an item ID, never the asset itself.

[CreateAssetMenu(menuName = "Game/Item")]
public class ItemData : ScriptableObject
{
    public string id;           // stable ID for save files, e.g. "potion_small"
    public string displayName;
    public Sprite icon;
    public int maxStack = 99;
}

[CreateAssetMenu(menuName = "Game/Item Database")]
public class ItemDatabase : ScriptableObject
{
    public ItemData[] items;
    Dictionary<string, ItemData> lookup;

    public ItemData Get(string id)
    {
        lookup ??= items.ToDictionary(i => i.id);
        return lookup.TryGetValue(id, out var item) ? item : null;
    }
}

(This needs using System.Collections.Generic; and using System.Linq;.) When loading a save, turn each stored ID back into an item with database.Get(id). See our JSON save system guide for the saving side.

Pattern 3: Shared Variables

Instead of the health bar finding the player to read its health, both reference a FloatVariable asset. The player writes it, the UI reads it, and neither knows the other exists.

[CreateAssetMenu(menuName = "Variables/Float")]
public class FloatVariable : ScriptableObject
{
    public float initialValue;
    [System.NonSerialized] public float Value;

    void OnEnable() => Value = initialValue;
}

[NonSerialized] keeps the runtime value from being saved into the asset, and OnEnable resets it. Without this, values changed during Play mode stay in the asset in the Editor (see below).

Use this pattern in moderation. A handful of shared variables (player health, score, currency) is clean. Hundreds of them make it hard to follow who writes what.

Pattern 4: Event Channels

An event channel is a ScriptableObject that other objects can raise and listen to. It’s a great way to connect things across scenes and prefabs, like “player died” triggering the game-over screen, music and analytics.

[CreateAssetMenu(menuName = "Events/Void Event Channel")]
public class VoidEventChannel : ScriptableObject
{
    public event System.Action OnRaised;
    public void Raise() => OnRaised?.Invoke();
}

// Raiser
public class PlayerHealth : MonoBehaviour
{
    [SerializeField] VoidEventChannel playerDied;
    public void Die() => playerDied.Raise();
}

// Listener
public class GameOverScreen : MonoBehaviour
{
    [SerializeField] VoidEventChannel playerDied;
    [SerializeField] GameObject panel;

    void OnEnable()  => playerDied.OnRaised += Show;
    void OnDisable() => playerDied.OnRaised -= Show;
    void Show() => panel.SetActive(true);
}

Always unsubscribe in OnDisable. The asset outlives scenes, so a destroyed listener that never unsubscribed will still be called and throw a MissingReferenceException.

๐Ÿ“š Want to go deeper on game architecture?

ScriptableObject patterns are one piece of a bigger topic: structuring game code that stays easy to change. Our list of the best programming and game design books includes the ones we’d recommend for that.

See the book recommendations →

Pattern 5: Runtime Sets

A runtime set is a list asset that objects add themselves to while they’re active. Other systems read the list instead of calling FindObjectsByType.

[CreateAssetMenu(menuName = "Sets/Enemy Set")]
public class EnemySet : ScriptableObject
{
    [System.NonSerialized] public List<Enemy> Items = new();
    public void Add(Enemy e)    { if (!Items.Contains(e)) Items.Add(e); }
    public void Remove(Enemy e) => Items.Remove(e);
}

public class Enemy : MonoBehaviour
{
    [SerializeField] EnemySet allEnemies;
    void OnEnable()  => allEnemies.Add(this);
    void OnDisable() => allEnemies.Remove(this);
}

A minimap, a wave spawner and an “enemies remaining” counter can all read allEnemies.Items with no searching.

Pattern 6: Assets as Types (Instead of Enums)

An enum DamageType { Fire, Ice, Poison } works until you need data per type: a color for the damage number, a status effect, a resistance icon. That data ends up in a switch statement copied into several scripts. Enums are also stored as numbers, so inserting a new value in the middle of the list can silently change what every saved prefab and scene refers to.

An empty (or nearly empty) ScriptableObject class makes each “value” an asset instead:

[CreateAssetMenu(menuName = "Game/Damage Type")]
public class DamageType : ScriptableObject
{
    public Color numberColor = Color.white;
    public Sprite icon;
}

public class Resistances : MonoBehaviour
{
    [SerializeField] DamageType[] immuneTo;

    public bool IsImmune(DamageType type) => System.Array.IndexOf(immuneTo, type) >= 0;
}

Create Fire, Ice and Poison assets, then compare references directly (hit.type == fireType). Adding a new type means creating an asset, not editing code, and reordering never breaks anything because fields store a reference to the asset, not a number. Keep enums for small fixed sets that only code cares about, like a state machine’s states.

When Unity Calls OnEnable and OnDisable

ScriptableObject messages don’t follow a scene, which surprises people who expect them to behave like a MonoBehaviour:

  • Awake runs when the instance is created: when you make the asset in the Editor, or when code calls CreateInstance. It does not run again every time the game starts.
  • OnEnable runs when the asset is loaded. In the Editor that also happens after every script recompile and, with domain reload on, when you enter Play mode. In a build it runs once, the first time something loads the asset (usually the first scene that references it).
  • OnDisable runs when the asset is unloaded, and in the Editor just before scripts reload.

The practical effect: in a build, an asset loaded by your first scene stays loaded while any scene still references it, so OnEnable won’t reset it when you load level 2. If a value must reset per level or per run, reset it explicitly from the code that starts the level, not from the asset’s own OnEnable.

Play Mode Changes and Saving

This is the most important thing to understand about ScriptableObjects:

  • In the Editor, a ScriptableObject asset is the real asset. If your code changes a serialized field during Play mode, the change stays after you stop playing, and it gets saved to disk. Your “max health 30” goblin might be “max health 12” next time.
  • In a build, assets are read-only. Changes last until the asset is unloaded or the game closes, then they’re gone. ScriptableObjects are not a save system.

Rules that avoid both problems:

  1. Treat design data (stats, item definitions) as read-only at runtime. Copy values into the MonoBehaviour (health = stats.maxHealth) and change the copy.
  2. For runtime state that must live in an asset (shared variables, runtime sets), mark it [NonSerialized] and reset it in OnEnable.
  3. For progress that must survive quitting, write it to a save file.

Note that OnEnable on a ScriptableObject doesn’t necessarily run every time you enter Play mode if Enter Play Mode Options has domain reload disabled. In that case, reset values from a bootstrap script, or subscribe to EditorApplication.playModeStateChanged in editor code.

Make design data read-only in code

Rule 1 is easier to keep if the compiler enforces it. Keep the fields private and serialized, and expose read-only properties:

public class EnemyStats : ScriptableObject
{
    [SerializeField] int maxHealth = 30;
    [SerializeField] float moveSpeed = 3.5f;

    public int MaxHealth => maxHealth;
    public float MoveSpeed => moveSpeed;
}

The Inspector still shows both fields, but stats.MaxHealth -= 5 no longer compiles, so no gameplay script can quietly rewrite the asset.

Watch out for lists and arrays

Copying an int out of an asset gives you your own value. Copying a List or array does not: myItems = loadout.startingItems; gives you a second name for the same list, and myItems.Add(...) adds to the asset. Make a real copy instead:

myItems = new List<ItemData>(loadout.startingItems);

Need a full editable copy? Instantiate it

When an object really needs its own version of a whole asset (an enemy that gets buffed during a fight, say), clone it at runtime:

EnemyStats runtimeStats;

void Awake()     => runtimeStats = Instantiate(stats);   // independent copy
void OnDestroy() => Destroy(runtimeStats);              // clean up the clone

The clone lives only in memory, so editing it never touches the asset on disk. Destroy it when you’re done: clones are Unity objects, and an abandoned one can sit in memory until unused assets are next cleaned up.

Catch bad values with OnValidate

OnValidate runs in the Editor whenever a value changes in the Inspector, which makes it a cheap guard against typos in design data:

void OnValidate()
{
    maxHealth = Mathf.Max(1, maxHealth);
    moveSpeed = Mathf.Max(0f, moveSpeed);
}

It doesn’t run in builds, so keep it to clamping and warnings, not gameplay logic.

Troubleshooting

“The asset menu item doesn’t appear”

Check the script compiles, the class derives from ScriptableObject, the file name matches the class name, and [CreateAssetMenu] is on the class. The menu is under right-click Create in the Project window.

Values reset or change unexpectedly

Runtime code is writing to a serialized field on a design asset. Search your code for writes to the asset’s fields and move that state into a MonoBehaviour or a [NonSerialized] field.

“ScriptableObject should be created with CreateInstance”

You used new on a ScriptableObject class. Use ScriptableObject.CreateInstance<T>().

Changes made from an editor script disappear on restart

Changing an asset from code doesn’t mark it dirty. Call EditorUtility.SetDirty(asset) and then AssetDatabase.SaveAssets().

MissingReferenceException from an event channel

A destroyed listener is still subscribed. Subscribe in OnEnable and unsubscribe in OnDisable.

Asset reference is None in a build

Assets are only included in a build when something in a built scene references them (or they’re in a Resources folder or Addressables). Make sure a scene object holds the reference.

“Type mismatch” when dragging a scene object into an asset field

An asset can’t keep a reference to an object in a scene, because the asset exists even when that scene isn’t loaded. The field may appear to work during Play mode and then turn into Type mismatch or Missing. Reference prefabs or other assets only. For scene objects, let them register themselves at runtime (the runtime set pattern above) or pass them in through a MonoBehaviour.

All the values on an asset went blank after renaming a field

Unity stores serialized data by field name, so renaming hp to maxHealth leaves the old value orphaned. Add [FormerlySerializedAs("hp")] (from UnityEngine.Serialization) to the renamed field before saving, and Unity carries the old value over. Once every asset has been re-saved you can remove the attribute.

Changing one object changed every object

Everything that references the asset shares it. Either runtime code is writing to the asset’s fields, or it holds a reference to one of its lists. Copy values out, copy lists with new List<T>(...), or Instantiate the asset for a private copy.

Still Broken? Check These

  • The class derives from ScriptableObject, not MonoBehaviour, and the file name matches the class name.
  • Nothing calls new on the class; use CreateInstance or Instantiate.
  • No gameplay code writes to a design asset’s fields (read-only properties make this a compile error).
  • Runtime fields on shared-variable and runtime-set assets are [NonSerialized] and reset somewhere that actually runs each play session.
  • If domain reload is off under Project Settings > Editor > Enter Play Mode Settings, don’t rely on OnEnable to reset assets.
  • Every event-channel listener unsubscribes in OnDisable.
  • Asset fields reference prefabs or assets, never scene objects.
  • Assets needed in a build are referenced from a built scene, a Resources folder or Addressables.
  • Player progress goes to a save file, not into an asset.

FAQ

What is a ScriptableObject used for in Unity?

Storing shared data as project assets: enemy stats, item definitions, settings and event channels. Many objects can reference one asset, which removes duplication and coupling.

Do ScriptableObject changes save at runtime?

In the Editor, changes made in Play mode are kept in the asset. In builds they’re lost when the game closes. Use a save file for persistent progress.

ScriptableObject vs MonoBehaviour: what’s the difference?

A MonoBehaviour is a component on a GameObject with Update and a Transform. A ScriptableObject is a standalone asset for data with no GameObject, Transform or Update.

Can a ScriptableObject have an Update method?

No. Unity doesn’t call Update on ScriptableObjects. Drive per-frame logic from a MonoBehaviour that uses the asset.

Are ScriptableObjects better than singletons?

For shared data and events, often yes: they’re easier to test and don’t need scene lookups. For systems that need Update or coroutines, a MonoBehaviour manager is still simpler.

How do I create a ScriptableObject from code?

Use ScriptableObject.CreateInstance<T>(). To save it as an asset in the Editor, call AssetDatabase.CreateAsset with a path ending in .asset.

Can a ScriptableObject reference a GameObject in the scene?

Not reliably. Assets outlive scenes, so a scene reference shows as Type mismatch or Missing. Reference prefabs, or have scene objects register with the asset at runtime.

Should I Instantiate a ScriptableObject?

Only when one object needs its own editable copy of the whole asset. For a few values, copying them into fields is simpler. Destroy clones when you’re done with them.

Can a ScriptableObject replace an enum?

Yes. One asset per value lets each type carry its own data (color, icon, effects), and adding a type means creating an asset instead of editing code.

Comments

6 responses to “ScriptableObjects in Unity: A Practical Guide with 5 Patterns”

  1. […] done” every time you test. In builds, they reset on restart. Keep assets read-only. The ScriptableObjects guide explains this trap in […]

  2. […] If your models are centered, put them under an empty parent with the pivot at the corner. The ScriptableObjects guide covers this data […]

  3. […] Inheritance lets consumables, weapons and quest items each define their own behaviour. Our ScriptableObjects guide explains why these assets are ideal for shared […]

  4. […] Variants vs ScriptableObjects: variants are great when objects differ in components or structure. If they differ only in numbers, a single prefab plus different ScriptableObject data assets is often cleaner (see our ScriptableObjects guide). […]

  5. […] means Instantiate returns the component directly and prevents dropping in the wrong prefab. Our ScriptableObjects guide explains why these assets suit configuration data, and our SerializeField and Inspector attributes […]

  6. […] saving. In a build they reset to the shipped values every launch. ScriptableObjects are great for shared game data and runtime state, but they are not a save format; copy the values into your save file […]

Leave a Reply

Your email address will not be published. Required fields are marked *