Getting Started

This document should help you learn what you need to know to get your first KitchenSync project going.

Note: All of the examples were built using an ActionScript 3.0 project in Adobe FlexBuilder 3 beta. If you're using KitchenSync for a Flex project, be sure to read this page on using KitchenSync with Flex. For help with setting up and running these examples in Flash CS3 or FlexBuilder, check out the installation notes wiki page.

Setting up KitchenSync

Before doing anything else, you'll first need to set up KitchenSync. This will set up the Synchronizer which is a utility that dispatches events at every frame and is used as the timing core of KitchenSync. To start KitchenSync, use the static method KitchenSync.initialize() and pass in a reference to any DisplayObject. Don't forget to import the right packages! The reference to the DisplayObject allows the Synchronizer to communicate with the stage so it can listen for events and get the current frame rate. You can also optionally set the frame rate if you want it to be something other than the default. I recommend doing this at the very beginning of your code in your main application file or in your document class.

package {

	import org.as3lib.kitchensync.*;
	import org.as3lib.kitchensync.action.*;
	
	import flash.display.Sprite;
	
	public class KSTutorial extends Sprite
	{
		public function KSTutorial ()
		{
			// set framerate to 30 frames per second
			stage.frameRate = 30;
			// start KitchenSync. You'll only need to do this once.
			KitchenSync.initialize(this);
		}
	}
}

After this, your KitchenSync is running. Since you don't need to register actions, you probably won't need to access it again.

A note on the version check parameter

As a safety feature, you can add a string for the version number of KitchenSync you're expecting to the initialize() method like this.

KitchenSync.initialize(this, "1.5");

This will throw an error if the version number of the library isn't what you're expecting. This can help prevent unexpected results when you upgrade the library.

Running your first action

To test that KitchenSync was set up properly, try running a simple script. For this, you'll use the KSTrace class which simply displays a trace statement after a set amount of time. The first argument is the message to display. This is usually a string but you can also pass in an Object as you would with the trace() statement. If you pass in an object, the resutls of its toString() method will be displayed. The second argument is the offset, or delay, before the trace statement is displayed. The default unit of time for this is milliseconds so the number 5000 = 5 seconds.

// display a message after 5 seconds.
var message:KSTrace = new KSTrace("HELLO, WORLD ... Sorry I'm late!", 5000);
message.start();

This code will display the message HELLO, WORLD ... Sorry I'm late! after five seconds. If you don't need to keep a reference to the KSTrace object, you could also write this in a slightly more compact way like this...

new KSTrace("HELLO, WORLD ... Sorry I'm late!", 5000).start();

Using timed Functions

The previous code is a fairly straightforward example but it illustrates how you can use KitchenSync to execute an action at a specific time. The KSTrace class is actually a subclass of a much more broad action called KSFunction. This class allows you to run any function, with arguments, after a specified delay.

new KSFunction(5000, sayHello, "world").start(); // Displays "Hello, world!" after 5 seconds.
...
protected function sayHello(who:String):void {
	trace("Hello, " + who + "!");
}

For more info on KSFunctions, check the wiki page.

Now, onto the good stuff...

Creating tweens

A Tween is an animation be-tween two key points. It uses the KSTween class. Our first demo will first create a rectangle to play with. After that, we'll use a KSTween object to move the rectangle from x=0 to x=300 over the course of 3 seconds.

package {
	import org.as3lib.kitchensync.*;
	import org.as3lib.kitchensync.action.*;
	import org.as3lib.kitchensync.easing.*;

	import flash.display.*;
	
	public class KSTutorial extends Sprite {
		public function KSTutorial() {
			// set framerate to 30 frames per second
			stage.frameRate = 30;
			// start KitchenSync. You'll only need to do this once.
			KitchenSync.initialize(this);
			
			// display a message after 5 seconds.
			var message:KSTrace = new KSTrace("HELLO, WORLD ... Sorry I'm late!", 5000);
			message.start();
			
			// Draw a rectangle to use for demonstrations.
			var sprite:Sprite = new Sprite();
			sprite.graphics.beginFill(0);
			sprite.graphics.drawRect(0,0,20,20);
			addChild(sprite);
			
			var tween:KSTween = new KSTween(sprite, "x", 0, 300, "3sec", "0sec", Cubic.easeInOut);
			tween.start();
		}
	}
}

Let's take a quick look at the syntax of KSTween.

The first two are the target object and the name property to change (representing sprite.x). The target can be any object (except primatives) and the property can be any numeric property.

The next two parameters are the start value and the end value of the tween. The sprite will be moved from 0 to 300.

The next two are the duration and offset. These determine the time that the tween will take place. The first is the duration (3 seconds), the second is the offset, or delay, (0 seconds). Note that the time was entered using a string - to read more about that, check out the wiki page for parsing time strings. Once the start() method is called, the tween will wait for the offset time (in this case, 0 seconds) before it starts. After that, the tween will take 3 seconds to complete (unless it's paused or stopped).

The final parameter is the easing function. This determines the type of motion you'll see. Try playing around with different ones for various effects. For examples of different easing types, check the Easing Demo and the Easing wiki page. Be sure you don't use parentheses when you add an easing function.

Once it's set up, use the start() method to get things rolling.

(Note: For more detailed information about how KSTweens and tween targets work, take a look at the tween wiki page

Cloning a KSTween

Since at this point you can only change one target/property at time with a KSTween object (I'll be adding functionality for multiple targets/properties soon), I've added the ability to make a copy a tween. Let's replace the tween lines with one that modifies x then copy it to target y using cloneWithTarget(). This will cause the square to move diagonally since x and y are being tweened at the same time.

var tweenX:KSTween = new KSTween(sprite, "x", 0, 300, "3sec", "0sec", Cubic.easeInOut);
var tweenY:KSTween = tweenX.cloneWithTarget(sprite, "y");
tweenX.start();
tweenY.start();

While all AbstractActions have a clone() method, KSTweens support the cloneWithTarget() method as well as the cloneReversed() method which clones the tween with the start and end points switched and cloneWithTweenTarget() which copies the tween but changes the tween target.

Now what if you wanted the box to move right then move down instead of moving diagonally? You could set the offset for tweenY to 3 seconds so it waits until the tweenX is done before starting OR you could use an action group...

Creating an Action Group

When working with multiple actions, it's often more convenient to combine them into groups that can be treated as a single unit. These are called action groups and they extend the AbstractActionGroup class.

There are three several kinds of groups including KSSequenceGroup, KSParallelGroup, and KSStaggeredGroup (explained on the groups wiki page). Since we want the box to move right then down, we'll use a KSSequenceGroup group which executes all of its children in a sequence.

The code below will create a new Sequence and add the x and y tweens using the constructor. Then we'll use the addAction() method and the cloneReversed() method to create the reversed animation back to the starting point

package {
	import org.as3lib.kitchensync.*;
	import org.as3lib.kitchensync.action.*;
	import org.as3lib.kitchensync.easing.*;
	
	import flash.display.*;
	
	public class KSTutorial extends Sprite {
		public function KSTutorial() {
			// set framerate to 30 frames per second
			stage.frameRate = 30;
			// start KitchenSync. You'll only need to do this once.
			KitchenSync.initialize(this);
			
			// display a message after 5 seconds.
			var message:KSTrace = new KSTrace("HELLO, WORLD ... Sorry I'm late!", 5000);
			message.start();
			
			// Draw a rectangle to use for demonstrations.
			var sprite:Sprite = new Sprite();
			sprite.graphics.beginFill(0);
			sprite.graphics.drawRect(0,0,20,20);
			addChild(sprite);
			
			// move the rectangle from left to right.
			var tweenX:KSTween = new KSTween(sprite, "x", 0, 300, "3sec", "0sec", Cubic.easeInOut);
			// apply the same animation to the y property.
			var tweenY:KSTween = tweenX.cloneWithTarget(sprite, "y");
			
			// add the x and y tweens to a new sequence.
			var sequence:KSSequenceGroup = new KSSequenceGroup(
				tweenX,
				tweenY
			);
			// why stop there... let's make the complete trip back to the starting point.
			sequence.addAction(tweenX.cloneReversed()); // adds a reversed clone of the x tween
			sequence.addAction(tweenY.cloneReversed()); // adds a reversed clone of the y tween
			
			// begin the sequence.
			sequence.start();
		}
	}
}

An important thing to remember about groups is that they are actions themselves. That means they can be started, stopped, paused, unpaused, and best of all, added to other groups.

Let's add a KSParallelGroup group to the KSSequenceGroup to change the size. A Parallel group executes all the child actions inside simultaneously. The tweens added to this particular parallel group will scale up the size of the box. Notice that the duration is slightly different on each and the easing function is Elastic.easeOut to make it wobble a bit.

var scaleUp:KSParallelGroup = new KSParallelGroup(
	new KSTween(sprite, "scaleX", 1.0, 3.0, "5s", 0, Elastic.easeOut),
	new KSTween(sprite, "scaleY", 1.0, 3.0, "6s", 0, Elastic.easeOut)
);
			
// after adding other child actions but before starting the sequence, add the parallel group.
sequence.addAction(scaleUp);

// begin the sequence.
sequence.start();

Click here to see the results of this code.

Go Play!

There's much more you can do with KitchenSync. I hope to add more to this page but for now the best place to find information is on the other wiki pages or in the API reference.