117 lines
4.0 KiB
Markdown
117 lines
4.0 KiB
Markdown
# 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`，不内置具体表系统。
|
|
|
|
## 目录结构
|
|
|
|
```text
|
|
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. 触发教程
|
|
|
|
可以直接调用：
|
|
|
|
```csharp
|
|
ShrinkTutorialManager.Instance.StartTutorial("tut.inventory.open");
|
|
```
|
|
|
|
也可以给入口物体挂 `ShrinkTutorialTrigger`，在 `OnEnable` 首次可见时自动触发。
|
|
|
|
### 4. 动态对象锚点
|
|
|
|
给动态实例化对象挂 `ShrinkTutorialAnchor`，填写 `anchorId`，步骤里选择 `AnchorId` 模式即可。
|
|
|
|
## 外部接口
|
|
|
|
```csharp
|
|
ShrinkTutorialManager.Instance.StartTutorial("tutorial.id");
|
|
ShrinkTutorialManager.Instance.CompleteStep("event_name");
|
|
ShrinkTutorialManager.Instance.SkipCurrent();
|
|
ShrinkTutorialManager.Instance.PauseCurrent();
|
|
ShrinkTutorialManager.Instance.ResumeCurrent();
|
|
```
|
|
|
|
状态查询：
|
|
|
|
```csharp
|
|
var done = ShrinkTutorialManager.Instance.HasCompleted("tutorial.id");
|
|
var skipped = ShrinkTutorialManager.Instance.HasSkipped("tutorial.id");
|
|
var running = ShrinkTutorialManager.Instance.IsRunning;
|
|
```
|
|
|
|
## 本地化接入
|
|
|
|
如果项目已有本地化系统，实现下面接口后注入即可：
|
|
|
|
```csharp
|
|
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(...)`。
|