プッシュダウンスタック

ゲームの上に割り込みをプッシュ。実行中だったものは、ポップされるまでその場で凍結します。

概要

プッシュダウンスタックは、スコープと呼ばれるゲームステートのヘッドレスな後入れ先出しスタックです。実行中のゲームプレイシミュレーション(や AI、メニュー)をサスペンドし、途中から再開できます。スコープをスタックにプッシュすると — ダイアログ割り込み、AI の意思決定、論理メニュー — その下で生きていたものは、まさにその場で凍結します。ポップすれば、前のスコープは(セッション内では)何も作り直すことなく目を覚まします。

ティックするのは最上位のスコープだけです。サスペンドされたスコープは、再開されるまで状態を凍結したまま保持します。スタックは純粋な C# で決定論的であり、その構造はセーブ/ロードサービスを通じて保存・復元できます。

クイックスタート

サービスロケーターからファクトリを解決し、スタックを作ります：

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 リファレンス

IPushdownStack — メインインターフェース

IStackScope — 各スコープで実装するもの

IPushdownStackService — Bootstrap が登録するファクトリ

PushdownStackOptions — 読み取り専用の設定構造体

PushdownStackSnapshot — セーブとリストア用の [Serializable] 構造体

IScopeFactory — ゲーム側が実装し、Restore にだけ渡すもの

使用例

ゲームプレイをサスペンドするダイアログ割り込み：

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.
    }
}

無効化する

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

NullPushdownStack は、呼び出しコードを変えることなくすべての操作をミュートします：Depth は常に 0、Top は常に null、すべての変更系呼び出しは何もせず、ScopeChanged は発火しません。ヘッドレスビルドやサーバービルド、あるいはスタックを使わない場面で使ってください。構築時に 1 回警告をログするので、有効になっていることが分かります。

よくある落とし穴

• メインスレッド専用です。 Push、Pop、Tick をはじめとするすべての操作はメインスレッドで実行しなければなりません。ワーカースレッドからの呼び出しは InvalidOperationException を投げます。
• スコープ内部の状態はあなたの責任です。 スナップショットがキャプチャするのはスタックの構造だけです：どのスコープキーが、どの順番か。各スコープの内部状態 — ダイアログの現在の行、ステートマシンの現在のステート — は別途保存し(セーブ/ロードを参照)、あなたの IScopeFactory.Create(key) で再構築する必要があります。
• フックの内側から発行された操作は遅延されます。 フック(OnEnter、OnSuspend、OnResume、OnExit、Tick)が Push、Pop、Replace、Clear を呼ぶと、その操作はキューに入り、現在のフックの終了後に要求順で実行されます。1 回のディスパッチで実行されるキュー済み操作は最大 EffectiveMaxOpsPerDispatch 件(デフォルト 8)で、それを超えると警告がログされ残りは破棄されます。
• ScopeChanged の購読者は例外を投げてはいけません。 このイベントは try/catch なしで操作の途中に発火します。Pop と Clear では、新しい最上位の OnResume より前に発火します — 例外を投げる購読者は、操作を中途半端に適用されたまま残します。
• IL2CPP：自分のスコープクラスは自分で保存してください。 フレームワークが保存するのは自分自身の型だけです。インターフェース経由でしか使われない、IStackScope や IScopeFactory を実装するゲームクラスは、IL2CPP のコードストリッピングで除去されることがあります。[Preserve] またはプロジェクトの link.xml のエントリでクラスを保護してください。
• AI スコープは再開後に再検証してください。 ダイアログやメニューは元のまま再開し、それで正しく動きます。しかし AI スコープがキャッシュした世界のビュー(最後に見たターゲット位置、実時間タイマー)は、サスペンドされていた時間のぶんだけ古くなっています — 盲目的に再開すると、キャラクターが敵のかつていた場所へ歩いていきかねません。OnResume で世界に関する前提を確認し直してください。Tick 駆動のタイマーは自然にポーズするのでリセット不要です。古くなるのは実時間(壁時計)タイマーだけです。

関連ページ

• ブートストラップ — サービスの起動の仕組み
• FSM(ステートマシン) — スコープの内側で動かすフラットなステートマシン
• UI フレームワーク — 視覚的な UI パネルスタック(別物の無関係なスタック)
• セーブ/ロード — スナップショットの保存