Topic: MODULE: TWEEN 2.1.0 with AGS 3.4.0 support!

[Edmundito]

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

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 "inbetweening". It's typically used in Adobe Flash to indicate interpolation of an object from one keyframe to another.

Instead of depending on while loops everywhere in your code:

Code: [Select]

while (gIconbar.Y > -gIconbar.Height) {
  gIconbar.Y = gIconbar.Y - 1;
  Wait(1);
}
You can do this:

Code: [Select]

gIconbar.TweenY(0.5, -gIconbar.Height, eEaseInBackTween);
Notable games using the tween module include: A Golden Wake, Primordia, the Ben Jordan series, and Gemini Rue.

---

Tween 2.x is a huge upgrade from Tween 1.x. It is closer to the vision I had when I first started working on the first Tween module while still keeping the simplicity of the original.

Major changes include:

New Easing Functions

The new easing functions are based on common easing functions used by other tween modules. These include elastic, bouncing, backing out, etc.
You can see a demo of these at http://easings.net.

Stop Individual Tweens

You can now stop individual tweens:

Code: [Select]

cEgo.TweenPosition(2.0, 100, 100, eEaseLinearTween, eReverseRepeatTween);

// ... Later:
cEgo.StopTweenPosition();
Tween by SPEED

You can tween ANYTHING by speed instead of seconds as well. This allows you to move objects at a constant speed regardless of where they are.

Start Delay

You can delay the start of any tween allowing you to create interesting effects.

Convenient fade out and fade in tween functions

Code: [Select]

gIconbar.TweenFadeOut(0.5);
Custom Tweens

For the advanced users who like to have control, you can also create your own custom tweens that take advantage of the module's easing and timing functions. This also allows you to create tweens for drawing surfaces.

Code: [Select]

function TweenIndyMapLine(int fromX, int fromY, int toX, int toY) {
  Tween.IncreaseGameSpeed();
 
  Tween myTweenX;
  Tween myTweenY;
  myTweenX.Init(3.0, fromX, toX);
  myTweenY.Init(3.0, fromY, toY);
  int previousX = FloatToInt(myTweenX.FromValue);
  int previousY = FloatToInt(myTweenY.FromValue);
  int drawColor = Game.GetColorFromRGB(255, 0, 0);
 
  while (myTweenX.IsPlaying() || myTweenY.IsPlaying()) {
    myTweenX.Update();
    myTweenY.Update();
   
    DrawingSurface *surface = Room.GetDrawingSurfaceForBackground();
    surface.DrawingColor = drawColor;
    surface.DrawLine(previousX, previousY, myTweenX.Value, myTweenY.Value, 3);
    surface.Release();
   
    previousX = myTweenX.Value;
    previousY = myTweenY.Value;
   
    Wait(1);
  }
   
  Tween.RestoreGameSpeed();
}
No longer compatible with AGS 2.x!

If you would like to use the tween module with an AGS 2 game, then get the Tween 1.x module.

---

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

Documentation:
http://ags-tween.readthedocs.io/en/v2.1.0/

Support Chat:
https://discord.gg/vmuCyWX

Issues and Feature Planning:
https://github.com/edmundito/ags-tween/issues

Special Thanks to:
Tzachs for expanding the original module to support most of the properties in AGS, Grundislav and Dualnames for promoting and creating very inspiring work with the original module, jwalts37 who I met in person at GDC 2014 and told me how much he liked the module, Vince Twelve 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.

[Ibispi]

Tween module is my favorite module! Congratulations on new version release! :-)
Thanks Edmundito, and everyone else who worked on it!

[Dualnames]

Stickied, Tween module is the single best thing out of an AGS script.

[ollj]

history and maths of tweening:

[Julius Dangerous]

Awesome!

[Edmundito]

2.0.1 now available with a minor fix related to Character, Object, or GUI FadeIn FadeOut tweens. Thanks to Blackthorne!

[Blackthorne]

2.0.1 now available with a minor fix related to Character, Object, or GUI FadeIn FadeOut tweens. Thanks to Blackthorne!

No problem! Thanks to YOU!!

Bt

[ollj]

The GUI."resize" tween pivots to the top left ot the GUI, and i assume thats the same for dynamicsprites...

having a function that somehow manages to set the scaling pivot, the point of the image that doesnt move when resizing, percentually with a float. That is whats missing for me.

[Julius Dangerous]

Thanks!

[Cassiebsg]

Many many thanks for creating and sharing this!
I need to give this one a try, love the possibilities already!

[Edmundito]

Quick update: I've set up a public Skype chat if you'd like to have some live support or chat about tween module techniques:

Tween Module Skype Chat Group: https://join.skype.com/CsrRAc17CJIb

(Also updated the main post with this info!)

[Edmundito]

The GUI."resize" tween pivots to the top left ot the GUI, and i assume thats the same for dynamicsprites...

having a function that somehow manages to set the scaling pivot, the point of the image that doesnt move when resizing, percentually with a float. That is whats missing for me.

Oh yeah, that's a fairly advanced issue that maybe I can look into including into the module. I've added it as an idea in the github issue tracker:
https://github.com/edmundito/ags-tween/issues/3

In the meantime, here is a function that can resize the GUI with the pivot, you can update it to fit the object that you need:

Add this to your Global Script or a Module Script:

Code: [Select]

int TweenSizeFromPivot(this GUI*, Pivot pivot, float timing, int toWidth, int toHeight, TweenEasingType easingType, TweenStyle style, float startDelay, TweenTimingType timingType) {
  int toX = this.X;
  int toY = this.Y;

  if (pivot == ePivotTopCenter || pivot == ePivotMiddleCenter || pivot == ePivotBottomCenter) {
    toX += (this.Width - toWidth) / 2;
  } else if (pivot == ePivotTopRight || pivot == ePivotMiddleRight || pivot == ePivotBottomRight) {
    toX += (this.Width - toWidth);
  }
 
  if (pivot == ePivotMiddleLeft || pivot == ePivotMiddleCenter || pivot == ePivotMiddleRight) {
    toY += (this.Height - toHeight) / 2;
  } else if (pivot == ePivotBottomLeft || pivot == ePivotBottomCenter || pivot == ePivotBottomRight) {
    toY += (this.Height - toHeight);
  }
 
  int sizeDuration = this.TweenSize(timing, toWidth, toHeight, easingType, eNoBlockTween, startDelay, timingType);
  int positionDuration = this.TweenPosition(timing, toX, toY, easingType, eNoBlockTween, startDelay, timingType);
  if (style == eBlockTween) {
    WaitForLongest(sizeDuration, positionDuration);
  }
}
Add this to your Global Script Header or a Module Header:

Code: [Select]

enum Pivot {
    ePivotTopLeft,
    ePivotTopCenter,
    ePivotTopRight,
    ePivotMiddleLeft,
    ePivotMiddleCenter,
    ePivotMiddleRight,
    ePivotBottomLeft,
    ePivotBottomCenter,
    ePivotBottomRight
};

import int TweenSizeFromPivot(this GUI*, Pivot pivot, float timing, int toWidth, int toHeight, TweenEasingType easingType=Tween_EASING_TYPE_GUI, TweenStyle style=Tween_STYLE_GUI, float startDelay=Tween_START_DELAY_GUI, TweenTimingType timingType=Tween_TIMING_GUI);
Simple Usage:

Code: [Select]

gIconbar.TweenSizeFromPivot(eBottomRight, 0.5, 160, 120);

[Monsieur OUXX]

I didn't find how to set a tween based on speed rather than duration, as advertised (I'm sure it's here somewhere but it eludes me).

EDIT: OK, found it: TimingType

[Monsieur OUXX]

Suggestion for next version:

Make it easier to bind together some tweens (one for X, and one for Y, and why not one for altitude, etc.), based on a shared movement speed.

Let me explain what I mean:

Imagine you have a room Object that you want to move at a given speed. Then you can simply use Object.TweenPosition along with TimingType == eTweenSpeed. The module takes charge of calculating the duration matching that speed, and then updates both X and Y automatically with the appropriate ratio applied to each of them (namely: cos, and sin).

However, now, imagine you want to do the same with your very own abstract Tween object, that you will use for drawing onto surfaces. Very much the same as you do in the "Indy map example" in the first post. Then it's a pain to calculate the duration and the ratios by hand. You didn't have to do it in your example because you simply set the same duration (3.0) to both X and Y.

It's not too hard to do it, but if you created a class for an abstract (X,Y) tween (not relying on an actual AGS Object or Character or whatnot) that would be really cool...

[Edmundito]

Suggestion for next version:

Make it easier to bind together some tweens (one for X, and one for Y, and why not one for altitude, etc.), based on a shared movement speed.

Let me explain what I mean:

Imagine you have a room Object that you want to move at a given speed. Then you can simply use Object.TweenPosition along with TimingType == eTweenSpeed. The module takes charge of calculating the duration matching that speed, and then updates both X and Y automatically with the appropriate ratio applied to each of them (namely: cos, and sin).

However, now, imagine you want to do the same with your very own abstract Tween object, that you will use for drawing onto surfaces. Very much the same as you do in the "Indy map example" in the first post. Then it's a pain to calculate the duration and the ratios by hand. You didn't have to do it in your example because you simply set the same duration (3.0) to both X and Y.

It's not too hard to do it, but if you created a class for an abstract (X,Y) tween (not relying on an actual AGS Object or Character or whatnot) that would be really cool...

Hey, interesting idea, glad to see that some of the new fancy features are getting pushed to the limit.

I was wondering two things:

Is this specific to creating custom Tweens or for other types of combinations as well? Could you give me some examples of things you were trying to do with speed that the module did not support?

Can tell me more about "altitude" and how it relates in AGS?

[Monsieur OUXX]

Is this specific to creating custom Tweens or for other types of combinations as well? Could you give me some examples of things you were trying to do with speed that the module did not support? Can tell me more about "altitude" and how it relates in AGS?

It's strictly for Tweens, and as I said you already did it inside the module to manage X and Y simultaneously in objects (Chracters, Guis, etc.) that have both a X and a Y.
I gave an example: manage my own objects that have a X and a Y property.
Don't stay focused on "altitude". It could be anything, for example a "Z" if you manage a 3-dimensional space.

Long things short: a way to tween more than 1 property at once, based on the speed. It's alreayd possible in the module, but one has to understand how to relate speed to FPS. A tiny utility class would make that easier.

[daneeca]

Hi!
I wanted to try it, but I got an error message:
"Tween.asc(212): Error (line 212): 'max' is a global var; cannot use as name for local"

Maybe It's not working with AGS 3.4.0.6? :/

[Edmundito]

Hi!
I wanted to try it, but I got an error message:
"Tween.asc(212): Error (line 212): 'max' is a global var; cannot use as name for local"

Maybe It's not working with AGS 3.4.0.6? :/

Hi! I have actually not tested it on 3.4 yet, but maybe I should. I'll take a look at it this weekend. I've created a bug report in:
https://github.com/edmundito/ags-tween/issues/7

If anyone else is testing in 3.4.x, please let me know what works for you and what doesn't. If you'd like to see some new tween supported for 3.4 features please let me know as well.

[Crimson Wizard]

AGS 3.4.0.6 does not have any "max" global variables.
daneeca, do you have any modules before Tween which has such variable declared in the header? Or any game object named "max"? Or variable called "max" on the Global Variables pane?

[daneeca]

I have the Smooth Scrolling & Parallax module and a global variable named "max".
So, maybe this is the problem. If I rename the max global variable it probably will work. I'll try it tomorrow and report the results.

Thanks for the help!