feat: add NuGet and Godot distribution

.gitea/workflows/publish-nuget.yml

@@ -0,0 +1,52 @@
+name: Publish NuGet packages
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    env:
+      NUGET_AUTH_TOKEN: ${{ secrets.SHRINKSDK_PACKAGE_TOKEN }}
+    steps:
+      - name: Checkout tagged source
+        uses: actions/checkout@v4
+
+      - name: Set up .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '8.0.x'
+
+      - name: Validate tag and pack projects
+        env:
+          GITEA_REF: ${{ gitea.ref }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          tag="${GITEA_REF#refs/tags/}"
+          version="$(node -p "require('./package.json').version")"
+          test "$tag" = "v$version"
+          mkdir -p packages
+          mapfile -d '' projects < <(find DotNet~ Godot~ -type f -name '*.csproj' -print0 2>/dev/null || true)
+          test "${#projects[@]}" -gt 0
+          for project in "${projects[@]}"; do
+            dotnet restore "$project" --configfile NuGet.Config
+            dotnet pack "$project" --configuration Release --no-restore --output "$PWD/packages" --include-symbols --include-source
+          done
+          find packages -maxdepth 1 -name '*.nupkg' -type f | grep -q .
+
+      - name: Publish packages
+        shell: bash
+        run: |
+          set -euo pipefail
+          : "${NUGET_AUTH_TOKEN:?SHRINKSDK_PACKAGE_TOKEN is required}"
+          dotnet nuget push 'packages/*.nupkg' --api-key "$NUGET_AUTH_TOKEN" --source https://git.crash.work/api/packages/ShrinkSDK/nuget/index.json --skip-duplicate
+          if compgen -G 'packages/*.snupkg' > /dev/null; then
+            dotnet nuget push 'packages/*.snupkg' --api-key "$NUGET_AUTH_TOKEN" --source https://git.crash.work/api/packages/ShrinkSDK/nuget/index.json --skip-duplicate
+          fi

.gitea/workflows/publish.yml

@@ -15,22 +15,39 @@ jobs:
     env:
       NODE_AUTH_TOKEN: ${{ secrets.SHRINKSDK_PACKAGE_TOKEN }}
     steps:
-      - name: Fetch tagged revision
+      - name: Fetch exact tagged release archive
+        env:
+          GITEA_REF: ${{ gitea.ref }}
         shell: bash
         run: |
           set -eu
-          ref="${{ gitea.sha }}"
-          test -n "$ref"
-          git init .
-          git remote add origin "https://git.crash.work/ShrinkSDK/ShrinkTutorial.git"
-          git fetch --depth=1 origin "$ref"
-          git checkout --detach FETCH_HEAD
+          tag="${GITEA_REF#refs/tags/}"
+          case "$tag" in
+            v[0-9]*) ;;
+            *) echo "Expected a version tag ref, got: $GITEA_REF" >&2; exit 1 ;;
+          esac
+          export SHRINKSDK_ARCHIVE_URL="https://git.crash.work/ShrinkSDK/ShrinkTutorial/archive/${tag}.tar.gz"
+          node --input-type=module <<'NODE'
+          import { writeFile } from 'node:fs/promises';
+
+          const response = await fetch(process.env.SHRINKSDK_ARCHIVE_URL);
+          if (!response.ok) {
+            throw new Error(`Release archive download failed: ${response.status} ${response.statusText}`);
+          }
+
+          await writeFile('release.tar.gz', new Uint8Array(await response.arrayBuffer()));
+          NODE
+          mkdir release
+          tar -xzf release.tar.gz --strip-components=1 -C release
+          rm -f release.tar.gz
+          printf '%s' "$tag" > release/.shrink-sdk-release-tag
 
       - name: Validate immutable release version
         shell: bash
         run: |
           set -eu
-          tag="$(git describe --exact-match --tags HEAD)"
+          cd release
+          tag="$(cat .shrink-sdk-release-tag)"
           version="$(node -p "require('./package.json').version")"
           test "$tag" = "v$version"
           npm pack --dry-run
@@ -40,10 +57,11 @@ jobs:
         run: |
           set -eu
           : "${NODE_AUTH_TOKEN:?SHRINKSDK_PACKAGE_TOKEN is required}"
+          cd release
           npmrc="$HOME/.npmrc"
           cleanup() { rm -f "$npmrc"; }
           trap cleanup EXIT
           printf '%s\n' \
             'registry=https://git.crash.work/api/packages/ShrinkSDK/npm/' \
             '//git.crash.work/api/packages/ShrinkSDK/npm/:_authToken=${NODE_AUTH_TOKEN}' > "$npmrc"
-          npm publish --registry=https://git.crash.work/api/packages/ShrinkSDK/npm/
+          npm publish --registry=https://git.crash.work/api/packages/ShrinkSDK/npm/

.gitea/workflows/unity-verify.yml

@@ -26,12 +26,17 @@ jobs:
         shell: bash
         run: |
           set -eu
+          machine_id_file="/root/.local/share/unity3d/Unity/.machine-id"
+          if test -s "$machine_id_file"; then
+            cat "$machine_id_file" > /etc/machine-id
+            echo "Unity machine identity restored"
+          fi
+          git config --global url."https://ghfast.top/https://github.com/".insteadOf "https://github.com/"
           unity_bin="$(command -v unity-editor || command -v unity || command -v Unity || true)"
           test -n "$unity_bin"
           "$unity_bin" \
             -batchmode \
             -nographics \
-            -quit \
             -projectPath "$PWD/Development~/UnityProject" \
             -runTests \
             -testPlatform EditMode \

.gitignore

@@ -8,3 +8,11 @@
 /Tools~/**/[Oo]bj/
 *.user
 *.DotSettings.user
+/DotNet~/**/[Bb]in/
+/DotNet~/**/[Oo]bj/
+/Godot~/**/[Bb]in/
+/Godot~/**/[Oo]bj/
+/artifacts/
+/packages/
+!DotNet~/**/*.csproj
+!Godot~/**/*.csproj

.npmignore

@@ -6,3 +6,7 @@ Tools~/
 *.sln
 *.user
 *.DotSettings.user
+DotNet~/
+Godot~/
+NuGet.Config
+Directory.Build.props

CHANGELOG.md

@@ -1,6 +1,15 @@
 # Changelog
 
-## Unreleased
+## 0.1.4
+
+- `ClickTarget` 对 UI Button 和显式 `ShrinkTutorialAnchor` 改为点击事件驱动，不再依赖轮询鼠标按下、抬起的帧时序；非 UI 目标保留原有指针检测。
+
+## 0.1.3
+
+- 修复 `ClickTarget` 在目标按钮点击后立即打开、关闭或替换 UI 时误判未命中的问题；现在按下时确认原目标，松开时按按下时的目标区域完成步骤。
+- 支持在场景中显式绑定教程 Canvas、遮罩和提示框，并可关闭运行时 UI 生成。
+
+## 0.1.2
 
 - 修复 `ClickTarget` 对 UI 目标过早在按下阶段完成的问题，改为等待指针释放并确认 EventSystem 射线真实命中目标后再过步。
 - 修复隐藏中的 `Path` 目标仍被教程当作可用目标的问题；现在 inactive 目标会继续等待，不会把提示框提前挂到尚未显示的控件上。
@@ -8,6 +17,10 @@
 - 修复教程结束或 `maskShape=None` 步骤下遮罩仍继续绘制/拦截的问题；现在无高亮时蒙版会完全隐藏。
 - 修复 `ShrinkTutorialSample` 在前一次演示完成后下次 Play 不再显示教程的问题；样例现在会在启动时清掉自身教程进度再重新播放。
 
+## 0.1.1
+
+- 声明 `JsonUtility` 所需的 Unity JSON Serialize 模块，使包可在最小消费者项目中独立解析与编译。
+
 ## 0.1.0
 
 - 初始版本。

Development~/UnityProject/Packages/manifest.json

@@ -11,5 +11,8 @@
   "dependencies": {
     "com.unity.test-framework": "1.1.33",
     "com.cneicy.shrink-tutorial": "file:../../.."
-  }
+  },
+  "testables": [
+    "com.cneicy.shrink-tutorial"
+  ]
 }

Directory.Build.props

@@ -0,0 +1,13 @@
+<Project>
+  <PropertyGroup>
+    <LangVersion>latest</LangVersion>
+    <Nullable>enable</Nullable>
+    <Deterministic>true</Deterministic>
+    <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
+    <Authors>ShrinkSDK</Authors>
+    <Company>ShrinkSDK</Company>
+    <RepositoryUrl>https://git.crash.work/ShrinkSDK</RepositoryUrl>
+    <IncludeSymbols>true</IncludeSymbols>
+    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
+  </PropertyGroup>
+</Project>

DotNet~/Runtime/ShrinkTutorialCore.cs

@@ -0,0 +1,76 @@
+using System;
+using System.Collections.Generic;
+
+namespace ShrinkTutorial;
+
+[Serializable]
+public sealed class ShrinkTutorialStep
+{
+    public string StepId = string.Empty;
+    public string Title = string.Empty;
+    public string Body = string.Empty;
+    public string Target = string.Empty;
+    public ShrinkTutorialTargetMode TargetMode;
+    public ShrinkTutorialCompleteCondition CompleteCondition = ShrinkTutorialCompleteCondition.ClickTarget;
+    public ShrinkTutorialDialogAnchor DialogAnchor = ShrinkTutorialDialogAnchor.Auto;
+    public ShrinkTutorialMaskShape MaskShape = ShrinkTutorialMaskShape.Rect;
+    public string CustomEventName = string.Empty;
+    public bool BlockInputOutsideTarget = true;
+}
+
+[Serializable]
+public sealed class ShrinkTutorialData
+{
+    public string TutorialId = string.Empty;
+    public List<ShrinkTutorialStep> Steps = new();
+}
+
+public sealed class ShrinkTutorialRunner
+{
+    private readonly IShrinkTutorialStorage _storage;
+    private ShrinkTutorialProgress _progress;
+    public ShrinkTutorialRunner(IShrinkTutorialStorage storage)
+    {
+        _storage = storage ?? throw new ArgumentNullException(nameof(storage));
+        _progress = storage.Load() ?? new ShrinkTutorialProgress();
+    }
+    public ShrinkTutorialData Current { get; private set; }
+    public int StepIndex { get; private set; } = -1;
+    public ShrinkTutorialStep CurrentStep => Current != null && StepIndex >= 0 && StepIndex < Current.Steps.Count ? Current.Steps[StepIndex] : null;
+    public event Action<ShrinkTutorialStep> StepChanged;
+    public event Action<string> Completed;
+
+    public bool Start(ShrinkTutorialData tutorial)
+    {
+        if (tutorial == null || tutorial.Steps.Count == 0 || _progress.completedTutorials.Contains(tutorial.TutorialId)) return false;
+        Current = tutorial;
+        StepIndex = 0;
+        StepChanged?.Invoke(CurrentStep);
+        return true;
+    }
+
+    public bool CompleteStep(string customEventName = null)
+    {
+        var step = CurrentStep;
+        if (step == null) return false;
+        if (step.CompleteCondition == ShrinkTutorialCompleteCondition.CustomEvent &&
+            !string.Equals(step.CustomEventName, customEventName, StringComparison.Ordinal)) return false;
+        StepIndex++;
+        if (StepIndex < Current.Steps.Count) { StepChanged?.Invoke(CurrentStep); return true; }
+        _progress.completedTutorials.Add(Current.TutorialId);
+        _storage.Save(_progress);
+        var id = Current.TutorialId;
+        Current = null;
+        StepIndex = -1;
+        Completed?.Invoke(id);
+        return true;
+    }
+
+    public void Reset()
+    {
+        Current = null;
+        StepIndex = -1;
+        _storage.Reset();
+        _progress = new ShrinkTutorialProgress();
+    }
+}

DotNet~/ShrinkSDK.Tutorial.csproj

@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>netstandard2.1</TargetFramework>
+    <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
+    <AssemblyName>ShrinkTutorial.Runtime</AssemblyName>
+    <RootNamespace>ShrinkTutorial</RootNamespace>
+    <PackageId>ShrinkSDK.Tutorial</PackageId>
+    <Version>0.2.0</Version>
+    <Description>Engine-neutral ShrinkSDK tutorial state and step runtime.</Description>
+    <Nullable>disable</Nullable>
+  </PropertyGroup>
+  <ItemGroup>
+    <Compile Include="Runtime\ShrinkTutorialCore.cs" />
+    <Compile Include="..\Runtime\Core\ShrinkTutorialEnums.cs" />
+    <Compile Include="..\Runtime\Core\ShrinkTutorialLocalization.cs" />
+    <Compile Include="..\Runtime\Storage\IShrinkTutorialStorage.cs" />
+    <PackageReference Include="ShrinkSDK.Runtime.Abstractions" Version="0.1.0" />
+  </ItemGroup>
+</Project>

Editor/Samples/ShrinkTutorialSampleSceneBuilder.cs

@@ -104,12 +104,6 @@ namespace ShrinkTutorial.Editor
             Debug.Log("[ShrinkTutorial] Sample scene created: Assets/Scenes/ShrinkTutorialSample.unity");
         }
 
-        [MenuItem("ShrinkSDK/Tutorial/Create Sample Scene")]
-        public static void BuildSampleSceneAlias()
-        {
-            BuildSampleScene();
-        }
-
         private static ShrinkTutorialSettings EnsureSettings()
         {
             var settings = AssetDatabase.LoadAssetAtPath<ShrinkTutorialSettings>(SettingsPath);

Editor/ShrinkTutorialEditorWindow.cs

@@ -22,12 +22,6 @@ namespace ShrinkTutorial.Editor
             window.Show();
         }
 
-        [MenuItem("ShrinkSDK/Tutorial/Editor")]
-        public static void ShowWindowAlias()
-        {
-            ShowWindow();
-        }
-
         [MenuItem("ShrinkSDK/引导/重置教程进度")]
         public static void ResetProgress()
         {
@@ -37,12 +31,6 @@ namespace ShrinkTutorial.Editor
             Debug.Log("[ShrinkTutorial] 已重置教程进度。");
         }
 
-        [MenuItem("ShrinkSDK/Tutorial/Reset Progress")]
-        public static void ResetProgressAlias()
-        {
-            ResetProgress();
-        }
-
         private void OnEnable()
         {
             TryAssignDefaultDatabase();

Godot~/ShrinkGodotTutorialOverlay.cs

@@ -0,0 +1,89 @@
+#nullable enable
+
+using Godot;
+
+namespace ShrinkTutorial.Godot;
+
+public partial class ShrinkGodotTutorialOverlay : Control
+{
+    private readonly Label _title = new();
+    private readonly Label _body = new();
+    private ShrinkTutorialRunner? _runner;
+    private Control? _target;
+
+    public override void _Ready()
+    {
+        SetAnchorsAndOffsetsPreset(LayoutPreset.FullRect);
+        MouseFilter = MouseFilterEnum.Stop;
+        var panel = new PanelContainer { CustomMinimumSize = new Vector2(320, 100) };
+        panel.Position = new Vector2(24, 24);
+        var text = new VBoxContainer();
+        text.AddChild(_title);
+        text.AddChild(_body);
+        panel.AddChild(text);
+        AddChild(panel);
+    }
+
+    public void Bind(ShrinkTutorialRunner runner)
+    {
+        if (_runner != null) _runner.StepChanged -= ShowStep;
+        _runner = runner;
+        _runner.StepChanged += ShowStep;
+        if (_runner.CurrentStep != null) ShowStep(_runner.CurrentStep);
+    }
+
+    public override void _ExitTree()
+    {
+        if (_runner != null) _runner.StepChanged -= ShowStep;
+        _runner = null;
+        _target = null;
+    }
+
+    public override void _Process(double delta)
+    {
+        if (_runner?.CurrentStep is not { } step) return;
+        _target = ResolveTarget(step);
+        QueueRedraw();
+    }
+
+    public override void _Draw()
+    {
+        var viewport = GetViewportRect();
+        if (_target == null)
+        {
+            DrawRect(viewport, new Color(0, 0, 0, 0.72f));
+            return;
+        }
+        var hole = _target.GetGlobalRect().Grow(8);
+        var shade = new Color(0, 0, 0, 0.72f);
+        DrawRect(new Rect2(viewport.Position, new Vector2(viewport.Size.X, hole.Position.Y)), shade);
+        DrawRect(new Rect2(new Vector2(0, hole.End.Y), new Vector2(viewport.Size.X, viewport.Size.Y - hole.End.Y)), shade);
+        DrawRect(new Rect2(new Vector2(0, hole.Position.Y), new Vector2(hole.Position.X, hole.Size.Y)), shade);
+        DrawRect(new Rect2(new Vector2(hole.End.X, hole.Position.Y), new Vector2(viewport.Size.X - hole.End.X, hole.Size.Y)), shade);
+    }
+
+    public override void _GuiInput(InputEvent @event)
+    {
+        if (@event is not InputEventMouseButton { Pressed: true }) return;
+        var step = _runner?.CurrentStep;
+        if (step == null) return;
+        if (step.CompleteCondition == ShrinkTutorialCompleteCondition.AnyClick ||
+            step.CompleteCondition == ShrinkTutorialCompleteCondition.ClickTarget && _target?.GetGlobalRect().HasPoint(GetGlobalMousePosition()) == true)
+            _runner!.CompleteStep();
+        AcceptEvent();
+    }
+
+    private void ShowStep(ShrinkTutorialStep step)
+    {
+        _title.Text = step.Title;
+        _body.Text = step.Body;
+        Visible = true;
+    }
+
+    private Control? ResolveTarget(ShrinkTutorialStep step)
+    {
+        if (step.TargetMode == ShrinkTutorialTargetMode.Path) return GetTree().Root.GetNodeOrNull<Control>(step.Target);
+        if (step.TargetMode == ShrinkTutorialTargetMode.AnchorId) return GetTree().GetFirstNodeInGroup("shrink_tutorial_" + step.Target) as Control;
+        return null;
+    }
+}

Godot~/ShrinkSDK.Tutorial.Godot.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <AssemblyName>ShrinkTutorial.Godot</AssemblyName>
+    <RootNamespace>ShrinkTutorial.Godot</RootNamespace>
+    <PackageId>ShrinkSDK.Tutorial.Godot</PackageId>
+    <Version>0.1.0</Version>
+    <Description>Godot Control overlay and Resources for ShrinkSDK Tutorial.</Description>
+    <ShrinkCodeGenEnabled>false</ShrinkCodeGenEnabled>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="GodotSharp" Version="4.6.3" />
+    <ProjectReference Include="..\DotNet~\ShrinkSDK.Tutorial.csproj" />
+  </ItemGroup>
+</Project>

NuGet.Config

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+  <packageSources>
+    <clear />
+    <add key="ShrinkSDK" value="https://git.crash.work/api/packages/ShrinkSDK/nuget/index.json" />
+    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
+  </packageSources>
+</configuration>

README.md

@@ -2,6 +2,8 @@
 
 一个面向 Unity 2022.3+ 的互动式引导系统，重点解决这几件事：
 
+共享教程状态与步骤运行时位于 `DotNet~`；Godot 4.6 的 `Resource`、`Control` 遮罩和输入适配位于 `Godot~`。Godot 项目安装 `ShrinkSDK.Tutorial.Godot`。
+
 - 通过真实点击完成步骤，而不是纯文案翻页。
 - 支持静态路径目标和动态锚点目标。
 - 遮罩只屏蔽无关区域，目标区域可继续点击。
@@ -67,6 +69,11 @@ Assets/Modules/ShrinkTutorial/
 ShrinkTutorialManager.Instance.StartTutorial("tut.inventory.open");
 ```
 
+如果项目要求所有 UI 预先存在于场景，可在 `ShrinkTutorialManager` 上显式绑定
+`Canvas Override`、`Mask Override` 与 `Dialog Override`，并关闭
+`Allow Runtime Ui Fallback`。`ShrinkTutorialDialog` 的内容文本、箭头与跳过按钮也要
+在场景中序列化绑定；该模式不会在运行时创建教程 UI。
+
 也可以给入口物体挂 `ShrinkTutorialTrigger`，在 `OnEnable` 首次可见时自动触发。
 
 ### 4. 动态对象锚点

Runtime/Core/ShrinkTutorialData.cs

@@ -3,7 +3,7 @@ using UnityEngine;
 
 namespace ShrinkTutorial
 {
-    [CreateAssetMenu(fileName = "ShrinkTutorialData", menuName = "ShrinkTutorial/Tutorial Data")]
+    [CreateAssetMenu(fileName = "ShrinkTutorialData", menuName = "ShrinkSDK/引导/教程数据")]
     public class ShrinkTutorialData : ScriptableObject
     {
         public string tutorialId = string.Empty;

Runtime/Core/ShrinkTutorialDatabase.cs

@@ -3,7 +3,7 @@ using UnityEngine;
 
 namespace ShrinkTutorial
 {
-    [CreateAssetMenu(fileName = "ShrinkTutorialDatabase", menuName = "ShrinkTutorial/Tutorial Database")]
+    [CreateAssetMenu(fileName = "ShrinkTutorialDatabase", menuName = "ShrinkSDK/引导/教程数据库")]
     public class ShrinkTutorialDatabase : ScriptableObject
     {
         [SerializeField] private List<ShrinkTutorialData> tutorials = new();

Runtime/Core/ShrinkTutorialManager.cs

@@ -15,6 +15,12 @@ namespace ShrinkTutorial
 
         [SerializeField] private ShrinkTutorialSettings settingsOverride;
 
+        [Header("Explicit scene UI")]
+        [SerializeField] private Canvas canvasOverride;
+        [SerializeField] private ShrinkTutorialMask maskOverride;
+        [SerializeField] private ShrinkTutorialDialog dialogOverride;
+        [SerializeField] private bool allowRuntimeUiFallback = true;
+
         private readonly List<string> _pendingTutorialIds = new();
         private readonly HashSet<string> _completedTutorials = new();
         private readonly HashSet<string> _skippedTutorials = new();
@@ -32,6 +38,13 @@ namespace ShrinkTutorial
         private bool _skipRequested;
         private bool _stepCompleted;
         private bool _stepCompletionQueued;
+        private bool _clickTargetArmed;
+        private Rect _clickTargetArmedRect;
+        private ShrinkTutorialMaskShape _clickTargetArmedShape;
+        private int _clickTargetArmedFrame;
+        private bool _clickTargetArmedWithTouch;
+        private Button _clickTargetButton;
+        private ShrinkTutorialAnchor _clickTargetAnchor;
         private float _stepAutoTimer;
         private string _receivedCustomEvent = string.Empty;
 
@@ -202,6 +215,8 @@ namespace ShrinkTutorial
                 _skipRequested = false;
                 _stepCompleted = false;
                 _stepCompletionQueued = false;
+                _clickTargetArmed = false;
+                UnbindClickTargetEvents();
                 _stepAutoTimer = tutorial.steps[stepIndex].autoDelay;
                 _receivedCustomEvent = string.Empty;
 
@@ -225,6 +240,8 @@ namespace ShrinkTutorial
                 if (targetTransform)
                     LogDebug($"Resolved target for step {stepIndex}: {GetTransformPath(targetTransform)}");
 
+                BindClickTargetEvents(step, targetTransform);
+
                 EmitSignal(step.enterSignal);
                 _dialog.SetSkipVisible(ResolveSettings().showSkipButton);
 
@@ -237,6 +254,7 @@ namespace ShrinkTutorial
                     yield return null;
                 }
 
+                UnbindClickTargetEvents();
                 EmitSignal(step.exitSignal);
                 _dialog.Hide();
 
@@ -298,16 +316,7 @@ namespace ShrinkTutorial
                     }
                     break;
                 case ShrinkTutorialCompleteCondition.ClickTarget:
-                    if (targetTransform &&
-                        ShrinkTutorialTargetUtility.TryBuildScreenRect(targetTransform, out var targetRect) &&
-                        WasPrimaryPointerReleased(targetRect, step.maskShape, out var screenPosition) &&
-                        WasPointerReleaseRoutedToTarget(targetTransform, screenPosition))
-                    {
-                        LogDebug(
-                            $"ClickTarget candidate accepted, tutorial={_currentTutorial?.tutorialId}, step={_currentStepIndex}, " +
-                            $"pointer={screenPosition}, target={GetTransformPath(targetTransform)}");
-                        QueueStepCompletion();
-                    }
+                    TickClickTargetCompletion(step, targetTransform);
                     break;
                 case ShrinkTutorialCompleteCondition.CustomEvent:
                 case ShrinkTutorialCompleteCondition.DragToTarget:
@@ -359,24 +368,131 @@ namespace ShrinkTutorial
             return pressed && !_dialog.ContainsScreenPoint(screenPosition);
         }
 
-        private bool WasPrimaryPointerReleased(Rect targetRect, ShrinkTutorialMaskShape maskShape, out Vector2 screenPosition)
+        private void TickClickTargetCompletion(ShrinkTutorialStep step, Transform targetTransform)
         {
-            if (!TryGetPointerUpPosition(out screenPosition))
-                return false;
+            if (_clickTargetButton || _clickTargetAnchor)
+                return;
 
-            if (_dialog.ContainsScreenPoint(screenPosition))
+            if (!_clickTargetArmed &&
+                targetTransform &&
+                ShrinkTutorialTargetUtility.TryBuildScreenRect(targetTransform, out var targetRect) &&
+                TryGetPointerDownPosition(out var pointerDownPosition))
             {
-                LogDebug($"Pointer release ignored because it hit dialog, pointer={screenPosition}");
-                return false;
+                if (_dialog.ContainsScreenPoint(pointerDownPosition))
+                {
+                    LogDebug($"Pointer down ignored because it hit dialog, pointer={pointerDownPosition}");
+                }
+                else if (!IsPointInsideTarget(targetRect, step.maskShape, pointerDownPosition))
+                {
+                    LogDebug($"Pointer down outside target, pointer={pointerDownPosition}, rect={targetRect}");
+                }
+                else if (WasPointerRoutedToTarget(targetTransform, pointerDownPosition))
+                {
+                    _clickTargetArmed = true;
+                    _clickTargetArmedRect = targetRect;
+                    _clickTargetArmedShape = step.maskShape;
+                    _clickTargetArmedFrame = Time.frameCount;
+                    _clickTargetArmedWithTouch = Input.touchCount > 0;
+                    LogDebug(
+                        $"ClickTarget armed, tutorial={_currentTutorial?.tutorialId}, step={_currentStepIndex}, " +
+                        $"pointer={pointerDownPosition}, target={GetTransformPath(targetTransform)}");
+                }
             }
 
-            var insideTarget = maskShape == ShrinkTutorialMaskShape.Circle
+            if (!_clickTargetArmed)
+                return;
+
+            if (!TryGetPointerUpPosition(out var pointerUpPosition))
+            {
+                if (_clickTargetArmedWithTouch ||
+                    Time.frameCount <= _clickTargetArmedFrame ||
+                    Input.GetMouseButton(0))
+                {
+                    return;
+                }
+
+                pointerUpPosition = Input.mousePosition;
+            }
+
+            var armedRect = _clickTargetArmedRect;
+            var armedShape = _clickTargetArmedShape;
+            _clickTargetArmed = false;
+
+            if (_dialog.ContainsScreenPoint(pointerUpPosition))
+            {
+                LogDebug($"Pointer release ignored because it hit dialog, pointer={pointerUpPosition}");
+                return;
+            }
+
+            if (!IsPointInsideTarget(armedRect, armedShape, pointerUpPosition))
+            {
+                LogDebug($"Pointer release outside armed target, pointer={pointerUpPosition}, rect={armedRect}");
+                return;
+            }
+
+            LogDebug(
+                $"ClickTarget candidate accepted, tutorial={_currentTutorial?.tutorialId}, step={_currentStepIndex}, " +
+                $"pointer={pointerUpPosition}, target={GetTransformPath(targetTransform)}");
+            QueueStepCompletion();
+        }
+
+        private void BindClickTargetEvents(ShrinkTutorialStep step, Transform targetTransform)
+        {
+            if (step.completeCondition != ShrinkTutorialCompleteCondition.ClickTarget || !targetTransform)
+                return;
+
+            _clickTargetButton = targetTransform.GetComponent<Button>() ??
+                                 targetTransform.GetComponentInParent<Button>() ??
+                                 targetTransform.GetComponentInChildren<Button>(true);
+            if (_clickTargetButton)
+            {
+                _clickTargetButton.onClick.AddListener(HandleClickTargetEvent);
+                LogDebug($"Bound ClickTarget button event: {GetTransformPath(_clickTargetButton.transform)}");
+                return;
+            }
+
+            _clickTargetAnchor = targetTransform.GetComponent<ShrinkTutorialAnchor>() ??
+                                 targetTransform.GetComponentInParent<ShrinkTutorialAnchor>() ??
+                                 targetTransform.GetComponentInChildren<ShrinkTutorialAnchor>(true);
+            if (_clickTargetAnchor)
+            {
+                _clickTargetAnchor.Clicked += HandleClickTargetPointerEvent;
+                LogDebug($"Bound ClickTarget anchor event: {GetTransformPath(_clickTargetAnchor.transform)}");
+            }
+        }
+
+        private void HandleClickTargetEvent()
+        {
+            LogDebug($"ClickTarget button event received, tutorial={_currentTutorial?.tutorialId}, step={_currentStepIndex}");
+            QueueStepCompletion();
+        }
+
+        private void HandleClickTargetPointerEvent(PointerEventData eventData)
+        {
+            if (eventData != null && eventData.button != PointerEventData.InputButton.Left)
+                return;
+
+            LogDebug($"ClickTarget pointer event received, tutorial={_currentTutorial?.tutorialId}, step={_currentStepIndex}");
+            QueueStepCompletion();
+        }
+
+        private void UnbindClickTargetEvents()
+        {
+            if (_clickTargetButton)
+                _clickTargetButton.onClick.RemoveListener(HandleClickTargetEvent);
+
+            if (_clickTargetAnchor)
+                _clickTargetAnchor.Clicked -= HandleClickTargetPointerEvent;
+
+            _clickTargetButton = null;
+            _clickTargetAnchor = null;
+        }
+
+        private static bool IsPointInsideTarget(Rect targetRect, ShrinkTutorialMaskShape maskShape, Vector2 screenPosition)
+        {
+            return maskShape == ShrinkTutorialMaskShape.Circle
                 ? IsPointInsideCircle(targetRect, screenPosition)
                 : targetRect.Contains(screenPosition);
-            if (!insideTarget)
-                LogDebug($"Pointer release outside target, pointer={screenPosition}, rect={targetRect}");
-
-            return insideTarget;
         }
 
         private static bool IsPointInsideCircle(Rect targetRect, Vector2 screenPosition)
@@ -430,7 +546,7 @@ namespace ShrinkTutorial
             return false;
         }
 
-        private bool WasPointerReleaseRoutedToTarget(Transform targetTransform, Vector2 screenPosition)
+        private bool WasPointerRoutedToTarget(Transform targetTransform, Vector2 screenPosition)
         {
             var eventSystem = EventSystem.current;
             if (!eventSystem)
@@ -521,6 +637,8 @@ namespace ShrinkTutorial
             _currentStepIndex = -1;
             _runner = null;
             _stepCompletionQueued = false;
+            _clickTargetArmed = false;
+            UnbindClickTargetEvents();
 
             TryStartQueuedTutorial();
         }
@@ -530,6 +648,24 @@ namespace ShrinkTutorial
             if (_canvas && _mask && _dialog)
                 return;
 
+            if (canvasOverride && maskOverride && dialogOverride)
+            {
+                _canvas = canvasOverride;
+                _mask = maskOverride;
+                _dialog = dialogOverride;
+                if (!_dialog.BindExisting())
+                    throw new InvalidOperationException("ShrinkTutorial explicit dialog bindings are incomplete.");
+
+                _dialog.Hide();
+                return;
+            }
+
+            if (!allowRuntimeUiFallback)
+            {
+                throw new InvalidOperationException(
+                    "ShrinkTutorialManager requires explicit Canvas, Mask and Dialog bindings when runtime UI fallback is disabled.");
+            }
+
             var settings = ResolveSettings();
             var canvasObject = new GameObject("ShrinkTutorialCanvas", typeof(RectTransform), typeof(Canvas), typeof(CanvasScaler),
                 typeof(GraphicRaycaster));

Runtime/Core/ShrinkTutorialSettings.cs

@@ -2,7 +2,7 @@ using UnityEngine;
 
 namespace ShrinkTutorial
 {
-    [CreateAssetMenu(fileName = "ShrinkTutorialSettings", menuName = "ShrinkTutorial/Settings")]
+    [CreateAssetMenu(fileName = "ShrinkTutorialSettings", menuName = "ShrinkSDK/引导/引导设置")]
     public class ShrinkTutorialSettings : ScriptableObject
     {
         private static ShrinkTutorialSettings _instance;

Runtime/Trigger/ShrinkTutorialAnchor.cs

@@ -1,12 +1,20 @@
+using System;
 using UnityEngine;
+using UnityEngine.EventSystems;
 
 namespace ShrinkTutorial
 {
-    public class ShrinkTutorialAnchor : MonoBehaviour
+    public class ShrinkTutorialAnchor : MonoBehaviour, IPointerClickHandler
     {
         [SerializeField] private string anchorId = string.Empty;
 
         public string AnchorId => anchorId;
+        public event Action<PointerEventData> Clicked;
+
+        public void OnPointerClick(PointerEventData eventData)
+        {
+            Clicked?.Invoke(eventData);
+        }
 
         public void SetAnchorId(string value)
         {

Runtime/UI/ShrinkTutorialDialog.cs

@@ -7,12 +7,30 @@ namespace ShrinkTutorial
 {
     public class ShrinkTutorialDialog : MonoBehaviour
     {
-        private RectTransform _rectTransform;
-        private RectTransform _arrowRectTransform;
-        private TextMeshProUGUI _contentText;
-        private GameObject _skipButtonObject;
+        [Header("Explicit scene bindings")]
+        [SerializeField] private RectTransform _rectTransform;
+        [SerializeField] private RectTransform _arrowRectTransform;
+        [SerializeField] private TextMeshProUGUI _contentText;
+        [SerializeField] private GameObject _skipButtonObject;
         private Action _skipAction;
 
+        /// <summary>
+        /// Uses UI objects that already exist in the scene. This path intentionally does not
+        /// create children or add listeners at runtime; scene-authored persistent callbacks
+        /// remain the source of truth.
+        /// </summary>
+        public bool BindExisting()
+        {
+            if (!_rectTransform)
+                _rectTransform = GetComponent<RectTransform>();
+
+            if (_rectTransform && _arrowRectTransform && _contentText)
+                return true;
+
+            Debug.LogError("[ShrinkTutorial] Explicit dialog bindings are incomplete.", this);
+            return false;
+        }
+
         public void Initialize(Transform parent, Action skipAction)
         {
             _skipAction = skipAction;

package.json

@@ -1,13 +1,14 @@
 {
   "name": "com.cneicy.shrink-tutorial",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "displayName": "ShrinkTutorial",
   "description": "面向 Unity 的互动式新手引导系统，提供数据驱动教程、遮罩挖洞、动态锚点、步骤条件与运行时调度。",
   "unity": "2022.3",
   "dependencies": {
     "com.unity.textmeshpro": "3.0.7",
     "com.unity.ugui": "1.0.0",
-    "com.unity.modules.physics": "1.0.0"
+    "com.unity.modules.physics": "1.0.0",
+    "com.unity.modules.jsonserialize": "1.0.0"
   },
   "keywords": [
     "tutorial",