unity-dotween-design

> Before calling any skill in this module: if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via GET /skills/recommend?includeSchema=true) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

Triggers

• Writing or reviewing DOTween code
• Building sequences
• Binding tween lifetime
• Debugging tween pitfalls
• 编写或审查 DOTween 代码、构建序列动画、绑定补间生命周期、排查补间陷阱

DOTween - Design Rules

Advisory module. Every rule is distilled from Demigiant DOTween source at:

• 1.3.015 — bundled in _DOTween.Assembly/DOTween/ and bin/Modules/ module files (Unity 2018+)

Each rule cites a concrete file/line so the reasoning is auditable and the AI does not improvise against stale memory.

> Mode: Documentation only — no REST skills to gate; load freely under any operating mode (Approval / Auto / Bypass).

When to Load This Module

Load before writing or reviewing any of:

• DOTween.Init(...) bootstrap, DOTweenSettings configuration, SetTweensCapacity adjustments
• Any .DOMove / .DORotate / .DOScale / .DOColor / .DOFade / .DOShake / .DOPath / .DOPunch shortcut call
• DOTween.Sequence() + .Append / .Join / .Insert / .Prepend / .AppendInterval / .PrependInterval / .AppendCallback
• .SetEase / .SetDelay / .SetLoops / .SetAutoKill / .SetLink / .SetId / .SetTarget / .SetUpdate / .SetRelative / .SetRecyclable / .SetSpeedBased
• .OnStart / .OnUpdate / .OnStepComplete / .OnComplete / .OnKill / .OnPlay / .OnPause / .OnRewind
• .AsyncWaitForCompletion / .AsyncWaitForKill / .AsyncWaitForRewind / .AsyncWaitForElapsedLoops / .AsyncWaitForPosition
• tween.ToUniTask(TweenCancelBehaviour, CancellationToken) (UniTask bridge)
• DOTween.Kill(target, complete) / DOTween.KillAll() batch operations
• Safe Mode debugging — useSafeMode, safeModeLogBehaviour, nestedTweenFailureBehaviour
• DOTween Module generation (Audio / Physics / Physics2D / Sprite / UI / UnityUI / TextMeshPro)

Critical Rule Summary

| # | Rule | Source anchor |

|---|------|---------------|

| 1 | DOTween.Init(recycleAllByDefault, useSafeMode, logBehaviour) returns IDOTweenInit for fluent .SetCapacity(...). If not called explicitly, Auto-init runs on first tween creation (AutoInit at DOTween.cs:236). DOTween.Version = "1.3.015" is exposed as a const. | DOTween.cs:38,227,236,243 |

| 2 | Every tween is driven by a single [DOTween] GameObject MonoBehaviour (DOTweenComponent) marked DontDestroyOnLoad. It is created on first init and survives scene loads. Don't destroy it — DOTween.Clear(destroy: true) is the only supported teardown. | DOTweenComponent.cs:268-270, DOTween.cs:311 |

| 3 | Default autoKill = true: tween is killed on completion. After kill, calls like .Restart() / .Kill() / .Complete() are no-ops (Safe Mode) or NullReferenceException (Safe Mode off). Use .SetAutoKill(false) to keep tween alive for replay. | DOTween.cs useSafeMode:49, TweenSettingsExtensions.cs:39,49 |

| 4 | Safe Mode is ON by default (useSafeMode = true). Target destroyed while tween plays → Safe Mode catches the exception and logs per safeModeLogBehaviour (default: Warning). Disable Safe Mode to locate missing-link bugs during development. | DOTween.cs:49,51 |

| 5 | SetLink(gameObject, LinkBehaviour) binds tween lifecycle to a GameObject. Default LinkBehaviour.KillOnDestroy. Without SetLink, tween continues running after target is destroyed and relies on Safe Mode for protection. | TweenSettingsExtensions.cs:91,103, LinkBehaviour.cs |

| 6 | SetTarget(object target) is required for DOTween.Kill(target) / DOTween.KillAll(target) grouping. Shortcut extensions (.DOMove, .DOFade, etc.) set target automatically; manual DOTween.To(...) does NOT. | TweenSettingsExtensions.cs:116, DOTween.cs:884,892 |

| 7 | Sequence.Append(t) runs after previous. Sequence.Join(t) runs in parallel with previous. Sequence.Insert(float atPosition, t) inserts at absolute time. Sequence.Prepend(t) pushes to front, shifting existing. | TweenSettingsExtensions.cs:499,508,517,528 |

| 8 | AsyncWaitForCompletion / AsyncWaitForKill / AsyncWaitForRewind live in DOTweenModuleUnityVersion.cs (MODULE file, gated by UNITY_2018_1_OR_NEWER && (NET_4_6 || NET_STANDARD_2_0)). If Modules are not generated (Tools → DOTween Utility Panel → Create ASMDEF), these APIs don't exist. | bin/Modules/DOTweenModuleUnityVersion.cs:216,244,230 |

| 9 | UniTask bridge tween.ToUniTask(TweenCancelBehaviour, CancellationToken) lives in UniTask's External/DOTween/ extensions and is the recommended await path over AsyncWaitForCompletion. TweenCancelBehaviour has 9 values (Kill / Complete / CancelAwait / KillAndCancelAwait / ...). | UniTask DOTweenAsyncExtensions.cs:14-27,54 |

| 10 | Ease enum has 38 entries (36 user-facing + 2 reserved INTERNAL_*): Unset / Linear + In/Out/InOut variants of Sine/Quad/Cubic/Quart/Quint/Expo/Circ/Elastic/Back/Bounce (10 × 3 = 30 math eases) + Flash / InFlash / OutFlash / InOutFlash. INTERNAL_Zero and INTERNAL_Custom are auto-assigned by DOTween for zero-duration and AnimationCurve-based tweens. | Ease.cs:9-53 |

Sub-doc Routing

| Sub-doc | When to read |

|---------|--------------|

| [BASICS.md](./BASICS.md) | DOTween.Init, driver GameObject, DOTweenSettings asset, Modules architecture, Safe Mode, tween capacity |

| [TWEEN.md](./TWEEN.md) | Tween base class, Tweener vs Sequence, autoKill, Play/Pause/Rewind/Restart/Kill/Complete/Goto lifecycle |

| [SEQUENCE.md](./SEQUENCE.md) | Sequence.Append / Join / Insert / Prepend / AppendInterval / PrependInterval / AppendCallback / InsertCallback, nesting, loop composition |

| [SHORTCUTS.md](./SHORTCUTS.md) | .DOMove / DOLocalMove / DOAnchorPos / DORotate / DOScale / DOColor / DOFade / DOPath / DOJump / DOPunch / DOShake* cheat sheet by target type |

| [EASE.md](./EASE.md) | Full Ease enum, SetEase overloads (Ease / amplitude+period / AnimationCurve / EaseFunction), Flash family, Elastic/Back overshoot |

| [LIFETIME.md](./LIFETIME.md) | SetAutoKill / SetLink / SetRecyclable / SetId / SetTarget / DOTween.Kill / DOTween.KillAll, Safe Mode, tween pool capacity |

| [INTEGRATION.md](./INTEGRATION.md) | DOTween + UniTask (ToUniTask), DOTween + Coroutine (WaitForCompletion), DOTween + Addressables lifetime, DOTween + Netcode deterministic replay |

| [PITFALLS.md](./PITFALLS.md) | 30 concrete hallucination / runtime pitfalls (missing target, stale tween handle, OnComplete not firing on infinite loop, Safe Mode hiding bugs, etc.) |

Routing to Other Modules

• Async integration (ToUniTask, AsyncWaitForCompletion) → load [unitask-design](../unitask-design/SKILL.md) and [async](../async/SKILL.md)
• UI animation (uGUI / UIToolkit) choice between DOTween and native animators → load [inspector](../inspector/SKILL.md)
• Architecture / performance review of tween-heavy scenes → load [performance](../performance/SKILL.md)
• Asmdef layout for DOTween consumers (DOTween.asmdef, DOTween Modules asmdef) → load [asmdef](../asmdef/SKILL.md)
• Addressables-loaded prefab tween lifetime (bundle unload vs tween running) → load [addressables-design](../addressables-design/SKILL.md)

Version Scope

Targets DOTween 1.3.015 (the Pro/Free source bundled in _DOTween.Assembly/). Version is exposed as the const DOTween.Version = "1.3.015" at DOTween.cs:38.

Earlier 1.2.x versions are source-compatible for most APIs. Key differences:

• Modules system (UI / TMP / Physics / etc.) requires post-1.2.0 source and the Utility Panel scanner.
• SetLink was added in 1.2.x series; LinkBehaviour.KillOnDestroy vs KillOnDisable variants in later 1.2/1.3.
• TweenCancelBehaviour (UniTask bridge) shipped separately via the UniTask package.

When in doubt, read the cited source — not your memory.