Tweenline documentation

The Tweenline docs has all the necesary to create the most amazing animations with only a few lines of code.

Getting Started

Setup Tweenline

You can download the Tweenline Animation Engine from the Game Maker Studio Marketplace:


Once you have adquired Tweenline from the marketplace, you only need to do the following:

  1. Go to Marketplace > My Library.
  2. Press the Download button next to the Tweenline label.
  3. Press Add to Project. And then Import All.
  4. Right click into any of the included files and select Open in Explorer.
  5. Copy all files to a secure folder outside game maker (for backup)

To view the demo files:

  1. File > New
  2. Import. And select Tweenline_demo_project.gmz (from the included files you make the backup)
  3. Click import.

To Import the basic tweenline SDK extension into your project:

  1. Open your existing project or create a new empty project
  2. Drag tweenline.gmez into the Game Maker Window. (from the included files you make the backup in the 3rd step)
  3. Right click in the extension, click "Import Resources", "Import All", "ok".
  4. Enjoy!

Your First Tween

To create your first Tween, add the following code to the creation event of an object, and place it in an empty room:

tween_to(id, 2, array("x",x+300,"patrol",true));

This will tween the x variable of the current object from the current value to the value x+300 in 2 seconds and then will repeat the animation backwards and forwards indefinitely.


Tween Creation Functions

tween_to( target_object, duration, vars);

Creates a new tween that animates the target_object variables to the specified destination values (from the current values) and returns its index.

Arguments
target_object [Game Maker Object]

Target object whose properties should be affected. The target can be any game maker object.

duration [Real]

Duration in seconds (or frames if "useframes" true is set in the vars parameter)

vars [Array]

An object defining the end value for each variable that should be tweened (SETTERS) as well as any special properties like "yoyo", "repeat", "ease", etc. (special VARS).

For example, to tween obj_enemy.x to 100 and obj_enemy.y to 200 with a bouncy easing effect and a duration of 1 second, do this:

tweenline_to( obj_enemy, 1, array("x",100, "y",200, "ease", ease_bounceout)); 

The vars array has the folowing syntax:

array( "SETTER_name",value, "other_SETTER",value, "etc_SETTER",value, "special_VARS_name",value);

You can mix SETTERS names and special VARS names. Other example: tween obj_player's alpha to zero while stretching in both x and y.

tweenline_to( obj_player, 2.5, array("xscale",1.2, "yscale",2, "alpha", 0});
Note: To get more info about Default SETTERS and special VARS, check the Apendix: Setters & Vars

tween_from( target_object, duration, vars);

Creates a new tween that animates the target_object variables FROM the specified values (from the current values) and returns its index.

You define the BEGINNING values and the current values are used as the destination values which is great for doing things like animating objects onto the screen because you can setthem up initially the way you want them to look at the end of the tween and then animate in from elsewhere.

Arguments
target_object [Game Maker Object]

Target object whose properties should be affected. The target can be any game maker object.

duration [Real]

Duration in seconds (or frames if "useframes" true is set in the vars parameter)

vars [Array]

An object defining the start value for each variable that should be tweened (SETTERS) as well as any special properties like "yoyo", "repeat", "ease", etc. (special VARS).

For example, to tween obj_enemy.x from 100 and obj_enemy.y from 200 to the current values, with a bouncy easing effect and a duration of 1 second, do this:

tweenline_from( obj_enemy, 1, array("x",100, "y",200, "ease", ease_bounceout)); 

The vars array has the folowing syntax:

array( "SETTER_name",value, "other_SETTER",value, "etc_SETTER",value, "special_VARS_name",value);

You can mix SETTERS names and special VARS names. Other example: tween obj_player's alpha to zero while stretching in both x and y.

tweenline_to( obj_player, 2.5, array("xscale",1.2, "yscale",2, "alpha", 0));
Note: To get more info about Default SETTERS and special VARS, check the Apendix: Setters & Vars

tween_fromto( target_object, duration, vars);

Allows you to define both the starting and ending values (as opposed to tween_to() and tween_from() tweens which are based on the target's current values at one end or the other).

Arguments
target_object [Game Maker Object]

Target object whose properties should be affected. The target can be any game maker object.

duration [Real]

Duration in seconds (or frames if "useframes" true is set in the vars parameter)

vars [Array]

An object defining the start and end values for each variable that should be tweened (SETTERS) as well as any special properties like "yoyo", "repeat", "ease", etc. (special VARS).

For example, to tween obj_enemy.x from 100 to 150 and obj_enemy.y from 200 to 400, with a bouncy easing effect and a duration of 1 second, do this:

tweenline_fromto( obj_enemy, 1, array("x",100, "y",200, "ease", ease_bounceout), array("x",150, "y",400, "ease", ease_bounceout)); 

The vars array has the folowing syntax:

array( "SETTER_name",value, "other_SETTER",value, "etc_SETTER",value, "special_VARS_name",value);
Note: To get more info about Default SETTERS and special VARS, check the Apendix: Setters & Vars

tween_set(target, vars);

Immediately sets properties of the target accordingly - essentially a zero-duration tween_from() with a more intuitive name.

NOTE: This function is not optimized at all. So, do not use it in the step event. Only use it when you want to set a lot of variables with less code.
NOTE: For a COMPLETE description of the ARGUMENTS and the usage mode, please refer to tween_to().
tween_set( obj_clown , array("x", 20, "y", mouse_y, "alpha", random(1), set_image_angle, 45, set_customvariable, 24.5));

This code do the same as: (But only ONE LINE OF CODE!!!)

obj_clown.x = 20;
obj_clown.y = mouse_y;
obj_clown.alpha = random(1);
obj_clown.image_angle = 45;
obj_clown.customvariable = 24.5;

tween_destroy(index);

Destroys the current tween. Use this to prevent memory leaks when you don't need the tween anymore.

Note: The Tweenline Engine's Garbage Collector will remove the unused tweens for you when the target game makers object does not exists anymore or when the room has changed. So, you only need to use this function when the tween is persistent or if you want to force the Tweenline Engine to free memory usage.
mytween = tween_destroy(mytween);

tween_duplicate(tween);

Create a duplicate of the tween specified and return the new index.

mytween2 = tween_duplicate(mytween1);

tween_exists(tween);

Returns true if a tween exists and false otherwise.

var exists = tween_exists(mytween);
tween_stagger_to(targets_array, duration, vars , stagger);

Tweens an array of targets to a common set of destination values (using the current values as the start values), but staggers their start times by a specified amount of time, creating an evenly-spaced sequence with a surprisingly small amount of code.

The parameter stagger is the amount of time in seconds (or frames if the timeline is frames-based) to stagger the start time of each tween.

wave_amount (optional) indicates how many instances will grouped in one "wave". For example, if you want to animate 30 obj_box placed one after another in a 6 rows and 5 columns, and you want to generate 5 staggers of 6 instances (one stagger for each column), you neeed to pass 6 as the value of waves_amount. The default is 1, meaning that each instance will be staggered.

For the other parameters, see tween_to

Returns an array of the indexes of the tweens that has been created

tweens_array = tween_stagger_to(array(obj_box1, obj_box2, obj_box3), 2.8,  array("x", 800,"angle",270, "ease", ease_backout), 0.4);
tween_stagger_from(targets_array, duration, vars , stagger);

Tweens an array of targets from a common set of destination values (using the current values as the end values), but staggers their start times by a specified amount of time, creating an evenly-spaced sequence with a surprisingly small amount of code.

The parameter stagger is the amount of time in seconds (or frames if the timeline is frames-based) to stagger the start time of each tween.

For the optional parameter wave_amount see tween_stagger_to
For the other parameters, see tween_to

Returns an array of the indexes of the tweens that has been created

tweens_array = tween_stagger_from(array(obj_box1, obj_box2, obj_box3), 2.8,  array("x", 800,"angle",270, "ease", ease_backout), 0.4);
tween_stagger_fromto(targets_array, duration, from_vars, to_vars , stagger);

Tweens an array of targets from and to a common set of destination values, but staggers their start times by a specified amount of time, creating an evenly-spaced sequence with a surprisingly small amount of code.

The parameter stagger is the amount of time in seconds (or frames if the timeline is frames-based) to stagger the start time of each tween.

For the optional parameter wave_amount see tween_stagger_to
For the other parameters, see tween_to

Returns an array of the indexes of the tweens that has been created

tweens_array = tween_stagger_from(array(obj_box1, obj_box2, obj_box3), 
    2.8,  
    array("x", 20,"angle",90),
    array("x", 800,"angle",270, "ease", ease_backout),
    0.4);

Tween's Getters


tween_is_playing(tween)

Returns true if the tween is playing and false if it is in pause.


tween_get_target(tween)

Return the tween target id. That is the Game Maker object that is afected by this tween


tween_get_ease(tween)

Gets the ease type of the tween as a string (see tween_to() for more info)


tween_get_time(tween)

Gets the playhead position of the tween.

Normally in seconds, but you can change the default measure unit from tween_system_init(), or with the function tween_set_useframes().


tween_get_progress(index)

Gets the progress as a value from 0 to 1.

The progress is calculated as: (position / duration)


tween_get_delay(index)

Get the initial delay of the tween in seconds (or frames for frames-based tweens)


tween_get_duration(index)

Gets the total duration of the tween (THIS VALUE IT'S NOT AFFECTED BY THE TWEEN SPEED)


tween_get_direction(index)

Gets the direction of the tween

Example:

  • direction = 1 means a normal playback
  • direction = -1 means a reverse playback
  • and so..

tween_get_speed(index)

Gets the speed of the tween

Example:

  • speed = 1 means a normal speed
  • speed = 2 means 2 times faster
  • speed = 0.5 means 2 times slower
  • and so..

tween_get_yoyo(index)

Gets true if the yoyo mode is active for the tween specified


tween_get_repeat(index)

Gets the current repeat count for the specified tween. This is the number of repetitions that left counting the current repeatition (or -1 if it will repeat indefinitely)


tween_get_parent(index)

Gets the parent tweenline index of the specified tween. (or -1 if it has not parent tweenline)


tween_get_useframes(index)

Returns true if the specified tween uses frames (steps) as a measuring unit of time. Returns false if uses seconds.


tween_get_starttime(tween)

Gets the time at which the animation begins on its parent tweenline (after any delay that was defined). If the tween has no parent tweenline, then zero is returned.


tween_get_endtime(tween)

Gets the time at which the animation end on its parent tweenline (after any delay that was defined). If the tween has no parent tweenline, then the duration is returned.


Tween's Setters


tween_set_ease(index, ease)

Sets the ease type of the tween as a easing function (see tween_to() for more info)

tween_set_ease( mytween, ease_backout);

tween_set_time(index,time)

Sets the playhead position of the tween. Normally in seconds, but you can change the default measure unit from tween_system_init, or with the function tween_set_useframes.

// move the playhead to the 3rd second 
// (or 3rd frame for frame based tweens)
tween_set_time( mytween, 3);

tween_set_progress(index, progress)

Sets the progress as a value from 0 to 1. This function is the same as tween_set_position, but the time is calculated as a coeficient respect to the duration. The progress is calculated as: (position / duration).

//go to the half of the animation
tween_set_progress( mytween, 0.5);

tween_set_delay(index,delay [, add?])

Set the initial delay of the tween in steps The optional parameter "Add", if true, add the current delay to the preexisting delay

//add 1.4 seconds to the current tween delay
tween_set_delay( mytween, 1.4, true);
// sets the tween delay to 3.2 seconds
tween_set_delay( mytween, 3.2);

tween_set_useframes(index, use)

Sets the value of useframes. Set to true if you want to use frames (steps) as a measuring unit of time for the specified tween. Set to false if you want to use seconds. All values (playhead time, duration, delay, etc) will be converted to the desired measuring unit using the current room_speed as conversion factor.

Returns false in case of error. (the tween has a parent tweenline, in wich case you need to use tweenline_set_useframes())

NOTE: You can change the value of useframes only if the tween is not inside any tweenline.
tween_set_useframes( mytween, true);

tween_set_speed(index,speed)

Sets the direction of the tween. Example:

  • speed = 1 means a normal speed
  • speed = 2 means 2 times faster
  • speed = 0.5 means 2 times slower
  • and so..
tween_set_speed( mytween, 2);

tween_set_yoyo(index, active)

Set true if you want the yoyo mode active for this tween, of false otherwise.

tween_set_yoyo( mytween, true);

tween_set_repeat(index, repeatcount)

sets the current repeat count for the specified tween. This is the number of repetitions that left counting the current repeatition (or -1 if it will repeat indefinitely)

// sets the tween to repeat 4 times
tween_set_repeat( mytween, 4);
// sets the tween to repeat indefinitely
tween_set_repeat( mytween, -1);
// sets the tween to no repeat
tween_set_repeat( mytween, 0);

tween_set_target(index, target)

Change the target object for the tween.

NOTE: All the changes made by a tween in a object will not be reverted.
tween_set_target( mytween, obj_clown);

tween_set_direction(index,direction)

Sets the direction of the tween. Example:

  • direction = 1 means a normal playback
  • direction = -1 means a reverse playback
  • direction = 4 means a normal playback but 4 times faster
  • direction = -4 means a reverse playback but 4 times faster
  • and so..
tween_set_direction( mytween, -2);

tween_set_modifiers(index, array)

Sets the modifiers array for the tween. This array is passed as the arguments to the easing script. array argument is an array of modifiers. (Or undefined, if you wan't to reset the modifiers to default)

tween_set_modifiers( mytween, array(2, 3, 0) );

tween_set_duration(index,duration)

Sets the total duration of the tween (THIS VALUE IT'S NOT AFFECTED BY THE TWEEN SPEED)

tween_set_duration( mytween, 5);

Tween Control


tween_play(tween_or_array_of_tweens [, time])

Plays the tween (or array of tweens). You can specify a time to play it from the specified time. (optional)

tween_play(tween, 2);
tween_play(array(tween1,tween2,tween3,tween4));

tween_pause(tween_or_array_of_tweens)

Pause the tween with the index specified. (or array of tweens)

tween_pause(tween);

tween_stop(tween_or_array_of_tweens)

Stops the tween and revert all tween states to the init value. If you want to PAUSE the tween use tween_pause instaed. You can pass to the function a tween or a array of tweens

tween_set_duration( mytween, 5);

tween_reverse(tween_or_array_of_tweens [, time])

Play the tween (or array of tweens) in reverse from the current position. You can specify a time to play it from the specified time. (optional)

tween_reverse( mytween);
tween_reverse( mytween, 5);

tween_resume( tween_or_array_of_tweens [, time])

Resume the tween with the index specified. (or array of tweens). You can specify a time to play it from the specified time. (optional)

tween_resume( mytween);
tween_resume( mytween, 5);

tween_seek( tween_or_array_of_tweens, time);

Seeks the the tween (or array of tweens) to a specified time and play it from there.

tween_seek( mytween, 5);

tween_progress( tween_or_array_of_tweens, time);

Seeks the the tween (or array of tweens) to a specified progress (from 0 to 1) and play it from there.

tween_progress( mytween, 1); //seek to the end of the tween

tween_render(index)

Force the rendering of the tween. Normaly you don't need to use this function. The tweenline engine will manage all automaticaly for you.

tween_render( mytween);

Tween Three Events System

Tweenline has three different Event Systems. You can choose the one that fit your needs or use all mixed for your convenience.

Info: For more information about the events that Tweenline has built in and how to use parameters in the Script Event System, check Tween Events VARS Apendix.

Script Event System

The normal event system is the script based event system. When you create your tween, you need to define the callback event scripts your tween will use:

///Create event
//First set the image_index and image_speed, so the animation will be static at the first frame
image_speed=0;
image_index=0;
//Then create a tween to the x=200 for 2 seconds, and with 
//the callback scr_my_callback on the "oncomplete" event
tween_to(id, 2, array("x", 200, "oncomplete", scr_my_callback));

And then, create a scr_my_callback script and put this code in it:

image_index=1; //Jump to the frame 1

This code will make the sprite jump to frame number 1 when the tween ends.

Event User Event System

Another way to detect events in Tweenline Engine is to use the user event system. Simply add a user event in your object. To do this you can go to:

[OPEN YOUR OBJECT IN THE RESOURCE TREE] > "Add Event" Button > "Other" > "User Defined" > [SELECT ONE OF THE 16 USER EVENTS]

Then create your tween, and your callback "user0" event:

///Create Event:
tween_to(id, 2, array("y", y+200, "patrol",true,"onrepeat", "user0")); 
//Note that we used "user0" string as a callback for the "onrepeat" event
/// In User Event 0
tween_to(id, .25, array("x", x+30)); 

This code will make the current instance move from the current position to 200px below. Then, the first tween will repeat backwards and the "onrepeat" event will fire and the "user0" code will execute, causing the instance to move in 0.25 seconds 30 pixels to the right. Then the first tween will reach the initial y position and will repeat other time, causing the "onrepeat" event fire another time and the "user0" code executing and the instance will move 30 pixels more to the right. This cycle will repeat indefinitely. Try it! With only 2 lines of code you have created an amazing animation that can be used for example for the enemy ship movement of a horizontal shooter space game!

Lazy Event System

Lazy events are a easy way to detect events without create aditional scripts or use event users. You can detect lazy events in the same way you can check if the player press a key with keyboard_check_pressed, but instaed of that, you can use the special lazy events functions listed below.

//// Create event: 
// define a tween and declare the "oncomplete" event as a "lazy" event.
tween = tween_to(id, 2, array("x",x+200, "oncomplete","lazy"));

//// Step event:
// when the tween performs the "oncomplete" event
if (tween_oncomplete(tween)) {
    //change the sprite colour to red
    image_blend = c_red;
    //and play a sound of a hit
    audio_play_sound( sound_hit, 1, false);
}
Note: The event must be defined as "lazy" and tween_system_lazy_events( eneable ) must be eneabled to get lazy events to work. (It is eneabled by default)

tween_oncomplete(tween)

Returns true in the single step when the tween performs the "oncomplete" event.


tween_onreversecomplete(tween)

Returns true in the single step when the tween performs the "onreversecomplete" event.


tween_onupdate(tween)

Returns true in the single step when the tween performs the "onupdate" event.


tween_onrepeat(tween)

Returns true in the single step when the tween performs the "onrepeat" event.


tween_onstart(tween)

Returns true in the single step when the tween performs the "onstart" event.


Tweenline Creation functions


tweenline_create()

Creates a new tweenline and returns his index

A tweenline is like a timeline with multiple tweens inside it. You can create a tweenline and then append multiple tween inside this timeline. Then, you can play it alltogether with a single function, and control it like a movie (tweenline_play, tweenline_pause, tweenline_reverse, etc). This way, control multiple tweens to create complex animations is posible thanks to Tweenline Engine.

EXAMPLE:

You have all your menu objects (buttons, logo, etc), but you need to create a complex menu animation sequence.

//create event obj_animation_controller
tl = tweenline_create(); 
tweenline_to ( obj_button_start, 1.2,  array("x", 140));
tweenline_to ( obj_button_exit,  1.2,  array("x", 250), "-=1"); // note the last argument "-=1"
tweenline_from ( obj_game_logo,  3.2,  array("x", room_width/2, "y",room_height/2, "scale",0));

With this code, we are creating a tweenline, and appending three tweens.

Normally the tweens are appended one after another, but you can pass as a last argument, the position of the tween. See tweenline_add to see all the posibilities you have with the position parameter.

Then, you can control this tweenline:

tweenline_pause( tl );
tweenline_stop( tl );
tweenline_reverse( tl );
tweenline_set_speed( tl );
// etc

NOTE:

You cannot have a tweenline with some tweens measured in seconds and other tweens measured in frames (steps) because it's imposible to synchronize tweens with diferent measures of time.

So, when you add a tween to a tweenline the meassure type setted as default in tween_system_init is ussed.

  • If you set seconds as default, and you append a tween that uses frames as measure type, the time is converted to seconds ussing the current room_speed.
  • If you set frames as default, and you append a tween that uses seconds as measure type, the time is converted to frames ussing the current room_speed.

The original tween is moddified to use the default measure type, so be careful.


tweenline_destroy(mytweenline)

Destroys the current tweenline and the tweens attached. Use this to prevent a memory leak.

mytweenline = tweenline_destroy(mytweenline);

tweenline_exists(tweenline)

Returns true if a tweenline exists and false otherwise.

if (tweenline_exists(tweenline)) {
    tweenline_play(tweenline);
}

Tweenline Add functions


tweenline_add( value [, position="+=0"])

Adds a tween or label to the last tweenline created or the tweenline that is currently in edit mode. See tweenline_edit for more info about edit mode.

Arguments
value [Tween index or label string]

The tween or label (string) to add to the tweenline

position: [String, optional]

The position parameter gives you complete control over the insertion point. By default, it's at the end of the timeline.

Use a number to indicate an absolute time in terms of seconds (or frames for frames-based timelines), or you can use a string with a "+=" or "-=" prefix to offset the insertion point relative to the END of the timeline. For example, "+=2" would place the object 2 seconds after the end, leaving a 2-second gap. "-=2" would create a 2-second overlap.

You may also use a label like "mylabel" to have the object inserted exactly at the label or combine a label and a relative offset like "mylabel+=2" to insert the object 2 seconds after "myLabel" or "myLabel-=3" to insert it 3 seconds before "myLabel".

If you define a label that doesn't exist yet, it will automatically be added to the end of the timeline before inserting the tween which can be quite convenient.

You can also use the special strings "_end" and "_start" (or "_end+=3" or "_start-=1.4") to reference to the end time and start time of the last tween added to the tweenline (wich not allways is the same as the total duration of the tweenline).

//Adds the tween at 3 seconds in absolute position of the tweenline
tweenline_add(tween, 3);

//Adds the tween 2 seconds after the end of the tweenline
tweenline_add(tween, "+=2");

//Adds the tween 0.3 seconds before the end of the tweenline
tweenline_add(tween, "-=.3");

//Adds the tween at the position of "myLabel" (if it doesn't exists, it will be 
//automatically created at the end of the timeline, in the same position of the tween)
tweenline_add(tween, "myLabel");

//Adds the tween half second after "myLabel"
tweenline_add(tween, "myLabel+=.5");

//Adds the label named "otherlabel" 1.5 seconds before "myLabel"
tweenline_add("otherlabel", "myLabel-=1.5");

//Adds the tween a half second before the end of the last tween added on 
//the current tweenline ("_end-=0.5" is also valid)
tweenline_add(tween, "_end-=.5");

//Adds the tween four seconds after the start of the last tween added on the current tweenline
tweenline_add(tween, "_start-=4");  
tweenline_remove(value [,destroyTween=false])

Removes a tween or label from the last created tweenline or the tweenline that is currently in edit mode. See tweenline_edit for more info about edit mode.

If you pass a tween as an argument, the script will find the parent of the tween for you, so you don't need to worry to call tweenline_edit.

If you pass a label (a string), you need to first call tweenline_edit to tell Tweenline engine wich tweenline do you want to edit

Arguments
value [Tween index or label string]

A tween or label to remove from the timeline

destroyTween: [Boolean]

If a tween is passed, you can force the destruction of the tween passing true to this argument. By default, the tween will not be destroyed, only removed from the tweenline. It is useful to remove a tween from one tweenline and place it in another tweenline. In this way, the tween will be not destroyed in the process.

// Remove the tween my_tween from his parent tweenline and destroy it
tweenline_remove( my_tween, true);

// Remove the tween my_tween from his parent tweenline but does not destroy it
tweenline_remove( my_tween);

// Removes the label "mylabel" from the tweenline my_tweenline
tweenline_edit(my_tweenline);
tweenline_remove("mylabel");

tweenline_to(target_object, duration, vars [, position="+=0"])

Adds a tween_to() tween to the end (or elsewhere using the "position" parameter) of the last created Tweenline or the Tweenline that is currently in edit mode. See tweenline_edit for more info about edit mode.

See tween_to for the reference for "target_object", "duration" and "vars" params.
See tweenline_add for the reference for the optional "position" parameter.

Returns the index of the tween that has been created


tweenline_from(tweenline, target_object, duration, vars [, position="+=0"])

Adds a tween_from() tween to the end (or elsewhere using the "position" parameter) of the last created Tweenline or the Tweenline that is currently in edit mode. See tweenline_edit for more info about edit mode.

See tween_from for the reference for "target_object", "duration" and "vars" params.
See tweenline_add for the reference for the optional "position" parameter.

Returns the index of the tween that has been created


tweenline_fromto(tweenline, target_object, duration, from_vars, to_vars [, position="+=0"])

Adds a tween_fromto() tween to the end (or elsewhere using the "position" parameter) of the last created Tweenline or the Tweenline that is currently in edit mode. See tweenline_edit for more info about edit mode.

See tween_fromto for the reference for "target_object", "duration" and "vars" params.
See tweenline_add for the reference for the optional "position" parameter.

Returns the index of the tween that has been created


tweenline_stagger_to(targets_array, duration, vars , stagger [, position="+=0"])

Tweens an array of targets to a common set of destination values (using the current values as the start values), but staggers their start times by a specified amount of time, creating an evenly-spaced sequence with a surprisingly small amount of code.

The parameter stagger is the amount of time in seconds (or frames if the timeline is frames-based) to stagger the start time of each tween.

For the optional parameter wave_amount see tween_stagger_to
For the other parameters, see tween_to

Returns the index of the tween that has been created


tweenline_stagger_from(targets_array, duration, vars , stagger [, position="+=0"])

Tweens an array of targets from a common set of destination values (using the current values as the destination), but staggers their start times by a specified amount of time, creating an evenly-spaced sequence with a surprisingly small amount of code.

The parameter stagger is the amount of time in seconds (or frames if the timeline is frames-based) to stagger the start time of each tween.

For the optional parameter wave_amount see tween_stagger_to
For the other parameters, see tween_from

Returns the index of the tween that has been created


tweenline_stagger_fromto(targets_array, duration, from_vars, to_vars , stagger [, position="+=0"])

Tweens an array of targets from and to a common set of destination values, but staggers their start times by a specified amount of time, creating an evenly-spaced sequence with a surprisingly small amount of code.

The parameter stagger is the amount of time in seconds (or frames if the timeline is frames-based) to stagger the start time of each tween.

For the optional parameter wave_amount see tween_stagger_to
For the other parameters, see tween_fromto

Returns the index of the tween that has been created


tweenline_edit( tweenline );

Sets the tweenline specified marked to be edited. All posterior calls to tweenline_add, tweenline_to, tweenline_from, tweenline_fromto and tweenline_remove will be applied to the specified tweenline.

You first call tweenline_begin passing it an already defined tweenline, and then you can make all the needed modifications.

Note: This function is in BETA. Unexpected results can ocurr if you modify an already defined tweenline.
Note: YOU DO NOT NEED TO USE THIS FUNCTION IF YOU ARE CREATING THE TWEENLINE FOR THE FIRST TIME. Please refer to tweenline_create for more info about creating tweenlines.
/// >>> Create event
twenline = tweenline_create();
tweenline_to( ... ); //first define your tweenline as you usually do
tweenline_to( ... );
tweenline_to( ... );

// >>> mouse left click event
tweenline_edit(tweenline); //when you have to edit your tweenline, call tweenline_edit
tweenline_to( ... ); // then, you can alter the existing tweenline
tweenline_add( ... );
tweenline_from( ... );
tweenline_remove( ... );
tween_system_set_default_ease(ease_bounceout);

Tweenline Getters


tweenline_is_playing(index)

Returns true if the tweenline is playing (not in pause)


tweenline_get_duration(tweenline)

Gets the total duration of the tweenline


tweenline_get_tween(tweenline, index);

get the index of the tween number "numb" in the tweenline starting from number 0.

Note: The are sorted in the order they has been added. So, the first tween doesn't need to be te first chronologically. Use tweenline_get_list or tweenline_get_priority for that purpose.

tweenline_get_priority(tweenline)

Returns the index of a ds priority queue (ds_priority_* functions) ordered by the start time of each tween in the tweenline.

The priority is asigned as follows:

  • Priority: The start time of each tween inside the tweenline.
  • Value: The tween in the tweenline.

You can use this priority to access to all tweens inside one tweenline ordered by the start time of each tween:

var priority = tweenline_get_priority(tweenline);
while ( !ds_priority_empty(priority) ){
    var tween = ds_priority_delete_min(priority);
    // Do something with each tween
}
// REMEMBER TO DESTROY THE PRIORITY QUEUE WHEN YOU DON'T NEED IT ANYMORE!
ds_priority_destroy(priority); 
NOTE: As with all dynamic resources, data structures take up memory and so should always be destroyed when no longer needed to prevent memory leaks which will slow down and eventually crash your game.

tweenline_get_list(tweenline)

Returns the index of a ds_list (ds_list_* functions) ordered by the start time of each tween in the tweenline.

You can use this priority to access to all tweens inside one tweenline ordered by the start time of each tween:

var list = tweenline_get_list(tweenline);
var size = ds_list_size(list);
for (var i=0; i<size; i++) {
    var tween = ds_list_find_value(list, i);
    // do something with each tween
}
ds_list_destroy(list); //REMEMBER TO DESTROY THE LIST WHEN YOU DON'T NEED IT ANYMORE
NOTE: This function is a bit slower than tweenline_get_priority, so If you don't really need it, use tweenline_get_tween or tweenline_get_priority insted.
NOTE: As with all dynamic resources, data structures take up memory and so should always be destroyed when no longer needed to prevent memory leaks which will slow down and eventually crash your game.

tweenline_get_size(tweenline)

Gets the number of tweens inside the tweenline


tweenline_get_time(easing_function)

Gets the playhead position of the tweenline. Normally in seconds, but you can change the default measure unit from tween_system_init


tweenline_get_speed(tweenline)

Gets the speed of the tweenline. Example:

  • speed = 1 means a normal speed
  • speed = 2 means 2 times faster
  • speed = 0.5 means 2 times slower
  • and so..

tweenline_get_progress(tweenline)

Return the progress of the tweenline as a value from 0 to 1 where 0 is the start of the tweenline, and 1 is the end.


tweenline_get_tweens_at_time( tweenline, time, includeOutside)

Return a ds_list with all tweens wich timespan intersects the specified time inside the specified tweenline.

If includeOutside is true, the tweens that are in the specified time and need to be rendered in this time are added to the ds_list too.

Note: THIS IS AN ADVANCED FUNCTION (But do not delete it, as it is used by the engine). Normally you do not need to use this function.

tweenline_get_tweens_by_target( tweenline, target, includeOutside)

Return a ds_list with all tweens wich the specified target object inside the Tweeline. The tweens in the list are sorted by they orders of start into the Tweenline.

Note: THIS IS AN ADVANCED FUNCTION (But do not delete it, as it is used by the engine). Normally you do not need to use this function.

Tweenline Setters


tweenline_set_speed(index, speed)

Sets the speed of the tweenline. Example:

  • speed = 1 means a normal speed
  • speed = 2 means 2 times faster
  • speed = 0.5 means 2 times slower
  • and so..

tweenline_set_yoyo(index, active)

set true if you want the yoyo mode active for this al the tweens inside this tweenline, of false otherwise.


tweenline_set_time(tweenline, time)

Sets the playhead position of all the tweens in the tweenline. Normally in seconds, but you can change the default measure unit from tween_system_init


tweenline_set_progress(tweenline, progress)

Sets the progress of the tweenline as a value from 0 to 1 where 0 is the start of the tweenline, and 1 is the end.


Tweenline Control Functions


tweenline_reverse(tweenline [, ForcePlay=true])

Reverse all the tweens in a tweenline. The optional parameter ForcePlay indicates if the tweenline should start playing. The default is true. NOTE: the tweens position will not change, only the playhead direction.


tweenline_pause(tweenline)

Pauses all the tweens in a tweenline.


tweenline_play(tweenline [, timeOrLabel ])

Plays all the tweens in a tweenline.

You can pass also a time or a label string in the timeOrLabel parameter, in wich case, the tweenline will jump to these time or label.


tweenline_resume(tweenline [, timeOrLabel ])

Resume all the tweens in a tweenline.

You can pass also a time or a label string in the timeOrLabel parameter, in wich case, the tweenline will jump to these time or label.


tweenline_stop(tweenline)

Stops all the tweens in a tweenline.


tweenline_restart(tweenline)

Restarts all tweens in a tweenline.


tweenline_seek(tweenline,time)

The same as tweenline_set_time(tweenline,time);


tweenline_progress(tweenline,progress)

The same as tweenline_set_progress(tweenline,progress);


Tweenline Label Functions


tweenline_label_find_time( tweenline, labelname );

Returns the time of the label "labelname" in the specified tweenline.


tweenline_label_list( tweenline )

Returns a ds_list with all the labels inside the tweenline


Global Tweenline System Functions


tween_system_get_tween_count()

Gets the number of tweens active in the tween system. You can use it this function to detect memory leaks.

//This will draw in the screen the number of active tweens
draw_text( 20, 20, "Active tweens: "+string(tween_system_get_tween_count()));

tween_system_get_singleton()

Use tween_system_get_singleton() if you need to access to the obj_tweenline for some reason. (But normally you don't need to access to it)

WARNING: DO NOT ACCESS TO obj_tweenline directly!!
WARNING: AND DO NOT DEACTIVATE IT!

//Use it this function to get the index of obj_tweenline:
var tween_controller = tween_system_get_singleton();

tween_system_is_tweenline(tween_or_tweenline)

Return true if tween_or_tweenline is a tweenline, false otherwise.

// returns false because mytween is a tween not a tweenline
tween_system_is_tweenline( mytween);
// returns true because mytweenline is a tweenline not a tween
tween_system_is_tweenline( mytweenline);

tween_system_is_tween(tween_or_tweenline)

Return true if tween_or_tweenline is a tween, false otherwise.

// returns true because mytween is a tween not a tweenline
tween_system_is_tween( mytween);
// returns false because mytweenline is a tweenline not a tween
tween_system_is_tween( mytweenline);

tween_system_set_default_ease(easing_function)

Changes the default easing function. The default is ease_quadout

tween_system_set_default_ease(ease_bounceout);

tween_system_set_speed(speed)

Sets the GLOBAL speed of the tweenline engine. That is a factor that's used to scale time in the animation where:

  • 1 = normal speed (the default),
  • 0.5 = half speed,
  • 2 = double speed,
  • etc.
tween_system_set_speed(.5);

tween_system_setter_add( setter_name, setter_script)

Adds a custom SETTER.

This is only requiered by the HTML5 Platform due to a bug with asset_get_name, so, If you are targeting HTML5, you need to add manually your custom setters. If you are not targeting HTML5, it is not necesary, but it's recomended to use it.

For more info about custom setters, see __tweenline_SETTERS script.

//Adds a custom setter called "myvar" with a setter script called set_myvar
tween_system_setter_add("myvar", set_myvar);

tween_system_lazy_events( eneable)

Adds a custom SETTER.

Eneable or disable the lazy events. The lazy events are a easy way to detect events without ussing extra scripts or extra events. For an example of use of the lazy events check the functions tween_oncomplete, tween_onrepeat, etc. The lazy events can cause a bit of overhead. So, if you are not using it in your game, disable it at the start of your game to gain a little bost.


Instance Selection Functions

This functions, are designed to generate an array of instances that can be used with the tween_stagger_* and tweenline_stagger_* functions.

In this way you can, for example, animate all the obj_dog and obj_cat instances that match a specified criteria and then sort by they "y" position and finally select only the even instances, in only four lines of code:

var arr = instance_select_filter(array(obj_dog, obj_cat), set_x, room_width/2);
arr = instance_select_sort(arr,set_y);
arr = instance_select_numb(arr,"mod",2);
tween_stagger_to(arr, 1, array("blend",c_red), 0.2);

instance_select_array( obj_or_instance_or_array_of_them [, array_to_prepend] )

Returns an array of all the INSTANCES (not objects, INSTANCES) passed. If no instance match the specified query, then undefined is returned.

obj_or_instance_or_array_of_them: This argument can be:

  1. An object id (all instances of this object will be sorted)
  2. An instance id
  3. An array of objects (all instances of those objects will be sorted)
  4. An array of instances
  5. An array with a mix of instances and objects

If you pass an array in array_to_prepend, the array will be prepended to the normal output array. This is useful to concatenate a series of instance_select_* functions.

Example:

Suppose that you have in your room 6 boxes, 1 player and 3 trees, and 4 enemys. So you need to SELECT an ARRAY that contains:

  • ALL the instances of the obj_box.
  • ONE specific tree. The instance wich id is 100023.
  • ALL the instances of obj_player (only one will be selected since there is only one instance in the room)

So, you need to call:

var arr = instance_select_array( array(obj_box, 100023, obj_player));

And the output will be an array like this:

[100453, 100054, 100055, 100056, ... , 100455]  

The first 6 will be ALL the instances of the boxes, the 7th item will be the tree and the last will be the id of the player.


instance_select_filter( obj_or_instance_or_array_of_them, setter_script, condition_string, condition_value)

This will return an array of instances filtered by the specified condition.

For more info about obj_or_instance_or_array_of_them argument check instance_select_array();

- setter_script: must be a setter script (wich value will be used for testing)

For more info about setter script check __tweenline_SETTERS script.

- condition_string: it will be the condition for testing. The posible values can be:

">"  "<"  ">="  "<="  "="  "=="  "!="  "<>" 

- condition_value: must be the value compared to. See the example for more info.

Example:

if you want to select the all the obj_tree instances which Y position is less than 180 you can do:

var arr = instance_select_filter( obj_tree, set_y, "<", 180);

This will return an array with ALL the ids of the instances of the obj_tree wich y position is below 180.


instance_select_numb( obj_or_instance_or_array_of_them, condition_string, condition_value [, numb_add=0])

This will return an array of instances filtered by the specified condition given by the number of the instance inside the array.

For more info about obj_or_instance_or_array_of_them argument check instance_select_array();

- condition_string: it will be the condition for testing. The posible values can be:

">"  "<"  ">="  "<="  "="  "=="  "!="  "<>"  "mod"  "%"  "mod!"  "%!"  "!mod"  "!%"

- condition_value: must be the value compared to. See the example for more info.

The internal process of selection is the following:

  1. First, all instances of obj_or_instance_or_array_of_them are selected and numbered from 0 to n-1 (n is the number of total instances)
  2. Then, each instance number is compared using the condition_string and the condition_value
  3. If the condition_string is "mod" "%" "mod!" "%!" "!mod" or "!%" then the numb_add is added to the number of the instance and then, compared using the condition and value.
  4. Then, an array containing all the matched instances is returned.

For example: [ FOR MORE INFO ABOUT THE mod OPERATOR, please reffer to the GM:S manual]

If you want to select all odd instances of the obj_box in the room (numbered from the top

to the bottom):
var arr = instance_select_sort( obj_box, set_y);
            arr = instance_select_numb( arr, "!mod", 2);

It is the same that saying all instances wich (n mod 2) != 0

You can also use "mod!" "!%" or "%!" for the same result.

Another example: [ FOR MORE INFO ABOUT THE mod OPERATOR, please reffer to the GM:S manual]

Suppose that you want to select obj_box the instances wich

number (sorted from left to right in the room) is 1, 4, 7, 10, etc. That is the same that all instances wich (n mod 3)+1 == 0 So, the formula will be:
(n mod condition_value)+numb_add == 0

Then, you need to call:

var arr = instance_select_sort( obj_box, set_x);
            arr = instance_select_numb( arr, "mod", 3, 1);

The last Example:

if you want to select the firsts 16 obj_tree instances sorted from right to left

var arr = instance_select_sort( obj_tree, set_x, false); 
            arr = instance_select_filter( arr, "<", 16); 

This will return an array with ALL the ids of the instances of the obj_tree wich number is below 16. (remember that the numbers starts from zero)


instance_select_sort( obj_or_instance_or_array_of_them, setter_script [, ascending=true ])

Returns an array with all instances specified (check below) sorted by the propietry of the setter_script specified. You can sort ascending or descending.

For more info about setter script check __tweenline_SETTERS script.

For more info about obj_or_instance_or_array_of_them argument check instance_select_array();

Example:

In the room you have 5 instances of obj_box placed at random locations. If you call:

var arr = instance_select_sort( obj_box, set_y ); 

It will return an array with the 5 instances of obj_box sorted from the top box to the

bottom box on the room. (using the set_y setter script). This script is useful to use it in conjunction with tween_stagger_to/from/fromto and tweenline_stagger_to/from/fromto functions like:
var arr = instance_select_sort( obj_box, set_y );
    tween_stagger_from( arr, 1, array("alpha",0), .5);

instance_select_filter_sort( obj_or_instance_or_array_of_them, setter_script, condition_string, condition_value, sort_setter_script [, ascending=true]);

Returns an array of instances that is the combination of perform: instance_select_filter and then instance_select_sort For more info, please reffer to those functions.


Appendix: Default SETTERS & VARS

Default SETTERS

Tweenline has lots of common variables setters that are incorporated within the engine. But you can easily ADD your CUSTOM setters for your variables. Please READ the script __tweenline_SETTERS to add your custom setters.

Below you have a list of the default setters incorporated in the Tweenline engine.You can use both the setter string "name" or the script set_name. The default setters included in the engine are:


Tween behavior VARS

Below is a full list of special properties you can specify on vars argument. For the special vars you can use both the string "name" or the script var_name.

"ease" (var_ease) [script]

You can choose from various eases to control the rate of change during the animation, giving it a specific "feel". For example, ease_elasticout or ease_stronginout. For best performance, use one of the Tweenline eases included in the "ease" folder with this extension. For linear animation, use the Tweenline ease_linear ease. The default ease is ease_quadout. (You can always change the default easing script with the tween_system_set_default_ease(ease) function)

"delay" (var_delay) [Real]

Amount of delay in seconds (or frames for frames-based tweens) before the animation should begin.

"paused" (var_paused) [Boolean]

If true, the tween will pause itself immediately upon creation.

"useframes" (var_useframes) [Boolean]

If var_useframes is true, the tweens's timing will be based on frames instead of seconds. This causes both its duration and delay to be based on frames. An animations's timing mode is always determined by its parent timeline.

"repeat" (var_repeat) [Integer]

Number of times that the animation should repeat after its first iteration. For example, if repeat is 1, the animation will play a total of twice (the initial play plus 1 repeat). To repeat indefinitely, use -1. repeat should always be an integer.

"repeatdelay" (var_repeatdelay) [Real]

Amount of time in seconds (or frames for frames-based tweens) between repeats. For example, if repeat is 2 and var_repeatdelay is 1, the animation will play initially, then wait for 1 second before it repeats, then play again, then wait 1 second again before doing its final repeat.

"yoyo" (var_yoyo) [Boolean]

If true, every other repeat cycle will run in the opposite direction so that the tween appears to go back and forth (forward then backward).

So if repeat is 2 and yoyo isfalse, it will look like: start - 1 - 2 - 3 - 1 - 2 - 3 - 1 - 2 - 3 - end.

But if yoyo is true, it will look like: start - 1 - 2 - 3 - 3 - 2 - 1 - 1 - 2 - 3 - end.

"patrol" (var_patrol) [Boolean]

Patrol it's a shorhand way of set var_repeat to -1 and var_yoyo to true. If true, every other repeat cycle will run in the opposite direction so that the tween appears to go back and forth indefinitely (forward then backward).

"loop" (var_loop) [Boolean]

If true, it has the same effect as set var_repeat to -1. The tween will loop indefinitely.


Tween Events VARS

Below is a full list of special properties you can specify on vars argument: For the special vars you can use both the string "oneventname" or the script var_oneventname. The following list are EVENTS. When you define an event the script passed will be called like:

script_passed( script_params[0], script_params[1], script_params[2], ... etc); 

For the params you can use an array that will be passed to the callback script like:

tween_to(id,2,array("oncomplete", scr_myscript, "oncompleteparams",array("param1", "param2")));

To self-reference the id of the tween in one of the parameters, use "{self}", like:

tween_to(id,2,array("oncomplete", scr_myscript, "oncompleteparams", array("{self}", "param2")));

If you pass a non array type of argument, the value will be passed as a single argument for the script:

tween_to(id,2,array("oncomplete", scr_myscript, "oncompleteparams", my_only_argument ));
"oncomplete" (var_oncomplete) [Callback Script]

A script that should be called when the timeline has completed.

"oncompleteparams" (var_oncompleteparams) [Array for multiple arguments, other value type for only one argument]

An Array of parameters to pass the "oncomplete" script.

"onreversecomplete" (var_onreversecomplete) [Callback Script]

A function that should be called when the Tween/Tweenline has reached its beginning again from the reverse direction. For example, if tweeen_reverse() or tweenline_reverse() is called, the Tween timeline will move back towards its beginning and when its time reaches 0, the passed script to "onreversecomplete" will be called. This can also happen if the timeline is placed in a Tweenline timeline that gets reversed and plays the timeline backwards to (or past) the beginning.

"onreversecompleteparams" (var_onreversecompleteparams) [Array for multiple arguments, other value type for only one argument]

An Array of parameters to pass the "onreversecomplete" script.

"onupdate" (var_onupdate) [Callback Script]

A script that should be called every time the Tween/Tweenline updates (on every frame while the timeline is active)

"onupdateparams" (var_onupdateparams) [Array for multiple arguments, other value type for only one argument]

An Array of parameters to pass the "onupdate" script.

"onstart" (var_onstart) [Callback Script]

A script that should be called when the Tween/Tweenline begins (when its time changes from 0 to some other value which can happen more than once if the timeline is restarted multiple times).

"onstartparms" (var_onstartparms) [Array for multiple arguments, other value type for only one argument]

An Array of parameters to pass the "onstart" script.

"onrepeat" (var_onrepeat) [Callback Script]

A function that should be called each time the Tween/Tweenline repeats.

"onrepeatparms" (var_onrepeatparms) [Array for multiple arguments, other value type for only one argument]

An Array of parameters to pass the "onrepeat" script.


Appendix: Custom Vars

What are custom vars?

Custom vars are variables for your game maker objects, that can be created or destroyed dinamically at runtime.

Custom vars are a bit slower than normal variables, so use only when you need a lazy way to create a variable.

The principal adventages of custom vars are:

  1. You can use cv_has([object=id,] var) to check if the specified object has the customvar "var" defined.
  2. You can use cv_get([object=id,] var) to get the customvar of an object, and if it does not exists, the function will return undefined. If you use normal variables, you probably get a compiller error.
  3. Other functions you can use are cv_set, cv_delete and cv_clear_object.

How do I define a custom var?

Simply do:

cv_set("_mycustomvar", 300);

This will define _mycustomvar inside the current instance and set its value to 300.

You can also do this to define _mycustomvar in a diferent object:

cv_set(obj_box1, "_mycustomvar", 300);

This will define _mycustomvar inside all the obj_box1 instances and set their value to 300.

How do I change the value of a custom var?

In the same way, you can use cv_set to override the value of that custom var. If the custom var does not exists in the object, it will be created; if not, the value will be changed.

How do I get the value of a customvar?

// This will get the value of _mycustomvar inside the current instance:
var myvalue1 = cv_get("_mycustomvar"); 
// This will get the value of _mycustomvar inside obj_box1:
var myvalue2 = cv_set(obj_box1, "_mycustomvar"); 

But what is the relation of this with the Tweenline Engine?

Tweenline integrates the use of custom vars. You can pass a string starting with "_" (underscore) to tell the system that the following value in the array will correspond with the custom var specified. For Example:

tween_to( id, 3, array("_mycustomvar",x+600));

This, will tween the custom var "_mycustomvar" inside the current instance, from the current value to x+600. If the custom var "_mycustomvar" is not defined in the current instance, the It's defined and the value is set to zero.


cv_system_init()

Inits the custom vars system. Call it once at the begining of the game, before any other cv_ script.

Note: If you are uning it with tweenline_engine, this call this script is not necesary. Tweenline will init custom vars system automatically.

cv_system_room_end()

Call this script in the ROOM END event. This script executes the garbage collector.

Note: If you are uning it with tweenline_engine, call this script is not necesary. Tweenline will call it for you.

cv_set([object = id,] var, value)

Sets the custom variable "var" of the specified object to value. If object is not defined, the actual object is used.

cv_set("myvariable", 9.5 );

cv_get([object = id,] var)

Gets the custom variable "var" of the specified object. If the value does not exists the script returns undefined. If object is not defined, the actual object is used.

var myvariable = cv_get("myvariable");

cv_has([object = id,] var);

Chacks if the custom variable "var" exists in object. If object is not defined, the actual object is used.

var variable_exists = cv_has("myvariable");

cv_delete([object = id,] var);

Deletes custom variable "var" from of the specified object. If object is not defined, the actual object is used.

cv_delete("myvariable");

cv_clear_object(object);

Deletes ALL custom variables from of the specified object.

cv_clear_object(id);

Appendix: Deprecated

These are the functions/VARS/SETTERS that are deprecated in favor of improvements. Below each function there is an explanation of why it is deprecated

Persistent tweens functions: Now the system auto detects persistent tweens. This functions and vars should not be used anymore.

[DEPRECATED] "persistent" (var_persistent) [Boolean]

If true, the tween will be persistent, and it will not be destroyed by the tweenline garbage collector. Check tween_set_persistent for more info about tweens persistent mode.

[DEPRECATED]tween_get_persistent(tween)

Returns true if the tween is persistent, false if not. By default a tween is not persistent. It means that it is deleted when the rooms end, to prevent memory leaks. But you can make a tween persistent with tween_set_persistent(tween, true); This means that the tween will be permament and you should manually destroy with tween_destroy(tween) when you don't need it anymore.

It can be used to create effects between diferent rooms, or to create transitions from one room to another.

[DEPRECATED]tween_set_persistent(tween, persistent)

Sets a tween as persistent. By default a tween is not persistent. It means that it is deleted when the rooms end, to prevent memory leaks. But you can make a tween persistent with tween_set_persistent(tween, true);. This means that the tween will be permament and you MUST manually destroy with tween_destroy() when you don't need it anymore. It can be used to create effects between diferent rooms, or to create transitions from one room to another.

tween_set_persistent( mytween, true);