游戏叙事与剧情 / 系统课时
处理异步表现带来的等待
处理异步表现带来的等待
动画、镜头和界面过渡往往需要多个帧才能完成。如果 Yarn 命令一触发就立即返回,下一句对白会提前出现。本课用一个可等待的界面淡出命令,让 DialogueRunner 在表现结束前暂停推进。
学习目标
- 识别“触发即可返回”和“必须等待完成”的表现命令
- 用返回
IEnumerator的命令处理器暂停 Yarn 对话 - 验证下一句对白只在异步表现结束后继续
为什么普通命令会抢跑
对话脚本通常按“命令完成后继续”理解流程。问题在于,如果处理器只是调用 StartCoroutine 或触发 Animator,然后自己立刻返回,DialogueRunner 会认为命令已经结束,后续台词就会马上继续。
正确做法是让命令处理器本身返回一个 Yarn Spinner 能等待的异步结果。Unity 集成支持可等待的协程形式,例如 IEnumerator 或 Coroutine;当前版本也能等待受支持的任务类型。核心不是“用了异步 API”,而是“把完成信号返回给 DialogueRunner”。

写一个会被对话等待的命令
下面的组件注册 fade_panel。它把 CanvasGroup.alpha 在指定时长内插值到目标值,并且整个协程直接作为命令结果返回给 DialogueRunner。
using System.Collections;
using UnityEngine;
using Yarn.Unity;
public sealed class DialoguePresentationCommands : MonoBehaviour
{
[SerializeField] private DialogueRunner dialogueRunner;
[SerializeField] private CanvasGroup panel;
private void Awake()
{
dialogueRunner.AddCommandHandler<float, float>("fade_panel", FadePanel);
}
private IEnumerator FadePanel(float targetAlpha, float duration)
{
targetAlpha = Mathf.Clamp01(targetAlpha);
duration = Mathf.Max(0f, duration);
float startAlpha = panel.alpha;
if (duration == 0f)
{
panel.alpha = targetAlpha;
yield break;
}
float elapsed = 0f;
while (elapsed < duration)
{
elapsed += Time.unscaledDeltaTime;
float progress = Mathf.Clamp01(elapsed / duration);
panel.alpha = Mathf.Lerp(startAlpha, targetAlpha, progress);
yield return null;
}
// 收尾时写入精确目标值,避免浮点插值留下微小误差。
panel.alpha = targetAlpha;
}
}预期结果
调用 fade_panel 0 0.35 后,面板会在约 0.35 秒内淡出。
在协程结束前,DialogueRunner 不会继续交付下一条对话内容。这里使用 Time.unscaledDeltaTime,即使游戏通过 Time.timeScale = 0 暂停,UI 过渡仍能推进。如果你的表现应该跟随游戏时间,则改用 Time.deltaTime。
在脚本中验证等待顺序
下面是片段示例。运行时先显示第一句,然后执行淡出;只有命令结束后,最后一句才会进入对话展示流程。
title: FadeExample
---
Guide: 我们先把旧面板收起来。
<<fade_panel 0 0.35>>
Narrator: 面板淡出完成后,这句才会出现。
===预期结果
先出现 Guide 台词。
随后面板开始淡出,约 0.35 秒内不会进入下一句。
淡出结束后,Narrator 台词才出现。同样的结构可以用于镜头移动、角色走位、非循环动画或 UI 转场:命令开始表现,持续等待,最后明确结束。等待条件最好与真正的完成状态绑定,而不是随意写一个固定延时。
避免把异步操作变成失控后台任务
最常见的错误是命令返回 void,内部却自行启动协程。这样表现仍在运行,但 Yarn 已经继续执行。另一个风险是协程没有终止条件,例如等待一个永远不会到达的动画状态,此时整个对话会永久卡住。
当一个表现动作会影响下一句对白的时机时,就把“完成”作为命令的一部分返回给 DialogueRunner;只有真正无需等待的音效触发、埋点等瞬时动作,才适合立即返回。