# TweenGMS Starter Guide v0.9.70

0. What is Tweening

1. Basic Setup

2. Simple Tweens

3. Property Setters

4. Creating and Playing Tweens

5. Fire Tweens

6. Play Modes

7. Tween Callbacks

8. Extended Property Setters

9. Troubleshooting

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, x__, EaseInOutQuad, TWEEN_MODE_ONCE, true, 0.0, 3.0, 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.

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.

Note: scripts located in the [Extra] and [Deprecated] folders are not required.

Do not manually create or destroy obj_SharedTweener. An instance of the object will, automatically, be 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.

It is suggested to create custom property setters and ease algorithms independent of [Default_Property_Setters], [Default_Property_Setters_Ext] and [Default_Ease_Algorithms]. This will prevent future updates from accidentally deleting any custom scripts you choose to add.

When updating TweenGMS, delete all outdated files and import the new ones to replace them.

Also, make sure to check out the included example projects which are located in [Extensions] -> [TweenGMS] ->

* Demo_Project.gmz

* AlienOdds_Game_Project.gmz

If needed, you can also find the previous version of TweenGMS as TweenGMS_Previous_Version.gmez

2. Simple Tweens

To start tweening things as easily and quickly as possible, you can use TweenSimple* scripts for basic easing of various object properties.

By default, simple tweens use STEP timing, but you can switch them to SECONDS(delta) timing by using the script TweenSimpleUseDelta(use_delta). Every new simple tween will use the previously set STEP/DELTA flag. Each simple tween can, optionally, supply a delay value for delaying the start of a tween. A unique tween id is returned from simple tweens which can be used to manipulate their state.

The following simple tweens are provided:

    TweenSimpleMove()
            Move instance's x/y position

    TweenSimpleMoveInt()
            Move instance's x/y position (eased x/y values are rounded)

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

    TweenSimpleRotate()
            Rotate instance's image angle

    TweenSimpleTurn()
            Turn instance's direction

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

    TweenSimpleColour()
            Change instance's image blend colour

    TweenSimpleImageCycle()
            Animate sprite through given image indexes

    TweenSimpleSpeedRamp()
            Gradually increase or decrease instance's speed

    TweenSimpleHVSpeedRamp()
            Gradually increase or decreases instance's hspeed and vspeed

Example:

            // Move from current x/y position to mouse position over 30 steps
            tween = TweenSimpleMove(x, y, mouse_x, mouse_y, 30, EaseInOutQuad);

            // Pause the tween
            TweenPause(tween);

            // Have following simple tweens use seconds(delta) timing
            TweenSimpleUseDelta(true);

            // Rotate from 0 to 360 over 1 second after a 2 second delay
            TweenSimpleRotate(0, 360, 1.0, EaseInOutElastic, 2.0);

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

3. Property Setters

In order for TweenGMS to access and ease different variables, property setter scripts must be created for each variable. Default property setter scripts are included with TweenGMS for various built-in object and global variables. They can be found in the tabbed script Default_Property_setters.

To create your own property setter scripts, you must create a new script and have the relevant variable equal argument0. If the variable is for an instance, you must use argument1 for assigning the value to the appropriate target instance. Property setter scripts for global variables are not required to use argument1 if a specific target isn't needed. It is suggested to name property setter scripts with a post-fixed double underscore “__” or a simliar convention to prevent potential variable naming conflicts.

            /// my_variable__(value,target)
            argument1.my_variable = argument0;

            /// g_variable__(value)
            global.variable = argument0;

The property can then be used with TweenGMS' to tween the appropriate value:

            TweenFire(id, my_variable__, EaseLinear, TWEEN_MODE_ONCE, true, 0.0, 1.0, 0, 100);
            TweenFire(id, g_variable__, EaseLinear, TWEEN_MODE_ONCE, true, 0.0, 1.0, 0, 100);

However, there are a couple of alternatives to using property setter scripts. One alternative is to create single-index arrays and pass them directly as the tween property. The tweened value can then be accessed from the array's [0] index value.

            // Create single-index array and assign it a value
            myArray[0] = 0;

            // Pass array (name only) as property of tween
            TweenFire(id, myArray, EaseInOutQuart, TWEEN_MODE_PATROL, true, 0.0, 1.0, 0, 100);

            // Draw value by accessing myArray[0]
            draw_text(x, y, myArray[0]);

Another alternative is to supply a property as an empty string “” which tells the system to not calculate a value automatically. The value will only be calculated and returned, when needed, using TweenCalc().

            // Fire tween using “” null property
            tween = TweenFire(id, “”, EaseInQuad, TWEEN_MODE_LOOP, true, 0.0, 1.0, 0, 100);

            // Show value by calculating value from tween's state
            draw_text(x, y, TweenCalc(tween));

    Note: There are two additional versions of TweenCalc() --> TweenCalcAmount() and TweenCalcTime()

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 this way, you can declare defined or undefined tweens.

Defintion:

            TweenCreate(target[,property,ease,mode,delta,delay,dur,start,dest,...])

            @target         instance to associate with tween (passed to property setter)
            (Optional if defining)
            @property       property setter script
            @ease           ease algorithm script
            @mode           play mode constant (0-4) TWEEN_MODE_****
            @delta          timing uses SECONDS if true or STEPS if false
            @delay          time to delay start of tween
            @dur            duration of time for tween to play
            @start          start value of eased property
            @dest           destination value of eased property
            @...            additional parameters for extended property setters

            Returns: tween id

Example:

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

            // Create defined tween
            tween_def = TweenCreate(id, x__, EaseInQuad, TWEEN_MODE_LOOP, true, 0.0, 1.0, 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[,property,ease,mode,delta,delay,duration,start,destination,...])

            @tween          previously created tween id
            (Optional if tween defined)
            @property       property setter script
            @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
            @dur            duration of time for tween to play
            @start          start value of eased property
            @dest           destination value of eased property
            @...            additional parameters for extended property setters

            Returns: na

Example:

            // Play undefined tween
            TweenPlay(tween_undef, x__, EaseInElastic, TWEEN_MODE_REPEAT, true, 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, y__, EaseInQuad, TWEEN_MODE_PATROL, false, 0, 30, 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. 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,property,ease,mode,delta,delay,duration,start,destination,...)

            @target         instance to associate with tween (passed to property setter)
            @property       property setter script
            @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
            @start          start value of eased property
            @dest           destination value of ease property
            @...            (optional) additional parameters for extended property setters

            Returns: tween id

Example:

            // Fire tween
            tween = TweenFire(id, x__, EaseOutCubic, TWEEN_MODE_ONCE, true, 0.0, 1.0, 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, x__, EaseInCubic, 0, true, 5.0, 1.0, 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

    NOTE: There is an additional script, TweenGo(), which is a simplified version of TweenFire() with only essential parameters required.

    IMPORTANT: Tween's will NOT be 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 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

`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,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, x__, EaseOutQuad, 0, true, 5.0, 1.0, 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 the TweenEventEnable(). Individual callbacks can also be suppressed by using TweenCallbackEnable().

`8.` `Extended Property Setters``` `(Advanced)`

Extended property setters allow you to access custom data passed to tweens. This data can be passed to tweens as optional arguments at the end of TweenFire(), TweenCreate(), or TweenPlay().

If you pass only one extra argument, the value will directly override the default argument1 (target) value passed to the property setter script. If you supply more than one extra argument, an array of extended data will override the default argument1 (target) value. If needed, the tween's target instance can still be accessed from argument2. Like standard property setters, the eased value is contained in argument0.

The following are some examples:

    #1      [Override “target” with view index]

            var _view = 0;
            TweenFire(id, ext_view_xview__, EaseInQuad, 0, true, 0.0, 1.0, 0, 320, _view);

            *** EXT SETTER ***
            /// ext_view_xview__(value,view)
            {
                    view_xview[argument1] = argument0;
            }

    #2      [Override “target” with view array data]

            var _view = 0;
            TweenFire(id, ext_view_xyview__, EaseInQuad, 0, true, 0.0, 1.0, 0, 1, _view, 0, 320, 0, 240);

            *** EXT SETTER ***
            /// ext_view_xyview(amount,[view,x1,x2,y1,y2])
            {
                    var _amount = argument0;
                    var _data   = argument1;
                    var _view   = _data[0];

                    view_xview[_view] = lerp(_data[1], _data[2], _amount);
                    view_yview[_view] = lerp(_data[3], _data[4], _amount);
            }

    #3      [Override target with position data and use target in argument2]

            TweenFire(id, ext_xy__, EaseOutSine, 0, true, 0.0, 1.0, 0, 1, x, mouse_x, y, mouse_y);

            *** EXT SETTER ***
            /// ext_xy__(amount,[x1,x2,y1,y2],target)
            {
                    var _amount = argument0;
                    var _data   = argument1;
                    var _target = argument2;

                    _target.x = lerp(_data[0], _data[1], _amount);
                    _target.y = lerp(_data[2], _data[3], _amount);
            }

If you need to pass a large number of arguments to extended property setters, for convenience, you can use TPExt() which returns an array of data. The following example works exactly the same as the previous example above:

            var _extData = TPExt(x, mouse_x, y, mouse_y);
            TweenFire(id, ext_xy__, EaseInQuad, 0, true, 0.0, 1.0, 0, 1, _extData);

When using extended property setters, it is often useful to create tweens with a start value of 0 and destination value of 1. The value between 0 and 1 can then be accessed from the extended property setter as a relative amount reflecting the tween's ease algorithm over time. This value can be used with GameMaker's lerp() function to calculate the custom data supplied to the extended property setter.

e.g.

    /// ext_xy__(amount,data[x1|x2|y1|y2],target)
    {

            var _amount = argument0; // Get amount reflecting ease algorithm over time
            var _data   = argument1; // Get extended data array
            var _target = argument2; // Get relative target instance

            // Extract extended data
            var _x1 = _data[0];
            var _x2 = _data[1];
            var _y1 = _data[2];
            var _y2 = _data[3];

            // Update x/y position by using lerp() with extended data and amount
            _target.x = lerp(_x1, _x2, _amount);
            _target.y = lerp(_y1, _y2, _amount);
    }

As shown in the example above, the eased amount is passed to the extended property setter as argument0. We can use this value as an amount for the lerp function and fill in the custom start/destination values as needed. Any extended values passed to the property setter are accessible via argument1 which holds an override value or an array of data in the order you supplied it. If needed, the tween's target can be accessed from argument2.

You can also have extended properties use different tweening algorithms for each eased variable. You can achieve this by using a linear tween (EaseLinear) with a start value of 0 and a destination value of 1. You can then use the Ease() function in the extended property setter with the linear value reflecting the total time elapsed. The modified version of the above example could look like this:

    /// ext_xy__(amount,data[x1|x2|y1|y2],target)
    {

            var _amount = argument0; // Get amount representing time elapsed (0.0 – 1.0)
            var _data   = argument1; // Get extended data
            var _target = argument2; // Get target instance

            // Extract extended data
            var _x1 = _data[0];
            var _x2 = _data[1];
            var _y1 = _data[2];
            var _y2 = _data[3];

            // Update x/y position by using Ease() with custom data and amount
            _target.x = Ease(_x1, _x2, _amount, EaseInOutQuad);
            _target.y = Ease(_y1, _y2, _amount, EaseInOutElastic);
    }

NOTE: It is advised to add custom extended property setters outside of Default_Property_Setters_Ext. It is also advised to use the "ext_property__" convention when naming custom extended property setters but is not required.

`9.` `Troubleshooting`

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

B) 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!!

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