动作序列 · 使用说明

〇它是干什么的

先花 30 秒建立直觉，再动手写。

RevSequencePlayer.Play(                                // ① 播放（Unity 里连"每帧驱动"都不用管）
    RevSequence.Create("开宝箱")                         // ② 开一张清单（名字会出现在日志里）
        .Do("播音效", ctx => Sound.Play("Box_Open"))      // ③ 一步一步写：Do = 立刻做一件事
        .Wait(1f)                                     //    Wait = 停一会儿
        .WaitUntil("等玩家点击", ctx => 点了, 15f));   //    WaitUntil = 等条件成立（带超时保护）

生活里它就长这样

游戏里的"开宝箱"是同一件事：

它解决什么问题（如果你现在是这样写代码的）

// 没有动作序列时，"先做 A、等条件、再做 B"通常长这样：
private bool _clicked;          // ← 为了"等玩家点" 得先加个字段
private float _timer;           // ← 为了"停 1 秒" 再加个字段
private int _step;              // ← 为了记住"走到第几步" 还得加个字段

void Update() {
    switch (_step) {
        case 0: PlaySound("Box_Appear"); _step = 1; break;
        case 1: if (_clicked) { PlaySound("Box_Open"); _step = 2; } break;
        // …再加需求就要再塞分支，而且"取消/回收"没地方放
    }
}

用动作序列写，上面那一坨变成：

RevSequence.Create("开宝箱")
    .Do("出现音效", ctx => PlaySound("Box_Appear"))
    .WaitUntil("等玩家点击", ctx => _clicked)
    .Do("开箱音效", ctx => PlaySound("Box_Open"))
    .Do("通知门",   ctx => ctx.Events.Publish(new ChestOpened()))
    .Build();

什么时候该用它 / 什么时候不该用

13 分钟跑起来

复制这一整段到任意脚本里，挂到场景任意物体上，运行就能看到日志。

using UnityEngine;
using Revolution;        // ← 框架的命名空间（忘了它会报"找不到 RevSequence"）

public sealed class MyFirstSequence : MonoBehaviour
{
    private void Start()
    {
        // ① 写清单（只写一次，写完存起来 —— 后面第 6 章坑 5 会讲为什么）
        RevSequenceDefinition flow = RevSequence.Create("我的第一个序列")
            .Do("打个招呼", ctx => Debug.Log("你好，动作序列！"))
            .Wait(1f)                                     // 停 1 秒（这 1 秒里游戏照常运行）
            .Do("再说一句", ctx => Debug.Log("1 秒过去了"))
            .Build();

        // ② 让它开始跑（不用你每帧喂时间，框架会自动创建驱动者；传 gameObject 后它被销毁时序列自动取消）
        flow.Play(gameObject);
    }
}

这几行分别是什么意思

把清单存起来（推荐从第一条序列就这么写）

清单是"不可变的"（定稿后不能改），所以它天生适合放进静态字段，写一次、用一辈子：

private static readonly RevSequenceDefinition Flow =      // ← 静态字段：整个游戏只构建一次
    RevSequence.Create("我的第一个序列")
        .Do("打个招呼", ctx => Debug.Log("你好"))
        .Wait(1f)
        .Build();

// 需要时随时播放（想播几次播几次，一份清单可以被多个玩家/多个对象同时使用）
Flow.Play(gameObject);

谁负责"每帧推进"（三种方式，挑一个）

2"我要做 X" 对照表

写业务时 90% 的情况都在下面这张表里 —— 找到你要的，照抄即可。

3五个最常用的写法（逐个讲透）

每个卡片都是"什么时候用 → 怎么写 → 要注意什么"。

.Do("播放音效", ctx => ctx.Get<ISoundService>()?.PostEvent("Play_Box_Open"))
.Do("打开奖励面板", ctx => UIManager.Open("RewardPanel"))
.Do("加金币", ctx => ctx.Get<IPlayerService>()?.AddGold(100))

// 等玩家点击（15 秒没点就放弃，并打一条告警）
.WaitUntil("等玩家点击", ctx => ctx.Get<IInputService>()?.ConsumeClick() == true, timeoutSeconds: 15f)

// 等相机推近到位（用业务服务的状态）
.WaitUntil("等镜头就位", ctx => ctx.Get<ICameraService>()?.IsArrived == true)

.DoBlocking("等角色走过去",
    execute:     ctx => ctx.Get<IMoveService>()?.MoveTo(target),
    isCompleted: ctx => ctx.Get<IMoveService>()?.IsArrived == true)

.Parallel("消失音效与飞行动画同时进行", p => p
    .Do("消失音效", ctx => ctx.Get<ISoundService>()?.PostEvent("Play_Disappear"))
    .Step(new MyFlyStep(duration: 0.35f)))      // 自定义步骤，见本节第 ⑥ 个卡片
// ↑ 两条都完成后，才继续后面的步骤

.Finally(f => f
    .Do("恢复镜头", ctx => ctx.Require<ICameraService>().Restore())
    .Do("回收特效", ctx => ctx.Require<IEffectService>().RecycleAll(ctx.Source)))

public sealed class MyFlyStep : RevStepBase
{
    private sealed class State { public float Duration; }

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

    public override void Execute(RevSequenceRun run, RevSequenceContext ctx)
        => GetOrCreateState<State>(run).Duration = 0.35f;     // ← 状态存这里，按"本次运行"隔离

    public override bool IsCompleted(RevSequenceRun run, RevSequenceContext ctx)
        => run.Elapsed >= GetState<State>(run).Duration;
}

4谁来启动它：三种触发方式

清单写好了，接下来要回答"什么时候开始跑"。

方式一：手动启动（最直接，够用一半场景）

// 点按钮、流程里走到某一步 —— 直接 Play 就行
ChestOpen.Play(gameObject);
//             ↑ source = "是谁触发的"（第 4.4 节会讲它为什么重要；它被销毁时序列自动取消）

方式二：玩家走进范围就播（区域触发）

框架不内置"范围检测"（每个项目检测方式不同：Unity 物理 / 自研网格 / 服务端下发），但把它接到序列上只要 8 行：

// ① 让触发物实现"触发源契约"：有人进来，就喊一声
public sealed class ChestZone : MonoBehaviour, RevITriggerSource
{
    public string Name => "宝箱区域";
    public event Action<RevTriggerSignal> Triggered;
    public void Dispose() => Triggered = null;          // 断开所有订阅

    // Unity 物理回调：谁走进来，就把"谁"喊出去
    private void OnTriggerEnter(Collider other)
        => Triggered?.Invoke(new RevTriggerSignal(other.gameObject, Name));
}

// ② 绑一下：这个区域触发 → 播这条序列（写在 Awake 里）
var zone = gameObject.AddComponent<ChestZone>();
_binding = RevSequencePlayer.Default.Bind(zone, GameSequences.ChestOpen);

// ③ 不需要时解绑（必须做，否则对象没了、回调还在被调用）
_binding.Dispose();

方式三：别的事件发生时启动（一行搞定）

// 场景：宝箱开了 → 门就该开（门这条序列被"宝箱开启"事件触发）
RevSequencePlayer.Default.BindEvents<ChestOpenedEvent>(
    RevSequencePlayer.Default.Events,      // 事件总线
    SlidingDoorOpen,                       // 要启动的序列
    e => e.Opener);                        // 从事件里取"是谁开的"

// 而"发事件"是这样发的（通常写在宝箱序列的最后一步）：
.Do("广播宝箱已开", ctx => ctx.Events.Publish(new ChestOpenedEvent(ctx.Source, uid)))

三种方式怎么选

4.4 防止"连点两次跑两遍"：并发策略

同一个玩家在极短时间内触发同一条序列（连点、快速进出区域），你希望怎样？框架给你三选一，写清单的时候声明：

RevSequence.Create("开宝箱", RevSequenceConcurrency.RejectPerSource)   // ← 第三个参数（不写就是 Free）
    .Do(...)
    .Build();

5中途取消：怎么停、怎么收拾

这是最容易被忽略、也最容易出事的一章。好消息是它只有两个 API。

5.1 什么时候会被取消（大多数时候不是你主动取消）

• 玩家点了关闭 / 中途退出；
• 切场景、断线重连 —— 触发者（Play 时传的 source）被 Destroy，框架会自动取消它的序列；
• 被"同源顶替"策略挤掉（第 4.4 节）；
• 某一步的代码抛了异常（框架打日志后按取消处理）；
• 你自己调了 Stop（比如玩家点了"取消加载"）—— 在步骤里 Stop 自己也行，后面的步骤不会再执行。

5.2 两个 API

// ① 存下句柄（Play 的返回值），想取消时用它
RevSequenceHandle handle = LoadingFlow.Play(player);

if (玩家点了取消) handle.Stop();                          // 取消这一条（走它的收尾）
if (切场景)        RevSequencePlayer.Default.StopAll();    // 全部取消（每条都走各自的收尾）

// ② 想知道它还在不在跑
if (handle.IsValid) Debug.Log("还在跑");

5.3 收尾：.Finally(...) 与 .OnCancel(...)

.Do("推近镜头", ctx => ctx.Require<ICameraService>().PushIn())
.WaitUntil("等对白结束", ctx => …, 15f)
.OnCancel(f => f
    .Do("回收生成的特效", ctx => ctx.Require<IEffectService>().RecycleAll(ctx.Source)))
.Finally(f => f
    .Do("恢复镜头与 HUD", ctx => ctx.Require<ICameraService>().Restore()))

.Do("生成特效", ctx => spawned = Effect.Spawn("Fx_Open"))
.Do("回收特效", ctx => Effect.Recycle(spawned))
// 玩家中途退出 → 回收那一步永远走不到 → 特效留在场上

.Do("生成特效", ctx => ctx.Require<IEffectService>().Spawn("Fx_Open", ctx.Source))
.Wait(1f)
.Finally(f => f.Do("回收特效", ctx => ctx.Require<IEffectService>().RecycleAll(ctx.Source)))

5.4 三种结束方式（对照表）

handle.Stop(runFinally: false) / StopAll(runFinally: false) 会显式跳过两种收尾。

6新手最容易白干的 6 个坑

每个坑都是"症状 → 原因 → 怎么改"。前两个坑占了新手问题的一大半。

var r = new RevSequenceRunner();
r.Play(Flow);   // 就没了 → 永远不动

Flow.Play(gameObject);
// 或
r.Play(Flow);  r.Tick(Time.deltaTime);

private float _start;   // 全天下共用一个

.DoBlocking("飞",
    ctx => _start = ctx.Elapsed,
    ctx => ctx.Elapsed - _start > 0.35f)
// 甲触发把 _start 改了 → 乙的进度被算错

// (a) 状态放业务服务里（推荐）
.DoBlocking("飞",
    ctx => fly.Begin(uid),
    ctx => fly.IsDone(uid))

// (b) 或写成 RevStepBase 用状态槽
//     见第 3 章第 ⑥ 个卡片

_runner.Play(RevSequence.Create("开宝箱",
        RevSequenceConcurrency.RejectPerSource)      // 声明了"只能一次"
    .Do(...).Build(), gameObject);
// 每次都是新实例 → 策略永远不命中

private static readonly RevSequenceDefinition ChestOpen =
    RevSequence.Create("开宝箱", RevSequenceConcurrency.RejectPerSource)
        .Do(...).Build();                             // 只构建一次

_runner.Play(ChestOpen, gameObject);                  // 反复播同一份 → 策略生效

7完整实战：宝箱开启全流程

把前面学的东西拼起来。这段代码包含：业务服务注入 · 清单 · 区域触发 · 事件接力 · 取消收尾，一共约 70 行。

7.1 先定义"业务服务"接口（框架不认识你的系统）

using UnityEngine;
using Revolution;

// 这些接口由你（业务）定义，实现也是你写 —— 框架完全不知道它们的存在
public interface ISoundService  { void Play(string eventName, object emitter = null); }
public interface IInputService  { bool ConsumeClick(); }
public interface IUIService     { void Open(string panel); void Close(string panel); }
public interface ISceneService  { void SetSlidingDoor(bool open); }

7.2 定义"事件"：宝箱开完要通知门

// 用 readonly struct：零分配，而且带什么字段由你决定
public readonly struct ChestOpenedEvent
{
    public readonly object Opener;      // 谁开的（会传给门那条序列）
    public readonly string ChestUid;
    public ChestOpenedEvent(object opener, string uid) { Opener = opener; ChestUid = uid; }
}

7.3 写两条清单（加载期构建一次）

public static class GameSequences
{
    private const string ChestUid = "chest_1601";

    // ① 开宝箱：出现音效 → 等点击 → 开箱音效 → 弹面板 → 通知门
    public static readonly RevSequenceDefinition ChestOpen =
        RevSequence.Create("次元\\宝箱开启", RevSequenceConcurrency.RejectPerSource)   // 只能开一次
            .Do("出现音效",     ctx => Sound(ctx)?.Play("Play_Box_Appear", ctx.Source))
            .WaitUntil("等玩家点击",
                       ctx => ctx.Get<IInputService>()?.ConsumeClick() == true,
                       timeoutSeconds: 15f)                                  // 15 秒没点就放弃并告警
            .Do("开箱音效",     ctx => Sound(ctx)?.Play("Play_Box_Open"))
            .Do("弹出奖励面板", ctx => ctx.Get<IUIService>()?.Open("RewardPanel"))
            .Do("通知门：可以开了", ctx => ctx.Events.Publish(new ChestOpenedEvent(ctx.Source, ChestUid)))
            .OnCancel(f => f.Do("收起面板", ctx => ctx.Get<IUIService>()?.Close("RewardPanel")))  // 取消也要收
            .Build();

    // ② 开门：被上面那条的事件触发（顺序里没写它，是事件接力的）
    public static readonly RevSequenceDefinition SlidingDoorOpen =
        RevSequence.Create("次元\\宝箱门开启", RevSequenceConcurrency.ReplacePerSource)
            .Do("滑门音效", ctx => Sound(ctx)?.Play("Play_Door_Slide"))
            .Do("滑门打开", ctx => ctx.Get<ISceneService>()?.SetSlidingDoor(true))
            .Build();

    private static ISoundService Sound(RevSequenceContext ctx) => ctx.Get<ISoundService>();
}

7.4 接上触发：玩家走进范围 → 开宝箱 → 门自动开

// 区域触发源：谁走进来，喊一声（换成你自己的距离检测 / 服务端下发也一样）
public sealed class ChestZone : 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));
}

public sealed class ChestDemo : MonoBehaviour
{
    private RevSequenceRunner _runner;
    private IDisposable _zoneBinding, _doorBinding;

    private void Awake()
    {
        _runner = RevSequencePlayer.Default;

        // ① 注入业务服务（★ 泛型参数要写接口类型，不然步骤里 ctx.Get<IXxx>() 取不到）
        _runner.Services
            .Add<ISoundService>(new MySoundService())
            .Add<IInputService>(new MyInputService())
            .Add<IUIService>(new MyUIService())
            .Add<ISceneService>(new MySceneService());

        // ② 区域触发 → 开宝箱清单（AddComponent 出来的就是上面那个实现接口的触发源）
        var zone = gameObject.AddComponent<ChestZone>();
        _zoneBinding = _runner.Bind(zone, GameSequences.ChestOpen);

        // ③ 宝箱开完 → 门自动开（事件接力，一行）
        _doorBinding = _runner.BindEvents<ChestOpenedEvent>(
            _runner.Events, GameSequences.SlidingDoorOpen, e => e.Opener);
    }

    private void OnDestroy()
    {
        // ★ 注册什么就反注册什么（否则对象没了、回调还在）
        _zoneBinding?.Dispose();
        _doorBinding?.Dispose();
    }
}

7.5 这段代码用到了前面哪几章

8怎么确认它真的在跑 / 出问题怎么查

好消息：不用你自己加日志，框架已经打好了。

8.1 先看 Console：出问题框架会主动告诉你

框架的日志走 RevLog（tag = ActionSequence，要静音就 RevLog.MuteTag("ActionSequence")），每条都写明哪条序列、第几步、步骤名：

另外两个观察口子：

// 回调：想统计什么就在这里记（订阅者抛异常会被记日志，不影响收尾）
runner.RunFinished += run => Debug.Log($"[序列] {run} 结束（{run.Status}，{run.Elapsed:F2}s）");

// 句柄与引擎：还在不在跑 / 现在有几条在跑
if (handle.IsValid) …
Debug.Log(RevSequencePlayer.Default.ActiveCount);

• 要「每步流水」：.Log("走到开门这一步了")；步骤名就是你的路标（省略名字时日志里显示"文件名:行号"）。

8.2 三种典型问题，先看哪里

9一页速查卡

打印出来贴在显示器旁边，写序列时不用回来翻文档。

写清单（Builder）

跑起来 / 停掉

触发 / 依赖注入

三条永远不要忘