Tweenline 2

Getting Started

Setup Tweenline

You can download the Tweenline Animation Engine from the Game Maker Studio Marketplace. Once you have adquired Tweenline from the marketplace, you only need to do the following:

To view the demo files:

  1. Import ALL the files into a NEW project
  2. Press the "Play" button in GameMaker Studio 2.

To Import the basic tweenline2 SDK extension into your project:

  1. Open your existig project or create a new empty project
  2. Import the Following folders:
  • scrips/tweenline
  • objects/tweenline
  1. If you want to use the advanced visual debugging features, you can also import:
  • scripts/tweenline_debug

Enjoy!

Your First Tween

A tween is an Animation (interpolation of values) of one or more variables of an instance during a period of time. To create your first Tween, add the following code to the creation event of an object, and place it in an empty room. This will tween the x variable of the current object from the current value to the value 300 in 2 seconds and then, stop.

tween_to(id, 2, ["x", 300]);

Congratulations! You have created your first Tween animation.

Multiple variables

You can also, animate multiple variables using the same tween:

tween_to(obj_box, 5, ["x", x + 200, "y", y + 300, "image_angle", 90]);

Variable Aliases

Some of the most used variables, like image_angle, image_xscale, image_blend, etc have aliases like "angle", "xscale" and "blend". To check the full list of aliases, check tween_system_add_alias script. So, you can rewrite the last tween like this:

tween_to(obj_foo, 5, ["x", x + 200, "y", y + 300, "angle", 90]);

Control an Animation

You can save a reference to the tween in a variable, and then use all the anim_* functions, to control the tween:

my_tween = tween_to(id, 2.5, ["blend", c_red]); // Blend to red in 2.5 seconds.
// Then you can play, pause, seek, reverse, timescale, and more!
anim_pause(my_tween);
anim_play(my_tween);
anim_seek(my_tween, 1.2);
anim_reverse(my_tween);
anim_set_timescale(my_tween, 0.5);

Check all the functions inside the Animation folder for more.

tween_from, tween_to and tween_fromto

Currently, you are tweening your variables from the current value to a final value that you pass to the tween_to function. If you want to do the oposite (from one value you pass, to the current variables values), you can use {@linkcode tween_from]:

x = 200;
tween_from(id, 2, ["x", 100]); // Will tween from the passed value (x=100) to the actual value (x=200)

Also, you can use tween_fromto to define the starting and ending values:

tween_fromto(id, 2, ["x", 100], ["x", 200, "angle", 90]); //from x=100 to x=200 and image_angle=90

The VARS array

The array you are passing to the tween_to, tween_from and tween_fromto is called VARS array. You will find references to this array across all the documentation. You can pass special VARS in this array. to control the behavior of the animation itself. For example:

tween_to(id, 2, ["alpha", 100, "ease", ease_elastincin, "patrol", true]);

Here, the "ease" and "patrol" are special VARS. The ease define the animation curve used to interpolate the values, and patrol means that the animation will repeat forever forwards and backwards. You can check all the special VARS you can use inside the Animation folder of this documentation.

Tweenlines vs Tweens

If you want to control multiple tweens at the same time with advanced timing functionality, you can create a "Tweenline". A Tweenline is like timeline for Tweens. You can have inside any number of tweens or another nested tweenlines. They can be sequantial, overlaped, or however you want. Your creativity is your limit!

Check the Tweenline folder for more info and examples.

Animation

Both Tweens and Tweenlines are Animations. It means that you can pass a instance of a tweenline, or a tween to any anim_* function.

Below there is a description of the content of each Documentation Folder.

  • Tween: A component that can interpolate values from any variable of any object in real time to create animations.
  • Tweenline: A timeline that can contain another Tweens or Tweenlines. They are used to create complex animations involving more than one Tween.
  • Animation: Base class of both Tweens and Tweenlines. You can use these functions to control (play, pause, reverse, timescale, etc) and manage them in real time. (Tweens and Tweenlines ARE Animations)
  • Easing: Contains all the built in easing functions that are integrated on Tweenline Engine.
  • System: Global functions that affects all the Tweenline Engine global configuration. Also, it contains the required functions executed by the obj_tweenline
  • InstanceSelect: Advanced functions to select instances acording to certain requirements. They are commonly used with the tween_stagger_* functions, but they can by used separately from Tweenline Engine.

Contact

For questions/Bugs/support or to show me the game you are making with Tweenline Animation Engine, please send me an email:

Enjoy!

Changelog

Version 2.0.4

New features:

  • NEW DEMO ADDED: "The position parameter" interactive demo
  • IMPROVED DEMO: The "Easing Visualizer" demo has been improved with playback and speed controls as requested by the Tweenline comunity.
  • Added tl_playhead_set_anim(playhead, anim)
  • Added is_anim(value). This is the same as is_tweenline(value) || is_tween(value)
  • Improved tl_draw_tweenline to support infinite tweens and improved tooltip positioning.
  • A simple `obj_tl_playhead`` object has been added for easy drag and drop debugging for your tween. Simply drag into your room and set the variable anim from the room editor to the animation you want to show the playhead.
  • Also a new obj_tl_draw_tweenline has been added. You can use it to easily debug your tweenlines.
  • Now the engine throws an error when you try to use an invalid variable name inside a tween
  • It also throws an error if you want to use as a variable name a value that is neither a string or a custom setter script.
  • Added anim_get_yoyo(anim)
  • Improved documentation

Bugs fixed:

  • Fixed bug whith the position parameter parser, where labels (including "_start" and "_end") were ignored if the string doesn't contain "+=" or "-=" in it.
  • Fixed bug where labels added with tweenline_add(label, pos) were always added at the end of the tweenline regardless of the position parameter given.
  • Added more unit tests.
  • tl_playhead_set_size now accept undefined as any parameter. This will use for that parameter the default value.
  • The visual playhead system will not throw an error if you pass something that is not an animation.
  • Fixed bug where tl_playhead_draw was not preserving the actual global drawing colour and alpha.
  • Fixed bug with anim_set_duration not working properly

Version 2.0.3

Warning: You need the newest version of the game maker runtime and IDE. New Features:

  • Improved "Event types" demo
  • Added tl_playhead_use_total_progress(...)
  • Added anim_set_totalprogress(...) Bugs fixed:
  • Fixed bug where "onreversecomplete" event were not fired
  • Improved tdd_gm (The test suite made specially for Tweenline)
  • Fixed bug with is_infinity.
  • Fixed various "Syntax Errors" warnings given by the new GMS2 IDE.

Version 2.0.2

  • Fixed bug where Tweenline Engine was not compiling for YYC Target
  • Fixed bug with tweenline_stager_ functions
  • Fixed bug when using ["paused", true] when creating an animation and then playing it.
  • UNIT TEST: Added test_tween_paused_at_creation
  • tl_draw_tweenline and tl_draw_tween_graph were improved to handle tweens and tweenlines with repeats, yoyo and patrol mode.

Version 2.0.1

  • Added this readme file and cleaned some files.

Version 2.0.0