TweenGMX Starter Guide

0. What is Tweening?

NOTE: After reviewing this document, please see the Reference Guide for more information about other TweenGMX features!

Tweening is the interpolation of two values determined by a specified algorithm over a set duration of time. It lets you set a start and destination value which are automatically eased between. Using different easing algorithms produces different behaviours for how the points between the start and destination values are filled in.

For example, we can tween an object's x position from 0 to 100 over 3 seconds:

    TweenFire(self, EaseInOutSine, TWEEN_MODE_ONCE, true, 0.0, 3.0, “x”, 0, 100);

Using the EaseInOutQuad algorithm, the object will smoothly accelerate from its starting position (0) and automatically move to it's destination point (100) where it will smoothly slow down before finishing.
There are various easing algorithms you can choose from to help achieve the look you want.

It is possible to tween multiple values at once by supplying more properties at the end:

    TweenFire(self, EaseInOutSine, TWEEN_MODE_ONCE, true, 0.0, 3.0, “x”, x, mouse_x, “y”, y, mouse_y);

You can find more information regarding the standard easing algorithms at easings.net.

Additionally, a good video to watch regarding tweening is Juice It or Lose It (YouTube) by Martin Jonasson and Petri Purho.

2. Easing Functions

TweenGMX includes many standard easing functions, including those by Robert Penner.

It is possible to directly use these functions by themselves, but that is not the main goal of TweenGMX.
Instead, TweenGMX references these functions in order to update things automatically “under the hood”.

We use the flat version of function names (e.g. EaseInOutSine) without the closing brackets () when passing them to tweening scripts:

e.g. TweenFire(self, EaseInOutSine, 0, true, 0, 1, “x”, 0, 1);

You can also reference easing functions by using their associated string name (e.g. “InOutSine”).
When using string names, you can optionally provide only “i” or “o” to reference “in” and “out” (e.g. “ioSine”).
You may also notice that string letter case does not matter, so “inSine” and “INSINE” would both be treated the same.
You can also use underscores if you want (e.g. “in_out_sine”).

Note: The “sine” functions also include shorthand versions “i”, “o”, and “io”.

It is also possible to pass Animation Curves instead of easing functions. Please see the section Animation Curves in the TGMX Reference Guide for more details.

The standard easing functions are:

FUNCTION NAME	STRING NAME(S)
EaseLinear	“linear” \| “”
EaseInSine	“InSine” \| “iSine” \| “i”
EaseOutSine	“OutSine” \| “oSine” \| “o”
EaseInOutSine	“InOutSine” \| “ioSine” \| “io”
EaseInQuad	“InQuad” \| “iQuad”
EaseOutQuad	“OutQuad” \| “oQuad”
EaseInOutQuad	“InOutQuad” \| “ioQuad”
EaseInCubic	“InCubic” \| “iCubic”
EaseOutCubic	“OutCubic” \| “oCubic”
EaseInOutCubic	“InOutCubic” \| “ioCubic”
EaseInQuart	“InQuart” \| “iQuart”
EaseOutQuart	“OutQuart” \| “oQuart”
EaseInOutQuart	“InOutQuart” \| “ioQuart”
EaseInQuint	“InQuint” \| “iQuint”
EaseOutQuint	“OutQuint” \| “oQuint”
EaseInOutQuint	“InOutQuint” \| “ioQuint”
EaseInExpo	“InExpo” \| “iExpo”
EaseOutExpo	“OutExpo” \| “oExpo”
EaseInOutExpo	“InOutExpo” \| “ioExpo”
EaseInCirc	“InCirc” \| “iCirc”
EaseOutCirc	“OutCirc” \| “oCirc”
EaseInOutCirc	“InOutCirc” \| “ioCirc”
EaseInBack	“InBack” \| “iBack”
EaseOutBack	“OutBack” \| “oBack”
EaseInOutBack	“InOutBack” \| “ioBack”
EaseInElastic	“InElastic” \| “iElastic”
EaseOutElastic	“OutElastic” \| “oElastic”
EaseInOutElastic	“InOutElastic” \| “ioElastic”
EaseInBounce	“InBounce” \| “iBounce”
EaseOutBounce	“OutBounce” \| “oBounce”
EaseInOutBounce	“InOutBounce” \| “ioBounce”

Additionally, there are included animation curves which can also be used.
You can reference these as examples of how to build your own!

CURVE NAME	STRING NAME(s)
EaseFastToSlow	“FastToSlow” \| “FastSlow”
EaseMidSlow	“MidSlow”
EaseHeartbeat	“Heartbeat” \| “Heart”

3. Easy Tweens

To start tweening things as easily and quickly as possible, you can use the TweenEasy*() functions to ease the most common object (or struct) properties.
By default, Easy Tweens use STEP timing, but you can switch them to use SECONDS (DELTA) timing by calling TweenEasyUseDelta(true).
Every new Easy Tween will use the previously set global STEP/DELTA flag for its timing.

Easy Tweens can set the play mode by providing an optional final [mode] argument.
If not supplied, the tween will use the default TWEEN_MODE_ONCE (“once”).

Starting an Easy Tween will automatically override any existing Easy Tween of the same type.
This means that you don’t need to worry about stopping or destroying previous tween calls.

A unique tween id is returned from each Easy Tween which can be used to later manipulate tween states, like pausing or adding event callbacks.

Tweens are automatically updated each step by o_SharedTweener.
Think of each tween call like firing a bullet.
Every time you press a trigger, a new bullet is fired.
Every time you call a TweenEasy*() function, a new tween is created.

The following Easy Tweens are provided:

TweenEasyMove()                       
        Move instance's x/y position

TweenEasyScale()                      
        Scale instance's image x/y scale

TweenEasyRotate()             
        Rotate instance's image angle

TweenEasyTurn()                       
        Turn instance's direction

TweenEasyFade()                       
        Fade in or out an instance's image alpha

TweenEasyBlend()             
        Change instance's image blend colour

TweenEasyImage()         
        Animate sprite through given image indexes

TweenEasySpeed()          
        Gradually change an instance's speed

TweenEasySpeedHV()        
        Gradually change an instance's hspeed and vspeed

TweenEasyPath()

       Move x/y position using a path resource

Example:

        // Move from current x/y position to mouse position over 30 steps
        tween = TweenEasyMove(x, y, mouse_x, mouse_y, 0, 30, EaseInOutQuad);
        
        // Pause the tween
        TweenPause(tween);
        
        // Have following simple tweens use seconds(delta) timing
        TweenEasyUseDelta(true);
        
        // Spin back and forth from 0 to 360 over 1 second after a 2 second delay
        TweenEasyRotate(0, 360, 2.0, 1.0, EaseInOutCubic, TWEEN_MODE_PATROL);

4. Fire Tweens

TweenFire() is the default function for playing tweens.
It allows you to create and play a tween from a single script call which returns a unique tween id.
Tweens created this way differ from tweens made with TweenCreate() in that they are destroyed and become invalid as soon as they are finished or manually stopped.
Like TweenCreate(), however, they will also be destroyed automatically if their target instance/struct is destroyed or if TweenDestroy() is manually called.

(Please use caution when using Struct Targets for tweens. You can read more about that from the Reference Guide)

Fired tweens are automatically updated each step by o_SharedTweener.
Think of each tween call like firing a bullet.
Every time you press a trigger, a new bullet is fired.
Every time you call TweenFire, a new tween is created.

Defintion:

        TweenFire(target, ease, mode, delta, delay, duration, property, start, destination, ...)
        
        @target         instance or struct to associate with tween (passed to property setter)
        @ease           ease algorithm script
        @mode           play mode constant (0-4) TWEEN_MODE_****
        @delta          timing will use SECONDS if true or STEPS if false
        @delay          time to delay start of tween in seconds or steps
        @dur            duration of time for tween to play
        @property       variable property string
        @start          start value of eased property
        @dest           destination value of eased property      
        @...            (optional) additional properties

        Returns: tween id

Example:

        
        // Fire tween
        tween = TweenFire(self, EaseInOutSine, TWEEN_MODE_ONCE, true, 0.0, 1.0, “x”, x, mouse_x);

        // Stop tween – will be immediately destroyed and removed from system
        TweenStop(tween);

Supplying a positive delay value will delay the start of the fired tween.

        // Fire tween with a 5 second delay
        tween = TweenFire(self, EaseInCubic, TWEEN_MODE_BOUNCE, true, 5.0, 1.0, “x”, x, mouse_x);

TweenFire() can use the following play mode constants or strings:

        0 | TWEEN_MODE_ONCE   | “once”
        1 | TWEEN_MODE_BOUNCE | “bounce” 
        2 | TWEEN_MODE_PATROL | “patrol” 
        3 | TWEEN_MODE_LOOP   | “loop”
        4 | TWEEN_MODE_REPEAT | “repeat”

Examples:

        // Fire tween with mode “patrol”
        TweenFire(self, EaseInCubic, “patrol”, true, 0, 1.0, “x”, 0, 100);

        // Fire tween with mode 1 (bounce)
        tween = TweenFire(self, EaseInCubic, 1, true, 5.0, 1.0, “x”, x, mouse_x);

The mode “strings” are not case sensitive. “ONCE” is the same as “once”

        

IMPORTANT: Tweens will NOT be updated if their target instance is deactivated. They will continue once their target instance is activated again.

5. Creating and Playing Tweens

TweenCreate() creates and returns a new tween which exists in memory until its associated target instance is destroyed or it is manually destroyed with TweenDestroy().
Unlike TweenFire(), tweens created with TweenCreate() will not be automatically destroyed when a tween finishes but will continue to persist.
When creating tweens this way, you can declare defined or undefined tweens.

(Please use caution when using Struct Targets for tweens. You can read more about that from the Reference Guide)

Defintion:

        TweenCreate(target, [ease, mode, delta, delay, dur, property, start, dest, ...])
  
        @target         instance to associate with tween
        (Optional if defining)
        @ease           ease algorithm script
        @mode           play mode constant (0-4) TWEEN_MODE_****
        @delta          timing method uses SECONDS if true or STEPS if false
        @delay          time to delay start of tween
        @dur            duration of time for tween to play
        @property       variable property string e.g. “x”
        @start          start value of eased property
        @dest           destination value of eased property      
        @...            (optional) additional properties

        Returns: tween id

Example:

        // Create undefined tween
        tween_undef = TweenCreate(self);

        // Create defined tween
        tween_def = TweenCreate(self, EaseInQuad, TWEEN_MODE_LOOP, true, 0.0, 1.0, “x”, x, mouse_x);

TweenPlay() can then be used to play previously created tweens.
Undefined tweens must supply the remaining parameters when they are played.
However, a defined tween only needs to supply it's unique id handle and will play according to its previously defined parameters.

Defintion:

        TweenPlay(tween, [ease, mode, delta, delay, duration, property, start, destination, ...])
        
        @tween          previously created tween id
        (Optional if tween is defined)
        @ease           ease algorithm script
        @mode           play mode constant (0-4) TWEEN_MODE_****
        @delta          timing method uses SECONDS if true or STEPS if false
        @delay          time to delay start of tween
        @dur            duration of time for tween to play
        @property       variable property string e.g. “x”
        @start          start value of eased property
        @dest           destination value of eased property      
        @...            (optional) additional properties

        Returns: tween id

Example:

        
        // Play undefined tween
        TweenPlay(tween_undef, EaseInElastic, TWEEN_MODE_REPEAT, true, “x”, x, mouse_x)

        // Play defined tween
        TweenPlay(tween_def);

TweenCreate() and TweenPlay() can use the following play mode constants:

        0 | TWEEN_MODE_ONCE   | “once”
        1 | TWEEN_MODE_BOUNCE | “bounce” 
        2 | TWEEN_MODE_PATROL | “patrol” 
        3 | TWEEN_MODE_LOOP   | “loop”
        4 | TWEEN_MODE_REPEAT | “repeat”

The mode “strings” are not case sensitive. “ONCE” is the same as “once”.

NOTE:
A fully defined tween can, optionally, still have its previously set values overridden when played.

        // Override defined tween
        TweenPlay(tween_def, EaseInQuad, TWEEN_MODE_PATROL, false, 0, 30, “y”, y, mouse_y);

NOTE:
Tween's will NOT be automatically updated if their target instance is deactivated.
They will continue once their target instance becomes active again.

6. Play Modes

Tweens can be played using one of five different play mode types.
Macros or “mode” strings are available for selecting desired modes. (Simply supplying a number between 0 and 4 is also valid)
Strings are not case sensitive, so “patrol”, “Patrol”, and “PATROL” are all valid.

0 | TWEEN_MODE_ONCE | “once”
        The default tween mode which will play a tween once from start to destination.
        TWEEN_EV_FINISH is called when the tween reaches its destination

1 | TWEEN_MODE_BOUNCE | “bounce”
        Plays a tween once from start to destination before it returns back to its start value and finishes.
        TWEEN_EV_CONTINUE is called when a tween reaches its destination
        TWEEN_EV_FINISH is called when a tween returns to its start value

2 | TWEEN_MODE_PATROL | “patrol”
        Plays a tween endlessly back and forth between its start and destination values.
        TWEEN_EV_CONTINUE is called when a tween reaches its start or destination values

3 | TWEEN_MODE_LOOP | “loop”
        Plays a tween, endlessly, from start to destination before jumping back to start and continuing.
        TWEEN_EV_CONTINUE is called when tween loops back to its start

4 | TWEEN_MODE_REPEAT | “repeat”
        Plays a tween endlessly, using its destination as a new relative start value when destination is reached.
        TWEEN_EV_CONTINUE is called when a tween repeats from its relative destination

7.Tween Callbacks

Tweens can have script callbacks attached to various events.
You can add multiple callbacks to events by using TweenAddCallback() which returns a unique callback id.
Up to 12 arguments can be passed to callback scripts.

Defintion:

        TweenAddCallback(tween, event, target, script, [arg0, ...])
        
        @tween   = tween id
        @event   = tween event constant -- TWEEN_EV_****
        @target  = instance environment to use when calling script
        @script  = script, function, or method to be executed
        @arg0... = (optional) additional arguments to pass to script

Tweens support the following EVENT CONSTANTS or “strings” for when they are playing:

        TWEEN_EV_PLAY     | “play”       tween starts to play
        TWEEN_EV_FINISH   | “finish”      tween finished
        TWEEN_EV_CONTINUE | “continue”   tween bounces, loops, or repeats
        TWEEN_EV_PAUSE    | “pause”       tween is paused
        TWEEN_EV_RESUME   | “resume”      tween is resumed
        TWEEN_EV_STOP     | “stop”        tween is stopped
        TWEEN_EV_REVERSE  | “reverse”    tween is reversed
          

Example:

        tween = TweenCreate(self);
        
        // Show “42” when tween is paused
        cb1 = TweenAddCallback(tween, “pause”, self, ShowNumber, 42);
        // Show “Don't Panic!” when tween finishes
        cb2 = TweenAddCallback(tween, “finish”, self, ShowMessage, “Don't Panic!”);
NOTE: 
Strings are not case sensitve, so “play”, “Play”, and “PLAY” are all valid.

Tweens also support the following EVENT CONSTANTS for when they are delayed:

        TWEEN_EV_FINISH_DELAY           delay finishes
        TWEEN_EV_PAUSE_DELAY            delayed tween is paused
        TWEEN_EV_RESUME_DELAY           delayed tween is resumed
        TWEEN_EV_STOP_DELAY             delayed tween is stopped


Example:
        tween = TweenFire(self, EaseOutQuad, 0, true, 5.0, 1.0, “x”, x, mouse_x);

        // Show message when tween's delay finishes
        cb = TweenAddCallback(tween, TWEEN_EV_FINISH_DELAY, self, ShowMessage, “Delay finished! Lets start playing!”);

Advanced: Callbacks can also be added to tween’s directly within tween calls themselves. After supplying properties to the tween, we can add callbacks by supplying event strings like so... (DOCS INCOMPLETE)

Example:

        TweenFire(self, “ioQuad”, 0, true, 0, 1, “x”, 0, 100, “@finish”, SomeFunction);

        TweenFire(self, “ioQuad”, 0, true, 0, 1, “x”, 0, 100, “@finish”, [show_message, “Done!”]);

IMPORTANT: Like tweens, callbacks are associated with a designated target instance which uses its environment to execute the script. Any callback associated with a deactivated target instance will not be executed. Those associated with destroyed target instances will be automatically removed and cleared from the system.

Note: If needed, specific tween events can be suppressed by using TweenEventEnable(). Individual callbacks can also be suppressed by using TweenCallbackEnable().

Callbacks can also be added to tween’s directly within tween calls themselves. After supplying properties to the tween, we can add callbacks by supplying event strings like so... (DOCS INCOMPLETE)

8. Property Builders (Advanced | Not Required)

Instance, Struct, or Global variables can be tweened by simply passing their variable names as a string to a property argument:

“variable” -- variable belonging to the tween’s target
“self.variable”
“other.variable”
“global.variable”
“some_object.variable”
“some_struct.variable”

Note: Local variables are not supported (e.g. var _temp)

Examples:

        TweenFire(self, EaseInQuad, 0, true, 0.0. 1.0, “my_variable”, 0, 100);

        TweenFire(self, EaseInCubic, 0, true, 0.0, 1.0, “global.variable”, 0, 10);

However, in order for TweenGMX to support more complex properties (or optimize), Property Builder functions can be used to apply setter/getter functions for specified variables.
Various optimized setter/getter functions are already included with TweenGMX for default built-in object variables (“x”, “y”, “image_angle”, etc...) which can be found in the script TGMX_7_Properties.

To build your own custom properties, you must create setter/getter functions and associate them with a variable name by using TPFuncShared() or TPFunc(). (Please read about them in the TGMX Reference Guide)

Please note that using Property Builders to optimize properties has the greatest impact on YYC and JS/HTML5 platforms. They do not make a big difference with VM targets.
Typically, I don’t suggest worrying about this. But if you have hundreds of tweens which call the same property at once, then you might have a good reason to optimise it with a function like TPFuncShared().

9.Tips

Use the special property tag “scale!” can be used to to scale both image_xscale and image_yscale together.

Examples:

TweenFire(self, EaseInQuad, 0, true, 0, 1, “scale!”, 0, 1);

TweenFire(self, “io”, 0, true, 0, 1, “scale!>”, 2);

Use the keyword [ all ] to affect all tweens for various scripts.

Example: TweenPause(all);

Arrays and data structures can be tweened by using the appropriate TP*() script as a property, such as TPArray() or TPList().

Example: TweenFire(self, EaseLinear, 0, true, 0, 1, TPMap(map, “key”), 0, 100);

Use TweenEasyUseDelta(true) to switch “easy tween” timing to use seconds instead of steps.

When using native YYC targets, clear the compiler cache (broom button at top) if strange errors occur. This should always be done after updating TweenGMX.

For debugging purposes, TweenSystemGet(“tween_count”) can help track the number of tweens in the system and to make sure tweens are being added or cleared as expected.

The script TweenPlay(tween) can be used to restart a tween.

TweenGMX v1.0.5 Starter Guide