# BaseStateMachine

**Repository Path**: maoyinhang/base-state-machine

## Basic Information

- **Project Name**: BaseStateMachine
- **Description**: 基础状态机，保证进入和退出成对调用。
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-06
- **Last Updated**: 2026-06-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BaseStateMachine

一个轻量级泛型有限状态机框架，核心解决 OnEnter/OnLeave 中嵌套切换状态导致的递归问题。

## 设计特点

- **防重入** — 通过内部队列缓冲切换请求，同一时刻只有一条切换链路在执行，避免递归
- **FIFO 保序** — 多次切换请求按调用顺序依次执行，不会丢失中间状态
- **OnEnter/OnLeave 成对保证** — 每个状态必然先 OnEnter 后 OnLeave，不会出现单边调用
- **泛型约束** — 编译期约束状态类型，防止传入非法状态

## 运行原理

```
ChangeState(A)  →  queue: [A]  →  启动 while，切换至 A
  └─ A.OnEnter() 中调 ChangeState(B)
     →  queue: [A, B]  →  count > 1，直接 return
  └─ A 切换完成，Dequeue
  └─ queue: [B]，循环继续，切换至 B
```

## 快速开始

```csharp
// 1. 定义状态
public class IdleState : BaseState
{
    public override void OnEnter() => Console.WriteLine("进入 Idle");
    public override void OnLeave() => Console.WriteLine("离开 Idle");
}

public class RunState : BaseState
{
    public override void OnEnter() => Console.WriteLine("进入 Run");
    public override void OnLeave() => Console.WriteLine("离开 Run");
}

// 2. 实现状态机
public class MyMachine : BaseStateMachine<BaseState>
{
    public override T? GetState<T>()
    {
        // 由你决定如何创建/查找状态实例
        return Activator.CreateInstance<T>();
    }

    public override void ReleaseState<T>(T? state)
    {
        // 由你决定如何释放状态实例
    }
}

// 3. 使用
var machine = new MyMachine();
machine.ChangeState<IdleState>();  // 进入 Idle
machine.ChangeState<RunState>();   // 离开 Idle → 进入 Run
```

## API

| 成员 | 说明 |
|------|------|
| `CurrentState` | 当前状态实例 |
| `ChangeState<T>()` | 请求切换到指定状态 |
| `GetState<T>()` | 抽象方法，需实现状态获取逻辑 |
| `ReleaseState<T>(T?)` | 抽象方法，需实现状态释放逻辑 |
| `BaseState.OnEnter()` | 状态进入回调 |
| `BaseState.OnLeave()` | 状态离开回调 |

## 环境要求

- .NET 8.0+

## License

MIT