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

API quick reference

Basic tweens (extension methods on GameObject)

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

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

gameObject.PathTween(points, duration: 1f, pathType: PathType.CatmullRom,
    pathMode: PathMode.Ignore, resolution: 10, closePath: false);

String

text.StringTween("", "Hello!", 1f, richTextEnabled: true,
    ScrambleMode.Custom, scrambleChars: "*");

Chain calls

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)

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

FF8.Tween.ValueTween(0f, 100f, 3f).SetOnUpdateFloat((float v) => { });
FF8.Tween.Move(gameObject, Vector3.one, 3f).SetOnUpdateVector3((Vector3 v) => { });

UI relative motion

// 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

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

// 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

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.