Unity Scripting Fundamentals

Retrieval Sources

Key Guidelines

Lifecycle & Execution Order

Unity calls "event functions" (Awake, OnEnable, Start, Update, etc.) by name/reflection, not through an interface — they are not virtual overrides, so a typo in the signature (wrong case, wrong parameter list, accidentally static) fails silently with no compiler error. Awake runs exactly once per instantiation, immediately after the object is created/loaded, regardless of whether the component or GameObject is enabled — use it for self-contained initialization that doesn't depend on other objects. OnEnable runs every time the object transitions to active (including the first time, right after Awake, and again after any SetActive(true)/enabled = true toggle) — use it to (re)subscribe to events and reset per-activation state, paired with unsubscription in OnDisable. Start runs exactly once, only if the object is enabled, immediately before the first Update — this is the right place for cross-object references, because every other object's Awake in the scene is guaranteed to have already run (but not necessarily their Start). SceneManager.sceneLoaded fires after OnEnable but before Start for all objects in a freshly loaded scene, per the execution-order manual — don't assume Start is the earliest point a loaded scene is queryable. Execution order across different GameObjects at the same phase (e.g. two objects' Awake) is undefined unless explicitly pinned via Project Settings > Script Execution Order — never rely on scene-hierarchy or component-list ordering by default; if two systems have a hard ordering dependency, either use that setting or restructure so the dependency is resolved lazily (e.g. a property that self-initializes on first access) rather than assumed. FixedUpdate runs on a fixed timestep, potentially zero or multiple times per rendered frame, before the physics step — put physics-affecting code (Rigidbody forces/velocity) here, never in Update. LateUpdate runs once per frame after every Update call across all objects has completed — use it for camera-follow and other logic that must react to a fully-updated frame. OnDisable and OnDestroy fire on deactivation/destruction respectively; OnDestroy is also called on scene unload for objects not marked DontDestroyOnLoad, and on application quit (mobile/editor ordering can vary — don't do critical save-on-quit work only in OnDestroy without also handling OnApplicationQuit/OnApplicationPause). OnValidate and Reset are Editor-only: OnValidate runs whenever a serialized field changes in the Inspector (including via Undo), Reset runs once when the component is first added or when "Reset" is chosen from its context menu — never put runtime-only logic (e.g. GetComponent expecting a scene reference) in OnValidate without null-guarding, since it also runs outside Play mode.

public class Turret : MonoBehaviour
{
    [SerializeField] private float fireRate = 1f;
    private Health targetHealth; // cross-object ref resolved in Start

    private void Awake()
    {
        // Safe: only touches this object's own components.
        GetComponent<Animator>();
    }

    private void OnEnable()
    {
        GameEvents.OnWaveStarted += HandleWaveStarted;
    }

    private void OnDisable()
    {
        GameEvents.OnWaveStarted -= HandleWaveStarted; // must mirror OnEnable exactly
    }

    private void Start()
    {
        // Safe here: every object's Awake in the scene has already run.
        targetHealth = FindFirstObjectByType<Health>();
    }

    private void HandleWaveStarted() { /* ... */ }
}

Serialization

Unity's serializer is not the .NET [Serializable]/BinaryFormatter system, and only understands a specific subset of types: it serializes public fields and [SerializeField]-marked private/protected fields of primitives, strings, enums, Unity object references, and [Serializable]-marked plain classes/structs (nested up to a fixed depth) — it never serializes properties, static fields, const/readonly fields, or fields marked [NonSerialized]. [Serializable] is not inherited: every class in a hierarchy that needs serialization must be marked individually. Unity cannot natively serialize Dictionary<TKey,TValue>, interfaces, abstract base-typed fields, or multidimensional arrays (jagged arrays of serializable types are fine) — for these, either restructure the data (e.g. two parallel List<>s instead of a Dictionary) or implement ISerializationCallbackReceiver to flatten the data into a serializable shape in OnBeforeSerialize and rebuild it in OnAfterDeserialize. [SerializeReference] is the exception for polymorphism: it lets a field typed as an interface or abstract class serialize by reference to a concrete [Serializable] instance, preserving the runtime type across domain reloads and scene saves — but every concrete type used this way must itself be [Serializable], and renaming/moving those types breaks existing serialized data unless [FormerlySerializedAs]-style migration is handled. Every serialized field, public or private, appears in the Inspector by default; [HideInInspector] keeps a field serialized (round-trips through saves/prefabs) while hiding it from the Inspector UI, whereas [NonSerialized] removes it from serialization entirely (and as a side effect it also disappears from the Inspector). Because serialization drives prefab instantiation, scene saving, Undo/Redo, and Editor hot-reload alike (per script-serialization-how-unity-uses.html), a field that fails to serialize correctly can silently reset on every domain reload during iteration — this is a common source of "my value keeps resetting in the Editor" bugs.

[Serializable]
public struct DamageInfo
{
    public float amount;
    public DamageType type;
}

public class Weapon : MonoBehaviour
{
    [SerializeField] private DamageInfo baseDamage;      // struct, serializes fine
    [SerializeField, HideInInspector] private int hitCount; // serialized, hidden from UI

    // Interfaces need SerializeReference + a concrete [Serializable] implementation.
    [SerializeReference] private IWeaponModifier modifier;
}

[Serializable]
public class SpreadModifier : IWeaponModifier
{
    public float spreadDegrees;
}

// Dictionary isn't serializable directly — flatten it.
public class LootTable : MonoBehaviour, ISerializationCallbackReceiver
{
    private Dictionary<string, int> weights = new();
    [SerializeField] private List<string> keys = new();
    [SerializeField] private List<int> values = new();

    public void OnBeforeSerialize()
    {
        keys.Clear(); values.Clear();
        foreach (var kv in weights) { keys.Add(kv.Key); values.Add(kv.Value); }
    }

    public void OnAfterDeserialize()
    {
        weights = new Dictionary<string, int>();
        for (int i = 0; i < keys.Count; i++) weights[keys[i]] = values[i];
    }
}

ScriptableObjects

ScriptableObject is Unity's asset-backed, non-MonoBehaviour data container: it isn't attached to a GameObject, doesn't live in a scene, and is instead a serialized asset on disk (or a runtime-only instance via ScriptableObject.CreateInstance<T>()). Use it for shared config, event channels, and inventories/data tables that multiple scenes or objects need to reference identically, instead of a scene-bound singleton/static manager — an SO reference survives scene loads/unloads because it isn't part of any scene. Its lifecycle is asset-based, not scene-based: OnEnable fires when the asset is loaded (including on Editor domain reload and when entering Play mode, since the asset gets reloaded/reinitialized), and OnDisable fires on unload — this is not the same as a MonoBehaviour "becoming active"; don't assume SO OnEnable maps to "GameObject became visible." A critical gotcha: an asset-based ScriptableObject instance is shared and persists across Play sessions in the Editor — if a script mutates its fields at runtime (e.g. a "current health" field on a shared CharacterStatsSO), that mutation survives after you stop Play mode, corrupting the authored asset for the next session. Either treat SO fields as read-only config and keep mutable runtime state elsewhere, or explicitly clone the SO at runtime (Instantiate(sourceSO)) and mutate the clone, or reset fields in OnEnable/OnDisable. [CreateAssetMenu] adds a "Create > ..." Project-window menu entry so designers can create asset instances without code; fileName sets the default asset name, menuName sets the menu path, order controls menu position.

[CreateAssetMenu(fileName = "NewCharacterStats", menuName = "Game/Character Stats", order = 0)]
public class CharacterStatsSO : ScriptableObject
{
    public float maxHealth = 100f;
    public float moveSpeed = 5f;
}

// Event-channel pattern: decouples publisher and subscribers via an asset, not a scene ref.
[CreateAssetMenu(menuName = "Game/Events/Void Event Channel")]
public class VoidEventChannelSO : ScriptableObject
{
    public event Action OnRaised;
    public void Raise() => OnRaised?.Invoke();
}

// Runtime-mutable state should be a clone, not the shared asset:
public class Character : MonoBehaviour
{
    [SerializeField] private CharacterStatsSO baseStats; // shared, read-only template
    private CharacterStatsSO runtimeStats;                // per-instance clone

    private void Awake()
    {
        runtimeStats = Instantiate(baseStats); // safe to mutate; doesn't touch the asset
    }
}

Coroutines

A coroutine is a method returning IEnumerator that Unity drives incrementally, resuming it once per matching update phase rather than running it to completion synchronously — it is not a thread, and all its code still runs on the main thread. yield return null resumes the coroutine on the next frame's Update-equivalent point; yield return new WaitForSeconds(t) resumes after t seconds of scaled time; yield return new WaitForFixedUpdate() resumes on the next FixedUpdate; yield return new WaitForEndOfFrame() resumes after rendering for that frame completes (useful for screenshot capture); yield return new WaitUntil(predicate) / WaitWhile(predicate) poll a condition each frame; yield return otherCoroutine (yielding another coroutine's IEnumerator or Coroutine) nests execution, resuming the parent only once the child finishes. StartCoroutine is a MonoBehaviour instance method — the coroutine is bound to that specific GameObject/component, and Unity automatically stops it if the host GameObject is deactivated or destroyed (it does not automatically stop merely because the component's enabled flag was set false while the GameObject stays active — component-level disable does not implicitly cancel its own coroutines, so explicit StopCoroutine in OnDisable is still required for correctness). StartCoroutine returns a Coroutine handle; store it if you need to StopCoroutine that specific instance later, since starting the "same" coroutine method twice by name only reliably stops the most recent call when using the string-based overload. StopAllCoroutines stops every coroutine started on that MonoBehaviour instance, which is a blunt instrument if the same component runs multiple independent coroutines. For long-lived coroutines that must survive their originating object being destroyed/disabled, host them on a persistent manager object instead. Unity 6 also offers Awaitable-based async/await as a coroutine alternative for a subset of cases — see Advanced Notes.

public class Fader : MonoBehaviour
{
    private Coroutine fadeRoutine;

    public void FadeTo(float target, float duration)
    {
        if (fadeRoutine != null) StopCoroutine(fadeRoutine);
        fadeRoutine = StartCoroutine(FadeRoutine(target, duration));
    }

    private IEnumerator FadeRoutine(float target, float duration)
    {
        float start = CanvasGroupAlpha();
        float t = 0f;
        while (t < duration)
        {
            t += Time.deltaTime;
            SetAlpha(Mathf.Lerp(start, target, t / duration));
            yield return null; // resume next frame
        }
        SetAlpha(target);
        fadeRoutine = null;
    }

    private void OnDisable()
    {
        // GameObject deactivation auto-stops coroutines, but explicit stop
        // guards against component-only disable and keeps intent explicit.
        if (fadeRoutine != null) { StopCoroutine(fadeRoutine); fadeRoutine = null; }
    }

    private float CanvasGroupAlpha() => 0f; // placeholder
    private void SetAlpha(float a) { }       // placeholder
}

Events & Delegates

Prefer plain C# event Action<T> (or event EventHandler<T>) over direct component references for decoupling one script from another's concrete type — subscribers only need to know the delegate signature, not the publisher's class. Always unsubscribe in the mirrored teardown method (OnDisable for a subscription made in OnEnable) — a missed unsubscription is a common source of MissingReferenceException/leaked-object bugs, because the event's invocation list keeps a live reference to the subscriber, preventing GC and firing callbacks on effectively-dead objects. UnityEvent (and its generic variants UnityEvent<T0> through the 4-type-parameter form) exists specifically so designers can wire method calls from the Inspector without code — use it for GameObject-level hooks meant to be authored visually (e.g. a Button's onClick, or a damage-received hook a designer wants to route to different effects per-prefab), but reserve it for that Inspector-wiring use case: UnityEvent.Invoke() is measurably slower than a C# delegate invocation (reflection-based persistent-listener resolution) and offers no compile-time type safety on manually-wired listener methods beyond parameter count/type matching at the moment of binding. UnityEvent supports up to four generic parameters (UnityEvent<T0,T1,T2,T3>); beyond that, or for anything performance-sensitive (e.g. per-frame or per-physics-step events), use a plain delegate. AddListener/RemoveListener on a UnityEvent mirror +=/-= on a C# event but only affect runtime ("non-persistent") listeners; listeners wired via the Inspector are "persistent" and are managed separately by Unity's serialization of the event.

public class Health : MonoBehaviour
{
    // Code-to-code decoupling: fast, type-safe, no Inspector wiring needed.
    public event Action<float> OnDamaged;
    public event Action OnDied;

    [SerializeField] private float currentHealth = 100f;

    public void TakeDamage(float amount)
    {
        currentHealth -= amount;
        OnDamaged?.Invoke(amount);
        if (currentHealth <= 0f) OnDied?.Invoke();
    }
}

public class DamageListener : MonoBehaviour
{
    [SerializeField] private Health health;

    private void OnEnable()  { health.OnDamaged += HandleDamaged; health.OnDied += HandleDied; }
    private void OnDisable() { health.OnDamaged -= HandleDamaged; health.OnDied -= HandleDied; }

    private void HandleDamaged(float amount) { /* flash red, play SFX */ }
    private void HandleDied() { /* ragdoll, disable input */ }
}

// Inspector-wireable version, for designer-facing hooks (e.g. on a UI Button):
public class DamageFlashUI : MonoBehaviour
{
    [SerializeField] private UnityEvent<float> onDamagedUI; // designer assigns listeners in Inspector
    public void Trigger(float amount) => onDamagedUI?.Invoke(amount);
}

Attributes

Built-in attributes fall into two buckets: Inspector-display-only (no runtime effect) and behavior-affecting. [Header("...")], [Tooltip("...")], [Space]/[Space(height)], [Multiline]/[Multiline(lines)], and [TextArea(minLines, maxLines)] only change how a field renders in the Inspector — stripping them changes nothing at runtime. [Range(min, max)] both constrains the Inspector to a slider and clamps values assigned via the Inspector, but does not clamp values set purely in code — a script can still assign an out-of-range value via field = 999f. [Delayed] defers committing a text field's edit until Enter/focus-loss rather than on every keystroke — useful for fields that trigger expensive OnValidate work. [SerializeField], [SerializeReference], [HideInInspector], and [NonSerialized] affect serialization (see above). [RequireComponent(typeof(T))] auto-adds a dependency component when this component is added via the Editor's "Add Component" and blocks manual removal of that dependency while this component is present — note it does not retroactively add the dependency to GameObjects that already have this script attached from before the attribute existed, and it has no effect on components added purely via code (AddComponent<T>() bypasses the auto-add safety net, so a script relying on [RequireComponent] should still null-check or GetComponent defensively if it can be added programmatically). [DisallowMultipleComponent] prevents a GameObject from carrying more than one instance of the component type. [ExecuteAlways] (current) and the older [ExecuteInEditMode] make lifecycle methods run in Edit mode as well as Play mode — essential for gizmo-driven tooling or live-preview components, but it means Awake/OnEnable/Update etc. can run without ever entering Play mode, so code must not assume Play-mode-only state (e.g. Time.deltaTime behaves differently, and singletons/managers may not exist yet). [ContextMenu("Label")] on a method adds a right-click Inspector action; [ContextMenuItem("Label", "MethodName")] on a field does the same but scoped to that field's context menu — both are Editor/debug conveniences, not shipped-build functionality (they still compile into player builds but are unreachable without the Editor UI).

[RequireComponent(typeof(Rigidbody))]
[DisallowMultipleComponent]
public class Projectile : MonoBehaviour
{
    [Header("Flight")]
    [Tooltip("Muzzle velocity in meters/second.")]
    [Range(1f, 200f)] public float speed = 40f;

    [Space(10)]
    [TextArea(2, 4)] public string debugNotes;

    [SerializeField, Delayed] private int poolSize = 32; // commit on Enter, not per keystroke

    private Rigidbody rb; // guaranteed present at runtime because of RequireComponent

    [ContextMenu("Reset Velocity")]
    private void ResetVelocity()
    {
        if (rb == null) rb = GetComponent<Rigidbody>();
        rb.linearVelocity = Vector3.zero;
    }
}

[ExecuteAlways]
public class GizmoRadius : MonoBehaviour
{
    public float radius = 3f;
    private void OnDrawGizmosSelected() => Gizmos.DrawWireSphere(transform.position, radius);
}

Object Pooling

Reusing instances instead of repeated Instantiate/Destroy avoids GC churn and instantiation overhead for frequently-spawned objects (bullets, particles, enemies). Unity 6 ships a generic UnityEngine.Pool.ObjectPool<T> (implementing IObjectPool<T>) so hand-rolled pools are rarely needed. Its constructor takes four delegates plus two capacity controls: createFunc (Func<T>) constructs a brand-new instance when the pool is empty; actionOnGet (Action<T>) runs when an instance is checked out — activate/reset it here; actionOnRelease (Action<T>) runs when an instance is returned — deactivate/clean it here; actionOnDestroy (Action<T>) runs when the pool must discard an instance because it's over maxSize; collectionCheck (bool) enables a debug-time check that throws if the same instance is released twice; defaultCapacity and maxSize bound the pool's internal collection size. Code against IObjectPool<T> in consumer classes so the concrete pool implementation can be swapped later without touching call sites.

public class BulletPool : MonoBehaviour
{
    [SerializeField] private Bullet bulletPrefab;
    private IObjectPool<Bullet> pool;

    private void Awake()
    {
        pool = new ObjectPool<Bullet>(
            createFunc: () => Instantiate(bulletPrefab),
            actionOnGet: b => b.gameObject.SetActive(true),
            actionOnRelease: b => b.gameObject.SetActive(false),
            actionOnDestroy: b => Destroy(b.gameObject),
            collectionCheck: true,
            defaultCapacity: 20,
            maxSize: 100);
    }

    public Bullet Spawn(Vector3 pos, Quaternion rot)
    {
        var bullet = pool.Get();
        bullet.transform.SetPositionAndRotation(pos, rot);
        bullet.Init(this); // bullet calls pool.Release(this) on impact/timeout
        return bullet;
    }

    public void Despawn(Bullet b) => pool.Release(b);
}

Generics

Generic MonoBehaviour subclasses (public class Foo<T> : MonoBehaviour) compile but Unity cannot serialize or attach an open generic type directly to a GameObject — the Inspector can't display it and it can't be added via "Add Component." The workaround is a non-generic subclass that closes the type parameter (public class IntFoo : Foo<int> { }); only the closed, concrete subclass is addable/serializable. This pattern is genuinely useful for shared base behavior (e.g. a generic StateMachine<TState> or a generic Singleton<T> base class) as long as every concrete usage goes through a closed subclass. Generic ScriptableObject subclasses have the same restriction — CreateAssetMenu and asset creation require a closed concrete type. Plain (non-MonoBehaviour, non-ScriptableObject) generic classes/structs have no such restriction and are ordinary C#; they only hit Unity-specific limits if a field of that generic type needs Inspector serialization, in which case the same "must be a closed, [Serializable]-marked concrete type" rule applies as for any other serialized field.

// Base generic logic — cannot be attached directly to a GameObject.
public abstract class Singleton<T> : MonoBehaviour where T : Singleton<T>
{
    public static T Instance { get; private set; }

    protected virtual void Awake()
    {
        if (Instance != null && Instance != this) { Destroy(gameObject); return; }
        Instance = (T)this;
    }
}

// Closed concrete subclass — this is what actually goes on a GameObject.
public class AudioManager : Singleton<AudioManager>
{
    public void PlayClip(AudioClip clip) { /* ... */ }
}

// Serializable generic field must also be a closed type:
[Serializable]
public class Pair<TA, TB> { public TA first; public TB second; }

public class Config : MonoBehaviour
{
    [SerializeField] private Pair<string, int> nameToScore; // closed: Pair<string,int> — serializes fine
}

Common Mistakes

Quick Reference

Advanced Notes

Domain reload behavior. By default, Unity reloads the scripting domain every time you enter Play mode, which wipes all managed state — static fields, cached singletons, subscribed events — back to their compile-time defaults, exactly as a fresh process launch would. This is why static counters/caches "reset" correctly between Play sessions without any explicit cleanup code, and it's a safety net that hides bugs where cleanup logic is actually missing. Domain reload is also comparatively slow, so Unity offers "Enter Play Mode Settings" to disable domain reload (and/or scene reload) for faster iteration — but disabling it means your code is now responsible for manually resetting every piece of static/persistent state on Play-mode entry (typically via [RuntimeInitializeOnLoadMethod] or explicit reset calls), because the previous session's static state otherwise leaks into the new one. Domain reload also occurs on script compilation while the Editor is not in Play mode and as part of asset-database refresh in some workflows — code that assumes "domain reload only happens between Play sessions" can be surprised by an Edit-mode reload triggered by simply saving a script.

Async/await vs coroutines. Unity 6 supports genuine C# async/await using its own Awaitable type (UnityEngine.Awaitable) as a Unity-aware alternative to System.Threading.Tasks.Task. Coroutines are Unity's original mechanism: an IEnumerator-based method driven frame-by-frame by the engine, cooperative and cancellation-by-convention (stopping requires holding the Coroutine handle or being GameObject-scoped). Awaitable-based async methods integrate with normal C# control flow (try/catch, return values, composing with await), support real cancellation via CancellationToken (including the built-in destroyCancellationToken, which fires automatically when the hosting MonoBehaviour is destroyed — critical for avoiding "continuing an async method on a destroyed object" bugs), and offer entry points like Awaitable.NextFrameAsync(), Awaitable.WaitForSecondsAsync(), Awaitable.FixedUpdateAsync(), Awaitable.MainThreadAsync(), and Awaitable.BackgroundThreadAsync() mirroring the common coroutine yield instructions plus explicit thread-affinity control that coroutines never had. The key gotcha, per the Awaitable class reference: instances are pooled internally and are not safe to await more than once — do not cache an Awaitable and re-await it, and do not fire the same async method call's result off to two separate awaiters. Prefer Awaitable over Task for Unity-facing async code specifically because Awaitable is allocation-lean (pooled) and integrates with Unity's player loop and destroy-cancellation, whereas a raw Task continuation can resume on a thread-pool thread and touch Unity API objects unsafely from off the main thread. Choose coroutines when the calling code is simple sequential frame-waiting with no need for return values or exception propagation and when working in codebases already standardized on IEnumerator; choose async/Awaitable when you need a return value, proper exception handling, cancellation tied to object lifetime, or composition with other async code (including real Task-based I/O, which still requires bridging back to the main thread before touching Unity objects).