Using the cc.tween in Cocos Creator
Authors: Xunyi, youyou
cc.tween introduction
Cocos Creator provides a new set of APIs in v2.0.9 -- cc.tween. cc.tween can easing any property of an object, similar to the cc.Action. But cc.tween is much easier to use than cc.Action, because cc.tween provides a chain-created method that can manipulate any object, and easing any of the object's properties.
cc.Action is migrated from Cocos2d-x to Cocos Creator. Providing an API that is cumbersome, only supports use on the node properties, and requires adding a new action if you want to support new properties. In order to provide a better API, cc.tween on the basis of cc.Action made a layer of API encapsulation. Here's a comparison between cc.Action and cc.tween in use:
cc.Action:
this.node.runAction( cc.sequence( cc.spawn( cc.moveTo(1, 100, 100), cc.rotateTo(1, 360), ), cc.scale(1, 2) ) )cc.tween:
cc.tween(this.node) .to(1, { position: cc.v2(100, 100), rotation: 360 }) .to(1, { scale: 2 }) .start()
Chain APIs
Each API of cc.tween generates a action internally and adds this action to the internal queue. After the API is called, it returns its own instance, so that the code can be organized by chain call.
When cc.tween calls start, a cc.sequence queue is generated that combines the previously generated action queue.
So the chain structure of cc.tween is to execute each API in turn, that is, it will execute an API and then execute the next API.
cc.tween(this.node)
// at 0s, node's scale is still 1.
.to(1, { scale: 2 })
// at 1s, after executing the first action, scale is 2
.to(1, { scale: 3 })
// at 2s, after executing the second action, scale is 3
.start()
// Call start and start executing cc.tween
Set the properties of cc.tween
cc.tween provides two APIs for setting properties:
to: Calculate the absolute value of the property. And the final run result is the property value that is set.by: Calculate the relative value of the property. And the final run result is the property value that is set, plus the property value of the node at the start of the run.
cc.tween(node)
.to(1, {scale: 2}) // node.scale === 2
.by(1, {scale: 2}) // node.scale === 4 (2+2)
.by(1, {scale: 1}) // node.scale === 5
.to(1, {scale: 2}) // node.scale === 2
.start()
Support for easing any property of any object
let obj = { a: 0 }
cc.tween(obj)
.to(1, { a: 100 })
.start()
Execute multiple properties simultaneously
cc.tween(this.node)
// Easing three properties a, b, c at the same time
.to(1, { scale: 2, position: cc.v2(100, 100), rotation: 90 })
.start()
easing
You can use easing to make the easing more vivid. cc.tween provides a variety of ways to use it for different situations.
// Pass in the easing name and use the built-in easing function directly
cc.tween().to(1, { scale: 2 }, { easing: 'sineOutIn'})
// Using custom easing functions
cc.tween().to(1, { scale: 2 }, { easing: t => t*t; })
// Use the easing function only for a single property
// value must be used with easing or progress
cc.tween().to(1, { scale: 2, position: { value: cc.v3(100, 100, 100), easing: 'sineOutIn' } })
Custom progress
Compared to easing, custom progress function has more freedom to control the easing process.
// Customize the progress for all properties
cc.tween().to(1, { scale: 2, rotation: 90 }, {
progress: (start, end, current, ratio) => {
return start + (end - start) * ratio;
}
})
// Customize the progress for a single property
cc.tween().to(1, {
scale: 2,
position: {
value: cc.v3(),
progress: (start, end, current, t) => {
// Note that the passed in property is cc.Vec3, so you need to use Vec3.lerp for interpolation calculations
return start.lerp(end, t, current);
}
}
})
Replication easing
The clone function will clone a current easing and accept a target as a parameter
// First create a easing as a template
let tween = cc.tween().to(4, { scale: 2 })
// Copy tween and use node Canvas/cocos as target
tween.clone(cc.find('Canvas/cocos')).start()
// Copy tween and use node Canvas/cocos2 as target
tween.clone(cc.find('Canvas/cocos2')).start()
Insert other easing into the queue
You can create some fixed easing in advance, and then reduce the writing of your code by combining these easing to form a new easing.
let scale = cc.tween().to(1, { scale: 2 })
let rotate = cc.tween().to(1, { rotation: 90})
let move = cc.tween().to(1, { position: cc.v3(100, 100, 100)})
// Zoom first, then rotate
cc.tween(this.node).then(scale).then(rotate)
// Zoom first, then move
cc.tween(this.node).then(scale).then(move)
Parallel execution easing
cc.tween is executed in the form of a sequence when it is executed in a chain. However, when writing complex easing, you may need to execute multiple queues in parallel at the same time. So cc.tween provides the parallel interface to meet this requirement.
let t = cc.tween;
t(this.node)
// Execute two cc.tween at the same time
.parallel(
t().to(1, { scale: 2 }),
t().to(2, { position: cc.v2(100, 100) })
)
.call(() => {
console.log('All tweens finished.')
})
.start()
Callback
cc.tween(this.node)
.to(2, { rotation: 90})
.to(1, { scale: 2})
// This callback function is not called until the preceding action has been performed
.call(() => { cc.log('This is a callback') })
.start()
Repeat execution
The repeat/repeatForever function will use the previous action as the object of action. However, if there are parameters that provide additional action or tween, the repeat/repeatForever function will use the incoming action or tween as the object of action.
cc.tween(this.node)
.by(1, { scale: 1 })
// Repeat 10 times for the previous by
.repeat(10)
// Finally node.scale === 11
.start()
// Can also be used like this
cc.tween(this.node)
.repeat(10,
cc.tween().by(1, { scale: 1 })
)
.start()
// Keep it going over and over again.
cc.tween(this.node)
.by(1, { scale: 1 })
.repeatForever()
.start()
Delayed execution
cc.tween(this.node)
// Delay 1s
.delay(1)
.to(1, { scale: 2 })
// Another delay of 1s
.delay(1)
.to(1, { scale: 3 })
.start()