wave6-ecs-state-machine-design

ECS State Machine Design — Decision Model

Intent

Choose the correct ECS state representation — enum field, IEnableableComponent, or structural add/remove — based on transition frequency, state count, and query-filtering requirements.

Decision Model

Senior Pattern — Enum FSM

public enum BotState { MoveToTarget, Attack, Retreat, Idle, Dead }

public struct BotAI : IComponentData
{
    public BotState State;
    public float StateTimer;
}

[BurstCompile]
public partial struct BotFSMJob : IJobEntity
{
    public float DeltaTime;

    [BurstCompile]
    public void Execute(ref BotAI bot, ref LocalTransform t)
    {
        switch (bot.State)
        {
            case BotState.MoveToTarget:
                bot.StateTimer -= DeltaTime;
                if (bot.StateTimer <= 0) bot.State = BotState.Attack;
                break;
            case BotState.Attack:
                // attack logic
                break;
            // ...
        }
    }
}

Senior Pattern — Enableable Binary Flag

// Zero-size component — just the enabled bit matters:
public struct Stealth : IComponentData, IEnableableComponent { }

// Systems automatically see only active entities:
new StealthBehaviorJob().ScheduleParallel(state.Dependency);   // only enabled
new StealthRevealJob().ScheduleParallel(state.Dependency);     // only enabled

// Mixed: enum for internal FSM, enableable for external visibility:
public struct EnemyAI : IComponentData { public EnemyState State; }
public struct DetectedByPlayer : IComponentData, IEnableableComponent { }
// Internal transitions via enum field; player detection via enableable