#### FIRE TWEENS

- TweenFire
- TweenFireTo
- TweenFireFrom

#### PREDEFINED TWEENS

- TweenCreate
- TweenPlay
- TweenPlayDelay

#### "EASY" TWEENS

- TweenEasyMove
- TweenEasyRotate
- TweenEasyScale
- TweenEasyTurn
- TweenEasyFade
- TweenEasyBlend
- TweenEasyImage
- TweenEasySpeed
- TweenEasySpeedHV
- TweenEasyUseDelta

#### TWEENS SELECTION

- Tweens
- TweensAll
- TweensGroup
- TweensTarget
- TweensIncludeDeactivated

#### STATE CONTROL

- TweenPause
- TweenResume
- TweenStop
- TweenReverse
- TweenFinish
- TweenFinishDelay

#### STATE CHECKS

- TweenExists
- TweenIsActive
- TweenIsPlaying
- TweenIsPaused
- TweenIsStopped

#### GET / SET

- TweenGet
- TweenSet

#### DESTRUCTION

- TweenDestroy
- TweenDestroySafe
- TweenDestroyWhenDone

#### SPECIAL HANDLES

- TweenNull
- TweenDefault

- #### TOOLS

- Ease
- TweenStep
- TweenPath
- TweenCalc
- TweenCalcTime
- TweenCalcAmount

#### ADVANCED PROPERTIES

- TPNull
- TPExt
- TPUser
- TPArray
- TPList
- TPMap
- TPGrid

#### EVENT CALLBACKS

- TweenAddCallback
- TweenAddCallbackUser
- TweenCallbackNull
- TweenCallbackInvalidate
- TweenCallbackIsValid
- TweenCallbackEnable
- TweenCallbackIsEnabled

#### EVENT MANAGEMENT

- TweenEventClear
- TweenEventEnable
- TweenEventIsEnabled

#### SYSTEM UTILITIES

- TweenSystemGet
- TweenSystemSet
- TweenSystemCount
- TweenSystemClearRoom
- TweenSystemFlushDestroyed
- SharedTweenerActivate
- SharedTweenerDestroy

#### PROPERTY BUILDERS

- TGMS_BuildProperty
- TGMS_BuildPropertyNormalize

# TweenGMS Pro v0.9.84
Script Reference

## === FIRE TWEENS ===

The TweenFire*() scripts are the default tweening scripts. Tweens created with TweenFire*() scripts are automatically destroyed when they are finished or if their target instance is destroyed. It is possible to ease up to 10 properties with a single tween. A tween ID handle is returned from these scripts for manipulating a tween's state.

TweenFire Creates and plays a tween which eases a property(variable) between two values over a set duration of time. Tween is automatically destroyed when finished, stopped, or if its associated target instance is destroyed. Returns unique tween id. TweenFire(target,ease,mode,delta,delay,dur,prop,start,dest,...)

target | Instance to associate with tween and its property
ease | Ease algorithm script (e.g. EaseInOutQuad)
mode | Play mode constant (0-4) (TWEEN_MODE_****)
delta | Whether to set timing in seconds(true) or steps (false)
delay | Amount of time to delay start of tween in seconds or steps
dur | Duration of time to ease property from start to destination
prop | Property string (e.g. "x")
start | Starting value of eased property
dest | Destination value of eased property
... | Additional properties (in order: prop,start,dest)

Returns: tween id Example
    // Tween x position to mouse_x over 30 steps
    Tween(id, EaseOutQuad, TWEEN_MODE_ONCE, false, 0, 30, "x", x, mouse_x);

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

TweenFireTo Creates and plays a tween which eases a property(variable) to a specified value over a set duration of time. Tween is automatically destroyed when finished, stopped, or if its associated target instance is destroyed. Returns unique tween id. TweenFireTo(target,ease,mode,delta,delay,dur,prop,to,...)

target | Instance to associate with tween and its property
ease | Ease algorithm script (e.g. EaseInOutQuad)
mode | Play mode constant (0-4) (TWEEN_MODE_****)
delta | Whether to set timing in seconds(true) or steps (false)
delay | Amount of time to delay start of tween in seconds or steps
dur | Duration of time to ease property from start to destination
prop | Property setter script (e.g. x__)
to | Destination value of eased property
... | Additional properties (in order: prop,to)

Returns: tween id Example
    // Tween x position to mouse_x over 30 steps
    TweenTo(id, EaseOutQuad, TWEEN_MODE_ONCE, false, 0, 30, "x", mouse_x);

    // Double instances image scale over 1.0 second
    TweenTo(id, EaseInOutQuad, TWEEN_MODE_PATROL, true, 0.0, 1.0, "image_scale", 2.0);

TweenFireFrom Creates and plays a tween which eases a property(variable) from a specified value over a set duration of time. Tween is automatically destroyed when finished, stopped, or if its associated target instance is destroyed. Returns unique tween id. TweenFireFrom(target,ease,mode,delta,delay,dur,prop,from,...)

target | Instance to associate with tween and its property
ease | Ease algorithm script (e.g. EaseInOutQuad)
mode | Play mode constant (0-4) (TWEEN_MODE_****)
delta | Whether to set timing in seconds(true) or steps (false)
delay | Amount of time to delay start of tween in seconds or steps
dur | Duration of time to ease property from start to destination
prop | Property setter script (e.g. x__)
from | Starting value of eased property
... | Additional properties (in order: prop,from)

Returns: tween id Example
    // Tween x position from mouse_x over 30 steps
    TweenFrom(id, EaseOutQuad, TWEEN_MODE_ONCE, false, 0, 30, "x", mouse_x);

    // Tween image scale from 2 to default value over 1.0 second
    TweenFrom(id, EaseInOutQuad, TWEEN_MODE_PATROL, true, 0.0, 1.0, "image_scale", 2.0);

## === PREDEFINED TWEENS ===

TweenCreate() can be used to create predefined (or undefined) tweens which can be started later with TweenPlay(). Tweens created with this method will continue to exist until the target instance is destroyed or until TweenDestroy() is called. You can also use TweenDestroyWhenDone() to have the tween auto-destroy when finished. It is possible to override a tween's predefined values with TweenPlay(). A tween ID handle is returned from these scripts for manipulating a tween's state.

TweenCreate Creates and returns a tween id to be played at a later time with TweenPlay(). Eases a property(variable) between two values over a set duration of time. The tween will continue to exist and be valid until its associated target instance is destroyed, or until TweenDestroy() is called. TweenCreate(target[,ease,mode,delta,delay,dur,prop,start,dest,...])

target | Instance to associate with tween and its property
ease | Ease algorithm script (e.g. EaseInOutQuad)
mode | Play mode constant (0-4) (TWEEN_MODE_****)
delta | Whether to set timing in seconds(true) or steps (false)
delay | Amount of time to delay start of tween in seconds or steps
dur | Duration of time to ease property from start to destination
prop | Property string (e.g. "x")
start | Starting value of eased property
dest | Destination value of eased property
... | Additional properties (in order: prop,start,dest)

Returns: tween id Example
    // Tween x position to mouse_x over 30 steps
    tween = TweenCreate(id, EaseOutQuad, TWEEN_MODE_ONCE, false, 0, 30, "x", x, mouse_x);
    TweenPlay(tween);

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

TweenPlay Starts playing tween[s] previously created with TweenCreate(). Can optionally override a predefined tween. This function supports the "Tween Selection" scripts for starting multiple tweens at once. TweenPlay(tween[s][,ease,mode,delta,delay,dur,prop,start,dest,...])

tweenID | Previously created tween[s] id
ease | Ease algorithm script (e.g. EaseInOutQuad)
mode | Play mode constant (0-4) (TWEEN_MODE_****)
delta | Whether to set timing in seconds(true) or steps (false)
delay | Amount of time to delay start of tween in seconds or steps
dur | Duration of time to ease property from start to destination
prop | Property string (e.g. "x")
start | Starting value of eased property
dest | Destination value of eased property
... | Additional properties (in order: prop,start,dest)

Returns: na Example
    // Tween x position to mouse_x over 30 steps
    tweenX = TweenCreate(id, EaseOutQuad, TWEEN_MODE_ONCE, false, 0, 30, "x", x, mouse_x);
    TweenPlay(tweenX);

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

    // This would optionally start both tweens at the same time by using the "Tween Selection" scripts// But note that all tweens should be previously defined.
    TweenPlay(Tweens(tweenX, tweenY));

TweenPlayDelay Starts playing defined tween[s] previously created with TweenCreate() after a set duration of time. This function supports the "Tween Selection" scripts for starting multiple tweens at once. TweenPlayDelay(tween[s],delay)

tween[s] | Previously created tween[s] id
delay | Amount of time to delay start of tween[s] in seconds or steps

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

## === EASY TWEENS ===

"Easy" Tweens are convenient for new users. They cover the most basic needs for easing instance values, such as position, rotation, and scaling. They are automatically destroyed when finished and automatically override any existing tweens using the same property/variable. A tween ID handle is returned from these scripts for later manipulating a tween's state. The default timing method(steps) for easy tweens can be switched to seconds by using TweenEasyUseDelta(true).

TweenEasyMove Eases the position of an instance. Can optionally supply a [mode] argument. Default mode is TWEEN_MODE_ONCE. TweenEasyMove(x1,y1,x2,y2,delay,duration,ease,[mode])

x1 | Starting x value
y1 | Starting y value
x2 | Destination x value
y2 | Destination y value
delay | Amount of time to delay start of tween in seconds or steps
dur | Duration of time to ease property from start to destination
ease | Ease algorithm script (e.g. EaseInOutQuad)
[mode] | (Optional) Play mode constant (0-4) (TWEEN_MODE_****) default = TWEEN_MODE_ONCE

Returns: tween id Example
    // Tween x position to mouse_x over 30 steps after a 60 step delay
    TweenEasyMove(x, y, mouse_x, mouse_y, 60, 30, EaseInOutQuad);

TweenEasyRotate Eases the image angle of an instance. Can optionally supply a [mode] argument. Default mode is TWEEN_MODE_ONCE. TweenEasyRotate(angle1,angle2,delay,duration,ease,[mode])

angle1 | Starting image angle value
angle2 | Destination image angle value
delay | Amount of time to delay start of tween in seconds or steps
dur | Duration of time to ease property from start to destination
ease | Ease algorithm script (e.g. EaseInOutQuad)
[mode] | (Optional) Play mode constant (0-4) (TWEEN_MODE_****) default = TWEEN_MODE_ONCE

Returns: tween id Example
    // Tween image angle from 0 to 360 over 30 steps
    TweenEasyRotate(0, 360, 0, 30, EaseInOutQuad);

TweenEasyScale Eases the image x/y scale of an instance. Can optionally supply a [mode] argument. Default mode is TWEEN_MODE_ONCE. TweenEasyScale(xscale1,yscale1,xscale2,yscale2,delay,duration,ease,[mode])

x1 | Starting xscale value
y1 | Starting yscale value
x2 | Destination xscale value
y2 | Destination yscale value
delay | Amount of time to delay start of tween in seconds or steps
dur | Duration of time to ease property from start to destination
ease | Ease algorithm script (e.g. EaseInOutQuad)
[mode] | (Optional) Play mode constant (0-4) (TWEEN_MODE_****) default = TWEEN_MODE_ONCE

Returns: tween id Example
    // Tween image x/y scale from 1.0 to 2.0 over 30 steps
    TweenEasyRotate(1.0, 1.0, 2.0, 2.0, 0, 30, EaseInOutQuad);

TweenEasyTurn Eases the direction of an instance. Can optionally supply a [mode] argument. Default mode is TWEEN_MODE_ONCE. TweenEasyTurn(dir1,dir2,delay,duration,ease,[mode])

dir1 | Starting direction value
dir2 | Destination direction value
delay | Amount of time to delay start of tween in seconds or steps
dur | Duration of time to ease property from start to destination
ease | Ease algorithm script (e.g. EaseInOutQuad)
[mode] | (Optional) Play mode constant (0-4) (TWEEN_MODE_****) default = TWEEN_MODE_ONCE

Returns: tween id Example
    // Tween instance's direction from 0 to 360 over 30 steps
    TweenEasyTurn(0, 360, 0, 30, EaseInOutQuad);

TweenEasyFade Eases the image alpha of an instance. Can optionally supply a [mode] argument. Default mode is TWEEN_MODE_ONCE. TweenEasyFade(alpha1,alpha2,delay,duration,ease,[mode])

alpha1 | Starting alpha value
alpha2 | Destination alpha value
delay | Amount of time to delay start of tween in seconds or steps
dur | Duration of time to ease property from start to destination
ease | Ease algorithm script (e.g. EaseInOutQuad)
[mode] | (Optional) Play mode constant (0-4) (TWEEN_MODE_****) default = TWEEN_MODE_ONCE

Returns: tween id Example
    // Tween instance's image alpha from 0.0 to 1.0 over 30 steps
    TweenEasyTurn(0.0, 1.0, 0, 30, EaseInOutQuad);

TweenEasyBlend Eases the image blend colour of an instance. Can optionally supply a [mode] argument. Default mode is TWEEN_MODE_ONCE. TweenEasyBlend(col1,col2,delay,duration,ease,[mode])

col1 | Starting image blend colour
col2 | Destination image blend colour
delay | Amount of time to delay start of tween in seconds or steps
dur | Duration of time to ease property from start to destination
ease | Ease algorithm script (e.g. EaseInOutQuad)
[mode] | (Optional) Play mode constant (0-4) (TWEEN_MODE_****) default = TWEEN_MODE_ONCE

Returns: tween id Example
    // Tween instance's image blend colour from white to red over 30 steps
    TweenEasyTurn(c_white, c_red, 0, 30, EaseInOutQuad);

TweenEasyImage Eases the image index of an instance. Can optionally supply a [mode] argument. Default mode is TWEEN_MODE_ONCE. TweenEasyImage(index1,index2,delay,duration,ease,[mode])

index1 | Starting image index value
index2 | Destination image index value
delay | Amount of time to delay start of tween in seconds or steps
dur | Duration of time to ease property from start to destination
ease | Ease algorithm script (e.g. EaseInOutQuad)
[mode] | (Optional) Play mode constant (0-4) (TWEEN_MODE_****) default = TWEEN_MODE_ONCE

Returns: tween id Example
    // Tween instance's image index from first to last frame over 30 steps
    TweenEasyTurn(0, image_number-1, 0, 30, EaseInOutQuad);

TweenEasySpeed Eases the image index of an instance. Can optionally supply a [mode] argument. Default mode is TWEEN_MODE_ONCE. TweenEasySpeed(speed1,speed2,delay,duration,ease,[mode])

speed1 | Starting image index value
speed2 | Destination image index value
delay | Amount of time to delay start of tween in seconds or steps
dur | Duration of time to ease property from start to destination
ease | Ease algorithm script (e.g. EaseInOutQuad)
[mode] | (Optional) Play mode constant (0-4) (TWEEN_MODE_****) default = TWEEN_MODE_ONCE

Returns: tween id Example
    // Tween instance's speed from 0 to 10 over 30 steps
    TweenEasyTurn(0, 10, 0, 30, EaseInOutQuad);

TweenEasySpeedHV Eases the image index of an instance. Can optionally supply a [mode] argument. Default mode is TWEEN_MODE_ONCE. TweenEasySpeedHV(hspeed1,vspeed1,hspeed2,vspeed2,delay,duration,ease,[mode])

hspeed1 | Starting hspeed value
vspeed1 | Starting vspeed value
hspeed2 | Destination hspeed value
vspeed2 | Destination vspeed value
delay | Amount of time to delay start of tween in seconds or steps
dur | Duration of time to ease property from start to destination
ease | Ease algorithm script (e.g. EaseInOutQuad)
[mode] | (Optional) Play mode constant (0-4) (TWEEN_MODE_****) default = TWEEN_MODE_ONCE

Returns: tween id Example
    // Tween instance's hspeed/vspeed from 0 to 10 over 30 steps
    TweenEasyTurn(0, 0, 10, 10, 0, 30, EaseInOutQuad);

TweenEasyUseDelta Toggles between step(false) and delta(true) timing for all "Easy Tweens". The default timing is step timing (false). TweenEasyUseDelta(use_seconds?)

use_seconds? | Use seconds?

Returns: na Example
    // Tween instance's position over 30 steps
    TweenEasyMove(x, y, mouse_x, mouse_y, 0, 30, EaseInOutQuad);

    // 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);

## === TWEEN[S] SELECETION ===

The Tweens*() selection scripts allow you to select multiple tweens for scripts supporting the "tween[s]" multi-tween parameter.

Tweens Selects and returns the indicated tween id[s]. Supported by all tween scripts which have the multi-tween parameter "tween[s]" Tweens()

Returns: tween id[s] Example
    // Pause all indicated tweens
    TweenPause(Tweens(someTween, anotherTween, derpTween));

TweensAll Selects and returns all tween id[s]. Supported by all tween scripts which have the multi-tween parameter "tween[s]" The built-in keyword "all" can be used instead. TweensAll()

Returns: tween id[s] Example
    // Pause all tweens
    TweenPause(TweensAll());

    // Resume all tweens with alternate "all" keyword
    TweenResume(all);

TweensGroup Selects and returns all tween id[s] associated with a group id. Supported by all tween scripts which have the multi-tween parameter "tween[s]" TweensGroup(group)

group | Tween group id

Returns: tween id[s] Example
    // Pause all tweens associated with group 2
    TweenPause(TweensGroup(2));

TweensTarget Selects and returns all tween id[s] associated with a target instance. Supported by all tween scripts which have the multi-tween parameter "tween[s]" TweensTarget(target)

target | Target instance id or object index

Returns: tween id[s] Example
    // Pause all tweens associated with a target instance id
    TweenPause(id);

    // Resume all tweens associated with a target's object index
    TweenResume(obj_Player);

TweensIncludeDeactivated Whether or not "Tweens*()" scripts should return tween[s] associated with deactivated targets. Default = false TweensIncludeDeactivated(target)

include_deactivated? | Include tweens belonging to deactivated targets/instances?

Returns: na Example
    // Set Tweens*() scripts to include deactivated targets
    TweensIncludeDeactivated(true);

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

## === STATE CONTROL ===

The following scripts can change the play state of a tween, such as pausing and resuming.

TweenPause Pauses the indicated tween TweenPause(tween)

tween[s] | Tween id[s]

Returns: na Example
    // Fire tween
    tween = TweenFire(id, EaseLinear, 0, true, 0, 1, "x", x, mouse_x);

    // Pause the tween
    TweenPause(tween);

TweenResume Resumes the indicated tween TweenResume(tween)

tween[s] | Tween id[s]

Returns: na Example
    // Fire tween
    tween = TweenFire(id, EaseLinear, 0, true, 0, 1, "x", x, mouse_x);

    // Pause the tween
    TweenPause(tween);

    // Resume the tween
    TweenResume(tween);

TweenStop Stops the indicated tween TweenStop(tween)

tween[s] | Tween id[s]

Returns: na Example
    // Fire tween
    tween = TweenFire(id, EaseLinear, 0, true, 0, 1, "x", x, mouse_x);

    // Stop the tween
    TweenStop(tween);

TweenReverse Reverses the indicated tween TweenReverse(tween)

tween[s] | Tween id[s]

Returns: na Example
    // Fire tween
    tween = TweenFire(id, EaseLinear, TWEEN_MODE_PATROL, true, 0, 1, "x", x, mouse_x);

    // Reverse the tween
    TweenReverse(tween);

TweenFinish Immediately finishes the indicated tween. It also asks if you want to call any "finish" event callbacks. TweenFinish(tween)

tween[s] | Tween id[s]

Returns: na Example
    // Fire tween
    tween = TweenFire(id, EaseLinear, 0, true, 0, 1, "x", x, mouse_x);

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

TweenFinishDelay Immediately finishes a tween's delay and starts playing the tween. It also asks if you want to call any associated "delay finish" event callbacks. TweenFinishDelay(tween)

tween[s] | Tween id[s]

Returns: na Example
    // Fire tween with a 3.0 second delay
    tween = TweenFire(id, EaseLinear, 0, true, 3.0, 1, "x", x, mouse_x);

    // Finish the tweens delay and start playing... call delay's "finish" event
    TweenFinishDelay(tween, true);

## === STATE CHECKS ===

The following scripts allow you to check the current state of a tween, such as whether it exists or is currently playing.

TweenExists Returns true if the indicated tween exists. TweenExists(tween)

tween | Tween id

Returns: bool Example
    // Fire tween from x/y to mouse_x/mouse_y
    tween = TweenFire(id, EaseLinear, 0, true, 0, 1, "x", x, mouse_x, "y", y, mouse_y);

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

TweenIsActive Returns true if the tween is playing or actively processing a delay. This is similar to TweenIsPlaying(), except that it also returns true if the tween is delayed. TweenIsActive(tween)

tween | Tween id

Returns: bool Example
    // Fire tween with a 3.0 second delay
    tween = TweenFire(id, EaseLinear, 0, true, 3.0, 1.0, "x", x, mouse_x);

    // Pause the tween if it is playing or delayed
    if (TweenIsActive(tween))
    {
        TweenPause(tween);
    }

TweenIsPlaying Returns true if the tween is playing. This is similar to TweenIsActive(), except that it will return false if the tween is delayed. TweenIsPlaying(tween)

tween | Tween id

Returns: bool Example
    // Fire tween with a 3.0 second delay
    tween = TweenFire(id, EaseLinear, 0, true, 3.0, 1.0, "x", x, mouse_x);

    // Pause the tween if it is playing
    if (TweenIsPlaying(tween))
    {
        TweenPause(tween);
    }

TweenIsPaused Returns true if the tween is paused. TweenIsPaused(tween)

tween | Tween id

Returns: bool Example
    // Fire tween
    tween = TweenFire(id, EaseLinear, 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);
    }

TweenIsStopped Returns true if the tween is stopped. TweenIsStopped(tween)

tween | Tween id

Returns: bool Example
    // Fire tween
    tween = TweenFire(id, EaseLinear, 0, true, 0.0, 1.0, "x", x, mouse_x);

    // Pause tween
    TweenStop(tween);

    // Show message if tween is stopped
    if (TweenIsStopped(tween))
    {
        show_message("Tween Stopped!");
    }

## === GET / SET ===

These scripts let you access or update various tween data properties, such as a tween's duration or starting value.

TweenGet Accesses specific data for a given tween by using a specified data label. If a tween has multiple properties, "start", "destination", and "property" will return an array of values.
    	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 effected by the tween
TweenGet(tween, dataLabel)

tween | Valid tween id
dataLabel | Specified data label

Returns: real/string Example
    // Fire a tween
    tween = TweenFire(id, 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");

TweenSet Changes the specific data for a given tween by using a specified data label. For tweens with multiple properties, "start", "destination", and "property" can be supplied additional arguments. Use keyword [undefined] to leave a value unchanged.
        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 effected by the tween

            e.g.
                tween = TweenFire(id, 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:

            "start"
            "destination"
            "property"

            e.g.
                tween = Tween(id, EaseLinear, 0, true, 0, 1, "x", 0, 100, "y", 0, 100); // multi-property tween (x/y)
                TweenSet(tween, "start", mouse_x, mouse_y); // update to x/y mouse coordinates

        // 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(tween[s], dataLabel, value, ...)

tween[s] | Valid tween id[s]
dataLabel | Specified data label
value | New data value
... | (optional) additional values for modifying multi-property tweens

Returns: na Example
    // Fire a new tween
    tween = TweenFire(id, EaseLinear, 0, true, 0, 1, "x", 0, 100);

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

## === DESTRUCTION ===

Tweens are automatically memory managed. Tweens created with TweenFire*() will automatically be destroyed when they finish or when their target instance is destroyed. Tweens created with TweenCreate() will auto-destroy only if their target instance is destroyed; they will not auto-destruct when the tween finishes but will continue to be valid. However, it is possible to manually destroy a tween if desired using TweenDestroy() or TweenDestroySafe(). It is also possible to force a tween to auto-destroy when finished with TweenDestroyWhenDone().

TweenDestroy Manually destroys tween[s]. TweenDestroy(tween[s])

tween[s] | Valid tween id[s]

Returns: na Example
    // Create an undefined tween
    tween = TweenCreate(id);

    // Manually destroy the tween
    TweenDestroy(tween);

TweenDestroySafe Manually destroys tween[s]. However, unlike TweenDestroy(), no error will be reported if the tween isn't valid. TweenDestroySafe(tween[s])

tween[s] | Valid tween id[s]

Returns: na Example
    // Manually destroy the tween without checking if it is valid. No error will occur. BE CAREFUL!
    TweenDestroySafe(tween);

TweenDestroyWhenDone Sets whether or not a tween should auto-destroy when it is finished playing. Default = true for TweenFire(). Default = false for TweenCreate(). TweenDestroyWhenDone(tween[s], destroy, kill_target)

tween[s] | Valid tween id[s]
destroy? | Destroy tween when finished?
kill_target? | Destroy the associated target instance when finished?

Returns: na Example
    // Create an undefined tween
    tween = TweenCreate(id);

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

## === SPECIAL HANDLES ===

The special tween handles are valid tween id's used for specific cases, such as setting a variable to a null tween with TweenNull(), or to change the default behaviour of newly created tweens with TweenDefault().

TweenNull Returns a null tween reference which can be safely called by tween scripts without causing an error. Checking if a null tween exists will return false. TweenNull()

Returns: null tween id Example
    // Set "tween" variable to a null tween id
    tween = TweenNull();

    // No error will be occur if tween is null
    TweenPause(tween);

    // Check if the tween exists
    if (TweenExists(tween))
    {
    	// ... this won't execute if tween is null
    }

TweenDefault Returns a null tween reference which can be safely called by tween scripts without causing an error. Checking if a null tween exists will return false. TweenDefault()

Returns: null tween id Example
    // Set the default group for new tweens to 2
    TweenSet(TweenDefault(), "group", 2);

    // New tween will belong to group 2
    TweenFire(id, EaseLinear, 0, true, 0.0, 1.0, "x", x, mouse_x);

## === TOOLS ===

Various additional scripts for your convenience!

Ease Works simliar to GameMaker's lerp() function, except that it takes an extra parameter for the ease type. Ease(value1,value2,amount,ease)

value1 | start value
value2 | end value
amount | amount to interpolate value (0-1)
ease | ease algorithm script

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

TweenStep
    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.
TweenStep(tween[s], amount)

tween[s] | Valid tween id[s]
amount | Amount to step tween[s]

Returns: real Example
    // Step a tween forward at half speed
    TweenStep(tween1, 0.5);

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

TweenPath
    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.
TweenPath(target,ease,mode,delta,delay,dur,path,absolute)

target | Target instance
ease | Ease script
mode | Tween play mode constant
delta | Use seconds?
delay | Time to delay start of tween
dur | Duration of time to play tween
path | Path id
absolute | Absolute path position?

Returns: tween id Example
    // Fire a tween using a GameMaker path
    TweenPath(id, EaseLinear, TWEEN_MODE_ONCE, true, 0.0, 1.0, path1, true);

TweenCalc Returns a calculated value using a tween's current state. TweenCalc(tween)

tween | Tween ID

Returns: real Example
    // Get value of a tween using it's current state
    value = TweenCalc(tween);

TweenCalcTime Returns a calculated value using a tween's current state at a specified point in time. Note: Useful with null property setters which can be set by using TPNull() as the property argument. TweenCalcTime(tween)

tween | Tween ID

Returns: real Example
    // Create defined tween with a duration of 3.0 seconds
    tween = TweenCreate(id, EaseInOutQuint, 0, true, 0.0, 3.0, TPNull(), x, mouse_x);

    // Calculate value of tween at 1.5 seconds
    x = TweenCalcTime(tween, 1.5);

TweenCalcAmount Returns a calculated value using a tween's current state at a relevant point in time. Note: Useful with null property setters which can be set by using TPNull() as the property argument. TweenCalcAmount(tween)

tween | Tween ID

Returns: real Example
    // Create defined tween with a duration of 3.0 seconds
    tween = TweenCreate(id, EaseInOutQuint, 0, true, 0.0, 3.0, TPNull(), x, mouse_x);

    // Calculate value of tween at 25% through time
    x = TweenCalcAmount(tween, 0.25);

## === ADVANCED PROPERTIES ===

Advanced tween property (TP*) scripts can be used in place of a property for more advanced uses. They include the ability to ease values belonging to various data structures. They can also be used to pass extended data to an advanced property script, or to use User Events for advanced properties.

TPNull Returns a null property which eases no value directly. This is useful if you want to manually calculate the tweened value with the TweenCalc() script. TPNull(tween)

Returns: null property Example
    // Tween a null property from 0 to 100
    tween = TweenFire(id, EaseLinear, 0, true, 0.0, 1.0, TPNull(), 0, 100);

    // Manually calculate and store the tween's current value
    myValue = TweenCalc(tween);

TPExt Prepares an extended property script with custom arguments to be passed to it. TPExt(property,[arg0,...])

property | Property script id
arg0... | Values to be passed to advanced property script

Returns: extended property Example
    // Create a defined tween with an extended property
    tween = TweenCreate(id, EaseInQuad, 0, true, 0.0, 3.0, TPExt(extColourBlend, c_red, c_blue), 0, 1);

    /// extColourBlend Script
    var _value = argument0;
    var _data = argument1;
    var _target = argument2;
    _target.image_blend = merge_colour(_data[0], _data[1], _value);

TPUser Prepares an extended property with custom arguments to be passed to a user event for calculation. TPUser(user_event,[arg0,...])

user_event | An object's user event
arg0... | (optional) Values to be passed to advanced property script
\

Returns: extended property Example
    // Create a defined tween with an extended property
    tween = TweenCreate(id, EaseInQuad, 0, true, 0.0, 3.0, TPUser(0, c_red, c_blue), 0, 1);

    /// User Event 0
    var _value = TWEEN_USER_VALUE;
    var _data = TWEEN_USER_DATA;
    var _target = TWEEN_USER_TARGET;
    _target.image_blend = merge_colour(_data[0], _data[1], _value);

TPArray Passes an array and its indexed value to be tweened. It supports both 1d and 2d arrays depending on the number of arguments supplied. TPArray(array,x,[y])

array | Valid array
x | The x index for array
[y] | (optional) The y index for a 2d array

Returns: array property Example
    // Create a 1d array and pass it as the tween property with TPArray().
    myArray[0] = 0;
    tween = TweenFire(id, EaseInQuad, 0, true, 0.0, 3.0, TPArray(myArray, 0), 0, 100);

    // Get value from tweened array index
    value = myArray[0];

TPList Passes a list and its indexed value to be tweened. TPList(list,index)

list | Valid ds_list id
index | The index of the list to tween

Returns: list property Example
    // Create a list and pass it as the tween property with TPList().
    myList = ds_list_create();
    myList[| 0] = 0;
    tween = TweenFire(id, EaseInQuad, 0, true, 0.0, 3.0, TPList(myList, 0), 0, 100);

    // Get value from tweened array index
    value = myList[| 0];

TPMap Passes a map and its key value to be tweened. TPMap(map,key)

map | Valid map id
key | The key of the map to tween

Returns: map property Example
    // Create a map and pass it as the tween property with TPMap().
    myMap = ds_map_create();
    myMap[? "key"] = 0;
    tween = TweenFire(id, EaseInQuad, 0, true, 0.0, 3.0, TPMap(myList, "key"), 0, 100);

    // Get value from tweened map key
    value = myMap[? "key"];

TPGrid Passes a grid and its indexed value to be tweened. TPGrid(grid,x,y)

grid | Valid grid id
x | The x index for grid
y | The y index for grid

Returns: grid property Example
    // Create a grid and pass it as the tween property with TPGrid().
    myGrid = ds_grid_create(10,10);
    tween = TweenFire(id, EaseInQuad, 0, true, 0.0, 3.0, TPGrid(myGrid, 2, 4), 0, 100);

    // Get value from tweened grid index
    value = myGrid(# 2, 4);

## === EVENT CALLBACKS ===

    Event callbacks allow you to execute scripts or user events when a specified tween event occurs.
    The following tween events 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

TweenAddCallback Adds a script to be called for the specified event. TweenAddCallback(tween,event,target,script,[arg0...])

tween | Tween id
event | Tween event macro (e.g. TWEEN_EV_FINISH)
target | Target instance id
script | Script resource id (e.g. MyScript)
[arg0...] | (optional) Arguments to pass to script

Returns: callback id Example
    // Fire a tween
    tween = TweenFire(id, EaseInQuad, 0, true, 0.0, 1.0, "x", x, mouse_x);

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

TweenAddCallbackUser Adds a user event to be called for the specified event. TweenAddCallbackUser(tween,event,target,user_event)

tween | Tween id
event | Tween event macro (e.g. TWEEN_EV_FINISH)
target | Target instance id
user_event | Object user event (e.g. 0-15)

Returns: callback id Example
    // Fire a tween
    tween = TweenFire(id, 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, id, 5);

TweenCallbackNull Returns a null callback id. TweenCallbackNull()

Returns: null callback id Example
    // Set a null callback
    cb = TweenCallbackNull();

    // No error will occur when calling null callback
    TweenCallbackInvalidate(cb);

TweenCallbackInvalidate Invalidates (destroys) the given callback id. TweenCallbackInvalidate(callback)

callback | Callback id

Returns: na Example
    // Add callback to a tween
    cb = TweenAddCallback(tween, TWEEN_EV_FINISH, id, ShowMessage, "Hi!");

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

TweenCallbackIsValid Checks if a callback id is valid. TweenCallbackIsValid(callback)

callback | Callback id

Returns: bool Example
    // Add callback to a tween
    cb = TweenAddCallback(tween, TWEEN_EV_FINISH, id, ShowMessage, "Hi!");

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

TweenCallbackEnable Allows callbacks to be temporarily disabled/enabled. TweenCallbackEnable(callback,enable)

callback | Callback id
enable | Enable the callback?

Returns: na Example
    // Add callback to a tween
    cb = TweenAddCallback(tween, TWEEN_EV_FINISH, id, ShowMessage, "Hi!");

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

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

TweenCallbackIsEnabled Checks if callback is enabled. TweenCallbackIsEnabled(callback)

callback | Callback id

Returns: bool Example
    // Add callback to a tween
    cb = TweenAddCallback(tween, TWEEN_EV_FINISH, id, 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 ===

Allows you to manage whole tween events related to event callbacks.

TweenEventClear Invalidates all callbacks associated with specified tween event. TweenEventClear(tween[s], event)

tween[s] | Tween id[s]
event | Tween event macro (e.g. TWEEN_EV_FINISH)

Returns: na Example
    // Fire a tween
    tween = TweenFire(id, 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);

TweenEventEnable Enables/disables specified tween event. TweenEventEnable(tween[s], event)

tween[s] | Tween id[s]
event | Tween event macro (e.g. TWEEN_EV_FINISH)
enable? | Enable event?

Returns: na Example
    // Fire a tween
    tween = TweenFire(id, EaseLinear, 0, true, 0.0, 1.0, "y", y, mouse_y);

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

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

TweenEventIsEnabled Checks if the specified callback event is enabled. TweenEventIsEnabled(tween[s], event)

tween[s] | Tween id[s]
event | Tween event macro (e.g. TWEEN_EV_FINISH)

Returns: bool Example
    // Fire a tween
    tween = TweenFire(id, 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, id, ShowMessage, "Hi!");
    }

## === SYSTEM UTILITIES ===

Scripts for managing system-wide state.

TweenSystemGet Accesses system data state by using a specified data label.
    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 begin (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
TweenSystemGet(dataLabel)

dataLabel | Specified data label

Returns: real Example
    // Get the system's current time scale value
    timeScale = TweenSystem("time_scale");

TweenSystemSet Updates system data state by using a specified data label.
    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 begin (default=10)
    	"auto_clean_count"	// number of tweens to check for auto-cleaning each step (default=10)
TweenSystemSet(dataLabel, value)

dataLabel | Specified data label
value | New data value

Returns: na Example
    // Set the system's current time scale to 0.5 (half speed)
    TweenSystem("time_scale", 0.5);

TweenSystemCount Returns total number of tweens in system, excluding those in inactive persistent rooms. Can pass optional label in for counting only specific tweens.
    OPTIONAL TWEEN LABELS:
    	"all"
    	"playing"
    	"paused"
    	"stopped"
TweenSystemCount([dataLabel])

dataLabel | (optional) Specified data label

Returns: real Example
    // Get number of tweens in system
    tCountAll = TweenSystemCount();

    // Get number of tweens playing
    tCountPlaying = TweenSystemCount("playing");

TweenSystemClearRoom Clears tweens in inactive persistent room(s). TweenSystemClearRoom(room)

room | Room index or [all] keyword for all rooms

Returns: na Example
    // Destroy tweens in persistent menu room
    TweenSystemClearRoom(rm_Menu);

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

TweenSystemFlushDestroyed Overrides passive memory manager by immediately removing all destroyed tweens from the system. TweenSystemFlushDestroyed()

Returns: na Example
    // Immediately flush all destroyed tweens from system
    TweenSystemFlushDestroyed();

SharedTweenerActivate Activate obj_SharedTweener controller object if deactivated. Only use if you know what you're doing! :) SharedTweenerActivate()

Returns: na Example
    // Activate the shared tweener controller object if deactivated
    SharedTweenerActivate();

SharedTweenerDestroy Destroys obj_SharedTweener controller object. Only use this if you know what you're doing! SharedTweenerDestroy()

Returns: na Example
    // Destroy the shared tweener controller object
    SharedTweenerDestroy();

## === PROPERTY BUILDERS ===

Required for creating optimised, extended, or normalized properties. These should be called once at the start of your game. Ideal for advanced users only. In TweenGMS -> Properties -> TGMS_BuildDefaultProperties() script, please see "x" for an instance example, "image_blend" for a normalized example, "score" for a global example, and "background_colour" for a normalized global example. To optimise property performance, you must create a SETTER and GETTER script for each before calling TGMS_BuildProperty().

    	[EXAMPLE FOR INSTANCE VARIABLE]

    	/// SETTER SCRIPT --> myVariable__
    	var _value = argument0; // updated value is passed as argument0
    	var _target = argument1; // target instance is passed as argument1
    	_target.myVariable = _value; // update instance's "myVariable" to updated value

    	/// GETTER SCRIPT --> __myVariable
    	var _target = argument0; // target instance is passed as argument0
    	return _target.myVariable; // return the target instance's "myVariable" value

    	/// Apply property builder with scripts above, only once at start of game
    	TGMS_BuildProperty("myVariable", myVariable__, __myVariable);

    	[EXAMPLE FOR GLOBAL VALUE]

    	/// SETTER SCRIPT --> myValue__
    	var _value = argument0; // updated value is passed as argument0
    	global.myValue = _value; // update global "myValue" to updated value

    	/// GETTER SCRIPT --> __myValue
    	return global.myValue; // return the global value "myValue"

    	/// Apply property builder with scripts above, only once at start of game
    	TGMS_BuildProperty("myValue", myValue__, __myValue);

TGMS_BuildProperty Prepares a property to be optimised for better performance. TGMS_BuildProperty("label", setter, getter)

label | String to associate with property
setter | Setter script to associate with property
getter | Getter script to associate with property

Returns: na Example
    // Prepare a property to be optmised with a setter and getter script
    TGMS_BuildProperty("x", x__, __x);

TGMS_BuildPropertyNormalize Prepares a property to be normalized for values between 0-1. Look up the image_blend__, and __image_blend scripts for an example. TGMS_BuildPropertyNormalize("label", setter, getter)

label | String to associate with property
setter | Setter script to associate with property
getter | Getter script to associate with property

Returns: na Example
    // Prepare a property to be normalized for values between 0-1.
    TGMS_BuildPropertyNormalize("image_blend", image_blend__, __image_blend);