TweenGMS Starter Guide v1.11

0. What is Tweening?

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(id, EaseInOutQuad, 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 (up to 10) by supplying more properties at the end:

    TweenFire(id, EaseInOutQuad, 0, 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.

1. Basic Setup

Import all resources associated with the TweenGMS extension into your project. If updating TweenGMS, make sure to delete all outdated files before importing the new ones to replace them.

Do not manually create or destroy obj_SharedTweener. An instance of the object will be automatically created and managed by the system. Try not to deactivate obj_SharedTweener with instance deactivation functions. If you do, call SharedTweenerActivate() to activate it again.

Unlike previous versions of TweenGMS, property setter scripts are no longer required for easing custom variables. However, they can still be used to boost performance or create normalized properties. Please see the [Property Scripts] section for more details.

2. Easy Tweens

To start tweening things as easily and quickly as possible, you can use the TweenEasy*() scripts to ease the most common object 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 STEP/DELTA flag for its timing.

Optionally, “easy tweens” can supply a tween play mode as a final argument. If not supplied, the default play mode is TWEEN_MODE_ONCE.

Starting an “easy tween” will automatically override any existing “easy tween” of the same type.

A unique tween id is returned from “easy tweens” which can be used later to manipulate their state.

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

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);


NOTE: TweenEasy*() scripts are not required and can be safely deleted from your project if desired.

3. Fire Tweens

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

Defintion:

        TweenFire(target,ease,mode,delta,delay,duration,property,start,destination,...)
        
        @target         instance 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(id, EaseOutCubic, TWEEN_MODE_ONCE, true, 0.0, 1.0, “x”, x, mouse_x, “y”, y, mouse_y);

        // 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(id, EaseInCubic, 0, true, 5.0, 1.0, “x”, x, mouse_x);
        

TweenFire() can use the following play mode constants:

        0 = TWEEN_MODE_ONCE
        1 = TWEEN_MODE_BOUNCE 
        2 = TWEEN_MODE_PATROL 
        3 = TWEEN_MODE_LOOP
        4 = TWEEN_MODE_REPEAT
        

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

4. 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(). When creating tweens in this way, you can declare defined or undefined tweens.

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(id);

        // Create defined tween
        tween_def = TweenCreate(id, 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”, 0.0, 1.0, x, mouse_x)

        // Play defined tween
        TweenPlay(tween_def);

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

        0 = TWEEN_MODE_ONCE
        1 = TWEEN_MODE_BOUNCE 
        2 = TWEEN_MODE_PATROL 
        3 = TWEEN_MODE_LOOP
        4 = TWEEN_MODE_REPEAT

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.

5. Play Modes

Tweens can be played using one of five different play mode types. Macros are available for selecting the desired mode. Simply supplying a number (0-4) is also sufficient.

0 = TWEEN_MODE_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
        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
        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
        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
        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

6. Tween Callbacks

Tweens can have function or method 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 callbacks.

Defintion:

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

Tweens support the following EVENT CONSTANTS for when they are playing:

        TWEEN_EV_PLAY           tween starts to play
        TWEEN_EV_FINISH         playing tween finished
        TWEEN_EV_CONTINUE       playing tween bounces, loops, or repeats
        TWEEN_EV_PAUSE          playing tween is paused
        TWEEN_EV_RESUME         playing tween is resumed
        TWEEN_EV_STOP           playing tween is stopped
        TWEEN_EV_REVERSE        playing tween is reversed
          

Example:

        tween = TweenCreate(id);
        
        // Show “490” when tween is paused
        cb1 = TweenAddCallback(tween, TWEEN_EV_PAUSE, id, ShowNumber, 490);
        // Show “Finished!” when tween finishes
        cb2 = TweenAddCallback(tween, TWEEN_EV_FINISH, id, ShowMessage, “Finished!”);

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

        TWEEN_EV_FINISH_DELAY           tween's 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(id, EaseOutQuad, 0, true, 5.0, 1.0, “x”, x, mouse_x);

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

The keyword undefined is also a valid callback target. This can be used to keep the function/method’s self environment as the callback target.

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

        // Use ‘undefined’ target to maintain original “self” (obj_Player) for the Jump method
        TweenAddCallback(tween, TWEEN_EV_FINISH_DELAY, undefined, obj_Player.Jump);

        // Omitting the target argument is also valid
        TweenAddCallback(tween, TWEEN_EV_FINISH, , obj_Player.SayWahoo);

When supplying an undefined callback target, if a function or method’s self is also undefined, then the current calling environment’s self will be used as the callback target.

Example:
        function MyFunction() { x = 1; }

        // ‘undefined’ in this case would be the same as ‘self’
        TweenAddCallback(tween, TWEEN_EV_FINISH, undefined, MyFunction);

IMPORTANT: Like tweens, callbacks are associated with a designated target instance which uses its environment to execute the script. Any callback associated with a dactivated target instance will not be executed. Those associated with destroyed target instances (or instances in another room) 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().

7. Property Scripts (Not Required)

Property scripts are no longer required by TweenGMS. Local and Global variables can be tweened by simply supplying their variable name as a string to the property argument:

e.g. “x”, “myVar”, “globalVar”

TweenFire(id, EaseInQuad, 0, true, 0.0. 1.0, “myVar”, 0, 100); // tween “myVar” from 0 – 100

TweenFire(id, EaseInCubic, 0, true, 0.0, 1.0, “globalVar”, 0, 10); // tween “globalVar” from 0 - 10

However, in order for TweenGMS to optimize performance, property setter/getter scripts can be created for a specified variable. Default property setter/getter scripts are included with TweenGMS for various built-in object and global variables. They can be found in the folder [Properties] -> [Built Properties].

To create your own property scripts, you must create both a setter and getter script and initialize them using the script TGMS_BuildProperty().

Please see the script TGMS_DefaultProperties() for examples of constructing your own optimized properties.

8. Tips

A) Use the property “image_scale” to scale image_xscale and image_yscale together.

Example: TweenFire(id, EaseInQuad, 0, true, 0, 1.0, “image_scale”, 0, 1);

B) The properties “round(x)” and “round(y)” can be used to round eased x/y values to whole numbers.

Example: TweenFire(id, EaseInQuad, 0, true, 0, 1.0, “round(x)”, 0, 10, “round(y)”, 0, 10);

C) Use the keyword [ all ] to affect all tweens for various scripts. This can be used as an alternative to TweensAll().

Example: TweenPause(all);

D) Structs, arrays, and data structures can be tweened by using the appropriate TP*() script as a property, such as TPArray() or TPStruct().

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

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

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

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

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