当前位置：首页 > news >正文

c#扩展包-Stateless

news 2026/5/16 19:15:24

准备

Stateless是一个有限状态机扩展包。在c#项目中可以直接通过NuGet安装。

使用他需要先用枚举写好你所有可能的状态和子状态。
例如移动，下蹲，空闲，跳跃，游泳，奔跑，走路。
其中，奔跑和走路是移动的子状态。

然后需要写触发器。所有状态转换必须要一个触发器。
所以你需要把所有的时机都精确描述，并且哪怕只有一个地方用到也要描写。

class Player
{enum State { 移动, 下蹲, 空闲, 空中, 二段跳, 游泳, 奔跑, 走路 }enum Trigger { 上, 下, 左, 右, 松开下, 落地, 落水, 出水, 跌落 }private StateMachine<State, Trigger> stateMachine = new StateMachine<State, Trigger>(State.空闲); 
}

配置状态机

对状态机调用Configure会启用对这个状态下的配置。
从这个配置上调用的配置方法全部都会再返回这个状态的配置。
需要以此法对所有的状态都进行配置。

	public Player(){stateMachine.Configure(State.空闲).Permit(Trigger.下, State.下蹲).Permit(Trigger.右, State.走路).Permit(Trigger.左, State.走路);stateMachine.Configure(State.下蹲).Permit(Trigger.松开下, State.空闲);}

触发器，目标，条件。

配置的方法有很多排列组合出来的版本，例如

Permit
PermitIf
PermitDynamic
PermitDynamicIf

一个基本的Permit方法接受两个参数，第一个是触发器，第二个是触发以后要变成谁。
例如空闲在触发了下的情况下会变成下蹲。
Permit(Trigger.下, State.下蹲)

Dynamic

如果有Dynamic，那么第二个参数会是一个委托，你可以动态的决定要变成谁。
PermitDynamic(Trigger.下, () => Guid.NewGuid() > Guid.NewGuid() ? State.下蹲 : State.空闲)
例如这句代码中，有50%概率变成下蹲，有50%概率变成空闲。

If

如果有If,那么还有第三个参数。也是一个委托，表示条件，需要你返回bool。
PermitIf(Trigger.下, State.下蹲, () => Guid.NewGuid() > Guid.NewGuid())
只有条件满足的时候，这个转化才能成功。

当一次触发时，会判断所有的转化。如果有多个方案可以通过（即便目标相同），会报错。

有多个相同的方案
一个方案存在的时候注册了他的If版本，并且If通过。
有多个If版本的方案种都通过了。

切换的目标

按照目标分组有以下分类

Permit
PermitReentry
InternalTransition
InitialTransition

Permit基础的转换，自选目标。

PermitReentry重新进入自己，意义是触发一次自己的退出和进入方法。
和直接Permit填自己是一样的。

InternalTransition不会发生切换，也不会触发退出和进入。
取而代之的是给定一个动作委托，触发你的动作。
使得看起来像因为切换状态发生了什么事情。
.InternalTransition(Trigger.上, () => { Console.WriteLine("在蹲下的时候不能跳"); })

InitialTransition指定一个子状态，表示这种状态的默认情况。
指定了以后就不会直接停留在这个状态身上了，一旦回来就会切换走。
例如走路和奔跑是移动的子状态。
为移动注册初始子状态为走路，那么以任何方式切换到移动都会变为走路。
包括从走路切到移动。

忽略和未定义的触发

Ignore方法可以忽略这个触发器，什么也不发生。
那如果声明忽略而调用这个转换会怎么样呢？会报一个错，表示这个转换没有注册。

你可以对状态机（不是配置）注册一个委托，来表示有未注册的转换时什么也不做。
stateMachine.OnUnhandledTrigger((s, t) => { });

有参数的转换

有时候，你从外部获取了输入，例如鼠标的位置。这种情况下不能用枚举来覆盖所有情况。
你需要对状态机调用SetTriggerParameters方法，然后保存这个返回值，之后要用到他。
var upTrigger = stateMachine.SetTriggerParameters<int>(Trigger.上);

只能在有If的情况下使用这个东西进行配置。
因为如果你没有条件，那么这个参数是没有意义的。
.PermitIf(upTrigger, State.下蹲, i => i > 4);
使用刚刚获得的东西作为触发器，那么你的条件委托就能使用他的参数。

给状态机触发器

使用Fire方法传递给状态机触发器。
他会根据配置进行转换状态。

如果你使用注册了参数的触发器，你还可以传递参数。

stateMachine.Fire(Trigger.出水);
stateMachine.Fire(upTrigger, 10086);

注册进入和退出

OnEntry方法注册进入这个状态时会发生什么事情。
OnExit方法注册退出这个状态时会发生什么事情。

OnEntryFrom版本的方法。表示从xx触发器来，使用注册了参数的触发器就能读取参数。

.OnEntry(() => { Console.WriteLine("进入到下蹲"); })
.OnExit(() => { Console.WriteLine("从下蹲退出"); }) 
.OnEntryFrom(Trigger.出水, () => { })
.OnEntryFrom(upTrigger, i => Console.WriteLine("携带的参数是" + i));

子级状态

一个状态可以声明为另一个状态的子状态（只能声明一个直接父状态）。

		stateMachine.Configure(State.二段跳).SubstateOf(State.空中);stateMachine.Configure(State.奔跑).SubstateOf(State.移动);stateMachine.Configure(State.走路).SubstateOf(State.移动);

如果只涉及子状态改变，状态是同一个，那么不会执行父状态的进入和退出。
例如说，从走路切换到奔跑，就移动而言是没有变化的。

如果从子状态越过父状态切换到了其他状态，那么他们的退出都会执行。
例如从走路切换到空闲。那么此时也不能算作移动状态，所以移动也会一起结束。

bool b1 = stateMachine.IsInState(State.移动);
bool b2 = stateMachine.State == State.移动;

可以使用IsInState方法带父子级进行状态检测。
例如如果当前是走路，那么b1是true，因为走路是移动。
b2是false，他是直接比较的。

异步任务

带有Async的方法可以把注册的委托改为异步形式。

StateMachine<string, int> st = new StateMachine<string, int>("1");
st.Configure("1").Permit(2, "2").Permit(3, "3");st.Configure("2").OnEntryFromAsync(2, async () =>{await Task.Delay(100);await Console.Out.WriteLineAsync("进入2的第一个异步");await Task.Delay(100);await Console.Out.WriteLineAsync("进入2的第二个异步");}).OnEntryFrom(3, () => Console.WriteLine("进入2的同步")).Permit(1, "1").Permit(3, "3").OnExit(() => Console.WriteLine("离开2"));st.Configure("3").OnEntry(() => Console.WriteLine("进入3")).Permit(1, "1").Permit(3, "2");var t = st.FireAsync(2);
_ = st.FireAsync(3);
_ = st.FireAsync(1);
await t;
Console.WriteLine(st.State);

会有以下几个影响

在异步期间，所有的输入会排队，直到异步完成再依次执行
- 如果不使用Async后缀的方法，注册的委托也可以是异步的。状态机会认为他是普通方法，而程序会在后台把异步继续下去。
如果转换的源状态的退出，或是目标状态的进入有异步任务，那么就要使用FireAsync
- 即便使用了OnEntryFromAsync 携带条件，并且没有通过此条件，也会报错。
- 可以使用Fire的转换，可以使用FireAsync而不会报错。
如果使用了任何通用转换的异步，那么所有转换都要使用FireAsync
- OnTransitionCompletedAsync
- OnTransitionedAsync
- OnUnhandledTriggerAsync

先后顺序

从子级到父级，依次经过所有Exit。
执行转换间隙。
从父级到子级，依次执行Entry，带参数的Entry，进入下一级。
完成切换后执行转换完成。

StateMachine<string, int> st = new StateMachine<string, int>("1.1");st.Configure("1").OnExit(() => Console.WriteLine("从1退出"));st.Configure("1.1").SubstateOf("1").Permit(0, "2.1").OnExit(() => Console.WriteLine("从1.1退出"));st.Configure("2").OnEntry(() => Console.WriteLine("进入2")).OnEntryFrom(0, () => Console.WriteLine("通过0进入2"));st.Configure("2.1").OnEntry(() => Console.WriteLine("进入2.1")).OnEntryFrom(0, () => Console.WriteLine("通过0进入2.2")).SubstateOf("2");st.OnTransitioned(st => Console.WriteLine("完成所有退出"));
st.OnTransitionCompleted(st => Console.WriteLine("进入到目标状态"));st.Fire(0);
/*
从1.1退出
从1退出
完成所有退出
进入2
通过0进入2
进入2.1
通过0进入2.2
进入到目标状态
*/

示例

class Player
{enum State { 移动, 下蹲, 空闲, 空中, 二段跳, 游泳, 奔跑, 走路 }enum Trigger { 键盘输入, 落地, 落水, 出水, 跌落, 超时 }DateTime TimeOut;StateMachine<State, Trigger> stateMachine;StateMachine<State, Trigger>.TriggerWithParameters<Vector2> InputTrigger;public Player(){stateMachine = new StateMachine<State, Trigger>(State.空闲);InputTrigger = stateMachine.SetTriggerParameters<Vector2>(Trigger.键盘输入);stateMachine.OnUnhandledTrigger((s, t) => { });stateMachine.Configure(State.移动).PermitIf(InputTrigger, State.空闲, vec => vec == Vector2.Zero).PermitIf(InputTrigger, State.空中, vec => vec == Vector2.UnitY).PermitIf(InputTrigger, State.下蹲, vec => vec == -Vector2.UnitY).Permit(Trigger.跌落, State.空中).Permit(Trigger.落水, State.游泳);stateMachine.Configure(State.下蹲).PermitIf(InputTrigger, State.空闲, vec => vec == Vector2.Zero).PermitIf(InputTrigger, State.空中, vec => vec == Vector2.UnitY);stateMachine.Configure(State.空闲).PermitIf(InputTrigger, State.走路, vec => vec.Y == 0 && vec.X != 0).PermitIf(InputTrigger, State.空中, vec => vec == Vector2.UnitY).PermitIf(InputTrigger, State.下蹲, vec => vec == -Vector2.UnitY);stateMachine.Configure(State.空中).Permit(Trigger.落地, State.空闲).PermitIf(InputTrigger, State.二段跳, vec => vec == Vector2.UnitY);stateMachine.Configure(State.二段跳).SubstateOf(State.空中).IgnoreIf(InputTrigger, vec => vec == Vector2.UnitY);stateMachine.Configure(State.游泳).Permit(Trigger.出水, State.空中);stateMachine.Configure(State.奔跑).SubstateOf(State.移动);stateMachine.Configure(State.走路).SubstateOf(State.移动).PermitIf(Trigger.超时, State.奔跑, () => DateTime.Now - TimeOut > TimeSpan.FromMicroseconds(500))//如果最后更新时间超过500秒则说明纯按住了走路0.5秒.OnEntry(async () =>{TimeOut = DateTime.Now;await Task.Delay(500);//在0.5秒延迟后尝试改为奔跑stateMachine.Fire(Trigger.超时);}).OnExit(() =>{TimeOut = DateTime.Now;});}
}

准备