# ShrinkTutorial

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

共享教程状态与步骤运行时位于 `DotNet~`；Godot 4.6 的 `Resource`、`Control` 遮罩和输入适配位于 `Godot~`。Godot 项目安装 `ShrinkSDK.Tutorial.Godot`。

- 通过真实点击完成步骤，而不是纯文案翻页。
- 支持静态路径目标和动态锚点目标。
- 遮罩只屏蔽无关区域，目标区域可继续点击。
- 教程内容由 `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");
```

如果项目要求所有 UI 预先存在于场景，可在 `ShrinkTutorialManager` 上显式绑定
`Canvas Override`、`Mask Override` 与 `Dialog Override`，并关闭
`Allow Runtime Ui Fallback`。`ShrinkTutorialDialog` 的内容文本、箭头与跳过按钮也要
在场景中序列化绑定；该模式不会在运行时创建教程 UI。

也可以给入口物体挂 `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(...)`。