f8-features-tween-workflow

# Tween Feature Workflow > **⚠️ IMPORTANT**: Before using this feature, you **MUST** formally initialize F8Framework in the launch sequence. Ensure `ModuleCenter.Initialize(this);` has run first, then create the required module, for example `FF8.Tween = ModuleCenter.CreateModule<Tween>();`. ## Use this skill when - The task is about tween/interpolation animations (move, rotate, scale, fade, etc.). - The user asks about animation sequencing, loop types, or UI-relative motion. - Troubleshooting tween timing, easing, or auto-kill behavior. ## Path resolution 1. Prefer project source at Assets/F8Framework. 2. For usage docs, read: Assets/F8Framework/Tests/Tween/README.md ## Sources of truth - Runtime module: Assets/F8Framework/Runtime/Tween - Test docs: Assets/F8Framework/Tests/Tween ## Key classes and interfaces | Class | Role | |-------|------| | `TweenManager` | Core module. Access via `FF8.Tween`. | | `BaseTween` | Tween handle with chain methods. | | `SequenceManager` | Creates and manages animation sequences. | | `Ease` | Easing curves (Linear, EaseOutQuad, EaseOutBounce, etc.). | | `LoopType` | Restart, Flip, Incremental, Yoyo. | ## API quick reference ### Basic tweens (extension methods on GameObject) ```csharp gameObject.ScaleTween(Vector3.one * 2f, 1f); // Scale gameObject.RotateTween(Vector3.one, 1f); // Rotate gameObject.EulerAnglesTween(Vector3.one * 360f, 1f); // Euler rotation gameObject.Move(Vector3.one, 1f); // World move gameObject.MoveAtSpeed(Vector3.one, 2f); // Move at speed gameObject.LocalMove(Vector3.one, 1f); // Local move gameObject.LocalMoveAtSpeed(Vector3.one, 1f); // Local move at speed gameObject.GetComponent<CanvasGroup>().Fade(0f, 1f); // Fade gameObject.GetComponent<Image>().ColorTween(Color.green, 1f); // Color gameObject.GetComponent<Image>().FillAmountTween(1f, 1f); // Fill ``` ### Shake ```csharp gameObject.ShakePosition(Vector3.one, shakeCount: 8, t: 0.05f, fadeOut: false); gameObject.ShakePositionAtSpeed(Vector3.one, shakeCount: 8, speed: 5f, fadeOut: false); gameObject.ShakeRotation(Vector3.one); gameObject.ShakeScale(Vector3.one); ``` ### Path ```csharp gameObject.PathTween(points, duration: 1f, pathType: PathType.CatmullRom, pathMode: PathMode.Ignore, resolution: 10, closePath: false); ``` ### String ```csharp text.StringTween("", "Hello!", 1f, richTextEnabled: true, ScrambleMode.Custom, scrambleChars: "*"); ``` ### Chain calls ```csharp BaseTween tween = gameObject.Move(Vector3.one, 10f) .SetEase(Ease.EaseOutQuad) .SetOnComplete(OnDone) .SetDelay(2f) .SetEvent(OnMidway, 2.5f) .SetLoopType(LoopType.Yoyo, 3) .SetUpdateMode(UpdateMode.Update) .SetOwner(gameObject) .SetIgnoreTimeScale(true) .SetUseSmoothDeltaTime(true) // Smooth visual motion; ignored when SetIgnoreTimeScale(true) .SetCustomId("myTween") .SetAutoKill(false); ``` ### Tween control (via FF8.Tween or BaseTween) ```csharp FF8.Tween.SetCurrentTime(id, 5f); // By id FF8.Tween.SetCurrentTime("customId", 5f); // By custom id FF8.Tween.SetProgress(id, 0.5f); FF8.Tween.Complete(id); FF8.Tween.ReplayReset(id); FF8.Tween.SetIsPause(id, true); FF8.Tween.SetIgnoreTimeScale(id, true); FF8.Tween.SetUseSmoothDeltaTime(id, true); FF8.Tween.CancelTween(id); gameObject.CancelAllTweens(); ``` ### Value tweens ```csharp FF8.Tween.ValueTween(0f, 100f, 3f).SetOnUpdateFloat((float v) => { }); FF8.Tween.Move(gameObject, Vector3.one, 3f).SetOnUpdateVector3((Vector3 v) => { }); ``` ### UI relative motion ```csharp // Move UI by viewport-relative coordinates (0,0)=bottom-left, (1,1)=top-right rectTransform.MoveUI(new Vector2(1f, 1f), canvasRect, 1f) .SetEase(Ease.EaseOutBounce); ``` ### Sequences ```csharp var seq = FF8.Tween.GetSequence(); seq.Append(tween1); // Sequential seq.Join(tween2); // Parallel with previous seq.Append(() => LogF8.Log("Done")); // Callback seq.SetOnComplete(() => { }); seq.SetLoops(3); // -1 = infinite seq.RunAtTime(() => { }, 1.5f); // Event at specific time seq.RunAtTime(tween3, 2.0f); // Tween at specific time FF8.Tween.KillSequence(seq); // Stop and recycle ``` ### Coroutine and async support ```csharp // Coroutine yield return gameObject.Move(Vector3.one, 1f); yield return sequence; // async/await await gameObject.Move(Vector3.one, 1f); await sequence; ``` ## Workflow 1. Choose tween type (move, rotate, scale, fade, path, etc.). 2. Chain configuration methods for easing, delay, loop. 3. Use sequences for complex multi-step animations. 4. For UI, use `MoveUI()` with canvas-relative coordinates. 5. Use `SetUseSmoothDeltaTime(true)` only for visual tweens that should smooth frame-time spikes. 6. Use `SetAutoKill(false)` if you need to replay or hold references. 7. Cancel/complete tweens when game state changes. ## Common error handling | Error | Cause | Solution | |-------|-------|----------| | Tween reference is stale | Auto-killed and recycled | Use `SetAutoKill(false)` | | UI animation jumps | Wrong coordinate space | Use MoveUI for viewport-relative | | Tween not playing during pause | TimeScale is 0 | Use `SetIgnoreTimeScale(true)` | | Visual tween jumps after frame spike | Raw `deltaTime` catches up immediately | Use `SetUseSmoothDeltaTime(true)` on that tween | ## Cross-module dependencies - **UI**: Used for panel open/close animations in BaseView. ## Output checklist - Tween type and parameters selected. - Easing and loop configured. - Sequence order defined if multi-step. - Validation status and remaining risks.