# TweenGMS Starter Guide v1.0.3

0. What is Tweening

1. Basic Setup

2. Easy Tweens

3. Creating and Playing Tweens

4. Fire Tweens

5. Play Modes

6. Tween Callbacks

7. Property S cripts

8. Tips

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 destroyed, as needed, 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. 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 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.

4. Fire Tweens

TweenFire() is an alternative to using TweenCreate() and TweenPlay(). 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 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);

            // 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.

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 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,arg1,...])

            @tween   = tween id
            @event   = tween event constant -- TWEEN_EV_****
            @target  = instance environment to use when calling script
            @script  = script 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 “42” when tween is paused
            cb1 = TweenAddCallback(tween, TWEEN_EV_PAUSE, id, ShowNumber, 42);
            // Show “Don't Panic!” when tween finishes
            cb2 = TweenAddCallback(tween, TWEEN_EV_FINISH, id, ShowMessage, “Don't Panic!”);

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
            cb = TweenAddCallback(tween, TWEEN_EV_FINISH_DELAY, id, ShowMessage, “Delay finished! Lets start playing!”);

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().

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_BuildDefaultProperties() 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) Arrays and data structures can be tweened by using the appropriate TP*() script as a property, such as TPArray() or TPList().

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) If nothing seems to be working, check that “Copies To:” is selected for your target platform. This can be done by going to [Extensions] -> [TweenGMS] -> right-clicking on [TGMS_Setup.gml] and selecting [Properties]. Make sure all target platforms are checked!!

H) 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.

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