Using Timelines in Corona SDK (MovieClipX)

A little over a year ago I released a tool that extended Corona SDK’s MovieClip library, in a sense it originally was just adding another layer of manipulability. Allow me to illustrate in flowcharts.

The original library

Here was how the original MovieClip library worked,

Timeline flowchart.001

As you can see, every animation was it’s own object. That means that if you wanted to make a walk animation and a run animation for your character, MovieClip would force you to create two separate objects and handle the toggling of visibility yourself.

MovieClipX was born…

I knew that wasn’t a good solution. It makes for messy and repetitive code, and I’m a stickler for clean code. So that spawned my idea for MovieClipX

Timeline flowchart.002


This already appears to be a better solution! With my library you can house unlimited animations inside a single MovieClipX object and switch animations with one line of code! It also adds one more level of control, you can edit your animation parameters on a per-animation basis or manipulate the parameters for an entire MovieClipX object!

Then came Timeline!

But then last week, I had one more epiphany on how to make this library better…

Timeline flowchart.003


Now we have a final level of manipulability, the timeline object. Timelines work sort of like MovieClipX objects; you create them, add MovieClipX objects inside them, then can manipulate time for multiple MovieClipX objects at once! This is useful for pausing multiple animations at once, fast forwarding time, or slow-motion!

Now that you’ve gotten a little rundown on how timelines work, time to roll up your sleeves and start coding!

The tutorial

If you’re familiar with MovieClipX already, feel free to skim through this tutorial while making notes of the changes with Timeline. This tutorial is assuming you have no knowledge of MovieClipX, but knowledge of using Corona SDK.

Make sure you’re running MovieClipX build 2013.215 or higher. If not, download from here.

In this tutorial I’m going to refer to the MovieClipX library as mcx and MovieClipX Object as mcxObject.

Setting up MovieClipX

First off, you’re going to want to include the library

View the code on Gist.

Creating your animations

Then you’ll need to create a few mcxObjects, for this tutorial I’m going to create john and tom.

View the code on Gist.

To continue, there’s a few different options; if your animation is stored in an image sequence (frame1.png, frame2.png,etc) then you can do the following

View the code on Gist.

This is for a sequence of files named: walk_left_001.png, walk_left_002.png, etc. However, you can customize the parameters to meet your needs.

  • Name = (Required) The prefix for the file
  • Extension = (Required) The file extension
  • startFrame = (Optional, default = 1) The start frame
  • endFrame = (Required) The last frame
  • zeros = (Optional, default = 0) The amount of leading zeros in the frame number.

However, if your animation files aren’t saved sequentially, then you have to create your frames list in a table:

View the code on Gist.

Now you can attach the frame table to an animation, like so:

View the code on Gist.

The animation name is important, that’s how you call the animation when you want to play or switch animations. You can add as many animations to John and Tom as you’d like, but for this tutorial I’m just giving them each one animation. If you want to know more about setting up your animations, you can find an article about it here.

Finally, to make them animate:

View the code on Gist.

Now if you run your project in the Corona Simulator, you should have two animating characters!

Creating and using Timelines

For this tutorial I’m only going to be using one timeline object, but it’s important to note that you can have as many timelines in your project as you desire!

Using timeline is easy, let’s create a timeline and add our friends John and Tom!

View the code on Gist.

And we’re ready to use it! Let’s go ahead and make John and Tom move in slow-motion by using alterTime()

View the code on Gist.

alterTime() is a pretty slick function, it takes one argument which is a float value. You can either insert a float value or you can use the built-in speed controls, which are:

  • mcx.normalSpeed()
  • mcx.halfSpeed()
  • mcx.doubleSpeed()

You can read about some of the other timeline functions on the docs page.

In conclusion

I hope you learned something from this brief rundown on the new timeline functions! Most of all, I hope that MovieClipX can boost your productivity in Corona SDK!