1. Basic Setup
4. Creating and Playing Tweens
5. Fire Tweens
6. Play Modes
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 stoppedExample:
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.