JosiahSiegel/unity-csharp-scripting

Unity C# Scripting Patterns

Overview

Core C# scripting reference for Unity development. Covers MonoBehaviour lifecycle, physics and collision APIs, animation scripting, audio, navigation, common design patterns, serialization, and ECS/DOTS coding patterns.

MonoBehaviour Lifecycle

Execution Order

Awake() -> OnEnable() -> Start() -> FixedUpdate() -> Update() -> LateUpdate() -> OnDisable() -> OnDestroy()

| Method | When Called | Use For | |--------|-----------|---------| | Awake() | Once, when object instantiates (before Start) | Self-initialization, caching references | | OnEnable() | Each time object becomes active | Subscribe to events, reset state | | Start() | Once, before first Update (after all Awake) | Cross-object initialization | | FixedUpdate() | Fixed timestep (default 0.02s) | Physics, Rigidbody movement | | Update() | Every frame | Input, non-physics logic | | LateUpdate() | After all Update calls | Camera follow, post-movement adjustments | | OnDisable() | When object deactivates | Unsubscribe events, save state | | OnDestroy() | When object is destroyed | Final cleanup, resource release |

Key Rules

• Awake runs even on disabled components (but not disabled GameObjects)
• Never rely on Awake/Start order between scripts -- use [DefaultExecutionOrder(N)] or Script Execution Order settings
• Use OnValidate() for editor-time validation of serialized fields

Coroutines and Async

Coroutines

IEnumerator SpawnWaves(int count, float delay)
{
    for (int i = 0; i < count; i++)
    {
        SpawnEnemy();
        yield return new WaitForSeconds(delay);
    }
}
// Start: Coroutine handle = StartCoroutine(SpawnWaves(5, 1f));
// Stop: StopCoroutine(handle); or StopAllCoroutines();

| Yield Instruction | Behavior | |-------------------|----------| | yield return null | Wait one frame | | yield return new WaitForSeconds(t) | Wait t seconds (affected by timeScale) | | yield return new WaitForSecondsRealtime(t) | Unscaled time | | yield return new WaitForFixedUpdate() | Wait for next FixedUpdate | | yield return new WaitForEndOfFrame() | After rendering | | yield return new WaitUntil(() => condition) | Wait until predicate is true | | yield return StartCoroutine(other) | Wait for nested coroutine |

Async/Await (Unity 6+ / UniTask)

For Unity 2023+/Unity 6, Awaitable is built-in. For older versions, use UniTask.

async Awaitable LoadLevelAsync(string sceneName)
{
    await Awaitable.WaitForSecondsAsync(1f);
    var op = SceneManager.LoadSceneAsync(sceneName);
    while (!op.isDone)
    {
        progressBar.value = op.progress;
        await Awaitable.NextFrameAsync();
    }
}

Events and Delegates

Event Pattern (Recommended)

// Publisher
public class Health : MonoBehaviour
{
    public event System.Action<float> OnDamaged;  // event keyword prevents external invocation
    public event System.Action OnDeath;

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

// Subscriber
void OnEnable() => health.OnDamaged += HandleDamage;
void OnDisable() => health.OnDamaged -= HandleDamage;
void HandleDamage(float amount) => /* react */;

ScriptableObject Event Channels

Decouple systems without direct references. Create GameEvent as a ScriptableObject asset, invoke from publishers, and listen from subscribers via GameEventListener MonoBehaviours. See references/design-patterns.md for full implementation.

Physics API Quick Reference

Rigidbody Movement (3D)

| Task | Method | Where | |------|--------|-------| | Continuous force | rb.AddForce(dir * force) | FixedUpdate | | Instant impulse | rb.AddForce(dir * force, ForceMode.Impulse) | FixedUpdate | | Direct velocity | rb.linearVelocity = dir * speed | FixedUpdate | | Kinematic move | rb.MovePosition(target) | FixedUpdate | | Rotation | rb.MoveRotation(targetRot) | FixedUpdate |

Note: In Unity 6, Rigidbody.velocity is renamed to Rigidbody.linearVelocity.

Raycasting

if (Physics.Raycast(origin, direction, out RaycastHit hit, maxDistance, layerMask))
{
    Debug.Log($"Hit {hit.collider.name} at {hit.point}");
}
// Use Physics.RaycastAll or Physics.RaycastNonAlloc for multiple hits
// 2D: Physics2D.Raycast, Physics2D.OverlapCircle, etc.

Collision vs Trigger

| Callback | Requires | Use For | |----------|----------|---------| | OnCollisionEnter/Stay/Exit | Both have colliders, at least one Rigidbody, isTrigger=false | Physical impacts | | OnTriggerEnter/Stay/Exit | One collider has isTrigger=true, at least one Rigidbody | Zones, pickups, detection |

Always use CompareTag("Enemy") instead of other.tag == "Enemy" (avoids GC allocation).

Animation Scripting

[RequireComponent(typeof(Animator))]
public class CharacterAnimation : MonoBehaviour
{
    static readonly int SpeedHash = Animator.StringToHash("Speed");
    static readonly int JumpTrigger = Animator.StringToHash("Jump");
    Animator _anim;

    void Awake() => _anim = GetComponent<Animator>();
    void Update()
    {
        _anim.SetFloat(SpeedHash, moveSpeed);
        if (jumped) _anim.SetTrigger(JumpTrigger);
    }
}

Cache Animator.StringToHash results as static readonly fields to avoid per-frame hashing. Use Animation Events for gameplay-timed callbacks (footsteps, hit frames). For IK, implement OnAnimatorIK(int layerIndex) with SetIKPosition/Rotation/Weight.

Audio Quick Reference

[RequireComponent(typeof(AudioSource))]
public class SFXPlayer : MonoBehaviour
{
    [SerializeField] AudioClip[] clips;
    AudioSource _source;
    void Awake() => _source = GetComponent<AudioSource>();
    public void PlayRandom() => _source.PlayOneShot(clips[Random.Range(0, clips.Length)]);
}

Use AudioSource.PlayOneShot() for overlapping SFX. Use AudioMixer with exposed parameters for volume control. Use snapshots for state transitions (combat vs. exploration).

Serialization

| Type | Serialized | Notes | |------|-----------|-------| | public fields | Yes | Visible in Inspector | | [SerializeField] private | Yes | Preferred -- maintains encapsulation | | [HideInInspector] public | Yes, hidden | Serialized but not shown | | [NonSerialized] public | No | Opt-out of serialization | | Properties | No | Never serialized by Unity | | Dictionaries | No | Use serialized list + rebuild, or Odin/SerializedDictionary | | Interfaces | No | Use abstract ScriptableObject or SerializeReference |

Use [SerializeReference] for polymorphic serialization of interfaces and abstract types.

Common Design Patterns

| Pattern | When to Use | Approach | |---------|------------|----------| | Singleton | Global managers (Audio, GameState) | ScriptableObject-based or lazy MonoBehaviour | | Observer | Decoupled communication | C# events or SO event channels | | Command | Input/undo systems | Command interface + history stack | | State Machine | AI, player states | Enum + switch, or class-based states | | Object Pool | Bullets, particles, enemies | Queue<T> with pre-instantiation | | Service Locator | Testable global access | Static registry with interface keys |

For detailed implementations and code examples, see references/design-patterns.md.

ECS/DOTS Quick Reference

| Concept | Role | |---------|------| | Entity | Lightweight ID (no MonoBehaviour) | | IComponentData | Pure data struct on entities | | SystemBase / ISystem | Logic operating on component queries | | EntityQuery | Filter entities by component sets | | Jobs (IJobEntity) | Multithreaded systems | | Burst Compiler | SIMD-optimized native code |

For ECS architecture patterns and migration guidance, see references/design-patterns.md.

Additional Resources

Reference Files

• references/design-patterns.md -- Full implementations of singleton, observer, command, state machine, object pool, service locator, and ECS patterns
• references/physics-animation-audio.md -- Detailed physics setup (2D and 3D), advanced animation (blend trees, IK, root motion, Animation Rigging), and audio architecture