动作序列 · 架构解析

源设计起源 · 为什么要做这个模块

• 没它会怎样：代码会慢慢烂掉：一开始只是"播个音效"这种还能接受的样子。接着需求一个个来 —— 要等玩家点击（于是需要跨帧状态，只能存字段）、要加超时、要能取消、取消后还要恢复现场、还要并行做两件事……最后状态散在 5 个字段里，没人能一眼说清"现在走到哪、谁负责在什么时机清理"。
• 为什么不用协程：协程轻量，但它时间绑死引擎、取消没有收尾契约、没有并行与重复的语义，参数还只能靠闭包捕获 —— 多实例共享正是并发坑的源头。一旦流程要复用、要取消、要诊断、要被别的系统驱动，就需要更结实的结构。
• 早期（原体系）真实的疼：状态写在节点组件的字段上，同一节点被多个对象并发触发时互相覆盖；没有句柄，一条正在等待的序列既不能取消也不能查进度；纯线性，没有并行、没有等待秒数；节点还和具体业务硬耦合，没法单测。
• 换来了什么：把"定义"和"运行"分开、把跨帧状态收进每次运行自己的槽位、把取消与收尾变成必然会执行的契约 —— 于是"同一条序列并发跑两份"从一个 bug 变成了一件自然的事。

本篇只讲为什么；怎么用见同目录《使用说明》。

0三句话速览（完整用法见《使用说明》）

第一步：它适合你的业务吗？

第二步：五行跑起来

// ① 构建一次（加载期），缓存到 static readonly —— 运行期零构建成本
private static readonly RevSequenceDefinition MyFlow =
    RevSequence.Create("演示\\一段流程")
        .Do("打个招呼", ctx => Debug.Log("你好"))
        .Wait(0.6f)                                          // 等 0.6 秒（用 Tick 的 dt，不读 Time.time）
        .WaitUntil("等条件成立", ctx => Ready(), 5f)          // 等条件（带 5 秒超时保护）
        .Publish(new MyEvent(1))                             // 发强类型事件（串联别的序列 / 通知系统）
        .Build();                                            // 构建会做静态校验，错误在启动时炸出来

// ② 播放（任何地方；不往场景里放任何东西也行）
RevSequencePlayer.Default.Play(MyFlow, source: gameObject);   // Default 自动创建驱动者（零配置）

第三步：记住三条铁律

1. 状态不存在步骤里，存在"本次运行"里 —— 自定义步骤用 GetOrCreateState<T>(run)，不要在 lambda 里闭包捕获字段（并发会互踩，这正是原体系的老毛病）；
2. 时间只认 Tick(deltaTime) —— 不读 Time.time，所以能暂停、快进、脱离引擎单测；
3. 取消必须走收尾 —— 被 Stop / StopAll / 宿主销毁时，OnCancel 里的步骤会执行；耗资源的序列都该在这里回收。

第四步：上手地图（学的时候只需要认识第一层）

第五步：常见需求 → 一行写法（背下这张表就会写 90% 的序列）

1它解决什么问题

1.1 "流程代码"为什么会烂成面条

// 一开始长这样（可以接受）
PlaySound("Box_Appear");
// 然后需求来了：等玩家点了再开箱
_clicked = false; _waiting = true;         // ← 需要跨帧状态 → 只能存字段
// 再然后：要加超时、要能取消、取消后要恢复镜头、要并行播两件事…
// 最后：状态散在 5 个字段里，onUpdate/onComplete 回调互相嵌套，
//       没人能一眼说清"这个流程现在走到哪了、谁负责在什么时机清理"

动作序列就是给这类代码一个结构：把流程写成一棵可读的步骤列表，把跨帧状态交给引擎托管，把取消与收尾变成契约。

1.2 为什么不用协程

1.3 它和状态机怎么分工

实战里最常见的是"状态机管形态，序列管演出"：Boss 进入二阶段时，先播登场演出（序列），演出结束再交割状态（状态机）。

2新版 vs 参考实现（动作序列执行系统）

2.1 总览

2.2 原体系那些"真实的疼"（本框架的设计动机）

3七个关键设计决策，以及为什么这么定

3.1 决策一：定义与运行分离（Definition / Run）

RevSequenceDefinition  ←  你写的"剧本"：不可变、可缓存、可被无限次播放
        ↓ runner.Play(def, source)
RevSequenceRun         ←  这一次播放的"现场"：步骤进度、状态槽、取消标记、句柄

原体系的组件既是定义又是状态（既描述"等输入"，又用字段存"这次等到了没"），所以"同一条序列被两个 actor 同时触发"必然互相踩。拆开后：Definition 可以放进 static readonly，每次 Play 拿到的 Run 完全独立 —— "同一条序列并发跑两份"从一个 bug 变成了一件自然的事。

3.2 决策二：状态槽 —— 并发安全的落点

// RevStepBase 给自定义步骤的状态 API（业务侧唯一需要关心的）
protected T GetState<T>(RevSequenceRun run);              // 读
protected void SetState(RevSequenceRun run, object state); // 写
protected T GetOrCreateState<T>(RevSequenceRun run);      // 取不到就 new（池化友好）

• 为什么不用 Dictionary<步骤, 状态>：哈希查找 + 装箱；而"槽位号"是构建期常量，运行时一次数组下标访问（O(1)、零哈希）；
• 为什么归还池时要清空：否则下一条复用本实例的序列会读到上一条的状态对象（"第一次跑对、第二次跑用了上次的数据"，极难查）。

3.3 决策三：并发策略是"配置"，不是"约定"

原体系"多 actor 并发触发互相覆盖"是缺陷；这里把同一件事变成每条序列自己声明的策略：

3.4 决策四：时间注入（Tick(deltaTime)），而不是 Time.time

runner.Tick(Time.deltaTime);        // 正式运行：宿主每帧调
runner.Tick(0.016f);                // 单测：手动推进，精确到帧
runner.Tick(0f);                    // 暂停：一行就能做"时间静止"

换来三件事：① 可暂停/慢放/快进（不改业务代码）；② 单测里"等 3 秒"= 循环调 30 次 Tick(0.1f)；③ 与渲染帧率脱钩。

代价：谁 Tick 谁负责 —— 所以额外给了 RevSequencePlayer.Default（自动创建驱动者，零配置）来兜底"我 Play 了怎么没反应"这个最烦人的问题。

3.5 决策五：框架零业务依赖（服务容器 + 事件总线）

// 业务侧：定义接口 + 实现（框架完全不知道这些类型）
public interface IDemoSoundService { void PostEvent(string eventName, object emitter = null); }

// 序列里：只面向接口
.Do("播放出现音效", ctx => ctx.Get<IDemoSoundService>()?.PostEvent("Play_Box_Appear"))

// 组装时：显式注册（★ 泛型参数要写接口类型）
runner = new RevSequenceRunner(RevDemoServiceHub.CreateServices(hub));

3.6 决策六：取消与收尾是契约，不是"自觉"

.OnCancel(finallySteps => finallySteps          // 被取消时必然执行（同步、一次性）
    .Do("回收生成物", ctx => ctx.Get<IEffectService>()?.Recycle(node))
    .Do("恢复镜头",   ctx => ctx.Get<ICameraService>()?.Restore()))

原体系对应的是"靠节点 OnDisable 自觉兜底"（00:38）—— 漏一处就是资源泄漏或"镜头还推着"。

3.7 决策七：组合优于内建，以及刻意不做的东西

刻意不做的三件事（保持轻量，避免变成"配置语言的方言"）：条件分支/跳转步骤（分支就是步骤里的 if；要两条流程就构建两条定义）；步骤间数据管道（用局部变量或业务服务）；区域/碰撞数学（只给触发源契约）。

4通用性论证：能不能经得起真实业务的考验

4.1 六条判据（逐条给证据）

4.2 能力对照：原体系 15 个动作节点 → 现在怎么写

4.3 八类业务场景的适配度

4.4 三条硬边界（诚实清单）

1. 不内置业务动作库 —— 播特效 / 音效 / 切镜头 / 播 Timeline 都要业务自己写服务或步骤。原体系那些 SimpleAction* 恰恰是"业务实现"，硬塞回框架就又把业务和框架绑回去了（原体系 ⑥ 号疼点）。
2. 不做状态网络 —— 没有条件跳转、没有"回退到第 3 步"这类图结构。序列管一条路走到底；要复杂决策请用状态机。
3. 异步那条线仍依赖 RevTask，而它是引擎相关的（RevTask.cs 2 处、RevTaskScheduler.cs 5 处引擎调用）。准确表述：不用 PlayAsync / WaitTask 时内核是纯 C#；用了就把 RevTask 的引擎依赖带上。

4.5 三个压力测试（"会不会被业务打穿"）

5怎么用（从"能跑"到"写对"）

5.1 三个概念，三种驱动方式

RevSequenceDefinition（剧本，不可变）  ←  用 RevSequence.Create(...).Build() 构建一次
        │  runner.Play(def, source)          source = 触发者（判定并发策略、日志定位）
        ▼
RevSequenceRun（这次播放的现场，池化复用）  ←  步骤进度 / 状态槽 / 取消标记 / 句柄
        │  runner.Tick(deltaTime)            每帧推进一步（谁 Tick 谁说了算）
        ▼
RevSequenceHandle（钥匙，值类型）          ←  handle.Stop() / IsValid（只答「还在不在跑」）

// ① 最省事（Unity，零配置）：内部自动创建隐藏驱动者 + 全局默认引擎
RevSequencePlayer.Default.Play(MyFlow, source: gameObject);

// ② 场景级引擎：勾选组件上的"使用自己的引擎"，随场景卸载一起收掉

// ③ 自己 new + 自己 Tick（单元测试 / 特殊时间源 / 多套隔离）
var runner = new RevSequenceRunner(services, events);
runner.Tick(0.016f);        // ← 时间由你决定：快进、慢放、暂停都是一行

5.2 步骤全集（DSL 一览）

5.3 自定义步骤：什么时候必须写

// Demo 里的真实例子：灵果抛物线飞向玩家
public sealed class RevFlyParabolaStep : RevStepBase
{
    private sealed class State { public float Duration; }      // ← 本次运行私有的状态

    private readonly float _duration;

    public RevFlyParabolaStep(float duration = 0.35f) => _duration = duration;

    public override string Name => "抛物线飞向玩家";

    public override void Execute(RevSequenceRun run, RevSequenceContext context)
    {
        State state = GetOrCreateState<State>(run);            // ★ 状态进槽位，按运行实例隔离
        state.Duration = _duration;
    }

    public override bool IsCompleted(RevSequenceRun run, RevSequenceContext context)
        => run.Elapsed >= GetState<State>(run).Duration;        // ★ 时间从 run 取，不读 Time.time
}

5.4 触发源与绑定

// ① 区域触发（对应原体系 enterActions）：让 MonoBehaviour 实现触发源契约 —— 8 行接上 Unity 物理
public sealed class MyZone : MonoBehaviour, RevITriggerSource
{
    public string Name => "宝箱区域";
    public event Action<RevTriggerSignal> Triggered;
    public void Dispose() => Triggered = null;                    // 断开所有订阅
    private void OnTriggerEnter(Collider other)
        => Triggered?.Invoke(new RevTriggerSignal(other.gameObject, Name));
}
runner.Bind(zone, ChestOpenSequences.ChestOpen);      // 返回值 Dispose 即解绑

// ② 事件触发（对应原体系 listenEventActions）—— 一行绑定
runner.BindEvents<ChestOpenedEvent>(runner.Events, SlidingDoorOpen, e => e.Opener);

// ③ 手动触发（最直接，永远可用）
runner.Play(LingGuoDemoSequences.Gather, source: player);

5.5 生命周期回调与三种结束路径

RevSequence.Create("带埋点的流程")
    .Do("第一步", ctx => ...)
    .OnCompleted(run => Analytics.End(run.ToString(), true))
    .OnCancelled(run => Analytics.End(run.ToString(), false))
    .OnCancel(f => f.Do("清理", ctx => ...))
    .Build();

5.6 五个必须避开的陷阱

1. 在 DoBlocking 谓词里闭包捕获字段（并发互踩）→ 用 Step 自定义步骤，或把状态放进业务服务。
2. 把运行期数据塞进 .Publish(evt)：它的载荷是构建期给定的，只适合常量事件；要带 ctx.Source / uid 就用 .Do("广播", ctx => ctx.Events.Publish(new X(ctx.Source, uid)))。
3. 创建了资源但不写 OnCancel：生成的演出物件、音频 Bank、推近的镜头都要在收尾里回收。
4. 忘了 Tick / Tick 了两次：忘了 → "我 Play 了没反应"；两次（场景里两个驱动全局引擎的组件）→ 所有序列速度翻倍、等待时间减半。框架会自动关闭第二个驱动者并告警。
5. 反复 Build()：构建器是一次性的，重复调用会抛异常 —— 正确姿势是构建一次缓存到 static readonly。

5.7 可复用性：把序列做成"库"（四个做法）

// 一座"序列库"：全部是 static readonly（加载期构建一次，运行期零成本）
internal static class GameSequences
{
    public static readonly RevSequenceDefinition ChestOpen = BuildChestOpen();
    public static readonly RevSequenceDefinition DoorOpen  = BuildDoorOpen();

    public static readonly RevSequenceDefinition BattleIntro =
        RevSequence.Create("战斗\\入场")
            .Sequence("先开箱", ChestOpen)          // ← 复用积木（父被取消时子一起取消）
            .Sequence("再开门", DoorOpen)
            .Do("播战斗音乐", ctx => ctx.Get<ISoundService>()?.PostEvent("Battle_BGM"))
            .Build();
}

6参考实现真实业务场景 Demo（Assets\Revolution.Demo\RevActionSequence.Demo\）

6.1 目录与怎么跑

RevActionSequence.Demo\              10 文件 / 1181 行
├── RevDemoServices.cs              业务服务接口 + 假实现（音效/特效/相机/Timeline/输入/奖励/场景）
├── RevDemoEvents.cs                强类型事件（替代 SendEvent + param1~param5）
├── RevDemoSteps.cs                 三个自定义步骤（等待点击 / 抛物线飞行 / 等演出播完）
├── RevDemoTriggerSource.cs         区域触发源（对应 enterActions / exitActions）
├── ChestOpenSequences.cs           场景① 宝箱 → 等待点击 → 开门（原体系唯一的完整样例）
├── LingGuoGatherSequences.cs       场景② 灵果采集（进出区域 + 并行表现 + 发奖 + 收尾回收）
├── FarmGiftBoxSequences.cs         场景③ 农场礼盒进入/离开（双向 + 防擦边抖动）
├── NpcCloseupSequence.cs           场景④ NPC 特写（推近 → 等对白 → 恢复；取消也恢复）
├── RocketTimelineSequence.cs       场景⑤ 火箭演出（预加载 → 并行 → 等播完 → 降级 → 回收）
└── RevActionSequenceDemo.cs        入口：挂到场景任意物体上，按键体验

6.2 五个场景，逐个对照原体系

场景① 宝箱 → 等待点击 → 开门（原体系《05 配置与架构解析》39~55 行）

演示的机制：触发源绑定；强类型事件替代字符串事件；事件触发另一条序列；嵌套写法（父被取消时子一起取消）。

场景② 灵果采集（原体系 DimensionObjectService.cs:585-666）

RevSequence.Create("次元\\灵果采集", RevSequenceConcurrency.ReplacePerSource)
    .Do("播放采集音效", ctx => Sound(ctx)?.PostEvent("Play_CiYuan_UI_LingGuo_Get"))
    .Parallel("消失表现与飞行动画同时进行", p => p                      // ← 原体系做不到（纯线性）
        .Do("播放消失音效", ctx => Sound(ctx)?.PostEvent("Play_CiYuan_UI_LingGuo_Disappear"))
        .Step(new RevFlyParabolaStep(duration: 0.35f)))
    .Do("发放灵果奖励", ctx => ctx.Get<IDemoRewardService>()?.Grant("LingGuo", 1, ctx.Source))
    .Do("广播采集事件", ctx => ctx.Events.Publish(new LingGuoGatheredEvent(ctx.Source, uid, id)))
    .OnCancel(f => f.Do("回收灵果物件", ctx => ...))                    // ← 原体系靠 OnDisable 自觉兜底
    .Build();

演示的机制：三种并发策略一起用；Parallel 并行；自定义步骤的状态隔离；取消收尾回收物件。

场景③ 农场礼盒进入/离开（原体系 DimensionObjectService.cs:360-431、1938-2011）

原体系在代码里 AddComponent<SimpleTrigger>() + 组两个 SimpleActionSendEvent（enter/exit）。 本框架两条序列 + 两个触发源事件。重点在"防擦边抖动"：离开序列先 Wait(0.2f) 再关面板 —— 这类"时间上的缓冲"用序列表达最自然，用 if/else 写就会散成"延迟调用 + 取消调用"。

场景④ NPC 特写（原体系 DimensionNpcCamera.cs:44-143）

原体系用 LeanTween 推近 + 隐藏 HUD/Player/Doll，靠外部 onComplete 回调串联；中途切场景就容易留下"镜头还推着"的状态。 本框架：隐藏 HUD → 推近 → 等 0.35s → 播对白 → WaitUntil(等点击，超时 15s) → 恢复 → OnCancel 里再恢复一遍。

演示的机制：WaitUntil 的超时保护（对应原体系 MoveActorTo 永久阻塞事故 05:113）；取消收尾是契约；两条结束路径各自埋点。

场景⑤ 火箭演出（原体系 DimensionSceneMgr.cs:2268-2403）

原体系：预加载 → 取用 → 播 Timeline → 回收，散在几个方法里；低画质设备替换材质走简化演出。 本框架一条序列从上到下读完，另有 ShortShow 走简化流程 —— 降级不是序列里的 if，而是"两条定义二选一"（更好读、也更好测）。

演示的机制：WaitUntil 等预加载（带超时）；Parallel（音乐 ∥ 演出）；自定义步骤等演出播完；OnCancel 停止并回收；业务判定（设备等级）留在业务侧。

6.3 Demo 刻意演示的 8 个机制

7API 速查

7.1 构建：RevSequence / RevSequenceBuilder

7.2 引擎：RevSequenceRunner

7.3 句柄 / 运行实例 / 上下文

7.4 触发源 / 事件总线

7.5 自定义步骤：RevStepBase / 配套类型

8验证结果（实测，含未做的部分）

编译器验证覆盖了什么：DSL 全链路、泛型约束与类型键事件、async RevTask 的自定义 AsyncMethodBuilder 接入、#if UNITY_5_3_OR_NEWER 两条分支、自定义步骤的抽象成员与状态槽 API、触发源契约与绑定扩展、以及 public/internal 边界（Demo 用独立程序集编译，误用 internal 成员会立刻报错）。

9关键文件索引

配套材料

10本期没做的 / 已知边界