ShrinkTutorial

一个面向 Unity 2022.3+ 的互动式引导系统，重点解决这几件事：

通过真实点击完成步骤，而不是纯文案翻页。
支持静态路径目标和动态锚点目标。
遮罩只屏蔽无关区域，目标区域可继续点击。
教程内容由 ScriptableObject 驱动，运行时由 ShrinkTutorialManager 调度。

当前能力

能力	说明
数据驱动教程	`ShrinkTutorialData + ShrinkTutorialStep + ShrinkTutorialDatabase`
运行时调度	`ShrinkTutorialManager` 负责排队、前置检查、逐步执行、完成/跳过持久化
目标定位	支持 `Hierarchy Path` 与 `AnchorId`
完成条件	`ClickTarget / AnyClick / CustomEvent / Auto`
动态目标等待	`waitForTarget + waitTimeout`
默认 UI	独立 Overlay Canvas、遮罩挖洞、提示框、箭头、跳过按钮
编辑器入口	`ShrinkSDK/引导/教程编辑器`、`ShrinkSDK/引导/重置教程进度`

暂未覆盖

DragToTarget 目前按自定义事件完成处理，尚未内建拖拽命中判定。
圆形高亮当前以圆形点击判定为主，视觉挖洞仍按外接矩形处理。
本地化只提供接口 IShrinkTutorialLocalizationProvider，不内置具体表系统。

目录结构

Assets/Modules/ShrinkTutorial/
├── Runtime/
│   ├── Core/
│   ├── Storage/
│   ├── Trigger/
│   └── UI/
└── Editor/

快速接入

1. 创建配置资产

通过菜单创建：

Assets -> Create -> ShrinkTutorial -> Settings
Assets -> Create -> ShrinkTutorial -> Tutorial Database
Assets -> Create -> ShrinkTutorial -> Tutorial Data

然后把教程资产挂到 ShrinkTutorialDatabase，再把数据库挂到 ShrinkTutorialSettings.database。

2. 配置步骤

常见配置建议：

targetMode = Path：用于静态 UI / 场景对象。
targetMode = AnchorId：用于运行时实例化对象。
completeCondition = ClickTarget：最常用的真实点击引导。对 UI 目标会在指针释放且 EventSystem 射线真实命中目标后再过步，避免遮罩或浮层导致“业务没执行但教程已前进”。
completeCondition = CustomEvent：业务代码在成功后调用 CompleteStep(...)。

3. 触发教程

可以直接调用：

ShrinkTutorialManager.Instance.StartTutorial("tut.inventory.open");

也可以给入口物体挂 ShrinkTutorialTrigger，在 OnEnable 首次可见时自动触发。

4. 动态对象锚点

给动态实例化对象挂 ShrinkTutorialAnchor，填写 anchorId，步骤里选择 AnchorId 模式即可。

外部接口

ShrinkTutorialManager.Instance.StartTutorial("tutorial.id");
ShrinkTutorialManager.Instance.CompleteStep("event_name");
ShrinkTutorialManager.Instance.SkipCurrent();
ShrinkTutorialManager.Instance.PauseCurrent();
ShrinkTutorialManager.Instance.ResumeCurrent();

状态查询：

var done = ShrinkTutorialManager.Instance.HasCompleted("tutorial.id");
var skipped = ShrinkTutorialManager.Instance.HasSkipped("tutorial.id");
var running = ShrinkTutorialManager.Instance.IsRunning;

本地化接入

如果项目已有本地化系统，实现下面接口后注入即可：

public sealed class MyTutorialLocalizer : IShrinkTutorialLocalizationProvider
{
    public bool TryResolve(string key, out string text)
    {
        text = MyLocalization.Get(key);
        return !string.IsNullOrWhiteSpace(text);
    }
}

ShrinkTutorialLocalization.Provider = new MyTutorialLocalizer();

调试建议

先确认 ShrinkTutorialSettings.database 已正确赋值。
如果目标是动态对象，优先检查 ShrinkTutorialAnchorRegistry 是否已注册该 anchorId。
如果步骤目标当前还没显示出来，不要把它视为异常；Path 目标在 activeInHierarchy == false 时现在会继续等待，而不是提前显示到隐藏控件上。
如果步骤走 CustomEvent，确认业务代码在真正完成后再调用 CompleteStep(...)。

4.0 KiB Raw Blame History