Google Code

Visit Twease on Google Code

svn checkout http://twease.googlecode.com/svn/trunk/ twease-read-only

News

03/04/2008 - Twease 2.0 Final is released! Now in AS3! Simply download the .zip or grab the source:svn checkout http://twease.googlecode.com/svn/tags/2.0 twease-read-only

For now, you can download the latest version here.

04/02/2008 - Twease 2.0 Beta 2 is now available, and in AS3 as well! This page will be undergoing big changes as it's incorporated into Google Code.

10/9/2007 - Just updated section on filters. Twease can do filters, with a tad more work. It's easy, and it'll save you a lot of bytes.

09/10/2007 - Twease v1.1 is now available! This page has been updated with the new features, so take a look. Read more.

08/06/2007 - Updated page with extended usage examples. Told you it was powerful.

07/26/2007 - v1.01 bug fix release. This update is highly recommended and is pretty much mandatory for proper engine function. Read more.

07/13/2007 - I'm going to be updating this site over the next few days with examples and more content, so check back often!

Watch my blog to keep up-to-date about Twease.

About

What's Twease?

Twease is an ActionScript tweening engine and sequencer developed by Andrew Fitzgerald. The core Twease class is less than 200 lines of code and weighs in at a miraculous 2k.

Twease is more efficient and lighter than just about any other major tween class, but still manages to rival the capabilities of engines 10x its size.

Features:

Most tweening engines do the same things these day, just in different ways. So chances are Twease does what you need, with the power and lightweight you want.

What's "tweening"?

Not quite following me? Not a problem. Tweening basically takes a numeric variable and 'takes it' to another value gradually over time, instead of instantly assigning it. This is used to semantically create animations with ActionScript, instead of the timeline and keyframes. This is one of the key things to learn to take your Flash skills to the next level.

Twease is a developer's engine that was made for those of you who want to get thing done. It's MTASC compliant (AS2), for the extra hardcore.

Why was this developed?

There are many incredible tweening classes out there, including one that I've been very involved with called Fuse. I'm sure you've heard of it.

Now don't get me wrong, it's an amazing kit, it's easy to use, and it does everything. But therein lies the problem: sometimes I don't want to do everything. Usually I just want to fade a MovieClip out, or slide a menu item out. Just for something simple like that I have to 'pay' 12k. All in all that's fine if I'm using it in a movie that will be much bigger with lots of super complex animations, but what about creating components or ad banners? File size is critical, and 12k just wont do.

Don't even get me started on sequencing. If you want to create animation sequences, you're up to a whopping 30k. Again, Fuse is amazing and can do brilliant things with all that 30k, but for something simple, it's a bit overkill.

Now there's also a few other ones out there, such as Tweener which is in both AS2 and AS3. Great class, but still too big for me, and no real sequencing that I'm aware of. The built in MX Tween class, to be completely blunt, sucks. Sure it works and everything, it's just very inefficient and bloated (v2 components anyone?) and no sequencing either. There are plenty of other small projects here and there, but not one everyone can really build off of.

Who and what's this for?

Twease was created for developers that needed tweening for classes, components, and size critical applications. If this isn't you, don't be afraid; Twease will work in all kinds of situations with some fairly basic AS2 knowledge.

If you're creating any sort of reusable or distributable class, component, or the sort, Twease is just what you need. Lightweight and powerful, you don't have to feel as if you're adding in a bunch of stuff that really doesn't help your project. If there's something you need that Twease doesn't do, you can do it yourself in a few lines, or make a request.

Functions != Features

Twease is very compact. This is due to what I call Power by Design™. You see, just by the way the engine works and was written, countless features are inherent. Almost all of Twease's abilities are of this nature, and that's what makes this engine so special. No need for function bloat when a little more thinking will do.

Twease Future

Twease 2.0 is pretty much at the peak of it's development. All planned features have been implemented and only maintenance released will be made. It's top-notch and ready for the big leagues.

Free as in beer

If you somehow missed it, just click the really obvious link in the header to download the latest version of Twease.

Twease is under the MIT license and is free to do with what you wish under its governance.

Enjoy, and I hope you find this as exciting of a project as I do. If you use this somewhere or do anything sweet with it, I'd love to see!

Usage

Getting Started

First copy the 'com' folder in the zip to your classes directory, or the same directory as your fla. Make sure the hierarchy stays the same as it is required to load the AS2 class.

Now to use the class, put the import statement at the beginning of your class or at the top of your keyframe. This is all you need to use the core tweening engine.

import com.visualcondition.twease.*;

If you would like to load any extensions, such as Easing, just register the class:

Twease.register(Easing); //this registers the Easing class

Why not just include it automatically? File size. This allows you to only load what you need, saving file size and keeping things modular.


Tweening Syntax

If you're familiar with other engines, this will be common sense. There's pretty much only one method you need to call, and that's:

Twease.tween(ab:Object, target:Object);

The first argument is an object that has all the tween settings. The second argument is a target override for adding the same target for all tweens in a sequence. You don not use this for a single tween.

The tween object you pass has these specific properties to pass:

So a full object(without a property to tween) would look like this:

Twease.tween({target:my_mc, time:2, delay:1, ease:Twease.easeOut, round:true, cycles:2, func:myEndFunction, startfunc:function(target, prop){trace:prop}, upfunc:intesiveFunction});

Now this wont really do anything because we haven't told Twease what to actually tween. So to do that, we just write the prop:value like so:

Twease.tween({target:my_mc, time:2, _x:200});

We can tween as many properties as we want in one object, but they will be treated as separate tweens internally. So if you have functions in the object, they will be fired for each property. This is just for the connivence of having all the identical other properties in one call.

Twease.tween({target:my_mc, time:2, _x:200, _y:0, _alpha:50});

A brilliant idea from the ZigoEngine (Fuse) is to have absolute values be Numbers, and relative (prop += value) values Strings. So if you're used to that, Twease has you covered.

Twease.tween({target:my_mc, time:2, _x:200}); //slides the mc from anywhere to the x position of 200 Twease.tween({target:my_mc, time:2, _x:'200'}); //slides the mc right 200px Twease.tween({target:my_mc, time:2, _x:'-200'}); //slides the mc left 200px

You can also use other easing types, by importing the classes you wish, and setting the ease as the function:

import mx.transitions.easing.*; //or penner easing Twease.tween({target:my_mc, _x:'100', time:1, ease:Bounce.easeOut});

You can now also use the included Penner Easing Equations by registering them:

Twease.register(Easing); Twease.tween({target:my_mc, _x:'100', time:1, ease:'easeInOutQuad'}); //you can set the ease as a string now

Twease 2.0 now has muli-point bezier tweening:

Twease.tween([{_x: 350, _y:380, bezier:[{_x:'-200', _y:'250'}, {_x:'200', _y:'100'}, {_x:0, _y:100}], time:5, ease:'easeOutBounce', cycles:-1}], target);

Sequencing Syntax

What makes Twease really shine, is the fact that such a powerful feature like animation and function sequencing, is just a result of how the engine was designed - with very little extra magic to make it work.

So to make a sequence, simply call Twease.tween() with all the tween objects you want in an array, and they will be fired off in order. The method returns the queue number for the given sequence, which can be used for advanced sequence manipulation.

Twease.tween([{target:my_mc, time:2, _x:'200'}, {target:movie2, _alpha:50, delay:2, time:1}, {func:myfunc, delay:1}, {target:my_mc, time:2, _rotation:'100', cycles:3}]);

Another very important feature, which is something to be aware of, is stacking properties. This amazing feature, again just by design, allows you to stack, or essentially sequence, the same property. So every time a tween() method is called, the current tween for that property isn't overwritten, but rather is placed in a mini-queue to be ran right after the current tween finishes. This only applies to the exact same target.property.

Twease.tween({target:my_mc, _x:200, time:2}); Twease.tween({target:my_mc, _x:0, time:1}); //waits until the first tween is done on that property Twease.tween({target:my_mc, _x:50, time:0.5, delay:1}); //waits until the first 2 tweens are done, then starts including the delay

Now you may not want this stacking, so be it. Just get rid of the tween for that property before the new call by deleting it in the Twease.tweens object (more information on this in the advanced section).

Twease.tween({target:my_mc, _x:200, time:2}); delete Twease.tweens.my_mc._x; //clears the current tween Twease.tween({target:my_mc, _x:0, time:1}); //runs right away

You can also use Twease to sequence functions, with or without using delays:

Twease.tween([{func:myfunc}, {func:myfunc2, delay:2}, {func:myfunc3}, {func:myfunc4, delay:.5}]);

setActive

Twease.setActive is what makes everything go. It allows you to control what objects and properties are active (are currently being tweened). Think of it as pausing/resuming tweens. You can also stop tweens and garbage collecting globally with this method, as it controls the update function.

Twease.setActive(setactive:Boolean, target:Object, prop:String);

The effect of each argument is as follows:



This should cover the basics. If there's something obvious I have missed, please just let me know.

Extended Usage

Removing and Deleting Tweens

Removing tweens is a very straight forward process: just delete the object or tween from the Twease.tweens object:

delete Twease.tweens[mytweened_mc]; //removes all tweens on an object delete Twease.tweens[mytweened_mc]._x; //removes just the tween for the _x property Twease.tweens[mytweened_mc]._x.splice(1,1);; //removes the just next tween in the _x tween stack

updatedepth

If you're using getNextHighestDepth(), you may want to change the depth of the update MovieClip to a negative, or a smaller number. Note that negative depths will not allow the garbage collection to remove the update MovieClip, but this isn't really a big deal.

Twease.updatedepth = -30;

roundresults

If your project needs to be pixel perfect, such as for using pixel fonts, you can make all tweens round their values. The default is false.

Twease.roundresults = true;

collectionrate

Twease uses a garbage collector to handle finished tweens instead of checking in the update loop, allowing for a great performance boost. You can set the rate at which Twease runs the collector in ms:

Twease.collectionrate = 10000; //runs collection every 10 seconds

stacking

If you do not like the stacking feature of Twease, or you just have a lot of buttons and the stacking messes them up, you can easily turn it off globally and each new tween on a property will over-wright the current one instead of waiting until it's finished.

Twease.stacking = false;

Targeting and tweening arrays

New in v1.1, you can tween entire arrays at once as well as an individual array value (index). To do this, there's 2 new props you can pass in: index and array. These are needed because there is no real property of an object for the engine to tween.

So to tween an entire Array, target the Array itself and pass the new Array as the value of array:

var myarr:Array = [50, 100, 40]; //create your array Twease.tween({target:myarr, array:['20', 35, '-10'], time:2}); //results in [70, 35, 30]

You can also just tween a single value of the array by calling the index param and passing an array with the index to tween and the new value (index:[arrayindex, newvalue]) like so:

var myarr:Array = [50, 100, 40]; //create your array Twease.tween({target:myarr, index:[1, 350], time:2}); //results in [50, 350, 40]

Filters

While there's no native functions or properties for filters yet, you can easily tween filters as well.

Just create the filter object like normal, with whatever starting values you want. Then apply a tween to that filter object for whichever properties you want, then run an upfunc applying it to the mc. Easier shown:

import flash.filters.BlurFilter; var filter:BlurFilter = new BlurFilter(0, 0, 3); Twease.tween({target:filter, blurX:8, blurY:8, time:3, ease:’easeOutElastic’, upfunc:function(){my_mc.filters = [filter]}});

Pretty simple, just replace my_mc with your real target movieclip, and interchange that with whatever filter and props you want. If you’re going to use multiple filters, then have that array in there all the filter objects. If you’re going to tween multiple filters at the exact same time, you can save a bit by only running one upfunc. That shouldn’t be an issue though unless you really notice a hit.


Extended Sequencing

Advancing Sequences

Twease has sequencing built into the core, and is actually ran by the public advance() function. We can use this core sequencing method to navigate through any running sequences. This can be used to loop a sequence, rewind it to the begging, advance to the end, or goto and point in the sequence.

To advance to the next item in the sequence, all we need to do is call the advance() function, passing the sequence number:

var seq1:Number = Twease.tween([{target:my_mc, time:2, _x:'200'}, {target:movie2, _alpha:50, delay:2, time:1}, {func:myfunc, delay:1}, {target:my_mc, time:2, _rotation:'100', cycles:3}]); Twease.advance(seq1);

To goto a particular spot in the sequence, just pass the index number of the position:

Twease.advance(seq1, 2); //goes to the 3rd item in the sequence Twease.advance(seq1, 0); //"rewinds" the sequence to the beginning

You can also use this inline a sequence set to loop the sequence:

var seq1:Number = Twease.tween([{target:my_mc, time:2, _x:'200'}, {target:movie2, _alpha:50, delay:2, time:1}, {func:function(to,po,q){Twease.advance(q, 0)}}]);

Manipulating Sequences

Since sequences are just arrays, you can easily manipulate them, this includes reversing the sequence:

var seq1:Number = Twease.tween([{target:my_mc, time:2, _x:'200'}, {target:movie2, _alpha:50, delay:2, time:1}, {func:myfunc, delay:1}, {target:my_mc, time:2, _rotation:'100', cycles:3}]); Twease.queue[seq1] = Twease.queue[seq1].reverse();

To remove an item from the sequence, splice it out:

Twease.queue[seq1].splice(2,1); //this removes the 3rd item

You can also add an item to the sequence, by pushing it in:

Twease.queue[s].push({target:my_mc, _alpha:20, _rotation:'70', time:2}); //adds another tween to the end of the sequence

Also, since stacks are arrays as well, you can manipulate them the same way as sequences.

Sequence Position

You can easily get the current position of a sequence by getting its position value:

var seq1:Number = Twease.tween([{target:my_mc, time:2, _x:'200'}, {target:movie2, _alpha:50, delay:2, time:1}, {func:myfunc, delay:1}, {target:my_mc, time:2, _rotation:'100', cycles:3}]); var sposition:Number = Twease.queue[seq1].position; trace(sposition);