(English | Japanese)

BetweenAS3

Fast, powerful and professional new tweening engine developed by Yoshihiro Shindo (BeInteractive!).

Currently release: Alpha r3022

This is Alpha version. Many features may works well but I don't give assurance about quality. Please test and send feedback (bug report, request, etc) to me.

You can checkout BetweenAS3 Alpha r3022 via SVN from:

or download as ZIP or SWC from:

Release Note for Alpha r3022 is found in this blog post.

Development version

Are you interested in development version? This is not stable than release version but including some bug fixes and new features.

You can checkout development version via SVN from:

Please see CHANGES file to find what is changed from release version.

Tutorials on Wonderfl.net

Some tutorials were posted on Wonderfl.net (Online flash builder) with tag 'BetweenAS3Tutorial'. You can start trying BetweenAS3 soon by forking these codes!

Slides and Demos

Features

Object Tween

You can create instance of the org.libspark.betweenas3.tweens.ITween interface by calling tween method, to method, or from method in the org.libspark.betweenas3.BetweenAS3 class.

var tween:ITween = BetweenAS3.tween(
    mc, // Target object
    {x: 200}, // Parameter object (Destination value)
    {x: 100}, // Parameter object (Source value)
    0.3, // Duration
    Cubic.easeOut // Easing
);

And you can start tweening by calling play method of the tween variable.

tween.play();

Easing

There are 11 Robert Penner's easing in org.libspark.betweenas3.easing package.

  • Back
  • Bounce
  • Circ (or Circular)
  • Cubic
  • Elastic
  • Expo (or Exponential)
  • Linear
  • Quad (or Quadratic)
  • Quart (or Quartic)
  • Quint (or Quintic)
  • SIne

Each easing has easeIn, easeOut, easeInOut, easeOutIn property. These properties returnes a instance of the org.libspark.betweenas3.core.easing.IEasing interface implementing each easing calculation.

Easing with Parameter

The following easings supports custom parameters.

  • Back
  • Elastic

You can create easing with custom parameter by code like the following:

BetweenAS3.to(mc, {x: 200}, 0.3, Back.easeInWith(2.0)).play();

Custom Easing

You can create your custom easing with org.libspark.betweenas3.easing.Custom class.

You have to declare function with parameters t (current time), b (begin value), c (amount of change), d (duration) and pass it to Custom.func method.

BetweenAS3.to(mc, {x: 100}, 0.3, Custom.func(function(t:Number, b:Number, c:Number, d:Number):Number
{
	// From Tweener transition example
	// http://hosted.zeh.com.br/tweener/docs/en-us/parameters/transition.html
	var ts:Number = (t /= d) * t;
	var tc:Number = ts * t;
	return b + c * (-97.1975 * tc * ts + 257.5975 * ts * ts - 234.4 * tc + 80 * ts - 5 * t);
})).play();

Relative Value

You can set relative value in destination or source value by appending $ as prefix of proeprty name.

// Move 200px right from current position.
BetweenAS3.to(mc, {$x: 200}, 0.3).play();

Tween Controlling

You can control instance of the tween like MovieClip by the following methods:

  • play()
  • gotoAndPlay()
  • stop()
  • gotoAndStop()
  • togglePause()
// Toggle stop and play on click stage

var t:ITween = BetweenAS3.to(mc, {x: 100}, 0.3);

stage.addEventListener(MouseEvent.CLICK, function(e:MouseEvent):void
{
	t.togglePause();
});

t.play();

Endless Repeat

Set stopOnComplete propperty to false to disable automatic stopping when complete tweening.

var t:ITween = BetweenAS3.to(mc, {x: 100}, 0.3);
t.stopOnComplete = false;
t.play();

Handling Events

ITween interface is also implementing IEventDispatcher interface so you can use AS3-style event handling. The following events are supported:

  • org.libspark.betweenas3.events.TweenEvent
    • PLAY
    • STOP
    • UPDATE
    • COMPLETE

Classic Event Handlers

Do you like AS2-style event handlers? No problem. Also the following event handler proeprties are supported in ITween interface.

  • onPlay
  • onPlayParams
  • onStop
  • onStopParams
  • onUpdate
  • onUpdateParams
  • onComplete
  • onCompleteParams

Sub Object Tween

If you want to tween sub-object (means object holded by parent object as a property) like colorTransform, soundTransform, etc, please use the following sub-object tween.

// ColorTransform in DisplayObject
BetweenAS3.to(mc, {
    transform: {
        colorTransform: {
            redOffset: 255
        }
    }
}).play();

// SoundTransform in SoundChannel
BetweenAS3.to(sc, {
    soundTransform: {
        volume: 0.0
    }
}).play();

You can nest parameter object as you like.

Special Properties

The following special properties are supported in parameter object.

  • DisplayObject
    • _bevelFilter
    • _blurFilter
    • _colorMatrixFilter
    • _convolutionFilter
    • _displacementMapFilter
    • _dropShadowFilter
    • _glowFilter
    • _gradientBevelFilter
    • _gradientGlowFilter
    • _shaderFilter
  • MovieClip
    • _frame

If you want filter tween, please use sub-object tween. Available property of the filter object is same as each BitmapFilter? class.

BetweenAS3.to(mc, {
    _glowFilter: {
        blurX: 32,
        blurY: 32
    }
}).play();

Bezier Tween

You can create bezier tween by using BetweenAS3.bezier method. Pass control points in argument 4. Set Array of control points for each property.

BetweenAS3.bezier(
	mc, // Target object
	{x: 385, y: 207}, // Parameter object (Destination value)
	null, // Parameter object (Source value)
	{
		x: [58.05, 145.9, 246.7, 345.55], // Controls points
		y: [61.4, 80.65, 167.05, 209.3]
	}
).play();

Physical Tween

You can create non time-based (Physical) tween with BetweenAS3.physical method and org.libspark.betweenas3.easing.Physical easing.

BetweenAS3.physical(mc, {x: 200}, {x: 100}, Physical.uniform(10.0)).play();

The following easings are supported:

  • uniform
  • accelerate
  • exponential

Delay Setting

Please see 'Delay' in the following Tween Decorating.

Tween Grouping

Please see 'Serial' and 'Parallel' in the following Tween Decorating.

Tween Decorating

You can create new tween instance by decorating already exists tween instance.

For example, you can create time-scaled tween with BetweenAS3.scale method.

var t1:ITween = BetweenAS3.tween(mc, {x: 100}, null, 0.5); // 0.5 sec tween
var t2:ITween = BetweenAS3.scale(t1, 3.0); // 1.5 sec tween

The following decoration method are supported.

Delay

Adds delay to the tween.

var t2:ITween = BetweenAS3.delay(t1, 2.0); // 2.0 sec delay

Reverse

Reverse the tween.

var t2:ITween = BetweenAS3.reverse(t1);

Repeat

Repeats the tween.

var t2:ITween = BetweenAS3.repeat(t1, 5); // 5 times repeat

Scale

Time-scales the tween.

var t2:ITween = BetweenAS3.scale(t1, 3.0); // 3.0 times scale

Slice

Slices the part of the tween.

var t2:ITween = BetweenAS3.slice(t1, 0.1, 0.2); // 0.1 sec - 0.2 sec

Serial

Joins multiple tweens. Tweens will play in sequence.

var t4:ITween = BetweenAS3.serial(t1, t2, t3);

Parallel

Joins multiple tweens. Tweens will play at same time.

var t4:ITween = BetweenAS3.parallel(t1, t2, t3);

You can assemble complex tween like the following by using above methods.

var t1:ITween = BetweenAS3.tween(mc, {x: 200}, {x: 100}, 0.3, Expo.easeOut);
var t2:ITween = BetweenAS3.repeat(BetweenAS3.serial(
    BetweenAS3.slice(t1, 0.0, 0.1),
    BetweenAS3.reverse(BetweenAS3.slice(t1, 0.0, 0.1)),
    BetweenAS3.slice(t1, 0.0, 0.1),
    BetweenAS3.scale(BetweenAS3.slice(t1, 0.1, 0.2)),
    BetweenAS3.slice(t1, 0.2, 0.3)
), 3);

Action Integration

You can do some actions within tweening. For example, you can call addChild before tweening and removeChild after tweening.

BetweenAS3.serial(
    BetweenAS3.addChild(mc, parent),
    BetweenAS3.to(mc, {scaleX: 2.0, scaleY: 2.0}),
    BetweenAS3.removeFromParent(mc)
);

The following action methods are supported:

  • addChild
  • removeFromParent
  • func

Applying

You can set value of proeprty without tweening by calling BetweenAS3.apply method. Especially, this is useful for filter setting.

BetweenAS3.apply(mc, {
    _bluerFilter: {
        blurX: 32,
        blurY: 32
    }
});

Better Performance

BetweenAS3 works very fast and low memory. Please see the following demo.

Known Issues

  • In Alpha r3022
    • onComplete will be called twice when 2nd loop of serial tween will start.
    • An error has occurred when tween an instance of flash.utils.Proxy.
    • gotoAndPlay() will not affected while playing. (fixed in r3080)
    • RagenError has occurred when using bezier tween with Elastic or Back easing. (fixed in r3079)
    • Sometimes ReferenceError has occurred in EnterFrameTicker. (fixed in r3077)

Future Plans

  • More special properties
  • More action methods
  • Library extension system
  • Preset mechanishm
  • etc

License

Licensed under the MIT License

Copyright (c) 2009 BeInteractive! (www.be-interactive.org) and
                   Spark project  (www.libspark.org)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.