FSM(ステートマシン)

すべての敵、メニュー、ゲームフェーズに名前付きステートの明快なセットを与え、切り替えは宣言的なガード付き遷移に任せましょう。

概要

有限ステートマシン(FSM)は、挙動を名前付きステート — 敵なら Idle、Chase、Dead など — と、その間を移動するルールに整理します。このサービスが提供するのはフラットでヘッドレスな FSM です：各ステートを小さなクラスとして定義し、宣言的なガード付き遷移(「敵がプレイヤーを見つけたら Idle から Chase へ」)または直接の ChangeState 呼び出しでマシンを駆動します。

クロックはゲーム側が所有します：毎フレーム各マシンをティックし、デルタタイムを自分で渡します。内部ティッカーも MonoBehaviour の荷物もありません。このマシンは敵 AI、メニューフロー、ゲームフェーズのループのために作られています — ティックあたりゼロアロケーション、決定論的な順序、純粋な C#、そして IL2CPP(プレイヤービルドに使われる Unity の事前コンパイラ)下でも安全です。

クイックスタート

ファクトリを一度だけ解決し、オブジェクトごとにマシンを作ります：

using CommonGameSystem.Core;
using UnityEngine;

[DefaultExecutionOrder(100)] // Run after the framework has started.
public class MyStateMachineUser : MonoBehaviour
{
    private IStateMachine<MyStateMachineUser> _fsm;

    private void Awake()
    {
        // Via the factory (recommended — you get diagnostics and the one-line off switch):
        _fsm = ServiceLocator.Resolve<IStateMachineService>().Create<MyStateMachineUser>(this);

        // Or construct one directly (works standalone, but is not counted in diagnostics):
        // _fsm = new StateMachine<MyStateMachineUser>(this);
    }
}

上のように、マシンはフィールドにキャッシュしてください。Update() の中でサービスを解決してはいけません。

API リファレンス

IStateMachine<TContext> — 毎フレームティックするインスタンス単位のマシン

TContext はステートが読み書きするオブジェクトです — 通常は所有側の MonoBehaviour やエンティティです。

IState<TContext> — 実装するもの

このインターフェースを実装するか、StateBase<TContext> を継承して必要なものだけをオーバーライドします：

IStateMachineService — ファクトリ

使用例

using CommonGameSystem.Core;
using UnityEngine;

// The context: the object your states read and modify.
public class Enemy : MonoBehaviour
{
    public bool SeesPlayer;
    public float Health = 100f;
}

// Define state names as public const strings to avoid typos.
public static class EnemyStates
{
    public const string Idle = "Idle";
    public const string Chase = "Chase";
    public const string Dead = "Dead";
}

// Minimal states — extend StateBase and override only what you need.
public class IdleState : StateBase<Enemy> { }
public class ChaseState : StateBase<Enemy> { }
public class DeadState : StateBase<Enemy> { }

[DefaultExecutionOrder(100)] // Run after the framework has started.
public class EnemyController : MonoBehaviour
{
    private IStateMachine<Enemy> _fsm;
    private ITimeService _time;

    private void Awake()
    {
        _time = ServiceLocator.Resolve<ITimeService>();
        var service = ServiceLocator.Resolve<IStateMachineService>();
        _fsm = service.Create<Enemy>(GetComponent<Enemy>());

        _fsm.Add(EnemyStates.Idle, new IdleState());
        _fsm.Add(EnemyStates.Chase, new ChaseState());
        _fsm.Add(EnemyStates.Dead, new DeadState());

        // Declarative transitions (preferred).
        _fsm.AddTransition(EnemyStates.Idle, EnemyStates.Chase, enemy => enemy.SeesPlayer);
        _fsm.AddTransition(EnemyStates.Chase, EnemyStates.Idle, enemy => !enemy.SeesPlayer);

        // Global interrupt: any state can go to Dead.
        _fsm.AddTransition(StateMachine<Enemy>.AnyState, EnemyStates.Dead, enemy => enemy.Health <= 0);

        _fsm.Start(EnemyStates.Idle);
    }

    private void Update()
    {
        // The machine reads no clock — you pass the delta, so you pick the clock.
        _fsm.Tick(_time.DeltaTime(Clock.Gameplay));
    }

    private void OnDestroy() => _fsm.Dispose();
}

無効化する

ServiceLocator.Replace<IStateMachineService>(new NullStateMachineService());

これでステートマシンがミュートされます：Tick、ChangeState、Start は no-op になり、CurrentStateName は常に null、StateChanged は発火せず、ActiveMachineCount は 0 です。呼び出しコードを変えずに、テスト中の AI やメニューフローを無効化するのに便利です。no-op サービスは構築時に 1 回だけ警告をログし、以後の各 Create<T> 呼び出しは無音です。

よくある落とし穴

• メインスレッド専用です。 Tick、ChangeState、Start はすべてメインスレッドで実行しなければなりません。ワーカースレッドからの呼び出しはエディタでは InvalidOperationException を投げます(このチェックは IL2CPP リリースビルドでは取り除かれます)。マシンはフレームループ上に置いてください。
• クロックを選ぶのはあなたです。 マシンはクロックを読みません — deltaTime を Tick に渡します。ゲームと一緒にポーズする挙動には timeService.DeltaTime(Clock.Gameplay) を渡します。ポーズやスローモーション中もティックし続けるには timeService.UnscaledDeltaTime(Clock.Gameplay) を渡します。独立した「unscaled」クロックはありません：クロックは Gameplay、UI、Background で、それぞれがスケール済みと非スケールの両方の読み値を持ちます — Time を参照してください。
• ガードは軽く保ってください。 遷移ガードはすべてのマシンで毎ティック実行されます。ガード内の高コストな処理 — レイキャスト、経路探索、アロケーション — はマシン数 × 遷移数で膨れ上がります。そうした結果は Tick を呼ぶ前にコンテキストオブジェクト上で計算してキャッシュしてください。
• struct コンテキストは変更を保持しません。 TContext が struct の場合、OnUpdate 内での変更はローカルコピーにしか影響せず失われます。可変の共有コンテキストとして参照型 — 通常は所有側の MonoBehaviour やエンティティ — を使ってください。
• struct コンテキストと IL2CPP。 TContext が値型の場合、ジェネリックのインスタンス化 StateMachine<YourStruct> が IL2CPP のコードストリッピングを生き残るよう、プロジェクトに link.xml エントリを追加してください。クラスのコンテキストにはエントリ不要です。

動作保証

• ステートフックの内側から要求された ChangeState は、現在のフックが終わった後に適用されます。複数要求された場合は最後のものが勝ちます。マシンはこれを再帰ではなくループで処理します — 遷移の連鎖でスタックがあふれることはありません。
• AnyState のグローバル割り込みは、常に現在ステート自身の遷移より先に評価されます。
• default(StateMachineOptions) が安全な構成です：警告オン、ステートの例外は封じ込め、現在のステートへの遷移は no-op。
• このマシンはフラットな FSM です — 組み込みの階層やステートのスタックはありません。スタック可能で再開可能なゲームステートにはプッシュダウンスタックを参照してください。バックスタック式のメニューナビゲーションには、UI フレームワークの UI パネルスタックを使ってください。

関連ページ

• Time — Tick を駆動するポーズ対応クロック
• プッシュダウンスタック — スタック可能で再開可能なステート
• UI フレームワーク — メニュー用の UI パネルスタック
• はじめに — フレームワークのインストールと起動