MODULE: Tween 2.2.2 with AGS 3.5.0 support!

[edmundito]

Latest Version is 2.3.0 - See the Tween 2.3.0 thread for more details!

About

The AGS Tween Module allows you to programmatically interpolate many of the AGS properties (objects, characters, regions, viewport, audio, gui, gui controls, etc.) over time in amazing ways. The term tween comes from the computer animation term inbetweening.




Ten years ago you probably depended on ugly while loops everywhere in your code to move something:

Code: ags

while (gIconbar.Y > -gIconbar.Height) {
  gIconbar.Y = gIconbar.Y - 1;
  Wait(1);
}

Today, with the Tween module, can do graceful things like this:

Code: ags

gIconbar.TweenY(0.5, -gIconbar.Height, eEaseInBackTween);

Notable games using the tween module include: Guard Duty, Lamplight City, Unavowed, Future Flashback, and Rosewater.

What are you waiting for? Start using the Tween module today!

---
What's new in 2.2.2?
Bug fixes. More info here: https://github.com/edmundito/ags-tween/releases/tag/v2.2.2

What's new in 2.2.0?

First, a brand new format for the documentation: https://edmundito.gitbook.io/ags-tween/

TL;DR: This is a great new release that supports all new features all the way AGS 3.5.0 beta 5. Additionally, it fixes a few bugs and removes compatibility with older AGS versions prior to 3.4.0.

Fixed Region StopTweenTint result parameter (was not used)
Fixed Region tween tint saturation to 1-100 and luminance clamping to 0-100
Fixed exception when using Button.TweenTextColorRed
Removed compatibility with any version below 3.4.0
Replaced internal #ifver checks to check based on SCRIPT_API_v* to improve compatibility
Replaced Region.TweenTintEx with additional luminance parameter in Region.TweenTint
Removed TweenSystemGamma and StopTweenSystemGamma in favor of using existing System.TweenGamma and System.StopTweenGamma
Removed TweenSystemVolume and StopTweenSystemVolume in favor of using exiting System.TweenVolume and System.StopTweenVolume
Added TweenTextColorRGB for Button, Label, and TextBox
3.4.1: Added Character TweenTint (+ Red/Green/Blue), TweenTintSaturation, TweenTintLuminance
3.4.1: Added Object TweenTint, TweenTintRed, TweenTintGreen, TweenTintBlue, TweenTintSaturation, TweenTintLuminance
3.5.0: Removed limitations of GUI tweens to screen width and height
3.5.0: Replaced old Viewport tweens with Camera TweenX, TweenY, TweenWidth, TweenHeight, TweenPosition, TweenSize
3.5.0: Added new Viewport object tweens TweenX, TweenY, TweenWidth, TweenHeight, TweenPosition
3.5.0: Updated Tween1Compatiblity module to support legacy Viewport tweens (via Camera)
3.5.0: Added Tween2Compatiblity module to support legacy Viewport tweens (via Camera)
3.5.0: Added GUI TweenBackgroundColor (+ Red/Green/Blue/RGB) and TweenBorderColor (+ Red/Green/Blue/RGB)
3.5.0: Added ListBox TweenSelectedBackColor (+ Red/Green/Blue/RGB), TweenSelectedTextColor (+ Red/Green/Blue/RGB), TweenTextColor (+ Red/Green/Blue/RGB)

---

Download from:
https://github.com/edmundito/ags-tween/releases/tag/v2.2.2

Documentation:
https://edmundito.gitbook.io/ags-tween/

Chat in the AGS Discord server:
https://discord.gg/vmuCyWX

Issues and feature planning:
https://github.com/edmundito/ags-tween/issues

10 years of Special Thanks to:

Crimson Wizard for continuing to support AGS and adding new features like Camera that inspired this version of the module
eri0o for worshiping this module and using it to its fullest potential
MattFrith for supporting the Discord channel in what became the AGS Discord server
Tzachs for expanding the original module to support most of the properties in AGS
Grundislav for the Ben Jordan games that inspired the creation of the original module
Dualnames for promoting and creating very inspiring work with the module since the very beginning
Blackthorne who made so many great games with this module and his overall encouragement motivated me to create Tween 2
jwalts37 who I met in person at GDC 2014 and told me how much he liked the module
Vince Twelve who wished he had this module in Resonance and for showing me some advanced code that was the inspiration for Tween 2's startDelay
Calin Leafshade for giving me more insight into scripting best practices, and everyone in the forum for reporting problems and making games with this
Dave Gilbert for praising the tween module every time I see him in person
TheJBurger who I kept exchanging emails about the module during the development of Gemini Rue
ThreeOhFour who early in the first of tween module suggested a feature that would later become custom tweens
Pumaman for reasons

[Vincent]

This is certainly the most useful module ever created for this engine. Congratulations and happy anniversary, thank you so much for this new release! 

[eri0o]

Those are sexy docs! XD

Wuhu, amazing work! I still need to remove headphones jack -> be courageous enough to fully move from 3.4.3 to 3.5.0   

Thank you for the work you put into this module. It's really great and it makes using AGS a much more joyful experience. 

[Laura Hunt]

Thanks Edmundito for creating this amazing life-saving module and maintaining it all these years! I was kind of scared to take the plunge at first but I used 2.1.0 for the first time a couple of days ago and now I can't imagine doing anything without it I agree 100% with whoever said back in the day that it should come bundled with AGS by default!

Wuhu, amazing work! I still need to remove headphones jack -> be courageous enough to fully move from 3.4.3 to 3.5.0   

Me too! So much potential there but also so scary! (and also a bit of laziness on my part, why not admit it)

[edmundito]

I just released 2.2.2! It's just a few small bug fixes that were present in 2.2.0. Thanks to AlanDrake for fixing some of these issues.
https://github.com/edmundito/ags-tween/releases/tag/v2.2.2

I'm always open for suggestions on what the next version should have. Some of these ideas have been posted in github issues:
https://github.com/edmundito/ags-tween/issues

[Rarefoil]

How does one move the mouse position with a tween?

[timid_dolphin]

Good question!

someone else could correct me here, but I believe the answer is: you can't, at least not without meddling with the module script.

Here's what I'd do:
1 - If you want to automate the cursor in just one room, create an object using the cursor sprite, if you want this in several rooms, make it a character.

2 - Hide the cursor at the same time make the object / character visible at the same screen position as the cursor.

3 - Tween that fake cursor!

Hope this helps.

[vga256]

As always, thanks for this lifesaving module Edmundo.

I've been using some of the less-often-used tweens lately, and was wondering: what do you think about adding a "from" and "to" Panning setting for TweenPanning? I made a few minor changes to the module (seen below), and this new TweenPanning function allows me to start a Pan at any location (from -100 to 100) and end it at another panning location. This gives me a crude form of procedural dynamic sound for rooms (e.g. rolling a chair across the floor from center to left, and then left to right).

The default (unmodified) behaviour is to start all tweens at their current panning position (usually zero) and takes no "fromPanning" parameter. I could also imagine having the parameter order changed to int toPanning, int fromPanning=0, so the "fromPanning" parameter can use zero as a default value for backwards-compatibility sake.

Tween.asc:

Code: ags

int TweenPanning(this AudioChannel*,  float timing, int fromPanning, int toPanning, TweenEasingType easingType, TweenStyle style, float startDelay, TweenTimingType timingType) {
  return _StartAudioTween(_eTweenAudioChannelPanning, this, timing, TweenMaths.ClampInt(toPanning, -100,  100), 0, TweenMaths.ClampInt(fromPanning, -100, 100), 0, easingType, style, startDelay, timingType);

Tween.ash:

Code: ags

import int TweenPanning(this AudioChannel*, float timing, int fromPanning, int toPanning, TweenEasingType easingType=Tween_EASING_TYPE_AUDIO, TweenStyle style=Tween_STYLE_AUDIO, float startDelay=Tween_START_DELAY_AUDIO, TweenTimingType timingType=Tween_TIMING_AUDIO);

I'm not sure if this was the most elegant way of doing it, but you get the idea

[timid_dolphin]

I was having issues with my camera continuing to tween when the game was paused, here's a quick fix for this.

With a bit of help from Edmundo, Crimson Wizard and Haloa, I've made this little modification to the Tween module's repeatedly_execute_always function:

Code: ags

function repeatedly_execute_always() {
  // Steps through every active tween
  _i = 0;
  _longestTweenDuration = 0.0;

  for (; _i < Tween_MAX_INSTANCES; _i++) {
    if (!(IsGamePaused() && (_tweens[_i].RefType == _eTweenReferenceCamera 
                           ||_tweens[_i].RefType == _eTweenReferenceObject)))
    {
      if (_tweens[_i].Update()) {
        if(_tweens[_i].IsPlaying()) {
          _CheckIfIsLongestTween(_i);
        }
      }
    }
  }
}

This will pause all camera tweens and object tweens while the game is paused, and resume when the game is unpaused. Works great for me because I have all sorts of GUI tweens going on in my pause menu.

Hope this is helpful to others on here!

[edmundito]

2.3.0 is out!