unity-dotween

**调用本模块中的任何技能前：**如果你打算根据技能名称或描述猜测参数后调用技能，请先停下——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已从 recommend/schema 获取参数定义，则可直接执行 dryRun。

触发条件

• 设置 DOTween
• 校验安装/模块
• 配置 DOTweenAnimation 组件
• 接入 DOTween、校验安装/模块、配置 DOTweenAnimation 组件

DOTween 技能

DOTween Free/Pro 支持项目诊断、设置、模块/API 发现和运行时脚本生成。DOTween Pro 专属的 DOTweenAnimation 编辑器时配置仍可通过 dotween_pro_* 技能使用。

防护措施

运行模式（v1.9 三级模式）：

• Approval（默认）：查询/诊断技能（dotween_get_status、dotween_settings_get、dotween_settings_find、dotween_settings_validate、dotween_list_modules、dotween_list_shortcuts、dotween_pro_get_animation、dotween_pro_list_animations）可直接运行。修改器（设置配置，以及其余 dotween_pro_* 写入技能）属于 FullAuto——遇到 MODE_RESTRICTED 时，执行授权流程。脚本生成器和 dotween_pro_remove_animation 则会被自动禁止（见下一条）；授权不会解锁这些技能。
• Auto / Bypass：SemiAuto 和 FullAuto 均可直接运行。
• 本模块中自动禁止的技能：dotween_generate_tween_script、dotween_generate_sequence_script、dotween_generate_lifetime_script（均带有 MayTriggerReload = true、RiskLevel = "high"，因为写入新的 .cs 文件会触发脚本编译和 Domain Reload），以及 dotween_pro_remove_animation（SkillOperation.Delete——仅 Delete 位就足以触发 NeverInSemi，即使其 RiskLevel 仍为 "low"）。以上四项在 Approval 和 Auto 模式下均会返回 MODE_FORBIDDEN，只有在 Bypass 模式或通过用户管理的 Allowlist 条目才能使用；授权流程也会返回 MODE_FORBIDDEN。请注意，其他 Pro 写入技能（dotween_pro_add_animation、dotween_pro_set_*、dotween_pro_copy_animation 等）不带 Delete 位，仍可授权。
• 当未安装 DOTween Free/Pro 时，DOTweenPresenceDetector 不会添加 DOTWEEN / DOTWEEN_PRO 定义，因此大多数技能会返回“未安装”诊断信息，而不会执行。dotween_pro_* 系列还需要 Pro，因为 DG.Tweening.DOTweenAnimation 仅 Pro 版提供。

前置条件：

• 必须安装 DOTween Free 或 Pro。安装后，DOTweenPresenceDetector 会自动添加 DOTWEEN / DOTWEEN_PRO 定义。
• Free 技能可用于 DOTween Free 和 Pro：状态、设置读取/查找/校验/配置、模块/快捷方式列表、运行时脚本生成。
• dotween_pro_* 技能需要 DOTween Pro，因为 DG.Tweening.DOTweenAnimation 仅 Pro 版提供。

不要混淆 Free 和 Pro：

• Free 技能不会创建或模拟 DOTweenAnimation 组件。
• 运行时补间生成只会创建 .cs 脚本；不会自动将脚本附加到场景对象，因为 Unity 可能需要先进行 Domain Reload。
• 有关源代码层面的运行时 API 设计规则，请加载 dotween-design。

Free 技能

诊断与设置

• dotween_get_status — 报告 DOTween/Pro 安装状态、DOTweenSettings.asset 路径和可见模块数量。
• dotween_settings_find — 列出名称为 DOTweenSettings 的项目资源。
• dotween_settings_get — 读取 DOTweenSettings.asset 的常见字段。
• dotween_settings_validate — 报告缺少设置、设置重复、容量无效以及值得注意的 SafeMode 警告。
• dotween_settings_configure — 编辑 Resources/DOTweenSettings.asset；参数：defaultEaseType?、defaultAutoKill?、defaultLoopType?、safeMode?、logBehaviour?、tweenersCapacity?、sequencesCapacity?。如果当前 DOTween 版本未声明某参数对应的字段，该参数会返回在 unsupported 数组中，而不会被视为已应用——DOTween Pro 1.0.381 的资源中根本没有容量字段（容量通过运行时调用 DOTween.SetTweensCapacity 设置）。容量必须 >= 1；无效的枚举值会被拒绝，并列出可接受的名称。

API 发现

• dotween_list_modules — 列出已加载的 DG.Tweening.DOTweenModule*、ShortcutExtensions、TweenExtensions 和 TweenSettingsExtensions 类型。可选参数：includeMethods=false、methodLimit=20。
• dotween_list_shortcuts — 列出公共扩展方法。可选筛选条件：targetType、methodPrefix、limit=100。

运行时脚本生成

所有生成技能都需要 className，默认文件夹为 folder=Assets/Scripts/DOTween，可选 namespaceName，且绝不会覆盖现有文件。

• dotween_generate_tween_script — 创建一个运行时 tween MonoBehaviour。
• dotween_generate_sequence_script — 创建一个运行时 Sequence MonoBehaviour；可选 stepsJson 数组，元素格式为 {op:"Append|Join|AppendInterval", tweenKind, duration}。
• dotween_generate_lifetime_script — 创建一个生命周期安全的封装器，默认使用 SetLink(gameObject)，并在禁用/销毁时调用 KillTween()。

通用参数：targetKind=Transform、tweenKind=DOMove、duration=1、ease=OutQuad、loops=1、autoPlay=true、useSetLink=true。

v1 支持的 targetKind / tweenKind 组合：

• Transform：DOMove、DOLocalMove、DORotate、DOLocalRotate、DOScale、DOPunchPosition、DOShakePosition
• RectTransform：DOAnchorPos、DOSizeDelta
• CanvasGroup：DOFade
• Graphic / Image：DOColor、DOFade
• Generic：DOTween.To

示例：

dotween_generate_tween_script className=HeroPanelIntro targetKind=RectTransform tweenKind=DOAnchorPos duration=0.35 ease=OutBack

Sequence 示例：

dotween_generate_sequence_script className=ButtonPop targetKind=Transform stepsJson='[
  {"op":"Append","tweenKind":"DOScale","duration":0.12},
  {"op":"AppendInterval","duration":0.05},
  {"op":"Join","tweenKind":"DOPunchPosition","duration":0.25}
]'

Pro 技能

dotween_pro_add_animation

向一个 GameObject 添加一个 DOTweenAnimation，并配置所有核心字段。 参数： target / animationType / endValueV3? / endValueFloat? / endValueColor? / endValueV2? / endValueString? / endValueRect? / duration=1 / ease="OutQuad" / loops=1 / loopType="Yoyo" / delay=0 / isRelative=false / isFrom=false / autoPlay=true / autoKill=true / id?

三个添加技能共用的数值/枚举约束会在添加任何内容前进行检查：duration > 0，loops 为 -1（无限循环）或 >= 1，delay >= 0，且 animationType / ease / loopType 必须属于已安装 DOTween 声明的枚举成员（以前拼错的 ease 会被静默忽略）。

dotween_pro_batch_add_animation

向多个 GameObject 添加相同的动画。 参数： targetsJson（JSON 字符串数组）+ dotween_pro_add_animation 的所有参数。

dotween_pro_stagger_animations

批量添加动画并递增延迟——用于 UI 级联入场效果。 参数： targetsJson / animationType / endValueV3? / endValueFloat? / endValueColor? / endValueV2? / duration=0.5 / ease="OutBack" / loops=1 / loopType="Yoyo" / baseDelay=0 / staggerDelay=0.1 / isFrom=true / autoPlay=true / autoKill=true baseDelay 和 staggerDelay 都必须 >= 0；如果其中一个为负数，会立即拒绝，而不会留待 DOTween 事后将其钳制。

dotween_pro_set_duration

更改现有 DOTweenAnimation 的 duration。参数：target、animationIndex=0、duration（必填，> 0）。

dotween_pro_set_ease

更改现有 DOTweenAnimation 的缓动方式。参数：target、animationIndex=0、ease="OutQuad"、easeCurveJson?。如果两者都已传入，则以 easeCurveJson 为准；无法解析的曲线会被拒绝，不会静默回退到 ease。

dotween_pro_set_loops

更改循环次数和／或 loopType。参数：target、animationIndex=0、loops?（-1 = 无限循环，否则 >= 1）、loopType?。至少传入 loops / loopType 之一——两者都省略时会拒绝操作，而不是将循环次数重置为 1；只传入其中一个时，另一个保持不变。

dotween_pro_set_animation_field

用于设置 DOTweenAnimation 字段的通用 setter，但不包括 duration/ease/easeType/easeCurve/loops/loopType；这些字段请使用专用技能。fieldName 和 fieldValue 均为必填项——要清空字符串字段，请显式传入 ""。

dotween_pro_get_animation

读取一个 DOTweenAnimation 的所有序列化字段。参数：target、animationIndex=0。

dotween_pro_list_animations

列出目标上或整个场景中的 DOTweenAnimation 组件。参数：target?、recursive=false。animationIndex 是组件在其所属 GameObject 上的位置，与 setter/remover 使用的索引完全相同——直接传入即可。

dotween_pro_copy_animation

将 sourceTarget[sourceIndex] 的所有字段复制到 destTarget 上新建的 DOTweenAnimation。无法复制的字段会列在 skippedFields 中。

dotween_pro_remove_animation

按索引移除一个 DOTweenAnimation 组件。

animationType → endValue 映射

animationType	必需参数
Move / LocalMove / Rotate / LocalRotate / Scale / PunchPosition / PunchRotation / PunchScale / ShakePosition / ShakeRotation / ShakeScale / AnchorPos3D	endValueV3（"1,2,3" 或 "[1,2,3]"）
AnchorPos / UIWidthHeight	endValueV2（"1,2"）
Fade / FillAmount / CameraOrthoSize / CameraFieldOfView / Value	endValueFloat
Color / CameraBackgroundColor	endValueColor（"#FF8800" 或 "1,0.5,0,1"）
Text	endValueString
UIRect	endValueRect（"x,y,width,height"）

---

精确签名

准确的名称、参数、默认值和返回值由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义，而非本文件。