Pushdown Stack

Push an interrupt on top of your game; whatever was running freezes mid-stride until it is popped.

What it does

The Pushdown Stack is a headless, last-in-first-out stack of game states, called scopes. It lets you suspend a running gameplay simulation (or AI, or menu) and resume it mid-stride. Push a scope onto the stack — a dialogue interrupt, an AI decision, a logical menu — and the live thing underneath freezes exactly where it was. Pop it, and the previous scope wakes up with nothing to rebuild (within a session).

Only the top scope ticks; suspended scopes hold their state, frozen, until resumed. The stack is pure C# and deterministic, and its structure can be saved and restored through the Save / Load service.

Quick start

Resolve the factory from the service locator, then create a stack:

using CommonGameSystem.Core;
using UnityEngine;

[DefaultExecutionOrder(100)] // Run after the framework has started.
public class MyStackUser : MonoBehaviour
{
    private IPushdownStack _stack;

    private void Awake()
    {
        _stack = ServiceLocator.Resolve<IPushdownStackService>().Create();

        // Or construct one directly — works standalone, with no service registration:
        // _stack = new PushdownStack();
    }
}

API reference

IPushdownStack — the main interface

IStackScope — what you implement for each scope

IPushdownStackService — the factory registered by Bootstrap

PushdownStackOptions — a readonly configuration struct

PushdownStackSnapshot — a [Serializable] struct for save and restore

IScopeFactory — implemented by your game, passed only to Restore

Examples

A dialogue interrupt that suspends gameplay:

using CommonGameSystem.Core;
using UnityEngine;

[DefaultExecutionOrder(100)] // Run after the framework has started.
public class GameplayController : MonoBehaviour
{
    private IPushdownStack _stack;

    void Awake()
    {
        _stack = ServiceLocator.Resolve<IPushdownStackService>().Create();
    }

    void Update()
    {
        RunGameplay();
        _stack.Tick(Time.deltaTime);
    }

    public void StartDialogue(DialogueScope dialogue)
    {
        _stack.Push("dialogue", dialogue);
        // Gameplay is now frozen; only the dialogue ticks.
    }

    // Called by the dialogue when it closes:
    public void EndDialogue()
    {
        _stack.Pop();
        // Gameplay resumes mid-stride.
    }

    void OnDestroy() => _stack?.Clear();  // Exits every scope top-to-bottom (nothing resumes).

    private void RunGameplay()
    {
        // Your per-frame gameplay update.
    }
}

// A simple dialogue scope:
public class DialogueScope : IStackScope
{
    public void OnEnter() => Debug.Log("Dialogue opened.");
    public void OnSuspend() { }  // Freezes naturally: suspended scopes never tick.
    public void OnResume() { }   // Nothing to do for a self-contained scope.
    public void OnExit() => Debug.Log("Dialogue closed.");
    public void Tick(float deltaTime)
    {
        // Advance the dialogue text here.
    }
}

Turning it off

ServiceLocator.Replace<IPushdownStackService>(new NullPushdownStackService());

The NullPushdownStack mutes every operation with no changes to calling code: Depth is always 0, Top is always null, all mutating calls do nothing, and ScopeChanged never fires. Use it in headless or server builds, or whenever the stack is unused. It logs one warning when constructed so you know it is active.

Common pitfalls

• Main thread only. All operations — Push, Pop, Tick, and the rest — must run on the main thread. Worker-thread calls throw InvalidOperationException.
• Scope internals are your responsibility. The snapshot captures only the stack structure: which scope keys, in what order. Each scope's internal state — a dialogue's current line, a state machine's current state — must be saved separately (see Save / Load) and rebuilt by your IScopeFactory.Create(key).
• Operations issued from inside a hook are deferred. If a hook (OnEnter, OnSuspend, OnResume, OnExit, or Tick) calls Push, Pop, Replace, or Clear, that operation is queued and runs after the current hook finishes, in the order requested. At most EffectiveMaxOpsPerDispatch queued operations (default 8) run per dispatch; beyond that, a warning is logged and the rest are dropped.
• ScopeChanged subscribers must not throw. The event fires in the middle of an operation without a try/catch. On Pop and Clear, it fires before the new top's OnResume — a throwing subscriber leaves the operation half applied.
• IL2CPP: preserve your own scope classes. The framework preserves its own types only. A game class implementing IStackScope or IScopeFactory that is used only through its interface can be removed by IL2CPP code stripping. Protect your classes with [Preserve] or an entry in your project's link.xml.
• Revalidate AI scopes after a resume. A dialogue or menu resumes exactly as it was, and that is correct. But an AI scope's cached view of the world (last-seen target position, real-time timers) is stale by however long it was suspended — resuming it blindly can walk a character to where an enemy used to be. Use OnResume to recheck world assumptions. Timers driven by Tick pause naturally and need no reset; only real-time (wall-clock) timers go stale.

Related pages

• Bootstrap — how services start
• FSM (State Machines) — flat state machines to run inside a scope
• UI Framework — the visual UI panel stack (a separate, unrelated stack)
• Save / Load — saving the snapshot