The Tweenline docs has all the necesary to create the most amazing animations with only a few lines of code.
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:
Marketplace > My Library. Download button next to the Tweenline label.Add to Project. And then Import All.Open in Explorer.To view the demo files:
File > NewTweenline_demo_project.gmz (from the included files you make the backup)import.To Import the basic tweenline SDK extension into your project:
tweenline.gmez into the Game Maker Window. (from the included files you make the backup in the 3rd step)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.
Creates a new tween that animates the target_object variables to the specified destination values (from the current values) and returns its index.
Target object whose properties should be affected. The target can be any game maker object.
Duration in seconds (or frames if "useframes" true is set in the vars parameter)
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});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.
Target object whose properties should be affected. The target can be any game maker object.
Duration in seconds (or frames if "useframes" true is set in the vars parameter)
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));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).
Target object whose properties should be affected. The target can be any game maker object.
Duration in seconds (or frames if "useframes" true is set in the vars parameter)
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);
Immediately sets properties of the target accordingly - essentially a zero-duration tween_from() with a more intuitive name.
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;
Destroys the current tween. Use this to prevent memory leaks when you don't need the tween anymore.
mytween = tween_destroy(mytween);
Create a duplicate of the tween specified and return the new index.
mytween2 = tween_duplicate(mytween1);
Returns true if a tween exists and false otherwise.
var exists = tween_exists(mytween);
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.
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);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.
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);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.
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);Returns true if the tween is playing and false if it is in pause.
Return the tween target id. That is the Game Maker object that is afected by this tween
Gets the ease type of the tween as a string (see tween_to() for more info)
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().
Gets the progress as a value from 0 to 1.
The progress is calculated as: (position / duration)
Get the initial delay of the tween in seconds (or frames for frames-based tweens)
Gets the total duration of the tween (THIS VALUE IT'S NOT AFFECTED BY THE TWEEN SPEED)
Gets the direction of the tween
Example:
Gets the speed of the tween
Example:
Gets true if the yoyo mode is active for the tween specified
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)
Gets the parent tweenline index of the specified tween. (or -1 if it has not parent tweenline)
Returns true if the specified tween uses frames (steps) as a measuring unit of time. Returns false if uses seconds.
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.
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.
Sets the ease type of the tween as a easing function (see tween_to() for more info)
tween_set_ease( mytween, ease_backout);
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);
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);
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);
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())
tween_set_useframes( mytween, true);
Sets the direction of the tween. Example:
tween_set_speed( mytween, 2);
Set true if you want the yoyo mode active for this tween, of false otherwise.
tween_set_yoyo( mytween, true);
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);
Change the target object for the tween.
tween_set_target( mytween, obj_clown);
Sets the direction of the tween. Example:
tween_set_direction( mytween, -2);
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) );
Sets the total duration of the tween (THIS VALUE IT'S NOT AFFECTED BY THE TWEEN SPEED)
tween_set_duration( mytween, 5);
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));
Pause the tween with the index specified. (or array of tweens)
tween_pause(tween);
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);
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);
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);
Seeks the the tween (or array of tweens) to a specified time and play it from there.
tween_seek( mytween, 5);
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
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);
Tweenline has three different Event Systems. You can choose the one that fit your needs or use all mixed for your convenience.
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.
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 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);
}
Returns true in the single step when the tween performs the "oncomplete" event.
Returns true in the single step when the tween performs the "onreversecomplete" event.
Returns true in the single step when the tween performs the "onupdate" event.
Returns true in the single step when the tween performs the "onrepeat" event.
Returns true in the single step when the tween performs the "onstart" event.
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.
The original tween is moddified to use the default measure type, so be careful.
Destroys the current tweenline and the tweens attached. Use this to prevent a memory leak.
mytweenline = tweenline_destroy(mytweenline);
Returns true if a tweenline exists and false otherwise.
if (tweenline_exists(tweenline)) {
tweenline_play(tweenline);
}
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.
The tween or label (string) to add to the tweenline
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");
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
A tween or label to remove from the timeline
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");
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.
Returns the index of the tween that has been created
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.
Returns the index of the tween that has been created
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.
Returns the index of the tween that has been created
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.
Returns the index of the tween that has been created
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.
Returns the index of the tween that has been created
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.
Returns the index of the tween that has been created
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.
/// >>> 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);
Returns true if the tweenline is playing (not in pause)
Gets the total duration of the tweenline
get the index of the tween number "numb" in the tweenline starting from number 0.
tweenline_get_list or tweenline_get_priority for that purpose.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:
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);
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
Gets the number of tweens inside the tweenline
Gets the playhead position of the tweenline. Normally in seconds, but you can change the default measure unit from tween_system_init
Gets the speed of the tweenline. Example:
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.
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.
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.
Sets the speed of the tweenline. Example:
set true if you want the yoyo mode active for this al the tweens inside this tweenline, of false otherwise.
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
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.
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.
Pauses all the tweens in a tweenline.
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.
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.
Stops all the tweens in a tweenline.
Restarts all tweens in a tweenline.
The same as tweenline_set_time(tweenline,time);
The same as tweenline_set_progress(tweenline,progress);
Returns the time of the label "labelname" in the specified tweenline.
Returns a ds_list with all the labels inside the tweenline
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()));
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)
//Use it this function to get the index of obj_tweenline: var tween_controller = tween_system_get_singleton();
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);
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);
Changes the default easing function. The default is ease_quadout
tween_system_set_default_ease(ease_bounceout);
Sets the GLOBAL speed of the tweenline engine. That is a factor that's used to scale time in the animation where:
tween_system_set_speed(.5);
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);
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.
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);
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:
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:
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.
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.
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:
obj_or_instance_or_array_of_them are selected and numbered from 0 to n-1 (n is the number of total instances)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
"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
(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)
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 theset_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);
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.
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:
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.
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)
Amount of delay in seconds (or frames for frames-based tweens) before the animation should begin.
If true, the tween will pause itself immediately upon creation.
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.
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.
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.
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 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).
If true, it has the same effect as set var_repeat to -1. The tween will loop indefinitely.
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 ));
A script that should be called when the timeline has completed.
An Array of parameters to pass the "oncomplete" 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.
An Array of parameters to pass the "onreversecomplete" script.
A script that should be called every time the Tween/Tweenline updates (on every frame while the timeline is active)
An Array of parameters to pass the "onupdate" 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).
An Array of parameters to pass the "onstart" script.
A function that should be called each time the Tween/Tweenline repeats.
An Array of parameters to pass the "onrepeat" script.
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:
cv_has([object=id,] var) to check if the specified object has the customvar "var" defined. 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. cv_set, cv_delete and cv_clear_object.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.
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.
// 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");
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.
Inits the custom vars system. Call it once at the begining of the game, before any other cv_ script.
Call this script in the ROOM END event. This script executes the garbage collector.
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 );
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");
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");
Deletes custom variable "var" from of the specified object. If object is not defined, the actual object is used.
cv_delete("myvariable");
Deletes ALL custom variables from of the specified object.
cv_clear_object(id);
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.
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.
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.
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);