TweenGMX v1.0.5 Reference Guide

// Tween x position to mouse_x over 30 steps
TweenFire(self, EaseOutQuad, "once", false, 0, 30, "x", x, mouse_x);

// Tween instance's scale back and forth from 0 to 1 over 2.0 seconds
TweenFire(self, EaseInOutQuad, "patrol", true, 0.0, 2.0, "image_xscale", 0, 1, "image_yscale", 0, 1);

// Chain various tweens to fire one after another
tween1 = TweenFire(self, EaseOutBounce, 0, true, 0, 1.0, "y", -100, y);
tween2 = TweenMore(tween1, self, EaseInOutQuad, 0, true, 0, 0.5, "image_yscale", 1, 0.25);
tween3 = TweenMore(tween1, self, EaseInOutSine, 0, true, 0, 1.0, "image_angle", 0, 360);
tween4 = TweenMore(tween3, self, EaseInOutQuad, 0, true, 0, 2.0, "image_xscale", 1, 0.5);

=== PERSISTENT TWEENS ===

// Create a defined tween, easing x position to mouse_x over 30 steps
tween = TweenCreate(self, EaseOutQuad, TWEEN_MODE_ONCE, false, 0, 30, "x", x, mouse_x);
TweenPlay(tween);

// Create an undefined tween and override it with TweenPlay()
tweenY = TweenCreate(self);
TweenPlay(tweenY, EaseLinear, TWEEN_MODE_ONCE, false, 0, 30, "y", y, mouse_y); 

// Tween x position to mouse_x over 30 steps
tweenX = TweenCreate(self, EaseOutQuad, TWEEN_MODE_ONCE, false, 0, 30, "x", x, mouse_x);
TweenPlay(tweenX);

// Create an undefined tween and override it with TweenPlay()
tweenY = TweenCreate(self);
TweenPlay(tweenY, "outQuad", "once", false, 0, 30, "y", y, mouse_y);

// This would optionally start both tweens at the same time by using Tween Selection
// But note that all tweens should be previously defined.
TweenPlay({ tween: [tweenX, tweenY] }); 

// Tween x position to mouse_x over 30 steps after a 60 step delay
tweenX = TweenCreate(self, EaseOutQuad, TWEEN_MODE_ONCE, false, 0, 0, "x", x, mouse_x);
TweenPlayDelay(tweenX, 60);

=== SCRIPT SCHEDULING ===

// Display a message after 1 second
TweenScript(self, true, 1.0, ShowMessage, "Hello, World!");

// Move player to x=250 and y=500 after 60 steps
TweenScript(obj_Player, false, 60, MoveTo, 250, 500);

// Call an anonymous function after 3 seconds
TweenScript(self, true, 3.0, function(){match_ready=true;});

// For advanced needs, different targets can be set for the underlying tween and the callback itself.
// This is done by passing an array to the target parameter. (e.g. [tween_target, callback_target])
// The first value sets the tween's target, and the second value sets the callbacks target.
// This is useful if you want the tween destroyed along with a different calling environment.
TweenScript([self, obj_Baddie], true, 1.0, MovePosition, 200, 300);

// Display a message after 1 second
ts = TweenScript(self, true, 1.0, ShowMessage, "Hello, World!");

// Schedule another script to be fired 2 seconds after first one finishes
ts = TweenMoreScript(ts, self, true, 2.0, ShowMessage, "Goodbye, World!");

// Fire a tween after showing second message
t = TweenMore(ts, self, EaseInQuad, 0, true, 0.0, 1.0, "image_scale", 1.0, 0.0);

=== EASY TWEENS ===

// Tween position to mouse position over 60 steps after 30 step delay
TweenEasyMove(x, y, mouse_x, mouse_y, 0, 60, EaseInOutSine);

// Tween position back and forth with a "patrol" mode after a 100 step delay
TweenEasyMove(1, 1, 2, 2, 100, 30, "InOutSine", TWEEN_MODE_PATROL);

// Tween image angle from 0 to 360 over 30 steps
TweenEasyRotate(0, 360, 0, 30, EaseInOutQuad);

// Tween image angle from -15 to 15 over 60 steps after a 100 step delay
TweenEasyRotate(-15, 15, 100, 60, "InOutQuad", "patrol");

// Tween image x/y scale from 1.0 to 2.0 over 30 steps
TweenEasyScale(1.0, 1.0, 2.0, 2.0, 0, 30, EaseInSine);

// Tween image x/y scale from 2.0 to 4.0 after a 60 step delay
TweenEasyScale(2.0, 2.0, 4.0, 4.0, 60, 30, "InSine");

// Tween instance's direction from 0 to 360 over 30 steps
TweenEasyTurn(0, 360, 0, 30, EaseOutSine);

// Tween instance's direction from 360 to 180 over 30 steps after a 100 step delay
TweenEasyTurn(360, 180, 100, 30, "OutSine");

// Tween instance's image alpha from 0.0 to 1.0 over 30 steps
TweenEasyFade(0.0, 1.0, 0, 30, EaseInOutSine);

// Tween image alpha back and forth with "bounce" mode after 100 step delay
TweenEasyFade(1.0, 0.0, 100, 30, "ioSine", "bounce");

// Tween instance's image blend colour from white to red over 30 steps
TweenEasyBlend(c_white, c_red, 0, 30, EaseLinear);

// Tween instance's image blend colour from red to green after 100 step delay 
TweenEasyBlend(c_red, c_green, 100, 30, "linear");

// Tween instance's image index from first to last frame over 30 steps
TweenEasyImage(0, image_number-1, 0, 30, EaseInOutQuad);

// Tween instance's image index from 0 to 5 and back after 100 step delay
TweenEasyImage(0, 5, 100, 30, "ioQuad", TWEEN_MODE_BOUNCE);

// Tween instance's speed from 0 to 10 over 30 steps
TweenEasySpeed(0, 10, 0, 30, EaseInCubic);

// Tween instance's speed from 10 to 50 after 100 step delay
TweenEasySpeed(10, 50, 100, 60, "inCubic");

// Tween instance's hspeed/vspeed from 0 to 10 over 30 steps
TweenEasySpeedHV(0, 0, 10, 10, 0, 30, EaseInOutQuad);

// Tween instance's position using a path over 200 steps
TweenEasyPath(my_path, true, 0, 200, EaseInOutSine);

// Tween position back and forth with mode "patrol" after 300 step delay
TweenEasyPath(my_path, true, 300, 200, "io", "patrol");

// Store the current "delta" setting
var ogUseDelta = TweenEasyUseDelta();

// Change default timing method to true (use seconds)
TweenEasyUseDelta(true);

// Tween instance's angle over 3.5 seconds
TweenEasyMoveRotate(0, 360, 0, 3.5, EaseInQuad);

// Put back original delta setting
TweenEasyUseDelta(ogUseDelta);

=== STATE CONTROL ===

// Fire tween
tween = TweenFire(self, EaseLinear, 0, true, 0, 1, "x", x, mouse_x);

// Pause the tween
TweenPause(tween);

// Fire tween
tween = TweenFire(self, EaseLinear, 0, true, 0, 1, "x", x, mouse_x);

// Pause the tween
TweenPause(tween);

// Resume the tween
TweenResume(tween);

// Fire tween
tween = TweenFire(self, EaseLinear, 0, true, 0, 1, "x", x, mouse_x);

// Stop the tween
TweenStop(tween);

// Fire tween
tween = TweenFire(self, EaseLinear, TWEEN_MODE_PATROL, true, 0, 1, "x", x, mouse_x);

// Reverse the tween
TweenReverse(tween);

// Fire tween
tween = TweenFire(self, EaseLinear, 0, true, 0, 1, "x", x, mouse_x);

// Finish tween and call "finish" event
TweenFinish(tween, true);

// Fire tween with a 3.0 second delay
tween = TweenFire(self, EaseLinear, 0, true, 3.0, 1, "x", x, mouse_x);

// Finish tween's delay and immediately start playing -- suppress "delay finished" event
TweenFinishDelay(tween, false);

// Create an undefined tween
tween = TweenCreate(self);

// Manually destroy the tween
TweenDestroy(tween);

// Create an undefined tween
tween = TweenCreate(self);

// Force tween to auto-destroy when it is finished playing
TweenDestroyWhenDone(tween);

// Force tween to auto-destroy and destroy it's target instance when finished
TweenDestroyWhenDone(tween, true, true);

=== STATE CHECKS ===

// Fire tween from x/y to mouse_x/mouse_y
tween = TweenFire(self, EaseLinear, 0, true, 0, 1, "x", x, mouse_x, "y", y, mouse_y);

// Pause the tween if it exists
if (TweenExists(tween))
{
    TweenPause(tween);
}

// Check if any tween is active
if (TweenIsActive())
{
    show_debug_message("A tween is active!");
}

// Check if a specific tween is active
if (TweenIsActive(tween))
{
    show_debug_message("The selected tween is active!");
}

// Check if any tween in an array is active by using Tween Selection
if (TweenIsActive({list: {[tween_a, tween_b, tween_c]})
{
    show_debug_message("One of the select tweens is active!");
}

// Check if any tween is playing
if (TweenIsPlaying())
{
    show_debug_message("A tween is playing!");
}

// Check if a specific tween is playing
if (TweenIsPlaying(tween))
{
    show_debug_message("The selected tween is playing!");
}

// Check if any tween in an array is playing by using Tween Selection
if (TweenIsPlaying({list: [tween_a, tween_b, tween_c]})
{
    show_debug_message("One of the select tweens is playing!");
}

// Fire tween
tween = TweenFire(self, "io", 0, true, 0.0, 1.0, "x", x, mouse_x);

// Pause tween
TweenPause(tween);

// Resume the tween if it is paused
if (TweenIsPaused(tween))
{
    TweenResume(tween);
}

// Fire tween to scale image back and forth between 1.0, and 2.0
tween = TweenFire(self, "io", "patrol", true, 0.0, 1.0, "image_scale", 1.0, 2.0);

// Have tween rest for 2 seconds before continuing
TweenSet(tween, "rest", 2.0);

// Show debug message if tween is resting
if (TweenIsResting(tween))
{
    show_debug_message("resting...");
}

// Fire a tween with a delay
tween = TweenFire(self, "io", "once", true, 5.0, 1.0, "x", 0, 100);

// Show debug message when tween first starts to play after delay
if (TweenJustStarted(tween))
{
    show_debug_message("Tween started playing!");
}

// Fire a tween
tween = TweenFire(self, "io", "once", true, 0.0, 1.0, "x", 0, 100);

// Show debug message when tween first finishes
if (TweenJustFinished(tween))
{
    show_debug_message("Tween just finished!");
}

// Fire a tween
tween = TweenFire(self, "io", "once", true, 0.0, 1.0, "x", 0, 100);

// Pause tween 
TweenPause(tween);

// Show debug message when tween first finishes
if (TweenJustPaused(tween))
{
    show_debug_message("Tween was just paused!");
}

// Fire a tween
tween = TweenFire(self, "io", "once", true, 0.0, 1.0, "x", 0, 100);

// Pause tween 
TweenPause(tween);

// Resume tween
TweenResume(tween);

// Show debug message when tween first resumes
if (TweenJustResumed(tween))
{
    show_debug_message("Tween was just resumed!");
}

// Fire a tween
tween = TweenFire(self, "io", "once", true, 0.0, 1.0, "x", 0, 100);

// Stop tween 
TweenStop(tween);

// Show debug message when tween first finishes
if (TweenJustStopped(tween))
{
    show_debug_message("Tween just stopped!");
}

// Fire a tween
tween = TweenFire(self, "io", "bounce", true, 0.0, 1.0, "x", 0, 100);
// Add 2 second rest to tween before continuing 
TweenSet(tween, "rest", 2.0);

// Show debug message when tween first rests
if (TweenJustRested(tween))
{
    show_debug_message("Tween just rested!");
}

// Fire a tween
tween = TweenFire(self, "io", "bounce", true, 0.0, 1.0, "x", 0, 100);
// Add 2 second rest to tween before continuing 
TweenSet(tween, "rest", 2.0);

// Show debug message when tween continues
if (TweenJustContinued(tween))
{
    show_debug_message("Tween just continued!");
}

=== GET / SET ===

	Supported Data Labels:
        "group"         -- Group which tween belongs to
        "time"          -- Current time of tween in steps or seconds
        "time_amount"   -- Sets the tween's time by a relative amount between 0.0 and 1.0 
        "time_scale"    -- How fast a tween updates : Default = 1.0
        "duration"      -- How long a tween takes to fully animate in steps or seconds
        "ease"          -- The easing algorithm used by the tween
        "mode"          -- The play mode used by the tween (ONCE, BOUNCE, PATROL, LOOP)
        "target"        -- The instance or struct associated with tween and properties
        "delta"         -- Toggle timing between seconds(true) and steps(false)
        "delay"         -- Current timer of active delay
        "delay_start"   -- The starting duration for a delay timer
        "start"         -- Start value of the property or properties
        "destination"   -- Destination value of the property or properties
		"rawstart"		-- The raw value supplied to start
		"rawdest"		-- The raw value supplied to destination
        "property"      -- Property or properties affected by the tween
        "caller"        -- The instance or struct environment which called the tween function

// Fire a tween
tween = TweenFire(self, EaseLinear, 0, true, 0.0, 1.0, "x", x, mouse_x);

// Track tween's start and destination values
start = TweenGet(tween, "start");
destination = TweenGet(tween, "destination");

// Shorthand "tags" are also supported!
duration = TweenGet(tween, "$");

    Supported Data Labels:
        "group"         -- Group which tween belongs to
        "time"          -- Current time of tween in steps or seconds
        "time_amount"   -- Sets the tween's time by a relative amount between 0.0 and 1.0 
        "time_scale"    -- How fast a tween updates : Default = 1.0
        "duration"      -- How long a tween takes to fully animate in steps or seconds
        "ease"          -- The easing algorithm used by the tween
        "mode"          -- The play mode used by the tween (ONCE, BOUNCE, PATROL, LOOP)
        "target"        -- Target instance associated with tween
        "delta"         -- Toggle timing between seconds(true) and steps(false)
        "delay"         -- Current timer of active delay
        "delay_start"   -- The starting duration for a delay timer
        "start"         -- Start value of the property or properties
        "destination"   -- Destination value of the property or properties
        "property"      -- Property or properties affected by the tween
        
        e.g.
            tween = TweenFire(self, EaseLinear, 0, true, 0, 1, "x", 0, 100);
            TweenSet(tween, "duration", 2.5);
            
    // The following labels can update multiple properties by supplying values
    // in the same order the properties were first assigned, within an [array]:
        
        "start"
        "destination"
        "property"
        
        e.g.
            tween = Tween(self, EaseLinear, 0, true, 0, 1, "x", 0, 100, "y", 0, 100); // multi-property tween (x/y)
            TweenSet(tween, "destination", [mouse_x, mouse_y]); // update "x"/"y" destination values
           
    // The keyword [undefined] can be used to leave a property value unchanged
        e.g.
            TweenSet(tween, "start", [undefined, mouse_y]); // update "y" but leave "x" unchanged
			
    // TweenSet() also supports shorthand "tags"!
        e.g
            TweenSet(tween, "$", 2); // Change duration
            TweenSet(tween, "$2"); // Will do the same as above

// Fire a new tween
tween = TweenFire(self, EaseLinear, 0, true, 0, 1, "x", 0, 100);

// Change tween's duration to 2.5 seconds
TweenSet(tween, "duration", 2.5);

// Set multiple data values at once
TweenSet(tween, "ease", "ioQuad", "mode", "patrol");

// Shorthand strings are also supported!
TweenSet(tween, "&", 10); // Set group to 10
TweenSet(tween, "~ioQuad", "#patrol"); // Change ease type and play mode

// Create an undefined tween, then define it with TweenDefine() before playing
tween = TweenCreate(self);
TweenDefine(tween, EaseOutQuad, TWEEN_MODE_ONCE, false, 0, 30, "x", x, mouse_x);
TweenPlay(tween);

// Track the current group default for newly created tweens
var _prev_group = TweenDefaultGet("group");

// Set default group for newly created tweens to 10
TweenDefaultSet("group", 10);

// Fire a new tween which will be automatically assigned to group 10
TweenFire(self, "io", "patrol", true, 0, 2.0, "x", 100, 200);

// Set default group back to original group value
TweenDefaultSet("group", _prev_group);

// Set default group for newly created tweens to 10
TweenDefaultSet("group", 10);

// Fire a new tween which will be automatically assigned to group 10
TweenFire(self, "io", "patrol", true, 0, 2.0, "x", 100, 200);

// Set group's timescale to 1.0 if currently 0.5
if (TweenGroupGetTimeScale(10) == 0.5)
{
    TweenGroupSetTimeScale(10, 1.0);
}

// Double group 10's timescale
TweenGroupSetTimeScale(10, 2.0);

=== TOOLS ===

// Find eased value between 0 and 100 at amount of 0.75 with EaseInOutQuad
value = Ease(0, 100, 0.75, EaseInOutQuad);

Steps a tween forward or backward by a given amount.
The direction can be a decimal (floating point) value.
        
Using 1.0 or -1.0 will step a tween 1 step in the indicated direction.
Lesser values, such as 0.5, will step the tween half a step foward.
Greater values, such as 2.0, will step a tween 2 steps forward.

This function supports Tween Selection.

// Step a tween forward at half speed
TweenStep(tween1, 0.5);

// Step another tween backward at double speed
TweenStep(tween2, -2.0);

// Create defined tween 
tween = TweenFire(id, EaseInOutQuint, 0, true, 0.0, 10, "", 0, 100);

// Calculate value of tween at its current state
x = TweenCalc(tween);

// Calculate a tweens "halfway" value by using an amount (0.0 - 1.0)
midPoint = TweenCalc(tween, 0.5);

// Calculate using an explicit time by passing time within an array
value = TweenCalc(tween, [5]);

// Create multi-property tween, then get array holding values for each calculated property
tweenXY = TweenFire(id, EaseOutQuad, 0, false, 0, 30, "", 0, 100, "", -50, 50);
midPoints = TweenCalc(tweenXY, 0.5);
var _x = midPoints[0];
var _y = midPoints[1];

// Associate name with custom animation curve
EaseToString("Bouncy", AnimCurve_Bouncy);

// Fire a tween using custom name as ease type
TweenFire(self, "Bouncy", 0, true, 0, 1, "x", 0, 100);

// Set Tweens*() scripts to include deactivated targets
TweensIncludeDeactivated(true);

// Pause all tweens, even tweens associated with deactivated instances 
TweenPause(all);

=== DATA PROPERTIES ===

// Create an array and pass it as the tween property with TPArray().
myArray[0] = 0;
tween = TweenFire(self, EaseInQuad, 0, true, 0.0, 3.0, TPArray(myArray, 0), 0, 100);
        
// Get value from tweened array index
value = myArray[0];

// Create a list and pass it as the tween property with TPList().
myList = ds_list_create();
myList[| 0] = 0;
tween = TweenFire(self, EaseInQuad, 0, true, 0.0, 3.0, TPList(myList, 0), 0, 100);
        
// Get value from tweened array index
value = myList[| 0];

// Create a map and pass it as the tween property with TPMap().
myMap = ds_map_create();
myMap[? "key"] = 0;
tween = TweenFire(self, EaseInQuad, 0, true, 0.0, 3.0, TPMap(myList, "key"), 0, 100);
        
// Get value from tweened map key
value = myMap[? "key"];

// Create a grid and pass it as the tween property with TPGrid().
myGrid = ds_grid_create(10,10);
tween = TweenFire(self, EaseInQuad, 0, true, 0.0, 3.0, TPGrid(myGrid, 2, 4), 0, 100);
        
// Get value from tweened grid index
value = myGrid(# 2, 4);

=== MODIFIER PROPERTIES ===

// Fire a tween for easing "x" with rounded up values.
TweenFire(self, EaseInOutSine, 0, true, 0, 1, TPCeil("x"), 250, 500);

// Fire a tween for easing "x" with rounded down values.
TweenFire(self, "ioSine", 0, true, 0, 1, TPFloor("x"), 250, 500);

// Fire a tween for easing "x" with rounded values.
TweenFire(self, "inBack", 0, true, 0, 1, TPRound("x"), 250, 500);

// Fire a tween for "x" with given shake amount.
TweenFire(self, "outCubic", 0, true, 0, 1, TPShake("x",10), 250, 500);

// Fire a tween for "x" and "y" snapped to a 16x16 grid.
TweenFire(self, "InOutQuart", 0, true, 0, 1, TPSnap("x",16),0,128, TPSnap("y",16),0,128);

=== SPECIAL PROPERTIES ===

/// [SOME EVENT] ///
// Fire tween using user event 0 as property setter -- pass custom colour data
TweenFire(self, EaseInSine, 0, true, 0.0, 1.0, TPUser(0, c_red, c_blue), 0, 1);
       
// Fire another tween using user event 1 as propety setter and getter
// Notice how event is passed as a string with the ">"(to) symbol
TweenFire(self, EaseInSine, 0, true, 0.0, 1.0, TPUser("1>"), mouse_x);
	   
	   
/// [USER EVENT 0] ///
image_blend = merge_colour(TWEEN_USER_DATA[0], TWEEN_USER_DATA[1], TWEEN_USER_VALUE);


/// [USER EVENT 1] ///
if (TWEEN_USER_GET)
{   // GET
    TWEEN_USER_GET = my_variable;
}
else
{   // SET
    my_variable = TWEEN_USER_VALUE;
}

// Fire a tween for "x" and "x" for another instance
TweenFire(self, "io", 0, true, 0, 1, "x", 0, 25, TPTarget(some_object,"x"), 50, 75);

// The TO and FROM ">" / "<" convention is also supported!
TweenFire(self, "io", 0, true, 0, 1, TPTarget(o_Player,"x>"), mouse_x);

// Fire a tween for easing a value from red to green
some_color = c_white;
TweenFire(self, "InOutSine", 0, true, 0, 1, TPCol("some_color"), c_red, c_green);

// Tween "some_color" to blue
TweenFire(self, "ioSine", 0, true, 0, 1, TPCol("some_color>"), c_blue);

// Tween position using a path resource
TweenFire(self, "outQuad", 0, true, 0, 1, TPPath(some_path,true),0,1);

// Tween position using a path resource starting at a given position
TweenFire(self, "outElastic", 0, true, 0, 1, TPPathExt(some_path,64,128),0,1);

=== EVENT CALLBACKS ===

Event callbacks allow you to execute scripts/functions/methods or user events when a specified tween event occurs.
The following tween event macros are:
	
	TWEEN_EV_PLAY		-- When tween starts to play
	TWEEN_EV_FINISH		-- When tween is finished playing
	TWEEN_EV_CONTINUE	-- When tween continues with TWEEN_MODE_BOUNCE, TWEEN_MODE_PATROL, TWEEN_MODE_REPEAT
	TWEEN_EV_STOP		-- When tween is manually stopped
	TWEEN_EV_PAUSE		-- When tween is paused
	TWEEN_EV_RESUME		-- When tween is resumed
	TWEEN_EV_REVERSE  	-- When tween is reversed
	
There are also events for delayed tweens:

	TWEEN_EV_FINISH_DELAY	-- When a tween's delay expires
	TWEEN_EV_STOP_DELAY  	-- When a delayed tween is stopped
	TWEEN_EV_PAUSE_DELAY	-- When a delayed tween is paused
	TWEEN_EV_RESUME_DELAY	-- When a paused delayed tween is resumed
	
Events also support string names as an alternative to macros:
	TWEEN_EV_PLAY		"play"		"played"
	TWEEN_EV_FINISH		"finish"	"finished"
	TWEEN_EV_CONTINUE	"continue"	"continued"
	TWEEN_EV_STOP		"stop"		"stopped"
	TWEEN_EV_PAUSE		"pause"		"paused"
	TWEEN_EV_RESUME		"resume"	"resumed"
	TWEEN_EV_REVERSE	"reverse"	"reversed"
	 											
	TWEEN_EV_FINISH_DELAY	"finish_delay"	"finished_delay"
	TWEEN_EV_STOP_DELAY	"stop_delay"	"stopped_delay"
	TWEEN_EV_PAUSE_DELAY	"pause_delay"	"paused_delay"
	TWEEN_EV_RESUME_DELAY	"resume_delay"	"resumed_delay"

// Fire a tween
tween = TweenFire(self, EaseInQuad, 0, true, 0.0, 1.0, "x", x, mouse_x);

// Have a script execute when tween finishes
TweenAddCallback(tween, TWEEN_EV_FINISH, self, ShowMessage, "Finished!");

// Fire a tween
tween = TweenFire(self, EaseInQuad, 0, true, 0.0, 1.0, "x", x, mouse_x);

// Have a user event 5 execute when tween finishes
cb = TweenAddCallbackUser(tween, TWEEN_EV_FINISH, self, 5);

// Add callback to a tween
cb = TweenAddCallback(tween, "finish", self, ShowMessage, "Hi!");

// Invalidate (destroy) the callback if valid
if (TweenCallbackIsValid(cb))
{
    TweenCallbackInvalidate(cb);
}
else
{
    show_message("Callback already invalidated!");
}

// Add callback to a tween
cb = TweenAddCallback(tween, TWEEN_EV_FINISH, self, ShowMessage, "Hi!");

// Check if a callback id is valid
if (TweenCallbackIsValid(cb))
{
    show_message("Callback is valid!");
}
else
{
    show_message("Callback is not valid!");
}

// Add callback to a tween
cb = TweenAddCallback(tween, "finished", self, ShowMessage, "Hi!");

// Temporarily disable the callback
TweenCallbackEnable(tween, false);

// Re-enable the disabled callback
TweenCallbackEnable(tween, true);

// Add callback to a tween
cb = TweenAddCallback(tween, TWEEN_EV_FINISH, self, ShowMessage, "Hi!");

// Temporarily disable the callback
TweenCallbackEnable(tween, false);

// Show message if callback not enabled
if (TweenCallbackIsEnabled(cb) == false)
{
    show_message("Callback is disabled!");
}

=== EVENT MANAGEMENT ===

// Fire a tween
tween = TweenFire(self, EaseLinear, 0, true, 0.0, 1.0, "y", y, mouse_y);

// Add callback to tween
cb = TweenAddCallback(tween, TWEEN_EV_FINISH, id, ShowMessage, "Hi!");

// Invalidate all callbacks associated with tween event "finish"
TweenEventClear(tween, TWEEN_EV_FINISH);

// Fire a tween
tween = TweenFire(self, EaseLinear, 0, true, 0.0, 1.0, "y", y, mouse_y);

// Add callback to tween
cb = TweenAddCallback(tween, TWEEN_EV_FINISH, self, ShowMessage, "Hi!");

// Disable event callbacks associated with tween event "finish"
TweenEventEnable(tween, TWEEN_EV_FINISH, false);

// Fire a tween
tween = TweenFire(self, EaseLinear, 0, true, 0.0, 1.0, "y", y, mouse_y);

// Add callback to tween if event is enabled
if (TweenEventIsEnabled(tween, TWEEN_EV_FINISH))
{
    cb = TweenAddCallback(tween, TWEEN_EV_FINISH, self, ShowMessage, "Hi!");
}

=== SYSTEM UTILITIES ===

SUPPORTED DATA LABELS:
	"enabled"		// is system enabled?
	"time_scale"		// global time scale
	"update_interval"	// how often system should update in steps (default = 1)
	"min_delta_fps"		// minimum frame rate before delta time lags behind (default=10)
	"auto_clean_count"	// number of tweens to check for auto-cleaning each step (default=10)
	"delta_time"		// tweening systems internal delta time
	"delta_time_scaled" 	// tweening systems scaled delta time

// Get the system's current time scale value
timeScale = TweenSystemGet("time_scale");

SUPPORTED DATA LABELS:
	"enabled"		// set system enabled state
	"time_scale"		// global time scale
	"update_interval"	// how often system should update in steps (default = 1)
	"min_delta_fps"		// minimum frame rate before delta time lags behind (default=10)
	"auto_clean_count"	// number of tweens to check for auto-cleaning each step (default=10)

// Set the system's current time scale to 0.5 (half speed)
TweenSystemSet("time_scale", 0.5);

// Destroy tweens in persistent menu room
TweenSystemClearRoom(rm_Menu);

// Destroy tweens in all persistent rooms 
TweenSystemClearRoom(all);

// Immediately flush all destroyed tweens from system
TweenSystemFlushDestroyed();

=== PROPERTY BUILDERS ===

	[EXAMPLE FOR INSTANCE VARIABLE]
	
	/// SETTER FUNCTION
	SET_my_var = function(value, target)
	{
	    target.my_var = value;
	}
	
	/// GETTER FUNCTION
	GET_my_variable = function(target) 
	{
	    return target.my_var;
        }
	
	/// Apply property builder with functions above, only once at start of game
	TPFuncShared("my_var", SET_my_var, GET_my_var);
	

	[EXAMPLE FOR GLOBAL VALUE]
	
	/// SETTER SCRIPT
	SET_global_my_var = function(value)
	{
	    global.my_var = value;
        }
	
	/// GETTER SCRIPT
	GET_global_my_var = function()
	{
	    return global.my_var;
        }
	
	/// Apply property builder with functions/methods above, only once at start of game
	TPFuncShared("global.my_var", SET_global_my_var, GET_global_my_var);

	// INSTANCE PROPERTY
	TPFuncShared("my_var", function(v,t){ t.my_var = v; }, function(t){ return t.my_var; });
	
	// GLOBAL PROPERTY
	TPFuncShared("global.my_var", function(v){ global.my_var = v; }, function(){ return global.my_var; });

// Override x property to use a rounded value
TPFunc(self, "x", 
    function(value,target){ target.x = round(value); },
    function(target){ return round(target.x); }
);

// Prepare a property to be optimised with setter and getter functions
TPFuncShared("my_var", 
    function(value,target){ target.my_var = value; }, 
    function(target){ return target.my_var; }
);

// Prepare a property to be normalized for values between 0-1
TPFuncSharedNormal("my_color", 
    function(value,target,data){ target.my_color = merge_colour(data[0], data[1], value); }, 
    function(target){ return target.my_color; }
);

// Tween the normalized "my_color" variable
TweenFire(self, "io", 0, true, 0, 1, "my_color", c_blue, c_yellow);

=== SPECIAL HANDLES ===

// ASSIGN A NULL TWEEN TO A VARIABLE
my_tween = TWEEN_NULL;
	
// NO ERROR WILL OCCUR
TweenPause(my_tween);

// WILL RETURN FALSE FOR EXISTENCE/PLAYING/ETC CHECKS
exists = TweenExists(my_tween);

// HAVE NEW TWEENS USE DELTA TIMING BY DEFAULT
TweenSet(TWEEN_DEFAULT, "delta", true);

// ASSIGN FUNCTION TO USE AS CALLBACK
my_callback = function()
{
    // CHANGE THE CALLING TWEEN'S EASE TYPE WHEN CONTINUING
    TweenSet(TWEEN_SELF, "ease", choose(EaseInSine, EaseInQuad));
}
	
// FIRE TWEEN AND ASSIGN CALLBACK EVENT
t = TweenFire(self, "inSine", "patrol", true, 0, 1, "x", 0, 1000);
TweenAddCallback(t, "continue", self, my_callback); 

// ASSIGN FUNCTION TO USE AS CALLBACK
my_callback = function()
{
    // HAVE CALLBACK INVALIDATE ITSELF WHEN CALLED
    TweenCallbackInvalidate(TWEEN_CALLBACK_SELF);
}
	
// FIRE TWEEN AND ASSIGN CALLBACK EVENT
t = TweenFire(self, "io", 0, true, 0, 1, "x", 0, 1000);
TweenAddCallback(t, "finish", self, my_callback); 

=== ADVANCED FEATURES ===

==================
 ANIMATION CURVES
==================
		
	GameMaker's built-in Animation Curves can be used in the place of easing algorithms:
	
		TweenFire(self, CurveIndex, 0, true, 0, 1, "x", 0, 100);
		
	Animation Curve channel's can also be used as an ease type:
	
		TweenFire(self, CurveChannel, 0, true, 0, 1, "x", 0, 100);
		
	For a curve to work well with TweenGMX, you typically want its 
	first point to start at {h:0, v:0} and its last point to finish at {h:1, v:1}.
	However, like the included EaseHeartbeat animation curve, this isn't always the case!
	You can make use of animation curves for more advanced use cases.
	
	Please see the folder [TweenGMX] >> [Extras] >> [Animation Curves] 
	for examples of how to make custom animation curves which work well with TweenGMX.
	
	Like easing functions, EaseToString() also supports animation curves.




===============
 TWEEN TO/FROM
===============

	Note: If coming from TweenGMS, TweenFireTo() and TweenFireFrom() are now obsolete.
	
	This convention can be used with:
		TweenFire
		TweenMore
		TweenCreate
		TweenPlay
		TweenDefine
		
	The ">" and "<" symbols can be used for easing a property TO or FROM its current value.
	For example, we can have 'x' ease from its current value to mouse_x...

		// EASE 'x' TO mouse_x
		TweenFire(self, EaseLinear, 0, true, 0, 1, "x>", mouse_x);
		
	As you might notice, no starting value is required for 'x', as its current value will be used.
	This would be similar to doing...
	
		TweenFire(self, EaseLinear, 0, true, 0, 1, "x", x, mouse_x);
		
	Likewise, we can have 'x' start FROM mouse_x and finish at its current position...

		// EASE 'x' FROM mouse_x to 'x'
		TweenFire(self, EaseLinear, 0, true, 0, 1, "x<", mouse_x);
		
	You can also mix To/From properties in the same function call...
	
		// EASE 'x' TO mouse_x AND EASE 'y' FROM mouse_y TO 'y'
		TweenFire(self, EaseLinear, 0, true, 0, 1, "x>", mouse_x, "y<", mouse_y);
		
	You can even mix To/From with the standard convention...
	
		TweenFire(self, EaseLinear, 0, true, 0, 1, "x>", mouse_x, "y<", mouse_y, "image_scale", 0, 1);
		
	Note that the symbol ":" can *optionally* be used for properties using the 
	default start/destination convention to help with code clarity...
	
		// THESE BOTH DO THE SAME THING
		TweenFire(self, EaseLinear, 0, true, 0, 1, "image_scale", 0, 1);
		TweenFire(self, EaseLinear, 0, true, 0, 1, "image_scale:", 0, 1);
		
	**
	** Please be careful to supply the proper number or arguments when using the to/from convention!
	**
		


===================
 "OFF-RAIL" TWEENS
===================

	An optional "off-rail" convention can be used for more user-specific control.
	This convention uses "-tags" which indicate which parameter we want to set.
	Here is a list of supported tags: (Associated shorthand tags [e.g. "?"] will be discussed later)
	
		"?" | "-target"
		"~" | "-ease"
		"#" | "-mode"
		"$" | "-duration" | "-dur"
		"^" | "-delta"
		"+" | "-delay"
		"|" | "-rest"
		">" | "-continue_count" | "-count" | "-cc"
		"&" | "-group"
		"=" | "-time" ***Not to be confused with duration
		"%" | "-time_amount" | "-amount"
		"*" | "-time_scale" | "-scale"
		"!" | "-destroy
	
	Now, both of these tweens will do the same thing...
	
		// STANDARD CONVENTION
		TweenFire(self, EaseLinear, 0, 1, 0, 1, "x", 0, 100);
		
		// OFF-RAIL CONVENTION
		TweenFire("-target", self, "-ease", EaseLinear, "-mode", 0, "-delta", 1, "-delay", 0, "-dur", 1, "x", 0, 100);
		
	The off-rail mode might seem worse at first, but it gets better!
	First, we can remove the tags which have default values we don't need to set explicitly, 
	such as "-target", "-mode", and "-delay"...
	
		// ASSUME TARGET=self, MODE=0, AND DELAY=0
		TweenFire("-ease", EaseLinear, "-delta", 1, "-dur", 1, "x", 0, 100);
		
	That is looking cleaner. But we can do even better! 
	We can actually set a global default for "delta" as well...
	
		// THIS ONLY NEEDS TO BE SET ONCE
		TweenDefaultSet("delta", true);
		
		// TWEEN WILL USE delta=true AS DEFAULT
		TweenFire("-ease", EaseLinear, "-dur", 1, "x", 0, 100);
		
		
	But, we can still go further!
	Shorthand symbols (e.g. "?") are also supported as tags.
	So, for example, we can use "~" instead of "-ease"...
	
		TweenFire("~", EaseLinear, "-dur", 1, "x", 0, 100);
		
	Likewise, we can replace "-dur" with "$" (time is money)
	
		TweenFire("~", EaseLinear, "$", 1, "x", 0, 100);
		
	Now, shorthand tags (except "?") support being condensed with explicit values.
	So, the example above could be shortened to this...
	
		TweenFire("~Linear", "$1", "x", 0, 100);
	
	And! Because EaseLinear is actually a tween default, it could even be shortened to just this...
	
		TweenFire("$1", "x", 0, 100);
		
	If we wanted to make this even shorter, we could use the TO/FROM ("x>") convention for our property...
	
		TweenFire("$1", "x>", 100);
		
	I hope you are getting the point! 
	The off-rail mode allows you to set only what you need to.
	
	NOTE: Standard tween calls can also go "off-rails" AFTER the duration parameter is set.
		  You are not even required to set variable properties first!
		  Here are some examples:
			
			// FIRE STANDARD TWEEN BUT GO OFF-RAIL AT THE END TO SET TWEEN'S GROUP AND TIMESCALE
			TweenFire(self, EaseLinear, 0, true, 0, 1.0, "x", 0, 100, "-group", 10, "-scale", 0.5");
			
			// GO OFF-RAIL RIGHT AFTER SETTING DURATION - SET x VARIABLE PROPERTY LAST
			TweenFire(self, EaseLinear, 0, true, 0, 1.0, "-group", 10, "-scale", 0.5, "x", 0, 100);
	
	
	Now, I will cover other supported conventions for shorthand tags.
	
	Note: upper/lower case and underscores DO NOT matter -- inQuad, IN_QUAD, and iNqUaD are all valid
	
	[EASE] Special Shorthand Tags 
	
		*** The SINE algorithm supports additional default shorthand tags... "~i", "~o", "~io", "~in", "~out", "~inout" ***
		
		"~linear"
		
		"~InSine", "~iSine", "~in", "~i"
		"~OutSine", "~oSine", "~out", ~o";
		"~InOutSine", "~ioSine", "~InOut", "~io"
		
		"~InQuad", "~iQuad"
		"~OutQuad", "~oQuad"
		"~InOutQuad", "~ioQuad"
		
		"~InCubic", "~iCubic"
		"~OutCubic", "~oCubic"
		"~InOutCubic", "~ioCubic"
		
		"~InElastic", "~iElastic"
		"~OutElastic", "~oElastic"
		"~InOutElastic", "~ioElastic"
		
		etc....
		
		Note: 
			These can also be used in regular "on-rail" tween calls, but remove the prefix "~" -> "ioElastic"
			e.g. 
			     // TWEEN USING EaseInOutSine ("io")
			     TweenFire(self, "io", 0, true, 0, 1, "x>", 100);
		
	[MODE] Special Shorthand Tags
	
		"#0", "#o", "#once"
		"#1", "#b", "#bounce",
		"#2", "#p", "#patrol",
		"#3", "#l", "#loop",
		"#4", "#r", "#repeat
		
		Note: 
			These can also be used in regular "on-rail" tween calls, but remove the prefix "#" -> "patrol"
		
	[ADDITONAL] Explicit Value Shorthand Tags 
	
		Delta
			"^0"  (STEP)
			"^1"  (DELTA)
		
		Delay
			"+30"
		
		Duration
			"$30"
			
		Rest
			"|100"
			
		Continue Count
			">5"
		
		Etc...
		
		NOTE:  "?" does not support explicit values
		
	
	Now, it is also possible to add event callbacks directly within a tween call by using an "@event" tag.
	All supported callback tags start with "@" ...
	
		(letters in [] are optional)
		"@finish[ed]" / "@" -- ** Note that "@" is the same as "@finish" **
		"@continue[d]" 	
		"@pause[d]"		
		"@play[ed]"			
		"@resume[d]"		
		"@stop[ped]"			
		"@rest[ed]"			
		"@resting"		
		"@reverse[d]"		
		"@finish[ed]_delay"
		"@pause[d]_delay"	
		"@resume[d]_delay"	
		"@stop[ped]_delay"	
	
	Let's continue with the previous example and extend it...
	
		// CALL FUNCTION 'ShowFireworks' WHEN TWEEN FINISHES
	
		// STANDARD WAY
		t = TweenFire("$1", "x>", 100);
		TweenAddCallback(t, TWEEN_EV_FINISH, self, ShowFireworks);
	
		// NEW WAY (OPTIONAL!)
		TweenFire("$1", "x>", 100, "@finish", ShowFireworks);
	
	If arguments need to be passed to the script, we can pass the callback as an array with additional arguments...
	
		// SHOW YELLOW FIREWORKS AT SPECIFIC LOCATION
		TweenFire("$1", "x>", 100, "@finish", [ShowFireworks, c_yellow, x, y]);
		
		// NOTE THAT "@" IS THE SAME AS "@finish" FOR EXTRA CONVENIENCE
		TweenFire("$1", "x>", 100, "@", [ShowFireworks, c_yellow, x, y]);
	
	If you want to set an explicit callback target, you can optionally pass a struct
	as the first array element, assigning a value to the 'target' field...
	
		// THIS WILL DO THE SAME THING AS ABOVE, EXCEPT THAT IT WILL USE 'obj_Player' AS THE CALLING ENVIRONMENT
		TweenFire("$1", "x>", 100, "@", [{target: obj_Player}, ShowFireworks, c_yellow, x, y]);
	
	Additionally, you can simply pass 'self' or 'other' as the first array element for assigning the callback target
		
		// USE 'other' AS THE CALLBACK TARGET
		TweenFire("$1", "x>", 100, "@", [other, ShowFireworks, c_yellow, x, y]);

	The keyword 'undefined' is also a valid callback target. This is useful for retaining a method's
	existing instance/struct calling environment as the callback target.
	
		// CALL obj_Enemy's 'meth_Explode' METHOD -- 'undefined' RETAINS ORIGINAL CALLING ENVIRONMENT FOR CALLBACK TARGET
		TweenFire("$1", "x>", 100, "@", [undefined, obj_Enemy.meth_Explode]);
		
	If a function ID is used, then 'undefined' will assign the tween's target as the callback target.
	Using 'undefined' in this case would be redundant, as callbacks already default to using the tween's target.
	
		// USE TWEEN'S TARGET AS CALLBACK TARGET FOR THE FUNCTION
		TweenFire("$1", "-target" obj_Enemy, "x>", 100, "@", [undefined, func_Explode]);
		
	NOTE: The keyword 'undefined' is also supported by TweenAddCallback() as a valid target.
		
		


=================
 TWEEN SELECTION
=================
	
	The keywords all, self, and other work as valid tween ids for various functions which support them.
	Functions which support multi-tween selection show 'tween{s}' as a parameter.
	So, for example, we can use self to pause all tweens associated with the current calling environment...
	
		// PAUSE ALL TWEENS ASSOCIATED WITH THE CALLING TARGET ENVIRONMENT
		TweenPause(self);
		
	You can likewise do this with the other keyword...
	
		// PAUSE ALL TWEENS ASSOCIATED WITH 'OTHER' ENVIRONMENT
		TweenPause(other);
		
	And! You can affect all tweens with the all keyword...
	
		// PAUSE ALL TWEENS
		TweenPause(all);
		
	For more advanced tween selection, structs can be used with specified properties...
		tween:	  -- ID HANDLE
		target:	  -- INSTANCE/OBJECT OR STRUCT REFERENCE
		group:	  -- ASSIGNED TWEEN GROUP VALUE
		list:	  -- ARRAY OR DS_LIST CONTAINING TWEEN IDS
	
	Here are some examples...
	
		// PAUSE TWEENS BELONGING TO GROUP 5
		TweenPause({group: 5});
		
		// PAUSE TWEENS BELONGING TO A SPECIFIC TARGET
		TweenPause({target: obj_Baddie});
		
		// PAUSE TWEENS STORED IN AN ARRAY OR LIST
		TweenPause({list: array_ui_tweens});
		TweenPause({list: list_baddie_tweens});
		
	More than one struct property can be used for a single call...
	
		// PAUSE TWEENS ASSOCIATED WITH GROUP 5 AND TARGET 'self' AND TWEEN 'myTween'
		TweenPause({group: 5, target: self, tween: myTween});
		
	And arrays can be used to pass more than one value to each struct property...
		
		// PAUSE TWEENS BELONGING TO GROUPS 5 AND 10, TARGETS self and other, AND VARIOUS TWEEN ID HANDLES 
		TweenPause({group:[5,10], target:[self,other], tween:[tween1,tween2,tween3]});
	
	



===================
 CONTINUE AND REST
===================

	There are 3 play modes which support "countinue counts": 

		PATROL 
		LOOP
		REPEAT

	When a tween reaches the start/destination points of the tween,
	continue counts determine if the tween will continue or finish.
	By default, countinue counts are infinite (-1).
	Setting a tween with a 'patrol' mode to a continue count of 1
	will effectively make it the same as the 'bounce' mode.

	A tween's continue count can be set in these various ways:

		// #1
		t = TweenFire(self, EaseLinear, "patrol", true, 0, 60, "x", 0, 100);
		TweenSet(t, "continue_count", 2);
		
		// #2 THE FOLLOWING ALL DO THE SAME THING
		TweenFire("$60", "#patrol", "-continue_count", 2, "x", 0, 100);
		TweenFire("$60", "#patrol", "-count", 2, "x", 0, 100);
		TweenFire("$60", "#patrol", "-cc", 2, "x", 0, 100)
		TweenFire("$60", "#patrol", ">", 2, "x", 0, 100);		// Use ">" shorthand symbol
		TweenFire("$60", "#patrol", ">2", "x", 0, 100);			// Use ">2" codensed shorthand
	
	It is also possible to set the "rest" duration for tweens which continue.
	This is the amount of time a tween will wait before continuing.
	This value can be set in the following ways...

		// #1
		t = TweenFire(self, EaseLinear, "patrol", true, 0, 1, "x", 0, 100);
		TweenSet(t, "rest", 30);
	
		// #2
		TweenFire("$60", "#patrol", "-rest", 30, "x", 0, 100);
		
		// THE FOLLOWING 2 EXAMPLES ARE THE SAME AS ABOVE BUT USE THE "|" SHORTHAND SYMBOL
		TweenFire("$60", "#patrol", "|", 30, "x", 0, 100);
		TweenFire("$60", "#patrol", "|30", "x", 0, 100); // Condensed shorthand
	
	The previous examples will cause the tween to rest for 30 steps before continuing.
	However, it also possible to have different rest durations for the start and destination points.
	This can be done by passing the rest parameter as an array...

		TweenFire("$60", "#patrol", "-rest", [30, 120], "x", 0, 100);
	
	This example above would cause the tween to rest for 30 steps after returning to
	the start position and have it rest for 120 steps after reaching the destination position.

	Now, if using the standard form of TweenFire() WITHOUT going "off-rails",
	you can still easily set these values by passing an array to the delay parameter.
	The first value is the main tween delay, and the second value the rest duration...

		// delay = 0
		// rest  = 30
		TweenFire(self, EaseLinear, "patrol", false, [0, 30], 60, "x", 0, 100);
	
	To set the rest value for both the start and destination, a third argument can be passed to the array...

		// delay = 0
		// start rest = 30
		// destination rest = 120
		TweenFire(self, EaseLinear, "patrol", false, [0, 30, 120], 60, "x", 0, 100);
	
	Optionally, you can also go "off-rail" after setting all required Tween*() parameters

		// GO OFF-RAIL AT THE END AND SET REST
		TweenFire(self, EaseLinear, "patrol", false, 0, 60, "x", 0, 100, "-rest", 30);
	
	


====================================
 PROPERTY START/DESTINATION STRINGS
====================================

	**Please be aware that this feature has strict limitations which will be explained further on**
	
	Start and destination values can now take string arguments which allow for more advanced uses. 
	For example, the following can be done...
	
		TweenFire(self, "io", 0, false, 0, 60, "x>", "x+100");
	
	The above example will move x to the *current* x position plus 100.
	Now, this isn't very useful in this case as we, instead, could directly do...
	
		TweenFire(self, "io", 0, false, 0, 60, "x>", x+100);
		
	However, if this tween adds a delay, then the string destination becomes useful.
	
		TweenFire(self, "io", 0, false, 30, 60, "x>", "x+100");
		
	Now, after the delay finishes, the tween will check the *current* position of x
	and add 100 to that current value. So, if the target instance is moving around, this
	method can be used to adjust for a moving x value.
	
	There is also a shorthand symbol "@" for extra convenience.
	The "@" will represent which variable is being tweened.
	So, we could do this...
	
		TweenFire(self, "io", 0, false, 30, 60, "image_scale>", "@*2", "image_angle>", "@+360");
		
	In the above example, the "@" symbol will be replaced with "image_scale" and "image_angle" respectively.
	
	Additionally, instance variables **from the current calling environment**
	and global variables can also be used in the string...
	
		value = 100;
		global.gValue = 200;
		TweenFire(self, "io", 0, false, 30, 60, "x>", "@+value; "y>", "@+gValue");
		
	The above example will add 'value' and 'gvalue' to the respective properties.
	If TweenGMX does not detect an instance variable, it will automatically check
	for a global variable with the same name. You can still explicitly use global
	variables by supplying the "global." prefix.
	
	You can also reference values from other instances using an object id prefix...
	
		TweenFire(self, "io", 0, false, 30, 60, "x>", "obj_SomeDude.x + 100");
	
	**NOTE: LOCAL VARIABLES ARE NOT SUPPORTED**
	
		// THIS WILL CAUSE AN ERROR!
		var _someVar = 100;
		TweenFire(self, "io", 0, false, 30, 60, "x>", "_someVar+100");
	
	Now, the use of string values are quite limited.
	You can only have 2 values added, subtracted, multiplied, or divided.
	Some examples...
			
			"value+2"
			"@-value"
			"value*2"
			"@/value"
			
	In addition to stringed values, you can also use an array to set values relative to
	the current value of the given property variable. For example...
	
		TweenFire(self, "io", 0, false, 30, 60, "x>", [100], "y>", [-200]);
		
	The above example would move the 'x' right by 100 and 'y' up by 200.
	This could be the better option when wanting to use local temporary variables to set values.
	
	In addition to adjusting for value changes during a delay, this feature could also
	be useful when using TweenCreate() with TweenPlay().




=================
PROPERTY METHODS
=================

	-----
	NOTE:
	This functionality is optional and advised for advanced users.
	You can often tween custom variables without having to set anything up.

	TPFuncShared() will affect all instances/structs with global defaults.
		* This is what built-in setters/getters use (e.g. "x", "direction", "image_angle")
	
	TPFunc() will prepare (and override) properties only for the given instance/struct.
	-----
	
	Methods can be used as property 'setters' and 'getters'.
	We can use TPFunc() or TPFuncShared() to set them up.
	
	Here is an example of using TPFuncShared() for creating globally shared custom properties:
	
	    // CREATE PROPERTY THAT ASSIGNS AND "SHAKES" THE X VALUE
	    TPFuncShared("shake_x",
	        function(value,target) { target.x = value + random_range(-5, 5); }, // SETTER
	        function(target) { return target.x; } // GETTER
	    );
		
	    // FIRE TWEEN USING CUSTOM PROPERTY "shake_x"
	    TweenFire(obj_Player, "io", 0, true, 0, 1, "shake_x", 0, 100);
	
	The first setter method takes both a 'value' and 'target' argument and determines how eased values are assigned to the target. 
	You can change the 'value' and 'target' parameter names to whatever you want...

            // THIS IS THE SAME AS EXAMPLE ABOVE
            TPFuncShared("shake_x",
                function(_v,_t) { _t.x = _v + random_range(-5, 5); }, // SETTER
                function(_t) { return _t.x; } // GETTER
            );
	
	The second method supplied to TPFuncShared() is used as the 'getter' which receives a target
	and returns the value for that target's variable. Again, 'target' can be renamed to whatever you like.

	Likewise, we can use TPFunc() to set up custom properties for individual instances or structs.
	If a global property has already been set, then TPFunc will override it for the specified target:
	
            // CREATE CUSTOM PROPERTY SETTER WHICH ADDS A "shake" TO THE TWEENED 'x' VARIABLE
            TPFunc(self, "shake_x", 
            function(value,target) // SETTER -- add random shake to x
            {
                target.x = value + random_range(-10, 10);
            });

            // FIRE TWEEN USING CUSTOM PROPERTY METHOD "shake_x"
            TweenFire(self, "io", 0, true, 0, 1, "shake_x", 0, 100);
		
	We can optionally supply our own getter as well by extending the example above...
		
            // CREATE CUSTOM METHOD PROPRETY SETTER WHICH ADDS A "shake" TO THE TWEENED VALUE
            TPFunc(self, "shake_x", 
                function(value,target) { target.x = value + random_range(10) }, // SETTER
                function(target)	   { return target.x } // GETTER
            );

            // THE ">" SYNTAX NOW USES THE CUSTOM 'GETTER' FUNCTION
            TweenFire(self, "io", 0, true, 0, 1, "shake_x>", 100);
	
        TPFunc can also be used directly inside of a tween function like so...
	
            // USE TPFunc DIRECTLY INSIDE TWEEN CALL
            TweenFire("$60", TPFunc(self,"myVar", function(v,t){ t.myVar = v; }), 0, 100);
		
            // ADDITIONAL CALLS CAN SIMPLY USE THE PREVIOUS "myVar" STRING INSTEAD OF CALLING TPFunc AGAIN
            // ** IN THE FOLLOWING EXAMPLE, '0' POINTS to the previously created tween above.
            TweenMore(0, "$60", "myVar", 0, 100);




============================
 EASE AND DURATION SWAPPING
============================

	For play modes which continue (bounce, patrol, loop, repeat), different EASE TYPES can be applied
	to the forward and backward motion of the tween by passing them as an array.
	The first index is the forward motion, and the second index is the backwards motion.
	
            eases = [EaseInSine, EaseLinear]; // forward=sine, backward=linear
            TweenFire(self, eases, "patrol", true, 0, 1, "x", 0, 100);

	Likewise, different DURATIONS can be applied for the forward and backward motion of a tween.
	
            durations = [1.0, 2.0]; // forward=1.0, backward=2.0
            TweenFire(self, [EaseInSine, EaseLinear], "patrol", true, 0, durations, "x", 0, 100);

	And! Different REST periods can also be applied by passing an array to the DELAY parameter.
	The first index will hold the tween's initial delay. The second index will be the REST duration
	for when a tween continues from the start, and the third index is the rest duration for when the
	tween first continues.
	
	[(0)INITIAL DELAY] [(1)REST] |=======================| [(2)REST]
		
            delay_rests = [0, 1.0, 2.0]; // delay=0.0, start_rest=1.0, finish_rest=2.0
            TweenFire(self, [EaseInSine, EaseLinear], "patrol", true, delay_rests, [5.0,8.0], "x", 0, 100);
		
	NOTE: 
	If both directions use the same rest duration (or using TWEEN_MODE_BOUNCE), you only need to pass an array with 2 indexes.
		
            delay_rests = [0.0, 1.0]; // delay=0.0, rests=1.0
            TweenFire(self, [EaseInSine, EaseLinear], "patrol", true, delay_rests, [5.0,8.0], "x", 0, 100);




================
 LAZY TWEEN IDS
================

	Previously created tweens can be addressed with the value '0'.
	For example...
	
            // FIRE A TWEEN BUT DON'T STORE ITS RETURNED ID
            TweenFire(self, "io", 0, true, 0, 1, "x>", 100);
		
            // USE '0' TO REFERENCE THE PREVIOUSLY CREATED TWEEN ID
            TweenAddCallback(0, TWEEN_EV_FINISH, SomeScript);
		
	It is even possible to use negative numbers to reference tweens created further back.
	But please be careful if you choose to use negative tween ids! Just because you can doesn't mean you should.
	
            // FIRE ANOTHER TWEEN 
            TweenFire(self, "io", 0, true, 0, 1, "abc>", 100);
	   
            // USING -1 WILL REFERENCE THE TWEEN CREATED JUST BEFORE THE ONE ABOVE
            TweenAddCallback(-1, TWEEN_EV_PLAY, AnotherScript);





=======================
 NEGATIVE TWEEN DELAYS
=======================

	This is bit of a hack at the moment which might not work in certain situations but
	it does remain as a cool nifty thing if you know it's there!
	
	Using a negative delay value will cause the tween properties to jump to the initial
	values of the tween, however, the tween will still be delayed by the absolute value of the delay.
	I hope that makes sense... let me show you!
	
		TweenFire(self, "io", 0, false, -30, 60, "x", x+100, x+200);
		
	In the above example, the 'x' variable will immediately jump to the start value right away.
	However, the tween will still be delayed for 30 steps before playing.
	This is in contrast to regular delays which will not automatically jump values to the start
	until the delay has first finished.
	
	WARNING: This is still buggy for some use cases but should be fine for basic needs.
	



================
 STRUCT TARGETS
================

	WARNING: Using structs as an explicit tween target can cause it to "stick around" longer than intended, as the garbage collector might be delayed in cleaning it up.
		 Please manually destroy tweens with struct targets, using TweenDestroy(), if you need to make sure they are destroyed right away. 
		 This can be especially important when using tweens with callbacks, which could continue to be executed unexpectedly.

	Structs are directly supported as both properties AND targets.
	So, you can do the following...
	
            // CREATE A NEW STRUCT
            my_struct = {thing1:0, thing2:0};
		
            // FIRE TWEEN, REFERENCING STRUCT FOR PROPERTIES
            TweenFire(self, "io", 0, true, 0, 1, "my_struct.thing1", 0, 100, "my_struct.thing2", 0, 200);
		
	But, we can also use a struct as an explicit tween target and directly supply it's given variables...
	
            // CREATE A NEW STRUCT
            my_struct = {thing1:0, thing2:0};
		
            // FIRE TWEEN WITH STRUCT AS TARGET
            TweenFire(my_struct, "io", 0, true, 0, 1, "thing1>", 100, "thing2>", 200);
		
	But again, please be careful when using structs directly as targets.
	It is advised to manually destroy tweens with struct targets as 
	GameMaker's garabage collector may be slow in clearing deleted structs from the system.
	This can cause TweenGMX to needlessly process tweens longer than desired.
		
	Note: If a tween is created within a struct, the struct's "self" will be used as the default target for off-rail tweens
		
			


===================
 GROUP TIME SCALES
===================

	Time scales can now be set per group by using the function TweenGroupSetTimeScale()...
	
		// SET GROUP 10 TO USE A TIME SCALE OF 0.5
		TweenGroupSetTimeScale(10, 0.5);
	
	Please note that this is different from the example below...
	
		// SET THE TIME SCALE FOR EACH TWEEN WITHIN THE GROUP
		TweenSet({group: 10}, "time_scale", 0.5);
		
	The example above would change the time scale for EACH tween individually within the group
	and not affect the ACTUAL group scale as a whole.
	
	With this new addition, there are now 3 levels of time scales...
		
		GLOBAL
		GROUP
		PER-TWEEN
	
	GLOBAL, GROUP, and PER-TWEEN time scales can all be stacked together for combined effects...
		
		// SET SYSTEM SCALE TO x10.0
		TweenSystemSet("time_scale", 10.0);
		
		// SET GROUP 2 SCALE TO x0.5
		TweenGroupSetTimeScale(2, 0.5);
		
		// SET SPECIFIC TWEEN SCALE TO x.0.25
		TweenSet(myTween, "time_scale", 0.25);
		
	The final output scale for 'myTween' above would be 1.25

			


======================
 CALCULATED DURATIONS
======================

	This feature allows you to set the duration as an average rate of change.
	STEP and DELTA timing are both handled a bit differently:
	
		STEP:  rate of change per step (on average)
		DELTA: rate of change per second (on average)
	
	This feature is enabled by passing a STRUCT as a tween's duration parameter.
	The struct can take various fields to determine how to calculate the total change for propreties.
	The calculated change is then divided by the amount passed to the given field to determine the final duration.
		
		1) dist:	calculates all property changes as a distance between points
		2) avg: 	averages out all property changes
		3) sum:		sums all property changes
		4) weight:	uses each property change as a percentage of the total sum
		5) min: 	uses only the property with the smallest change
		6) max: 	uses only the property with the greatest change
			
	NOTE: When there is only one property tweened, all options will work exactly the same.
			
		Examples:
		
		    // USE 'dist:' TO SET DURATION
		    TweenFire(self, "io", 0, true, 0, {dist:50}, "x", 0, 100, "y", 0, 100); // 2.83 Seconds
			
		    // USE 'avg:' TO SET DURATION
		    TweenFire(self, "io", 0, true, 0, {avg:50}, "x", 0, 100, "y", 0, 100); // 2 Seconds
			
		    // USE 'sum:' TO SET DURATION
		    TweenFire(self, "io", 0, true, 0, {sum:50}, "x", 0, 100, "y", 0, 100); // 4 Seconds
			
		    // USE 'weight:' TO SET DURATION
		    TweenFire(self, "io", 0, true, 0, {avg:50}, "x", 0, 100, "y", 0, 100); // 2 Seconds
			
		    // USE 'min:' TO SET DURATION
		    TweenFire(self, "io", 0, true, 0, {min:50}, "x", 0, 50, "y", 0, 100); // 1 Second

		    // USE 'max:' TO SET DURATION
		    TweenFire(self, "io", 0, true, 0, {max:50}, "x", 0, 50, "y", 0, 100); // 2 Seconds
	
	TIP: A shorthand version for 'dist:' can be used by simply passing duration as an array.
	
            // USE 'dist:' TO SET DURATION BY PASSING ARRAY (e.g. [50])
            TweenFire(self, "io", 0, true, 0, [50], "x", 0, 100, "y", 0, 100);
	
	The optional field 'use:' can also be set to limit the amount of properties to include in the calculation.
			
            // USE ONLY THE FIRST 2 PROPERTIES (x,y) FOR DURATION CALCULATION
            TweenFire(self, "io", 0, true, 0, {dist:50, use:2}, "x>", 100, "y>", 100, "image_angle", 0, 360);

	Calculated Durations can be useful for delayed tweens where you don't know the final start and/or destination values.

            // FIRE TWEEN WITH DELAY USING CALCULATED DURATION
            TwenFire("~io", "-delay", 100, "-duration", {dist:10}, "x>", mouse_x);
	
	** Please note that calculated durations are not currently supported for ease/duration swapping **
	
            // THIS CURRENTLY WON'T WORK
            TweenFire("-duration", [{avg:10},{avg:20}], "#patrol", "x", 0, 100);