add cc.tween #3660

2youyou2 · 2018-12-20T10:44:41Z

Changes:

add cc.tween to simplify action creation

Use Cases

// run a sequence action

// node.scale === 1
var node = cc.find('Canvas/cocos');

cc.tween(node)
  .to(1, {scale: 2})      // node.scale === 2
  .call( () => { console.log('This is a callback.') } )
  .by(1, {scale: 2})      // node.scale === 4
  .start()

// run tween on a simple object
var obj = { a: 0 }
cc.tween(obj)
  .to(1, { a: 100 })
  .start()

// run tween on different target
var tween = cc.tween()
  .to(4, { 
    scale: 2
  })

tween.clone(cc.find('Canvas/cocos')).start()
tween.clone(cc.find('Canvas/cocos2')).start()

// easing

// builtin easing
cc.tween().to(1, { scale: 2 }, { easing: 'sineOutIn'})

// custom easing
cc.tween().to(1, { scale: 2 }, { easing: (t) => { return t*t; }})

// easing to single property
cc.tween().to(1, { scale: 2, position: { value: cc.v3(100, 100, 100), easing: 'sineOutIn' } })

// custom property progress
cc.tween().to(1, { scale: 2}, { 
  progress: (start, end, current, t) => { 
    return start + (end - start) * t; 
  }
})

// custom property progress to single property
cc.tween().to(1, { 
  scale: 2, 
  position: {
    value: cc.v3(),
    process: (start, end, current, t) => { 
      return start.lerp(end, t, current); 
    }
  }
})

// reuse 
let scale = cc.tween().to(1, { scale: 2 })
let angle = cc.tween().to(1, { angle: 90})
let position = cc.tween().to(1, { position: cc.v3(100, 100, 100)})

let sa = cc.tween().then(scale).then(angle)
let sp = cc.tween().then(scale).then(position)

jareguo · 2018-12-20T12:19:22Z

干嘛不叫 tween，避免和 animation 以及将来可能的 animator 混淆。
另外建议可以在构造时指定 target 并且默认 run。

let action1 = cc.animate(node).to(4, {
    scale: 2
});
let action2 = action.clone(node);

另外 run 建议叫做 start，因为通常还需要有 stop，start 和 stop 比较好对应。

jareguo · 2018-12-20T12:34:45Z

还有一种更简单的 tween 实现方式是，只给用户返回一个进度值( 0~1 )，由用户自行对那个值进行计算。如

let fromScale = node.scale;
let action = cc.tween(curveOrEase, progression => {
  this.scale = cc.lerp(fromScale, 2, progression);  // 相当于 to 2
  this.scale = fromScale * cc.lerp(1, 2, progression);  // 相当于 乘 2
  this.scale = fromScale + cc.lerp(0, 2, progression);  // 相当于 加 2
}, node);

curve 可以暴露到编辑器中在属性检查器里进行设置。也可以传入 ease 函数。如果省略，则默认是 linear。
action 最好继承自 AnimationState，这样就能让用户额外控制播放、暂停、wrapMode。
最后一个 node 参数可选，如果指定了，则 node 或组件销毁时动效也会跟着销毁。

jareguo · 2018-12-20T12:27:04Z

cocos2d/actions/animate.js

+     * @param {Object} props - {scale: 2, position: cc.v3(100, 100, 100)}
+     * @param {Object} opts 
+     */
+    to (duration, props, opts) {


props 放在 duration 前面不是更好看吗？

所有 action 都是以 duration 开始的

jareguo · 2018-12-20T12:29:25Z

cocos2d/actions/animate.js

+     * @param {*} props - {scale: 2, position: cc.v3(100, 100, 100)}
+     * @param {*} opts 
+     */
+    by (duration, props, opts) {


支持乘法的话，也应该支持加法才对，要不然就都不要支持。

by 的意思是 props 里指定的值是相对于 target 初始值来计算的，没有乘法加法的区分
比如 vec3 会用 vec3.add，而 quat 则应该用 quat.mul，更奇葩的就应该自己定义 progress 了

这就有点 hack 了吧…… 这样的规则很难一眼看出来。而且如果我想要放大一倍的话，vec3 是需要乘法而不是加法的。

2youyou2 · 2018-12-20T13:34:36Z

默认 run。

这样只能处理第一个 action ，后面想再接 action 的时候就不知道要什么时候才应该结束了

处理不了这样的需求

cc.animate()
  .to(...)
  .to(...)
  .by(...)

只给用户返回一个进度值( 0~1 )，由用户自行对那个值进行计算

这个需求添加一个 action 或者用户自己实现就可以了，而且现在已经有提供了很方便的自定义方法了，你可以自定义 easing 或者 progress 方法

action 最好继承自 AnimationState

这个工程就太大了

2youyou2 · 2018-12-20T14:33:44Z

@pandamicro
这种多 properties 并行的处理应该是比之前更快才对。
之前需要创建多个 action，这样就会计算多次时间，而现在只需要计算一次时间，这个时间比判断 properties 消耗肯定要更大

jareguo · 2018-12-21T04:33:26Z

这个没问题吧？所有 action 都应该是在 update 和 lateUpdate 之间触发的。所以不可能在用户的代码定义时就生效，而是异步的（等待半帧）

by 的意思是 props 里指定的值是相对于 target 初始值来计算的，没有乘法加法的区分
比如 vec3 会用 vec3.add，而 quat 则应该用 quat.mul，更奇葩的就应该自己定义 progress 了

// reuse
let scale = cc.animate().to(1, { scale: 2 })
let angle = cc.animate().to(1, { angle: 90})
let position = cc.animate().to(1, { position: cc.v3(100, 100, 100)})
let sa = cc.animate().add(scale).add(angle)
let sp = cc.animate().add(scale).add(position)

感觉 by 的含义还是要再澄清下。否则用户想要做加法的话，第一直觉就是调用 add ……，容易混淆。
建议把 by 就简化成 mul，乘法操作。add 就是加法。action 之间的串联，改成 .then

sp.clone().then(scaleTo).then(moveTo);

2youyou2 · 2018-12-21T06:08:18Z

这个没问题吧？所有 action 都应该是在 update 和 lateUpdate 之间触发的。所以不可能在用户的代码定义时

默认 run 的话，那如果我要 init 时创建一个 tween 缓存住，并不想现在就运行，而是每次 click 时再去执行这个 tween 要怎么做？

感觉 by 的含义还是要再澄清下。否则用户想要做加法的话，第一直觉就是调用 add ……，容易混淆。
建议把 by 就简化成 mul，乘法操作。add 就是加法。action 之间的串联，改成 .then

有点道理

jareguo · 2018-12-22T07:44:09Z

默认 run 的话，那如果我要 init 时创建一个 tween 缓存住，并不想现在就运行，而是每次 click 时再去执行这个 tween 要怎么做？

所以才建议实现和 AnimationState 一样的 API。通常 tweening 都是支持 pause/play 什么的。

pandamicro · 2018-12-24T02:23:07Z

感觉 by 的含义还是要再澄清下。否则用户想要做加法的话，第一直觉就是调用 add ……，容易混淆。
建议把 by 就简化成 mul，乘法操作。add 就是加法。action 之间的串联，改成 .then

我也赞同把 add 改为 then，但是这样就不需要 add 和 mul 了，核心 API 就：to, by, then

pandamicro · 2018-12-24T02:30:03Z

cocos2d/actions/animate.js

+        }
+
+        this._originProps = props;
+		this.initWithDuration(duration);


indent issue

pandamicro · 2018-12-24T02:50:16Z

cocos2d/actions/animate.js

+};
+
+// action constructors
+let constructors = {


为什么需要把这些 constructors 也放到 cc.Animate 下面？

这些本来就不应该放到 cc 下的，cc 下的东西太多了，希望能把 cc.moveTo 等都干掉放到这下面来访问

pandamicro · 2018-12-24T02:51:28Z

cocos2d/animation/easing.js


-cc.Easing = module.exports = Easing;
+cc.easing = module.exports = easing;


这个修改要在 deprecated 里面做兼容

pandamicro · 2018-12-24T02:53:29Z

cocos2d/actions/animate.js

+            else {
+                prop.start = value.clone();
+                prop.current = value.clone();
+                prop.end = relative ? (value.add || value.mul).call(value, prop.value) : prop.value;


这个地方的处理感觉有点随意啊，对 props 的兼容性可能会有问题，另外，value.add 和 mul 也可能都不存在

ctor 里有检测类型啦！

if (!isNumber && (!value.lerp || (!value.add && !value.mul) || !value.clone)) { cc.warn(`Can not animate ${name} property, because it do not have [lerp, (add|mul), clone] function.`); continue; }

pandamicro · 2018-12-24T02:55:31Z

另外，能不能展示一下 sequence 和 repeat 在 Animate 下的使用

pandamicro · 2018-12-24T02:56:25Z

还有反向的结合，比如用户用

var action = cc.sequence(moveTo, cc.animate(...))

这样的用法有没有什么限制？

jareguo · 2018-12-24T07:49:27Z

但是这样就不需要 add 和 mul 了，核心 API 就：to, by, then

用户自己的 prop，怎么区分要加还是要乘？比如就一个 number 的话。

2youyou2 · 2018-12-24T08:10:33Z

用户自己的 prop，怎么区分要加还是要乘？比如就一个 number 的话。

没看到其他 tween 还有分 add 和 mul 的

另外，能不能展示一下 sequence 和 repeat 在 Animate 下的使用

cc.animate()
  .to(...)
  .by(...)
  .repeat(5)

这里 to 和 by 会组合成一个 sequence，repeat 会对这个 sequence repeat 5 次

var action = cc.sequence(moveTo, cc.animate(...))

cc.animate 创建的是 Animate 类，不是 action，你这里应该这样使用

cc.animate()
.to()
.then(cc.animate()...)

pandamicro · 2018-12-24T08:27:11Z

所以反向在 cc.sequence，cc.repeat 等 API 中，无法使用 cc.Animate 是吗？

jareguo · 2018-12-24T09:21:52Z

用户自己的 prop，怎么区分要加还是要乘？比如就一个 number 的话。

没看到其他 tween 还有分 add 和 mul 的

其它根本就不支持 by，只有一个 to，所以就没区分了……

pandamicro · 2018-12-24T11:38:58Z

这个 add 和 mul 函数的使用还是很奇怪，要么就都是 add 对应 lerp，什么情况下需要 mul ？
需要 mul 的情况可以都让用户自己写 progression

jareguo · 2018-12-25T03:23:07Z

什么情况下需要 mul ？
需要 mul 的情况可以都让用户自己写 progression

视觉上主要是缩放的时候（缩小到 0.5 倍）、修改透明度的时候（透明度变成原先的 0.5）。

2youyou2 · 2018-12-25T06:29:38Z

要么就都是 add 对应 lerp，什么情况下需要 mul

quat 就没有 add 这个函数，只有 mul，还有 mat，如果要做一个四元数的相对旋转，就要用 mul 来计算

所以反向在 cc.sequence，cc.repeat 等 API 中，无法使用 cc.Animate 是吗

原来 action 可以支持的，cc.animate 都可以使用，最不济就是用 .then 来串联原来的 action

jareguo · 2018-12-27T09:01:19Z

嗯，我不是很纠结 by/mul/add，都可以的。

jareguo · 2019-01-15T13:55:32Z

这个 PR 后续还需要更新吗？如果需要的话，麻烦补充一下文档和范例！

2youyou2 · 2019-01-16T03:16:51Z

会更新，暂时没时间

pandamicro · 2019-02-12T09:47:47Z

cocos2d/actions/tween.js

+        }
+
+        this._originProps = props;
+		this.initWithDuration(duration);


indent issue

pandamicro · 2019-02-12T09:56:48Z

cocos2d/actions/tween.js

+ * !#en
+ * Provide a simple and flexible way to create action
+ * !#zh
+ * 提供了一个简单灵活的方法来创建 action


文档强调啊一下 tween 的使用场景，比如是否可以和 cc.sequence, cc.spawn 混用，是否支持 .easing 接口，是否支持用户自定义属性等。

pandamicro · 2019-02-12T10:07:47Z

cocos2d/actions/tween.js

+ * @method get
+ * @return Action
+ */
+Tween.prototype.get = function () {


这个 API 在什么时候有用？感觉完全不需要啊

内部需要，可以把 api 注释去掉并改为内部方法

没看到哪里有用到

搜一下 this._get

pandamicro · 2019-02-12T10:09:36Z

cocos2d/actions/tween.js

+ *   .by(1, {scale: 3, position: cc.v3(200, 200, 200)}, {easing: 'sineOutIn'})
+ *   .run(cc.find('Canvas/cocos'));
+ */
+function Tween (target) {


如果 run 的时候必须传递 target，那么在构造的时候传递 target 的意义是什么？

run 改为 start/stop 了，start 也不需要传 target 了

pandamicro · 2019-02-12T10:34:32Z

cocos2d/actions/tween.js

+    ReverseTime: cc.ReverseTime,
+};
+
+Object.assign(Tween, actions, otherActions, constructors);


为啥除了 prototype 还要放到类静态成员里面？

这些本来就不应该放到 cc 下的，cc 下的东西太多了，希望能把 cc.moveTo 等都干掉放到这下面来访问

看到了这条，之前这个类叫 cc.Animate，是可以的，现在叫 Tween 不太合适，把这些都放在 cc.Action 下面就可以了，或者单独创立一个命名空间：cc.actions。另外，为了调整命名空间的话，应该在各个类声明的位置修改，同时给原始的 cc.moveTo 之类的接口添加 deprecation 说明

是的，现在放到 Tween 下不合适了，可以改为放到 cc.Action 下，以后再改吧

一气改好啊，合进去万一有人用又蛋疼

或者你把这个快捷方式删除

哦，看到你去掉了

pandamicro · 2019-02-15T08:50:53Z

https://github.com/cocos-creator/2d-tasks/issues/1105

Ronsku · 2019-03-06T13:06:21Z

@2youyou2 I think Typescript types needs some updates

Also a comprehensive documentation would be really lovely, since I don't completely understand everything that this allows me to do. If Typings would be in place it would be easier to figure out 👍

LootKeeper · 2019-07-08T17:33:35Z

@Ronsku you need to write:
new cc.Tween().target(this.node).to(1, { scale: 2 }, null).start();

jareguo · 2019-07-19T06:48:33Z

@Ronsku please refer to https://docs.cocos2d-x.org/creator/manual/en/scripting/tween.html

Co-authored-by: cocos-robot <engine-deploy@cocos.com>

add cc.animate

2a30e9d

pandamicro requested review from knoxHuang and PPpro December 20, 2018 10:57

pandamicro mentioned this pull request Dec 20, 2018

Add cc.sizeTo action for resizing. #3638

Closed

add animate.clone

b357750

jareguo reviewed Dec 20, 2018

View reviewed changes

refine animate.add

98ae871

rename process to progress

3f92a78

jareguo added the PR: merge in next release label Dec 21, 2018

pandamicro reviewed Dec 24, 2018

View reviewed changes

jareguo removed the PR: merge in next release label Jan 15, 2019

knoxHuang assigned 2youyou2 Jan 16, 2019

2youyou2 added 2 commits January 22, 2019 11:40

change animate to tween

a6f78c5

change Tween.add to Tween.then

2c7580c

2youyou2 changed the title ~~add cc.animate~~ add cc.tween Jan 22, 2019

refine tween

b4c36cd

knoxHuang approved these changes Jan 28, 2019

View reviewed changes

jareguo approved these changes Jan 28, 2019

View reviewed changes

pandamicro reviewed Feb 12, 2019

View reviewed changes

2youyou2 added 4 commits February 15, 2019 14:37

refine code

800ac08

refine api comment

253bf25

mark cc.Easing deprecated

30b4bdf

refine tween comment

d326181

pandamicro approved these changes Feb 15, 2019

View reviewed changes

pandamicro merged commit b526af8 into cocos:v2.0-release Feb 15, 2019

2youyou2 deleted the v2.0-release-animate branch August 30, 2019 10:25

minggo pushed a commit that referenced this pull request Feb 10, 2022

[ci skip][AUTO]: updating jsbinding automatically: 0a0f858 (#3660)

d7bd772

Co-authored-by: cocos-robot <engine-deploy@cocos.com>


		cc.Easing = module.exports = Easing;
		cc.easing = module.exports = easing;

add cc.tween #3660

add cc.tween #3660

Conversation

2youyou2 commented Dec 20, 2018 • edited

Use Cases

jareguo commented Dec 20, 2018

jareguo commented Dec 20, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

2youyou2 Dec 20, 2018 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

2youyou2 commented Dec 20, 2018 • edited

2youyou2 commented Dec 20, 2018

jareguo commented Dec 21, 2018 • edited

2youyou2 commented Dec 21, 2018

jareguo commented Dec 22, 2018

pandamicro commented Dec 24, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pandamicro commented Dec 24, 2018

pandamicro commented Dec 24, 2018

jareguo commented Dec 24, 2018

2youyou2 commented Dec 24, 2018 • edited

pandamicro commented Dec 24, 2018

jareguo commented Dec 24, 2018

pandamicro commented Dec 24, 2018

jareguo commented Dec 25, 2018

2youyou2 commented Dec 25, 2018 • edited

jareguo commented Dec 27, 2018

jareguo commented Jan 15, 2019

2youyou2 commented Jan 16, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pandamicro commented Feb 15, 2019

Ronsku commented Mar 6, 2019

LootKeeper commented Jul 8, 2019

jareguo commented Jul 19, 2019

2youyou2 commented Dec 20, 2018 •

edited

jareguo commented Dec 20, 2018 •

edited

2youyou2 Dec 20, 2018 •

edited

2youyou2 commented Dec 20, 2018 •

edited

jareguo commented Dec 21, 2018 •

edited

2youyou2 commented Dec 24, 2018 •

edited

2youyou2 commented Dec 25, 2018 •

edited