Tween Module

Version 1.0

Created by Edmundo Ruiz (edmundo@edmundito.com)

This module can be used to create programatic animations. It supports GUIs, room objects, and characters. It allows these effects to be blocking, non blocking, or loop them, and it has acceleration/deceleration timing functions.

Note that the script syntax differs a bit between AGS 3.x and AGS 2.x, which will be noted in this documentation. You can also make the AGS 2.x syntax also available in AGS 3.x by commenting out line 51 in the module script header, in case that you are porting your game to AGS 3.x and have written functions using Tween.

Enumerated types

TweenTiming

enum TweenTiming {
  eLinearTween,
  eEaseInTween,
  eEaseOutTween, 
  eEaseInEaseOutTween
};

Used to set the timing of the tween, whether it's just a linear interpolation, one that only accelerates when it starts, one that only decelerates when it ends, or both accelerates at start and decelerates at end.

TweenStyle

enum TweenStyle {
  eBlockTween, 
  eNoBlockTween, 
  eRepeatTween, 
  eReverseRepeatTween,
};

Used to set the style of the tween, whether is blocking, non-blocking, repeating, or repeating reverse (where at the end of the tween cycle and repeats, it reverses the direction of the tween).

Functions

SecondsToLoops

// AGS 3.x and 2.x
SecondsToLoops(float seconds);

Converts and returns the number of seconds into game loops.

Example:

Wait(SecondsToLoops(5.0));

Will wait for 5 seconds.

StopAllTweens

// AGS 3.x
Character.StopAllTweens()
GUI.StopAllTweens()
Object.StopAllTweens()

// AGS 2.x
TweenStopAllForCharacter(Character* character)
TweenStopAllForGUI(GUI* gui)
TweenStopAllForObject(Object* object)

Stops all the Tweens currently playing on the a character, GUI, or room object.

Example:

// AGS 3.x
cEgo.StopAllTweens();
gIconbar.StopAllTweens();
oBluecup.StopAllTweens();

// AGS 2.x
TweenStopAllForCharacter(cEgo);
TweenStopAllForGUI(gIconbar);
TweenStopAllForObject(oBluecup);

Will stop all the tweens for cEgo, cIconbar, and oBluecup.

See Also: TweenStopAll

TweenPosition

// AGS 3.x
Character.TweenPosition(float timeInSeconds, short toX, short toY, TweenTiming timing=eLinearTween, TweenStyle style=eBlockTween)
GUI.TweenPosition(float timeInSeconds, short toX, short toY, TweenTiming timing=eLinearTween, TweenStyle style=eNoBlockTween)
Object.TweenPosition(float timeInSeconds, short toX, short toY, TweenTiming timing=eLinearTween, TweenStyle style=eBlockTween)

// AGS 2.x
TweenCharacterPosition(Character* character, float timeInSeconds, short toX, short toY, TweenTiming timing=eLinearTween, TweenStyle style=eBlockTween)
TweenGUIPosition(GUI* gui, float timeInSeconds, short toX, short toY, TweenTiming timing=eLinearTween, TweenStyle style=eNoBlockTween)
TweenObjectPosition(Object* object, float timeInSeconds, short toX, short toY, TweenTiming timing=eLinearTween, TweenStyle style=eBlockTween)

Tweens the position of a character, GUI, or object from its current position to another. Note that by default, GUI tweens are non-blocking unlike the character and object tweens.

Returns the tween duration (in loops) if the TweenStyle is non-blocking (eNoBlockTween). For a repeat TweenStyle (eRepeatTween or eRepeatReverseTween) it returns the duration of one tween cycle. For blocking tweens, it returns a 1.

Example:

// AGS 3.x
cEgo.TweenPosition(2.5, 100, 100);

// AGS 2.x
TweenCharacterPosition(cEgo, 2.5, 100, 100);

Will tween the position of the character from its current position to x 100, y 100 in 2.5 seconds.

TweenScaling

// AGS 3.x
Character.TweenScaling(float timeInSeconds, short toScale, TweenTiming timing=eLinearTween, TweenStyle style=eBlockTween)

// AGS 2.x
TweenCharacterScaling(Character* character, float timeInSeconds, short toScale, TweenTiming timing=eLinearTween, TweenStyle style=eBlockTween)

Tweens the scaling of a character.

Example:

// AGS 3.x
cEgo.TweenScaling(1.5, 200);

// AGS 2.x
TweenCharacterScaling(cEgo, 1.5, 200);

Will tween the scaling of Ego from its current scale to 200% in 1.5 seconds.

TweenSize

// AGS 3.x
GUI.TweenSize(float timeInSeconds, short toWidth, short toHeight, TweenTiming timing=eLinearTween, TweenStyle style=eNoBlockTween)

// AGS 2.x
TweenGUISize(GUI* gui, float timeInSeconds, short toWidth, short toHeight, TweenTiming timing=eLinearTween, TweenStyle style=eNoBlockTween)

Tweens the size of a GUI.

Example:

// AGS 3.x
gStatusline.TweenSize(1.0, 50, 50);

// AGS 2.x
TweenGUISize(gStatusline, 1.0, 50, 50);

Will tween the size the statusline GUI from its current size to 50x50 pixels in 1 second.

TweenStopAll

// AGS 3.x and 2.x
TweenStopAll()

Stops all tweens currently playing.

Example:

TweenStopAll();

Will stop whatever tweens where currently playing, whether it was a GUI, character, or room object tween.

TweenTransparency

// AGS 3.x
Character.TweenTransparency(float timeInSeconds, short toTransparency, TweenTiming timing=eLinearTween, TweenStyle style=eBlockTween)
GUI.TweenTransparency(float timeInSeconds, short toTransparency, TweenTiming timing=eLinearTween, TweenStyle style=eNoBlockTween)
Object.TweenTransparency(float timeInSeconds, short toTransparency, TweenTiming timing=eLinearTween, TweenStyle style=eBlockTween)

// AGS 2.x
TweenCharacterTransparency(Character* character, float timeInSeconds, short toTransparency, TweenTiming timing=eLinearTween, TweenStyle style=eBlockTween)
TweenGUITransparency(GUI* gui, float timeInSeconds, short toTransparency, TweenTiming timing=eLinearTween, TweenStyle style=eNoBlockTween)
TweenObjectTransparency(Object* object, float timeInSeconds, short toTransparency, TweenTiming timing=eLinearTween, TweenStyle style=eBlockTween)

Tweens the transparency of a character, GUI, or object from its current transparecy to another. Note that by default, GUI tweens are non-blocking unlike the character and object tweens.

Example:

// AGS 3.x
oBluecup.TweenTransparency(3.0, 100);

// AGS 2.x
TweenObjectTransparency(oBluecup, 3.0, 100);

Will tween the transparency of the room object Bluecup to from its current value to 100% (thus fading it out).