Cocos2D-XNA Tutorial 2: Basic Actions

In my last post (Cocos2D-XNA Tutorial 1: Basic Sprites), I explored some of the basic ways that sprites in Cocos2D-XNA (C2D from here on) could be used in a game.  In that project, I changed properties on the sprite object directly to perform different actions, such as movement, scaling, rotation, etc.  In some cases, this is appropriate so that you can control the sprites exactly the way you want.  But sometimes it would be nice to have a sprite do something specific repeatedly or in a specific sequence of actions, without having to write a bunch of boilerplate code to make it work.

Well then, welcome to Actions in C2D.  Actions provide a great way to manipulate the sprites in a game by performing changes to one or more properties of the sprite.  C2D provides a large number of actions that can be used in your game and I debated whether to include them all in this post… since I’m still learning, I don’t have a perfect understanding of how they all work as I haven’t used them all yet. :)  However, I haven’t been able to find a lot of good references on the internet that provide a decent description of how they work (though most are reasonably obvious), so I thought I’d do my best to list them all here for reference.  If you notice something amiss here, any actions that I’ve missed, or suggestions for improvement, drop me a comment.

With that said, there are two basic types of actions:

  • Instant – The action is performed immediately on the sprite.  The following list shows the instant actions available in C2D:
    • CCFlipX – Flips the sprite on the horizontal axis.
    • CCFlipY – Flips the sprite on the vertical axis.
    • CCHide – Makes the sprite invisible on the screen.
    • CCPlace – Moves the sprite to the specified position.
    • CCRemoveSelf – Removes the sprite from it’s associated parent.
    • CCReuseGrid – Allows a grid to be reused a specified number of times (not sure how this is used??)
    • CCShow – Makes the sprite visible on the screen.
    • CCStopGrid – Stops an effect being executed on a sprite.
    • CCToggleVisibility – Toggles the visible state of the sprite.
  • Interval – The action is performed over a period of time on the sprite.  Also, almost all interval actions have a Reverse method that lets you reverse the action.  The following list shows the interval actions available in C2D:
    • CCAnimate – Animates a sprite using the associated sprite frames.
    • CCBezierBy – Moves a sprite in a bezier curve relative to the sprite’s current position.
    • CCBezierTo – Moves a sprite in a bezier curve at a fixed starting and ending position on the screen.
    • CCBlink – Toggles the visibility of a sprite off and on to flash it a specified number of times on the screen.
    • CCCardinalSplineBy – Moves a sprite in a curved motion based on a specified tension and series of control points relative to the sprite’s current position.  Microsoft has a decent description of Cardinal Splines, though their tension values are backwards vs. C2D (in C2D, 0 = smooth curve, 1 = straight line).
    • CCCardinalSplineTo – Moves a sprite in a curved motion based on a specified tension and series of fixed control points on the screen.
    • CCCatmullRomBy – Moves a sprite in a curved motion based on a series of control points relative to the sprite’s current position.  This page provides some introductory information about Catmull-Rom splines.
    • CCCatmullRomTo – Moves a sprite in a curved motion based on a series of fixed control points on the screen.
    • CCDelayTime – Waits a specified amount of time before continuing a sprite’s next action.  Useful in action sequences.
    • CCFadeIn – Adjusts the opacity of a sprite until it is completely visible on the screen.
    • CCFadeOut – Adjusts the opacity of a sprite until it is completely invisible on the screen.
    • CCFadeTo – Adjusts the opacity of a sprite to a specified level.
    • CCJumpBy – Makes a sprite jump on the screen by a specified amount, amplitude, and number of times relative to the sprite’s current position.
    • CCJumpTo – Makes a sprite jump on the screen to a specified position by a specified amount, amplitude, and number of times.
    • CCMoveBy – Moves a sprite by a specified amount on the screen relative to the sprite’s current position.
    • CCMoveTo – Moves a sprite to a specified position on the screen.
    • CCReverseTime -
    • CCRotateBy – Rotates a sprite by a specified number of degrees relative to the sprite’s current position.
    • CCRotateTo – Rotates a sprite a specified number of degrees on the screen.
    • CCScaleBy – Adjusts the size of a sprite by a specified amount relative to the sprite’s current size.  Values: 1 = original size, < 1 = smaller, > 1 = larger
    • CCScaleTo – Adjusts the size of a sprite to a specified amount.
    • CCSkewBy – Adjusts the horizontal and/or vertical angle of the sprite by a specified amount relative to the sprite’s current angle.
    • CCSkewTo – Adjusts the horizontal and/or vertical angle of the sprite to the specified amount.
    • CCTargetedAction – Applies an action to the specified target sprite.
    • CCTintBy – Adjusts the tint of a sprite by a specified RGB amount relative to the sprite’s current color.
    • CCTintTo – Adjusts the tint of a sprite to a specified RGB value.

C2D also provides a special set of composite interval actions called Easing actions, which modify the speed of the specified action while not altering the total running time (e.g. if an action should run in 2 seconds, it will continue to run in 2 seconds but it’s acceleration will be altered).  These actions come in three flavors:

  • In – The acceleration happens at the beginning of the action.
  • Out – The acceleration happens at the end of the action.
  • InOut – The acceleration happens at the beginning and end of the action.

These easing actions can be applied to movement, rotation, skewing, etc.  C2D provides the following easing actions:

  • CCEaseBackIn – Moves a sprite slightly backwards at the beginning of the action.
  • CCEaseBackInOut – Moves a sprite slightly backwards at the beginning and end of the action.
  • CCEaseBackOut – Moves a sprite slightly backwards at the end of the action.
  • CCEaseBounceIn – Moves a sprite with a bouncing motion at the beginning of the action.
  • CCEaseBounceInOut – Moves a sprite with a bouncing motion at the beginning and end of the action.
  • CCEaseBounceOut – Moves a sprite with a bouncing motion at the end of the action.
  • CCEaseCustom – Moves a sprite using a custom function.
  • CCEaseElasticIn – Moves a sprite in an elastic motion at the beginning of the action.
  • CCEaseElasticInOut – Moves a sprite in an elastic motion at the beginning and end of the action.
  • CCEaseElasticOut – Moves a sprite in an elastic motion at the end of the action.
  • CCEaseExponentialIn – Moves a sprite slowly at the beginning of the action, then with increasing speed.
  • CCEaseExponentialInOut – Moves a sprite slowly at the beginning and end of the action, with increasing speed in the middle.
  • CCEaseExponentialOut – Moves a sprite slowly at the end of the action, with increased speed at the beginning.
  • CCEaseIn – Moves a sprite slowly over a specified duration at the beginning of the action.
  • CCEaseInOut – Moves a sprite slowly over a specified duration at the beginning and end of the action.
  • CCEaseOut – Moves a sprite slowly over a specified duration at the end of the action.
  • CCEaseSineIn – Moves a sprite in a yo-yo motion, moving from beginning to end position and then back to beginning position.
  • CCEaseSineInOut – Moves a sprite slowly from beginning to end of the action.
  • CCEaseSineOut – Moves a sprite to the ending position, reverses to move beyond the beginning position by the same distance, then ends at the beginning position.

Using the basic actions in C2D can help simplify the coding in your game a good bit.  But where actions really shine in C2D is the ability to execute groups of actions in various ways, allowing you to do some wicked cool stuff.  The following special actions exist for this purpose:

  • CCParallel – Executes several actions at the same time.  Appears identical to CCSpawn below, which is the standard cocos2d method of running actions in parallel.  From what I can tell, this class appears to be exclusive to Cocos2d-XNA.
  • CCRepeat – Repeats an action a specified number of times.
  • CCRepeatForever – Repeats the action indefinitely.
  • CCSequence – Executes a series of actions one after another.
  • CCSpawn – Executes several actions at the same time.

Using the above actions, you can accomplish quite a number of things in your game with ease and simplicity that would otherwise take you some considerable time to implement yourself.  Also, if you’d like to write your own custom actions, then you can inherit from the appropriate base class and code away, so the possibilities are nearly endless.  The original cocos2d Programming Guide has a section about creating custom actions, which you should be able to translate over to C2D without too much difficulty.

I created a new project called Basic Actions in my Cocos2d-XNA-Tutorials solution on GitHub that explores some of the actions listed above.  It should be enough to give you a good idea on how to use actions and explore the ones I didn’t implement in the project.

Well, that’s about it for this post… it took several iterations to get through as I couldn’t get it all churned out in one sitting.  Hopefully you find it helpful.  Happy proggy.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>