Phaser 新手引导导演：步骤条件、遮罩和跳过逻辑要尊重玩家

新手引导不是把玩家的手按在按钮上

很多 Phaser 游戏的新手引导会犯一个错误：每一步都弹遮罩，强制玩家点指定按钮，不点就不能继续。短期看完成率高，长期看玩家烦。尤其是动作、策略、解谜类游戏，玩家需要理解为什么操作，而不是只完成点击。好的新手引导像导演：在合适时机给提示、限制危险操作、允许玩家试错、必要时跳过，并且不会因为版本更新或 UI 改动就卡死。

新手引导系统的核心是步骤条件和目标锚点。步骤描述“什么时候出现”“指向哪个 UI 或世界对象”“允许哪些输入”“完成条件是什么”“失败或跳过后怎么恢复”。Phaser Scene 负责渲染遮罩、箭头、文本和高亮，但引导状态应该由 TutorialDirector 管理。不要把引导逻辑写进每个按钮的点击回调里，否则 UI 一改，整条引导就碎。

步骤要基于条件而不是固定时间

新手引导最怕固定延迟。比如“进入场景 2 秒后提示点击背包”，但低端机资源还没加载完，背包按钮不存在；或者玩家已经自己打开背包，提示才出现。步骤应该由条件触发：场景 ready、按钮可见、玩家未完成某任务、背包里有新物品、战斗已暂停。完成也应由条件判断：玩家打开了背包、装备了武器、击败了训练怪，而不是点击了某个坐标。

条件系统可以复用游戏事件和状态查询。Director 每帧或按事件检查当前步骤是否可开始和可完成。这样引导更稳，也更容易处理回归玩家。玩家已经学会移动，就不要再强制他看移动教程。

flowchart TD
  A["TutorialDirector 读取玩家教学进度"] --> B["StepSelector 找到下一个候选步骤"]
  B --> C["ConditionEvaluator 检查场景和玩家状态"]
  C --> D["TutorialOverlay 高亮目标、显示文案"]
  D --> E["InputGate 限制或放行输入"]
  E --> F["玩家完成操作"]
  F --> G["ProgressStore 标记步骤完成"]
  G --> B
  D --> H["Skip / Timeout / SceneChanged"]
  H --> I["RecoveryPolicy 恢复输入和 UI"]

遮罩要帮助理解，不要破坏布局

Phaser 可以用 Graphics 画半透明遮罩，再挖出目标区域。也可以用 DOM Overlay 做更复杂的文本和按钮。无论哪种方式，遮罩都要适配屏幕尺寸和 UI 缩放。目标按钮在不同分辨率位置不同，不能用固定坐标。最好让 UI 组件注册 tutorial anchor，比如 inventory.button.open，Director 根据 anchor 查询当前 bounds。

高亮区域要留足边距，箭头不要挡住按钮，文本不要遮挡关键画面。移动端上，底部按钮容易被手指挡住，引导文本可以放上方。不要在战斗中用大段文字遮住敌人。引导是为了降低理解成本，不是制造新的视觉障碍。

输入锁定要最小化

有些步骤需要限制输入，比如要求玩家点击升级按钮。但锁定范围要尽量小。不要把全屏都锁死，只允许目标按钮响应；如果玩家点其他区域，可以轻微提示而不是完全无反馈。动作教学中，最好允许玩家自由移动，只在危险操作上加保护。过度锁定会让玩家觉得游戏在替他玩。

输入锁定还要有恢复机制。Scene 切换、弹窗关闭、广告播放、浏览器失焦都可能打断引导。如果锁没有释放，玩家会卡死。InputGate 应该使用 token 或栈管理，某个步骤结束时释放自己的锁；场景销毁时强制清理该场景的锁。

一个步骤模型

下面的代码展示步骤配置和 Director 的核心思路。条件和动作可以映射到项目内注册表。

interface TutorialStep {
  id: string;
  anchorId: string;
  textKey: string;
  startWhen: string[];
  completeWhen: string[];
  allowedInputs: string[];
  skippable: boolean;
}

export class TutorialDirector {
  private current?: TutorialStep;

  constructor(
    private readonly steps: TutorialStep[],
    private readonly progress: Set<string>,
    private readonly conditions: TutorialConditionRegistry,
  ) {}

  update() {
    if (this.current && this.conditions.all(this.current.completeWhen)) {
      this.progress.add(this.current.id);
      this.current = undefined;
    }
    if (!this.current) {
      this.current = this.steps.find((step) =>
        !this.progress.has(step.id) && this.conditions.all(step.startWhen),
      );
    }
    return this.current;
  }
}

这个模型把步骤选择和渲染分开。Overlay 拿到当前 step 后再找 anchor、显示文案和输入规则。条件注册表可以查询任务、UI、场景、背包、战斗状态。后续新增步骤时，不需要改 Scene 代码。

跳过不是失败

玩家可能是老玩家、换设备、重新安装、看过教程。跳过按钮应该存在，尤其是长流程。跳过后要标记哪些步骤已完成，哪些关键奖励已发放，哪些系统已解锁。不能跳过后玩家没有拿到基础武器，也不能跳过后卡在“请点击不存在按钮”。跳过是一条正式路径，不是调试后门。

回归玩家也要处理。版本更新后新增功能，需要局部引导；老玩家不应重看完整新手教程。可以按系统维度保存教学进度：移动、战斗、背包、合成、活动。新增合成系统时，只触发合成教程。教学进度进入存档或账号数据，避免换场景丢失。

文案要短而具体

引导文案不要写成说明书。每一步只解释当前动作和意图：“拖动摇杆移动到亮光处”，比“你可以通过左下角虚拟摇杆控制角色移动”更直接。复杂系统可以分多步，每步只引导一个概念。文案要支持本地化，长度变化会影响布局，所以 Overlay 要能自适应换行。

如果教程涉及奖励或消耗，必须写清楚。比如“点击强化会消耗 20 金币”，不要为了流畅隐藏成本。玩家在教程中被强制消耗资源，会很容易不满。可以使用教程专用免费强化或返还材料。

调试工具和统计

引导系统必须有调试面板：当前步骤、开始条件、完成条件、anchor 是否存在、输入锁状态、已完成步骤。还要能重置某个步骤、跳到某个步骤、模拟新玩家。没有这些工具，调试新手流程会非常痛苦。

数据上，记录每一步展示、完成、跳过、超时和退出。某一步退出率高，可能是文案不清楚、目标按钮不明显、条件错误或奖励不吸引。不要只看整体新手完成率。分步骤漏斗能告诉你真正的问题在哪。

上线前检查清单

确认步骤基于条件，不依赖固定坐标和固定延迟；确认 UI 组件提供 anchor；确认遮罩适配不同分辨率；确认输入锁有 token 并能释放；确认跳过流程发放必要奖励和解锁；确认回归玩家不会重看完整教程；确认文案短且可本地化；确认开发面板能显示条件和 anchor；确认每步都有埋点；确认场景切换、失焦和弹窗不会卡住引导。

新手引导的目标不是证明玩家按过每个按钮，而是让玩家建立信心。Phaser 让遮罩、箭头和高亮很容易实现，但真正的质量来自步骤条件、输入边界和恢复策略。尊重玩家的节奏，新手流程才不会成为第一道流失关卡。

世界对象引导和 UI 引导不同

UI 引导通常锚定按钮，世界对象引导则锚定场景里的角色、宝箱、敌人或地块。世界对象可能移动、被销毁、还没加载，锚点查询必须处理这些情况。如果目标敌人已经被玩家提前击败，就不应继续提示“攻击这只敌人”；Director 应检测完成条件并跳过或进入替代步骤。世界对象引导最好使用对象 id 或标签，而不是保存 Sprite 引用。

相机也要参与世界对象引导。目标不在屏幕内时，可以先引导玩家移动或让相机轻微提示方向；不要直接在屏幕边缘放一个箭头就要求点击。对于自由探索游戏，引导可以更松：在小地图标记区域，玩家到达后再出现具体提示。过度控制相机会破坏探索感。

奖励和教学节奏

教学步骤可以配合小奖励，但奖励不是贿赂玩家点按钮。每个奖励应强化刚学到的系统：学会战斗后给一件武器，学会合成后给下一次合成材料，学会邮件后领取一封欢迎信。奖励发放同样要幂等，步骤完成事件可能因为重试触发多次。TutorialRewardService 记录 stepId 是否已发放，避免重复。

教学节奏要留空。连续 20 个步骤会让玩家疲劳。可以把新手流程拆成几个教学岛：移动和战斗在第一局，背包在获得第一件装备时，合成在回到基地时，活动入口等玩家完成核心循环后再介绍。玩家已经有目标时，不要突然插入非必要系统介绍。

A/B 测试和配置风险

新手引导经常做 A/B 测试：文案不同、步骤顺序不同、是否强制不同。测试配置必须和存档进度兼容。玩家今天在 A 组完成前三步，明天被切到 B 组，不能重新卡在已完成系统。最稳妥的是步骤 id 稳定，实验只改变文案、可跳过性或触发时机；若步骤结构变化，需要迁移规则。

配置错误要能降级。目标 anchor 不存在时，开发环境报错，正式环境跳过该步骤并上报。条件引用未知字段时也要安全处理。新手引导卡死比少一个提示更严重。宁可跳过有问题的步骤，也不要让玩家停在不可点击遮罩下。

引导和无障碍

引导系统也要考虑无障碍。文本要能被放大，关键提示不要只靠颜色，遮罩透明度不能低到看不清目标。移动端上，手指会遮挡目标按钮，可以把箭头和说明放在目标上方或侧边。若玩家开启减少动态效果，箭头动画和闪烁高亮应降低频率。

键盘和手柄玩家也需要引导。不要只写“点击这里”，可以根据当前输入方式显示“按 E 互动”或“按 A 确认”。InputService 识别最近输入设备，TutorialOverlay 使用对应文案。Phaser 游戏常同时支持桌面和移动，这个细节会显著影响专业度。

教学失败也要有恢复路径

玩家可能在教学中做了意外操作：卖掉教程物品、提前击杀目标、离开区域、关闭浏览器。每个关键步骤都需要 recovery policy。教程物品被卖掉，可以补发一次；目标不存在，可以跳过该战斗教学；玩家离开区域，可以暂停步骤直到回来。没有恢复策略的引导，只能在理想路径上工作，一上线就会被真实玩家打破。

跨场景引导的状态传递

有些引导会跨多个 Scene：大厅点击任务，进入关卡，完成战斗，再回到奖励页。Director 不应绑定单个 Scene 生命周期，而应由全局服务保存当前教程阶段。每个 Scene 启动时注册自己的 anchor 和条件，离开时注销。当前步骤如果依赖未注册 anchor，就等待或切换到过渡提示。这样引导不会因为场景重建而丢失。

跨场景步骤还要处理加载失败。玩家点击任务后关卡加载失败，教程不能继续显示“击败训练怪”。它应回到可恢复状态，提示重试或跳过。引导系统越靠近主流程，越要像任务系统一样可靠。

所有恢复路径都应写入埋点，否则团队只会看到玩家流失，看不到具体卡在哪个步骤。

这些埋点还应包含设备、输入方式和场景名，便于定位移动端特有问题。