YYKA Tween · Cocos Creator 缓动动画可视化编辑器

在 Cocos Creator 里用时间轴 + 关键帧 + 缓动曲线做动画，点一下导出可直接运行的 Tween 代码——不用再手写 tween().to().delay().repeat()。

编辑器内所见即所得：拖动关键帧、实时预览、切播放模式（循环 / 反向 / 往返）、有限或无限循环，全部对着场景里的真实节点做，停止后节点属性自动还原。

✨ 功能特性

1. 时间轴可视化编辑

  • 一条属性轨道 = 一个属性：位置 Position / 缩放 Scale / 旋转 Rotation（完整支持，预览与导出都走引擎节点原生属性）；透明度 Opacity / 颜色 Color（可编辑、可存档，导出产物仍在补齐组件驱动，见 FAQ Q5）。
  • 「添加属性」一键加轨道；新轨道 0s 的关键帧取的是该节点当前的真实值（位置/缩放/旋转直读节点；透明度读 UIOpacity、颜色读渲染组件），不会一律从 0 开始。
  • 多节点同台编辑：一个 clip 可以放多个目标节点，左侧「节点」列切换正在编辑的节点；每个节点各自持有自己的属性轨道，导出时一节点一份脚本。
  • 点轨道空白处加关键帧，按住菱形左右拖动改时间（0.05 秒吸附网格，不会拖出脏小数）。
  • 每条轨道内直接画出该段的缓动曲线，拐点、回弹、弹跳一眼可见。
  • 播放头（红线）可拖动，场景节点同步对位到当前帧，逐帧抠动画很方便。
  • 滚轮横向滚动时间轴，Ctrl + 滚轮缩放（8–240 像素/秒）。
  • 拖节点自动打关键帧：在场景里拖动节点（gizmo）松手即记录；若当前选中了同一节点、同一属性的关键帧就改写它（时间与缓动都沿用你选好的），没选中才在播放头新增。
  • 点左侧节点列 = 单选同步：面板切到哪个节点，编辑器里就单选选中哪个节点（层级管理器/场景高亮同步，拖 gizmo 只动它）。

2. 关键帧属性编辑

点选关键帧后，右上角「关键帧属性」浮窗里改它的一切：

  • 时间（数值 + 吸附）
  • 数值：旋转/透明度是单值；位置/缩放是 X·Y·Z 三个分量；颜色是官方取色器（RGBA）
  • 缓动：31 个内置缓动预设 + 自定义三次贝塞尔（x1 / y1 / x2 / y2 可调）
  • 删除关键帧（独立一行，不会误点）

内置缓动覆盖：linear、quad / cubic / quart / quint / sine / expo / circ / back / bounce / elastic 的 In / Out / InOut 共 31 档。

3. 编辑器内实时预览

  • 播放 / 暂停（空格）、上一帧 / 下一帧（← / , 与 → / .），播放中按钮状态自洽。
  • 预览直接驱动场景里的目标节点，停止或切节点后自动还原节点原始属性，不会把你的场景摆乱。
  • 起播延时（Delay）期间一个属性都不写，节点保持进场原状 —— 与导出代码的 .delay(d) 行为完全一致。

4. 五种播放模式（对齐引擎 cc.animation.WrapMode）

模式 表现
Normal 正常 正向播放一遍，停在末帧
Reverse 反向 从末帧反向播放回首帧
Loop 循环 正向循环播放
LoopReverse 反向循环 反向循环播放
PingPong 往返 正放到底 → 倒放回首 → 如此往复（一圈 = 两倍单遍时长）

5. 有限循环 / 无限循环

循环类模式下可自由选择：

  • 无限 → 导出 .repeatForever()
  • 有限 N 遍 → 导出 .repeat(n)（n 是一共执行几遍，含第一遍，与引擎 Repeat 的语义一致）

时间轴右上角与导出面板两处都能改，写的是同一份数据。

6. 一键导出可运行代码（两种模式）

  • 函数模式：生成一个 play(node) 函数，直接复制粘贴进你自己的脚本调用。可选：函数名、节点参数名、是否 return 返回 tween 实例（不自动 start）、是否带 onStart / onComplete 回调占位、起播延时。
    • 单节点时签名就是 play(node: Node)，你直接把节点传进去即可；多节点时生成 play(node: Record<string, Node>)，并在代码里用注释标出每个 uuid 对应哪个节点。
  • 脚本模式 —— 一个节点一份独立脚本：每个目标节点各自生成一个组件类（@ccclass + start/onDestroy/TweenPlay/TweenStop），脚本名自动取 节点名 + _tween（例如 Panel_tween、Icon_tween；节点名里的空格/短横线自动安全化，重名节点自动加 _2）。可选：组件启动时自动播放、是否带回调、是否挂载、起播延时。
    • 每个脚本只作用于自己挂着的那个节点（tween(this.node)）——挂哪个节点就动哪个，不需要 uuid、也不在场景里搜节点。
    • 保存位置：assets/scripts/tween_anim/<脚本名>.ts，保存后自动刷新资源（返回 db:// 地址）。
    • 保存并挂载：勾选后每个脚本各自挂到各自的节点上；挂载按类名去重，反复导出不会越挂越多（历史遗留的重复副本会被收敛为 1 个）。
  • 代码区语法高亮（关键字 / 字符串 / 数字 / 注释 / 引擎 API / 方法名分色）且文字可选可复制，一键复制到剪贴板；脚本模式有多份脚本时，代码区上方列出文件名，点一下切换预览与复制哪一份。

7. 生成规则贴着引擎原生写法

  • 一条属性轨道 = 一条独立 tween 链，多轨道 .parallel() 并行：每条轨道保留自己的段边界与缓动，长度不够由引擎自动补位（不会像"按时间网格统一切段"那样把缓动曲线切变形）。
  • 每一遍开头 .set(首帧值) 锚定绝对值：否则循环第二遍起 to() 的起点=上一遍终点，动画会原地不动。
  • 反向 / 往返按关键帧镜像生成（段序倒置 + 首末值互换 + 缓动取镜像 g(t)=1-f(1-t)），没有用引擎那个对绝对 to() 无效的 reverseTime()。
  • 全程链式、不产生 sequence(...) 包装：循环体聚成 _cycle 常量后用引擎自带的 .then(_cycle) 接上（这也是官方文档推荐的写法）。

8. 动画库（存档复用）

  • 把当前动画命名存档到插件目录 yyka-tween-clips/*.json（纯关键帧 JSON，不含任何素材），可跨场景、跨项目载入复用。
  • 列表式管理：载入 / 删除。
  • 载入会自动对账：场景节点的 uuid 只在编辑器会话内稳定（节点没随场景保存就重开、或节点来自 prefab 实例化，id 都会换），载入时按 uuid → 层级路径 → 唯一节点名 重新绑定回对应节点；对不上的会明确提示"哪个节点在场景里找不到"，绝不把动画悄悄套到别的节点上。
  • 内置 4 个预设：呼吸缩放、弹跳、左右晃动、循环旋转，一键套用到当前节点。
    • 预设按"基准值"编写（位置 0 / 缩放 1 / 旋转 0 / 透明度 1 / 颜色 1），套用时落到节点当前值上：位置/旋转相加、缩放/透明度/颜色相乘 —— 所以模板在任何位置、任何缩放的节点上都成立（缩放 2 倍的节点套"呼吸"仍然是起伏 12%）。
    • 同属性替换、不同属性并入：往已有位置轨道的节点上套「呼吸缩放」，只会替换缩放轨道，不会抹掉位置那一份。

9. 预览所见 = 导出所得

预览（场景进程）与导出（代码生成）读的是同一份 clip 数据、同一套播放模式语义，并有自动化测试逐帧比对「生成代码在引擎里跑出来的值」与「预览映射出来的值」——包括五种模式、有限次数循环、组件模式、以及"去掉锚定就会跑飞"的负向对照。

📋 使用说明

安装与启用

  1. 把 yyka-tween 扩展目录放到：
    • 项目级：<你的项目>/extensions/
    • 全局级（Windows）：%USERPROFILE%\.CocosCreator\extensions\
    • 全局级（macOS）：~/.CocosCreator/extensions/
  2. 重启 Cocos Creator，或使用菜单 开发者 → 重新加载扩展。
  3. 扩展已内置运行依赖，无需 npm install。

打开面板

顶部菜单：YYKA插件 → 缓动动画编辑 → 默认面板。
面板标题为「YYKA缓动编辑」，默认停靠在编辑器内置「动画编辑器」的同一停靠区（也可以把它拖到任意停靠位）。

五步上手

  1. 添加节点：在场景或层级管理器里选中节点 → 点时间轴左上角「+ 添加节点」；如果没取到选中节点，会直接把场景节点列出来让你点选。要编辑另一个节点，就在左侧「节点」列点它 —— 面板切过去的同时，编辑器里也会单选选中该节点（拖 gizmo 只动它）。
  2. 加属性轨道：左侧「属性」列点「添加属性」→ 选 位置 / 缩放 / 旋转 / 透明度 / 颜色。新轨道 0s 的关键帧取的是节点当前值。
  3. 打关键帧：在轨道行空白处点击即可加帧（时间自动吸附 0.05s）；按住菱形拖动改时间；点选菱形后，右上角「关键帧属性」浮窗改数值与缓动。也可以直接在场景里拖动节点，松手即自动记录。
  4. 选播放模式 + 预览：顶栏选 Normal / Reverse / Loop / LoopReverse / PingPong；循环类模式再选「无限」或「有限 N 遍」；按空格播放预览。
  5. 导出：点「导出」→ 选「函数」页或「脚本」页 → 「复制」或「保存脚本」。

时间轴操作速查

操作 方式
添加节点 左侧「节点」列点「+ 添加节点」（取当前选中节点；取不到时列出场景节点点选）
切换编辑节点 点左侧「节点」列的某一行（编辑器选中同步单选）
添加属性轨道 左侧「属性」列「添加属性」→ 选属性
删除属性轨道 轨道行右侧 ×
添加关键帧 在轨道行空白处点击
移动关键帧 按住菱形左右拖动（0.05s 吸附）
编辑关键帧 点击菱形 → 右上角属性浮窗（时间 / 值 / 缓动 / 贝塞尔 / 删除）
拖动播放头 按住红色播放头横拖（场景同步对位）
缩放时间轴 Ctrl + 滚轮（8–240 像素/秒）
横向滚动 滚轮
播放 / 暂停 空格 或 ▶ 按钮
上一帧 / 下一帧 ← / , 与 → / .

播放模式与循环次数

播放模式 时间轴预览 导出产物
Normal 正常 正向一遍，停末帧 正向那一遍直接接在链上（无重复调用）
Reverse 反向 从末帧倒放回首帧 反向那一遍直接接在链上
Loop 循环 t = e % D .then(_cycle) + .repeatForever() / .repeat(n)
LoopReverse 反向循环 反向后循环 同上（循环体是反向那一遍）
PingPong 往返 周期 2D，后半段镜像 .then(_cycle) + 同上（循环体 = 正放一遍接着倒放一遍）
  • 「起播延时」只作用一次、不参与循环；「onComplete」只在有限次数播完时触发。
  • 往返与循环的区别：单向动画（例如 0 → 255 一段）时，循环是"到顶瞬跳回起点再往上"，往返是"原路退回"；如果动画本身首尾同值（例如 0 → 255 → 0），倒放之后与正放完全一样，这时两种模式看起来才会一致（数学必然，不是缺陷）。

导出示例（真实产物）

示例里的节点叫 Panel，脚本名就自动是 Panel_tween（节点名 + _tween）。脚本模式是一个节点一份，每个脚本只作用于自己挂着的那个节点。

循环（无限）——组件脚本模式：

生成的代码只有 import { ... } from 'cc'，无任何第三方依赖、无运行时框架，可直接进项目。

导出参数说明

页签 参数 说明
函数 函数名 生成的函数名，默认 play
函数 节点参数 函数第一个参数名，默认 node
函数 返回实例 勾选后 return tween 实例、不自动 start()（方便你自己控制停止/暂停）
函数 / 脚本 含回调 生成 onStart / onComplete 回调占位（可直接写代码）
函数 / 脚本 延时 (s) 起播延时，只作用一次、不进循环
脚本 脚本名 自动取「节点名 + _tween」（如 Panel_tween），不需要填；重名节点自动加 _2
脚本 组件启动时自动播放 在 start() 里自动播放；关闭则只提供 TweenPlay() 供你手动调用
脚本 保存后各自挂到各自节点上 每个节点的脚本分别挂到它自己的节点（不勾选则只保存脚本）；挂载按类名去重
两页共用 播放模式 只读展示，来自时间轴（预览与导出同一个值）
两页共用 循环次数 无限 / 有限 N 遍（循环类模式才有）

动画库（存档复用）

  • 保存：给当前动画命名 → 存到插件目录 yyka-tween-clips/<名称>.json。
  • 载入：列表里点「载入」，会把动画按 uuid → 层级路径 → 唯一节点名 对账回场景里的节点（节点显示名用节点真实名称，不会出现 uuid）；对不上会在提示里点名是哪个节点找不到。
  • 删除：列表内直接删除。
  • 预设：呼吸缩放 / 弹跳 / 左右晃动 / 循环旋转，一键套到当前节点（按基准值换算到节点当前值；同属性替换、不同属性并入）。

⚙️ 引擎与环境要求

项目 要求
Cocos Creator 3.8.8 及以上（package.json 中 editor: ">=3.8.8"）
类型 编辑器扩展（含面板 + 场景脚本），不是运行时组件，构建发布时可按需移除
第三方依赖 无。vue3 由编辑器提供、fs-extra 已随扩展打包，不需要 npm install
生成代码依赖 仅 cc 原生 tween / Node / Vec3 / Color / Tween，无自定义运行时
网络 全程本地：预览、导出、存档都在本机完成，不联网、不上传任何素材
磁盘写入 仅两处：导出的脚本 assets/scripts/tween_anim/、动画存档 <扩展目录>/yyka-tween-clips/

🖥️ 平台支持情况

平台 支持情况
Windows + Cocos Creator 3.8.8+ ✅ 完整支持（编辑器扩展在编辑器进程内运行）
macOS + Cocos Creator 3.8.8+ ✅ 完整支持
Cocos Creator 3.7 及更早 ❌ 不支持（面板与场景脚本使用了 3.8 的扩展 API 与 Tween.then）
项目类型 ✅ 2D / 3D 项目均可（动画作用在节点上，与项目是 2D 还是 3D 无关）
目标平台（Web / 原生 / 小游戏） ✅ 生成的是标准 Tween 代码，运行时与目标平台无关

📜 更新日志

v1.0.0（首次发布）

  • 时间轴可视化编辑：属性轨道（位置 / 缩放 / 旋转 / 透明度 / 颜色）、关键帧增删拖动（0.05s 吸附）、轨道内缓动曲线预览。
  • 关键帧属性浮窗：时间、数值（单值 / X·Y·Z / 取色器）、缓动（31 档预设 + 自定义三次贝塞尔）、删除关键帧。
  • 编辑器内实时预览：播放 / 暂停（空格）、上一帧 / 下一帧、拖动播放头对位；停止后自动还原节点属性；起播延时期间不写属性。
  • 五种播放模式（Normal / Reverse / Loop / LoopReverse / PingPong），与 cc.animation.WrapMode 对齐，预览与导出同源。
  • 有限循环与无限循环：无限 → .repeatForever()；有限 N 遍 → .repeat(n)。
  • 代码导出两种模式：函数模式（函数名 / 节点参数 / 返回实例 / 回占位 / 延时）与脚本模式（一节点一份独立脚本，名字 = 节点名 + _tween，各自挂到各自节点），保存到 assets/scripts/tween_anim 并自动刷新资源。
  • 多节点同台编辑：一个 clip 可编排多个目标节点，左侧节点列切换；每节点独立轨道。
  • 拖节点自动关键帧：场景里拖动节点松手即记录；选中同属性关键帧时改写它，否则在播放头新增。
  • 点节点列 = 编辑器单选同步：面板切节点时编辑器里同步单选该节点（不形成多选）。
  • 添加属性取当前值：新轨道首个关键帧取节点当前真实值（位置/缩放/旋转读节点，透明度读 UIOpacity、颜色读渲染组件）。
  • 载入存档自动对账：uuid → 层级路径 → 唯一节点名 三级重新绑定，对不上如实提示。
  • 预设套用按属性语义落到当前值：位置/旋转相加、缩放/透明度/颜色相乘；同属性替换、不同属性并入。
  • 导出挂载去重：同一节点同名组件只保留一个。
  • 代码区语法高亮 + 文字可选可复制 + 一键复制。
  • 动画库：命名存档 / 载入 / 删除，内置 4 个动画预设。
  • 生成规则：一条轨道一条 tween 链（多轨道 .parallel()）、每遍 .set() 锚定、反向按关键帧镜像、全程链式（.then）不出现 sequence()。
  • 自动化测试：五种播放模式逐帧等价性、缓动表与引擎公式逐点一致、生成产物全部过 tsc。

❓ 常见问题 FAQ

Q1. 为什么循环播放第二遍之后节点不动了？
导出代码里每一遍开头都有 .set(首帧值) 锚定绝对值，循环才成立。如果你手动把这一行删掉，to() 的起点会变成"上一遍结束时的值"，第二遍就会原地不动——工具里有专门的负向对照测试钉住这个行为。

Q2. 我把播放模式设成「往返」，为什么看起来和「循环」一模一样？
先看你的动画是不是首尾同值（比如 0 → 255 → 0 这种上去再回来的）。首尾同值的动画，倒放之后和正放完全一样，往返与循环本来就该长得一样，这是数学必然，不是 bug。想直观看出差别，用单向动画试（比如 0 → 255 一段或 0° → 360° 旋转）：循环是到顶瞬跳回起点，往返是原路退回。

Q3. 导出面板里脚本模式有「延时」吗？
有。「延时 (s)」在参数列里，函数模式与脚本模式共用同一个值，并且和时间轴预览用的是同一份数据（改完预览也跟着变）。延时只作用一次、不参与循环。

Q4. 为什么反复导出会挂一堆重复的组件？
当前版本已经处理：保存脚本并挂载时，会在场景进程里用引擎 API 精确判断该节点上是否已有同类组件，只保留一个，历史上重复挂载的多余副本也会被收敛掉。如果节点上仍有重复，请确认扩展已重载（编辑器菜单：开发者 → 重新加载扩展）。

Q5. 支持哪些属性轨道？

  • 位置 Position / 缩放 Scale / 旋转 Rotation：完整支持。预览与导出都作用在引擎节点的原生属性上（position / scale / angle）。
  • 透明度 Opacity / 颜色 Color：这两条轨道目前可以在时间轴与关键帧浮窗里编辑、存档、并生成代码，但导出产物写的是节点属性，而引擎 3.8 的 Node 上并没有 opacity / color（tween-action 对不存在的属性会静默跳过，不会报错）。其中颜色轨道在编辑器预览里能通过节点的渲染组件显示，透明度轨道在预览与导出里都还没生效。
    结论：当前版本请以位置 / 缩放 / 旋转为主；这两条轨道的组件驱动（UIOpacity / 渲染组件）正在补齐。

Q6. 能编辑自定义组件上的属性吗（例如 Sprite.fillRange）？
当前版本提供的是位置 / 缩放 / 旋转 / 透明度 / 颜色五类常用轨道，自定义组件属性尚未开放，已列入后续规划。

Q7. 关键帧时间可以更精确吗？数值小数位呢？
时间按 0.05 秒吸附（避免拖出 0.30000000000000004 这类脏值）；数值按你填写的值原样保存，导出代码里统一按最多 6 位小数输出，不会出现一长串浮点尾巴。

Q8. 循环次数填 3，是"再播 3 次"还是"一共 3 遍"？
一共 3 遍（含第一遍），与引擎 Repeat 的语义一致。填 1 等于不循环，只播一遍。

Q9. 动画存档放在哪？会不会跟着项目走？会不会上传？
存档是纯关键帧 JSON，落在扩展目录下的 yyka-tween-clips/。它不包含任何图片/音频素材，也不会上传——插件全程本地运行、不联网。

Q10. 打开面板后为什么出现在「动画编辑器」旁边？
面板默认停靠在编辑器内置动画编辑器的同一停靠区，方便对照使用；你可以把它拖到任意停靠位置，下次仍按编辑器自己的布局记忆。

Q11. 预览会不会把我场景里的节点属性改坏？
不会。预览会先记录本次动画涉及属性的原始值，停止预览或切换节点时逐个还原。

Q12. 生成的代码能在构建 / 原生 / 小游戏里跑吗？
能。生成的是标准 cc.tween 代码，只用引擎原生 API，与目标平台无关。

Q13. 载入存档后，我的动画跟场景里的节点对不上了怎么办？
场景节点的 uuid 只在这次编辑器会话里稳定：节点如果没随场景保存就重开编辑器、或者节点是从 prefab 实例化出来的，id 会换一批，存档里记的 id 自然就找不到。插件在载入时会自动对账：先按 uuid 找，找不到就用层级路径（如 Canvas/ui_主标题文字）、再退到唯一的节点名重新绑定；名字重名、或者节点确实没了，会在提示里点名说"哪个节点在场景里找不到"，不会把动画悄悄套到别的节点上。想少遇到这种情况：把节点随场景保存一下再重开。

Q14. 点左侧节点列，编辑器为什么会跟着选中那个节点？
这是刻意的：面板当前编辑的节点和编辑器选中的节点保持一致，你在场景里拖 gizmo 时会只动这一个节点（不会出现"一拽好几个跟着走"）。切换节点时编辑器里是单选，不会累积成多选。

⚠️ 购买须知

本产品为付费虚拟插件商品，一经购买成功概不退款，请支付前谨慎确认购买内容。

购买后获得对应版本授权，仅限授权范围内使用；
插件仅支持标注的 Cocos Creator 版本，请确认引擎版本符合要求再下单；
不包含定制开发服务，如有定制需求可单独咨询；
严禁二次分发、转售、反编译本插件。

📞 联系我们

如遇问题、有定制需求或希望增加动画 / 功能，欢迎联系作者：

官网：https://www.yyka.cn
邮箱：yykacn@qq.com
公众号：智能运营咖

关键词

Cocos Creator 插件、Cocos Creator 3.8、tween、缓动动画、动画编辑器、时间轴、关键帧、缓动曲线、贝塞尔、代码导出、可视化动画、Tween 代码生成、循环动画、往返动画、2D 动画、UI 动画

感谢用户的内容

感谢每一位购买与反馈的朋友。

这个插件的起点很朴素：手写 tween().to().delay().repeat() 调动画太慢——时间靠猜、缓动靠试、循环顺序第二遍不对还得回头改代码。所以我们把它做成了时间轴：拖、看、导出。

上线后收到的反馈（尤其是"预览和导出的效果不一致""往返怎么和循环一样""怎么越导出挂的组件越多"这类较真的问题）都被逐条查到底、补进自动化测试里了。有想加的功能或觉得哪里别扭，随时找我们——你的使用场景，就是下一版的路线图。