Skills
skills/ostrichhermit/oh-unity-gamedev-skills/prime-tween-unity

prime-tween-unity

SKILL.md

PrimeTween Unity Skill

PrimeTween 是一个高性能、零内存分配的 Unity 动画库。用一行代码实现任何动画，支持 Inspector 调试、复杂序列、相机震动等功能。

何时使用此 Skill

在以下情况下触发此 Skill ：

  • PrimeTween 动画库 (com.kyrylokuzyk.primetween)
  • UI 动画和过渡效果 (UI animations and transitions)
  • Transform 动画 (位置、旋转、缩放)
  • Material 和 Color 动画
  • 相机震动和屏幕特效 (Camera shake and screen effects)
  • 动画序列和时序控制 (Animation sequences)
  • 延迟执行和回调 (Delays and callbacks)
  • TextMeshPro 文字打字机效果
  • 从 DOTween 迁移到 PrimeTween

快速参考

Hello World - 基础动画

using PrimeTween;

// 位置动画 - 将 transform.position.y 从当前值动画到 10，持续 1 秒，使用 Ease.InOutSine 缓动
Tween.PositionY(transform, endValue: 10, duration: 1, ease: Ease.InOutSine);

// 旋转动画 - 将 transform 从当前旋转旋转到 (0, 90, 0)，持续 1 秒
Tween.Rotation(transform, endValue: Quaternion.Euler(0, 90, 0), duration: 1);

// 欧拉角旋转 - 绕 Y 轴旋转 360 度
Tween.EulerAngles(transform, startValue: Vector3.zero, endValue: new Vector3(0, 360), duration: 1);

// 缩放动画 - 将对象缩放到 2 倍大小
Tween.Scale(transform, endValue: 2f, duration: 0.5f);

// UI 透明度动画
Tween.Alpha(image, endValue: 0f, duration: 1f);

1. 常用动画类型

Transform 动画

using PrimeTween;

// Position (世界坐标)
Tween.Position(transform, endValue: new Vector3(10, 0, 5), duration: 1f);
Tween.PositionX(transform, endValue: 10f, duration: 1f);
Tween.PositionY(transform, endValue: 5f, duration: 1f);
Tween.PositionZ(transform, endValue: 0f, duration: 1f);

// Local Position (本地坐标)
Tween.LocalPosition(transform, endValue: Vector3.zero, duration: 1f);
Tween.LocalPositionX/Y/Z(transform, endValue: 0f, duration: 1f);

// Rotation (四元数旋转)
Tween.Rotation(transform, endValue: Quaternion.Euler(0, 90, 0), duration: 1f);
Tween.LocalRotation(transform, endValue: Quaternion.identity, duration: 1f);

// EulerAngles (欧拉角旋转 - 支持超过 180 度的旋转)
Tween.EulerAngles(transform, endValue: new Vector3(0, 360, 0), duration: 1f);
Tween.LocalEulerAngles(transform, endValue: new Vector3(360, 0, 0), duration: 1f);

// Scale (缩放)
Tween.Scale(transform, endValue: 2f, duration: 0.5f); // 均匀缩放
Tween.Scale(transform, endValue: new Vector3(2, 1, 0.5f), duration: 0.5f); // 非均匀缩放

UI 动画

using PrimeTween;
using UnityEngine.UI;

// UI 位置和大小
Tween.UIAnchoredPosition(rectTransform, endValue: Vector2.zero, duration: 0.5f);
Tween.UIAnchoredPositionX(rectTransform, endValue: 100f, duration: 0.5f);
Tween.UISizeDelta(rectTransform, endValue: new Vector2(200, 100), duration: 0.5f);

// UI 颜色和透明度
Tween.Color(image, endValue: Color.red, duration: 1f);
Tween.Alpha(image, endValue: 0.5f, duration: 1f);

// CanvasGroup 透明度
Tween.Alpha(canvasGroup, endValue: 1f, duration: 0.3f);

Material 动画

using PrimeTween;

// Material 颜色
Tween.Color(material, endValue: Color.blue, duration: 1f);
Tween.Alpha(material, endValue: 0f, duration: 1f);

// 自定义属性颜色
Tween.Color(material, "_EmissionColor", Color.white, duration: 1f);

相机动画

using PrimeTween;

// 相机属性
Tween.OrthoSize(camera, endValue: 5f, duration: 1f);
Tween.FieldOfView(camera, endValue: 60f, duration: 1f);
Tween.BackgroundColor(camera, endValue: Color.black, duration: 2f);

// 相机震动
Tween.ShakeCamera(camera, strengthFactor: 0.5f); // 中等强度震动
Tween.ShakeCamera(camera, strengthFactor: 1.0f, duration: 0.5f, frequency: 10); // 强烈震动

文字动画

using PrimeTween;
using TMPro;

// TextMeshPro 颜色和透明度
Tween.Color(textMeshPro, endValue: Color.yellow, duration: 1f);
Tween.Alpha(textMeshPro, endValue: 0f, duration: 1f);

// 字体大小
Tween.FontSize(textMeshPro, endValue: 48f, duration: 0.5f);

// 打字机效果 (简单)
textMeshPro.ForceMeshUpdate();
int charCount = textMeshPro.textInfo.characterCount;
Tween.TextMaxVisibleCharacters(textMeshPro, 0, charCount, duration: 2f, ease: Ease.Linear);

2. 震动和冲击效果

using PrimeTween;

// 位置震动
Tween.ShakeLocalPosition(transform, strength: new Vector3(0, 1, 0), duration: 1f, frequency: 10);

// 旋转震动
Tween.ShakeLocalRotation(transform, strength: new Vector3(0, 0, 15), duration: 1f, frequency: 10);

// 缩放震动
Tween.ShakeLocalScale(transform, strength: Vector3.one * 0.5f, duration: 0.5f, frequency: 15);

// Punch 效果 (单向冲击)
Tween.PunchLocalPosition(transform, strength: transform.up * 2, duration: 0.5f, frequency: 10);

// 自定义震动
var shakeSettings = new ShakeSettings(
    strength: new Vector3(1, 1, 0),
    duration: 1f,
    frequency: 10,
    easeBetweenShakes: Ease.OutQuad
);
Tween.ShakeCustom(this, startValue: transform.localPosition, shakeSettings,
    (target, val) => transform.localPosition = val);

3. 回调和延迟

using PrimeTween;

// OnComplete 回调
Tween.Position(transform, endValue: new Vector3(10, 0), duration: 1f)
    .OnComplete(() => Debug.Log("Animation completed!"));

// 零分配回调 (推荐)
Tween.Position(transform, endValue: new Vector3(10, 0), duration: 1f)
    .OnComplete(target: this, (target) => target.SomeMethod());

// 延迟执行
Tween.Delay(duration: 1f, () => Debug.Log("Executed after 1 second"));

// 延迟调用方法 (零分配)
Tween.Delay(this, duration: 1f, target => target.SomeMethod());

// 带延迟的动画
Tween.Scale(transform, endValue: 0f, duration: 1f, endDelay: 0.5f)
    .OnComplete(target: this, target => Destroy(target.gameObject));

4. 循环动画

using PrimeTween;

// 无限循环
Tween.PositionY(transform, endValue: 10, duration: 0.5f, cycles: -1, cycleMode: CycleMode.Yoyo);

// 指定循环次数
Tween.Scale(transform, endValue: 2f, duration: 0.5f, cycles: 3, cycleMode: CycleMode.Yoyo);

// CycleMode 选项:
// - Restart: 从头重新开始
// - Yoyo: 往返动画
// - Incremental: 每次循环递增 endValue
// - Rewind: 时间倒流

5. 序列动画

using PrimeTween;

// 基础序列
var sequence = Sequence.Create()
    .Chain(Tween.PositionX(transform, 10f, duration: 1f))
    .Chain(Tween.Scale(transform, 2f, duration: 0.5f))
    .Chain(Tween.Rotation(transform, new Vector3(0, 90, 0), duration: 0.5f));

// 并行动画 (Group)
Sequence.Create()
    .Group(Tween.PositionX(transform, 10f, duration: 1f))
    .Group(Tween.Scale(transform, 2f, duration: 1f))
    .Chain(Tween.Rotation(transform, new Vector3(0, 90, 0), duration: 0.5f));

// 复杂序列
Sequence.Create(cycles: 2, CycleMode.Yoyo)
    .Group(Tween.PositionX(transform, 10f, duration: 1.5f))
    .Group(Tween.Scale(transform, 2f, duration: 0.5f, startDelay: 1f))
    .Chain(Tween.Rotation(transform, new Vector3(0f, 0f, 45f), duration: 1f))
    .ChainDelay(1f)
    .ChainCallback(this, target => Debug.Log("Animation completed"))
    .Insert(atTime: 0.5f, Tween.Color(image, Color.red, duration: 0.5f));

// 序列回调
Sequence.Create()
    .Chain(Tween.PositionX(transform, 10f, 1f))
    .ChainCallback(this, target => target.OnPositionComplete())
    .Chain(Tween.Scale(transform, 2f, 0.5f));

6. 协程和异步

using PrimeTween;
using System.Collections;

// 协程
IEnumerator CoroutineExample() {
    Tween.PositionX(transform, endValue: 10f, duration: 1.5f);
    yield return Tween.Scale(transform, 2f, 0.5f, startDelay: 1f).ToYieldInstruction();
    yield return Tween.Rotation(transform, new Vector3(0f, 0f, 45f), 1f).ToYieldInstruction();
    yield return Tween.Delay(1f).ToYieldInstruction();
    Debug.Log("Sequence completed");
}

// Async/Await
async void AsyncExample() {
    Tween.PositionX(transform, endValue: 10f, duration: 1.5f);
    await Tween.Scale(transform, endValue: 2f, duration: 0.5f, startDelay: 1f);
    await Tween.Rotation(transform, endValue: new Vector3(0f, 0f, 45f), duration: 1f);
    await Tween.Delay(1f);
    Debug.Log("Sequence completed");
}

7. 控制动画

using PrimeTween;

// 创建并存储 tween 引用
Tween tween = Tween.LocalPositionX(transform, endValue: 1.5f, duration: 1f);

// 检查是否存活
if (tween.isAlive) {
    Debug.Log($"Animation is running. Elapsed: {tween.elapsedTime}");
}

// 停止动画
tween.Stop();
Tween.StopAll(onTarget: transform);

// 完成动画
tween.Complete();
Tween.CompleteAll(onTarget: transform);

// 暂停/恢复
tween.isPaused = true;
Tween.SetPausedAll(true, onTarget: transform);
Tween.SetPausedAll(false, onTarget: transform);

// 手动设置进度
tween.elapsedTime = 0.5f;
tween.progress = 0.5f;
tween.timeScale = 2f;

// 设置剩余循环次数
tween.SetRemainingCycles(3);
tween.SetRemainingCycles(stopAtEndValue: true);

8. Inspector 集成

using PrimeTween;
using UnityEngine;

public class AnimationExample : MonoBehaviour {
    // 在 Inspector 中配置动画参数
    [SerializeField] TweenSettings<float> positionYTweenSettings;
    [SerializeField] TweenSettings<Vector3> rotationTweenSettings;
    [SerializeField] TweenSettings<Color> colorTweenSettings;
    [SerializeField] ShakeSettings cameraShakeSettings;

    public void PlayAnimation() {
        // 使用 Inspector 中配置的设置
        Tween.PositionY(transform, positionYTweenSettings);
        Tween.Rotation(transform, rotationTweenSettings);
        Tween.Color(material, colorTweenSettings);
        Tween.ShakeCamera(camera, cameraShakeSettings);
    }

    // 示例：使用 WithDirection 方法
    [SerializeField] RectTransform window;
    [SerializeField] TweenSettings<float> windowAnimationSettings;

    public void SetWindowOpened(bool isOpened) {
        Tween.UIAnchoredPositionY(window,
            windowAnimationSettings.WithDirection(toEndValue: isOpened));
    }
}

9. 自定义动画

using PrimeTween;

// 自定义 float 动画
float myFloatField;
Tween.Custom(0f, 10f, duration: 1f,
    onValueChange: newVal => myFloatField = newVal);

// 零分配方式
Tween.Custom(this, 0f, 10f, duration: 1f,
    (target, newVal) => target.myFloatField = newVal);

// 自定义 Color 动画
Color myColor;
Tween.Custom(Color.white, Color.black, duration: 1f,
    onValueChange: newVal => myColor = newVal);

// 自定义 Vector3 动画
Vector3 myVector;
Tween.Custom(Vector3.zero, Vector3.one, duration: 1f,
    onValueChange: newVal => myVector = newVal);

// 使用 TweenSettings
[SerializeField] TweenSettings<float> customTweenSettings;

void AnimateCustomField() {
    Tween.Custom(customTweenSettings,
        onValueChange: newVal => myFloatField = newVal);
}

10. 缓动函数

using PrimeTween;

// 使用标准 Ease
Tween.PositionY(transform, 10f, 1f, ease: Ease.InOutSine);
Tween.Scale(transform, 2f, 0.5f, ease: Ease.OutBounce);
Tween.Alpha(image, 0f, 1f, ease: Ease.InQuad);

// 使用 AnimationCurve
AnimationCurve customCurve = new AnimationCurve();
customCurve.AddKey(0, 0);
customCurve.AddKey(1, 1);
Tween.PositionY(transform, 10f, 1f, customCurve);

// 参数化缓动
Tween.PositionY(transform, 10f, 1f, Easing.BounceExact(1f)); // 精确反弹 1 米
Tween.PositionY(transform, 10f, 1f, Easing.Overshoot(2f));    // 强度 2 的过冲
Tween.PositionY(transform, 10f, 1f, Easing.Elastic(1f, 0.3f)); // 弹性效果

11. Update 类型

using PrimeTween;

// Update (默认)
Tween.PositionX(transform, 10f, 1f, new TweenSettings(duration: 1f, updateType: UpdateType.Update));

// LateUpdate (适用于相机跟随等)
Tween.PositionX(transform, 10f, 1f, new TweenSettings(duration: 1f, updateType: UpdateType.LateUpdate));

// FixedUpdate (适用于物理相关动画)
Tween.PositionX(transform, 10f, 1f, new TweenSettings(duration: 1f, updateType: UpdateType.FixedUpdate));

// Sequence UpdateType
Sequence.Create(updateType: UpdateType.LateUpdate);

12. 速度基础动画

using PrimeTween;

// 速度基础动画 (duration 会自动计算)
Tween.PositionAtSpeed(transform, endValue: targetPosition, speed: 10f);
Tween.LocalPositionAtSpeed(transform, endValue: targetPosition, speed: 5f);

// 链接速度基础动画需要指定 startValue
Vector3 midPos = new Vector3(5, 0, 0);
Vector3 endPos = new Vector3(10, 0, 0);
Tween.LocalPositionAtSpeed(transform, endValue: midPos, speed: 5f)
    .Chain(Tween.LocalPositionAtSpeed(transform, startValue: midPos, endValue: endPos, speed: 5f));

13. TimeScale 控制

using PrimeTween;

// 动画独立 timeScale
Tween tween = Tween.PositionY(transform, 10f, 1f);
tween.timeScale = 2f; // 2 倍速播放

// 动画 timeScale 动画
Tween tween = Tween.PositionY(transform, 10f, 1f);
Tween.TweenTimeScale(tween, 2f, 0.5f); // 将 timeScale 从 1 动画到 2

// 全局 Time.timeScale 动画
Tween.GlobalTimeScale(0.5f, 1f); // 慢动作效果

14. DOTween 迁移

// 启用 DOTween Adapter
// 在 Project Settings/Player/Script Compilation 中添加: PRIME_TWEEN_DOTWEEN_ADAPTER

// 替换 using
// using DG.Tweening;
using PrimeTween;

// API 映射:
// transform.DOMove(...)          -> Tween.Position(transform, ...)
// uiImage.DOFade(...)            -> Tween.Alpha(uiImage, ...)
// material.DOColor(...)          -> Tween.Color(material, ...)
// transform.DOShakePosition(...) -> Tween.ShakeLocalPosition(transform, ...)
// tween.SetEase(...)             -> Tween.Position(..., ease: ...)
// tween.SetLoops(...)            -> Tween.Position(..., cycles: ..., cycleMode: ...)
// tween.Kill(false)              -> tween.Stop()
// tween.Kill(true)               -> tween.Complete()
// DOVirtual.DelayedCall()        -> Tween.Delay()
// DOTween.To()                   -> Tween.Custom()
// DOTween.Sequence()             -> Sequence.Create()
// sequence.Join()                -> sequence.Group()
// sequence.Append()              -> sequence.Chain()

参考文件

此 Skill 包含完整的 PrimeTween 文档，位于 references/ 目录：

使用此 Skill

初学者

  1. 从简单的 Tween.Position/Rotation/Scale 开始
  2. 学习使用 Sequence.Create() 组合多个动画
  3. 了解 Ease 缓动函数的效果
  4. 使用 TweenSettings 在 Inspector 中调试动画参数

中级用户

  1. 使用 OnComplete 和 OnUpdate 回调
  2. 掌握 Group、Chain 和 Insert 的区别
  3. 使用协程或 async/await 管理复杂动画序列
  4. 理解零分配委托模式避免 GC

高级用户

  1. 自定义 Tween.Custom() 动画任意类型
  2. 使用参数化缓动 (Easing.BounceExact 等)
  3. 优化动画性能 (设置 PrimeTweenConfig.SetTweensCapacity)
  4. 从 DOTween 迁移现有项目

核心概念

PrimeTween 核心特性

  • 零 GC 分配: 运行时不会产生任何堆内存分配
  • 高性能: 专为性能优化，比 DOTween 快得多
  • Inspector 集成: 所有动画参数可在 Inspector 中调整
  • 类型安全: 使用 struct 而非 class，避免空引用异常
  • 不可重用: Tweens 完成后自动销毁，无需手动管理

Tween vs Sequence

  • Tween: 单个动画，返回 Tween struct
  • Sequence: 多个动画的组合，可以串行、并行或混合执行

内存分配注意事项

  • ❌ OnComplete(() => MyMethod()) - 闭包会分配内存
  • ✅ OnComplete(target: this, target => target.MyMethod()) - 零分配

推荐命名空间

using PrimeTween;

推荐编译选项

// 启用安全检查 (开发时)
#define PRIME_TWEEN_SAFETY_CHECKS

// 启用 DOTween 适配器 (迁移时)
#define PRIME_TWEEN_DOTWEEN_ADAPTER

// 启用实验性功能
#define PRIME_TWEEN_EXPERIMENTAL

资源

官方资源

Demo 场景位置

本地 Demo 场景位于 Assets/Plugins/PrimeTween/Demo/:

  • Demo.cs - 主 Demo 脚本
  • TypewriterAnimatorExample.cs - 打字机效果示例
  • CameraController.cs - 相机控制示例
  • MeasureMemoryAllocations.cs - 内存分配测量

常用 API 模式

// 基础动画模式
Tween.TweenType(target, endValue, duration, ease, cycles, cycleMode, startDelay, useUnscaledTime)

// TweenSettings 模式
Tween.TweenType(target, tweenSettings)

// 回调链模式
Tween.TweenType(...).OnComplete(...).OnUpdate(...)

// 序列模式
Sequence.Create().Chain(...).Group(...).Insert(...)

说明

  • 此 Skill 基于 PrimeTween v1.3.7 (2025-12-20)
  • 支持 Unity 2020.1+
  • 所有代码示例遵循 C# 编码规范
  • PrimeTween 与 DOTween 可以共存于同一项目中
  • 首次使用建议运行 Demo 场景了解功能

性能优势

PrimeTween 相比其他 Tween 库的优势：

  • 运行时零 GC 分配
  • 更快的动画执行速度
  • 无需缓存和重用 tweens
  • 自动资源清理
  • 更少的内存占用

此 Skill 基于 KyryloKuzyk/PrimeTween 的官方文档和示例生成。

Weekly Installs
3
Repository
ostrichhermit/o…v-skills
GitHub Stars
6
First Seen
13 days ago
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
openclaw3
gemini-cli3
github-copilot3
codex3
kimi-cli3
cursor3