July 29, 2014

Cocos2D-X series - Actions

Lately, I've tried to dabble a bit with Cocos2D-X. Pretty much all the time while trying to do something, I get stuck for a loooong time trying to figure how to do something. For the purpose of creating a "cheat-sheet" of some sort - and to help out others who struggle with learning Cocos2D-X - I'm writing these categorized posts about features of Cocos2D-X.


Cocos2D-X relies quite heavily on actions. If you've used LibGDX's Scene2D system or something similar, you may already know about action system. Actions are basically commands for objects like sprites to do something. They can be commands to move to a new location, rotate for a bit or something else. Almost all properties can be changed via actions.

So, how do we use actions? Basically, like this:

// Create a new sprite called 'tile', using an image file 'tile.png'
Sprite* tile = Sprite::create("tile.png");

// Add the tile sprite to the scene

// Tell the sprite to rotate 90 degrees clockwise during the next three seconds
tile->runAction(RotateBy::create(3.f, 90.f));

The last line here is the most important one. As you can see, you take the sprite, call its 'runAction()' method, and pass an action to it - in this case, RotateBy action, which rotates the sprite 90 degrees clockwise and uses three seconds on the action, making the rotation quite slow. Cool!

Action types

So, what types of actions are there? Let's take a look! First off, the actions are divided into two categories called "interval actions" and "instant actions". The "interval actions" are executed for a period of time, while the "instant actions" are, well, instant.

Instant actions

CallFunc is an action that calls a callback function. You can give it a function pointer and the function gets called. Doesn't sound that useful right away? "Why not just call the function?" As it turns out, you can chain actions (we'll learn about that later), and you can - for example - put CallFunc as the final action in a sequence, for example to inform about a completed sequence of actions.

FlipX and FlipY flip a sprite horizontally or vertically, in that order. For a quick reminder, horizontal flip makes "left to be right and right to be left", while vertical flip flips the sprite upside-down..!

Hide is pretty self-explanatory. It hides the node so it's not visible anymore. Show, on the other hand, makes a node visible again. ToggleVisibility is closely related; it hides the node if it's visible, and shows the node if it's hidden.

Place is an instant location change actions. It basically just places the node to the specified location.

RemoveSelf removes the node from the scene.

ReuseGrid is a bit more complicated - it basically lets you reuse a grid. I'd say this is a bit more advanced usage of actions - don't panic if you don't understand this right away. StopGrid is related to this, but I haven't yet figured out what it does.

Interval actions

AccelAmplitude is a complex action class that has an amplitude and a duration. Again, it's a bit more advanced stuff. AccelDecelAmplitude and DeccelAmplitude are related.

ActionCamera is a base class for camera-related actions - that is, actions that control camera properties.

ActionEase is a base class for all "easings". Easings are simply modificators on the value changes on other actions - I'll discuss these in depth a bit later.

ActionTween is an interval action that can modify custom properties.

Animate is used to animate a sprite. It automatically changes frames and plays the animation for a certain duration.

Animate3D is similar to Animate, but it uses Sprite3D and Animation3D objects instead.

BezierBy moves a target along a bezier curve.

Blink makes a sprite blink for a certain time and at certain rate. Remember those old NES games where whenever you took damage, your character started blinking? It's really easy to do using this action!

CardinalSplineTo is a bit similar to BezierBy, but uses a cardinal spline instead.

DelayTime takes another action and delays it for a certain amount of time. It can be useful sometimes to delay something happening immediately, and this is the way to do it.

FadeTo fades an object's opacity - that is, the alpha channel - to the given value. If the value is 0, it fades the object out until it's completely invisible. If the value is 1, it fades the object in until it's completely visible.

GridAction is a base class for all grid-based actions. Grid-based actions are more special kind of actions that perform certain cool effects like shattering the object into tiny parts or creating a ripple effect that traverses through the object like if something was dropped in water.

JumpBy is a command that makes an object to travel like it jumped. The movement follows the parabolic curve of a jump.

MoveBy is probably the most common one of these. It makes an object move a certain distance.

MoveTo is closely related to MoveBy, but it takes an absolute location where the object is then moved to.

ProgressFromTo changes a percentage value from one value to another.

ProgressTo progresses a percentage value from zero to the given value.

Repeat takes another action and repeats it.

RepeatForever takes another action and, well, repeats it forever.

ReverseTime takes another action and executes it backwards.

RotateBy rotates the object by a certain amount of degrees.

RotateTo rotates the objects to a certain orientation.

ScaleBy scale the object by a certain scale. If an object's scale is 1 and you first run an action to scale it by 3 and then by 2, the resulting scale will be 6.

ScaleTo scales the object to a certain scale. If an object's scale is 1 and you first run an action to scale it to 3 and then to 2, the resulting scale will be 2.

Sequence is an action that takes a number of actions and executes them as a sequence, first running the first action, and when it's done, continuing with the second one and so on until all the actions are done.

SkewTo skews a node, either horizontally or vertically.

SkewBy skews a node, either horizontally or vertically, adding to the skewness it already has.

TargetedAction overrides the target set by the node's runAction() method, allowing you to specify another target instead.

TintBy changes the node's color by the amount specified.

TintTo changes the node's color to the color specified.

Phew! There's a whole lot of actions there already! It's not all of them, but those are probably the ones you're going to use the most. Next time, I'll write more about the easings and action chaining.

No comments:

Post a Comment