Documentation for :to() tweening animation function.

  • #1, z Raven SingularitySaturday, 15. April 2017, 03:02 hodinky 8 years ago
    Google was unable to find any documentation for the :to() animation function.  I was only able to locate a few random examples of the function being used.  I'll post what I've gathered so far.



    Function:
    object:to(delay-in-ms, {action1, action2, action3, ...}, easing, loop, reverse)
    object

    This is a reference to an object, you can assign a short notation variable to make it easier to call functions on this object:
    local object = game.CurrentScene.SceneObjects["some_object_name"]
    


    delay-in-ms

    The amount of time it takes to perform the transition (1000 ms = 1 second).


    actions

    A comma-separated list of actions to perform during this transition period, including:

    • Visibility
    • Rotation
    • AnimationSize
    • AnimationCurrentPosition
    • ...more...


    easing

    Specify the type of curve used for the transition.  This allows the start or end of the transition to be slower or faster, to bounce or overshoot slightly, etc.

    The following easing types are available:

    • Linear
    • Sine
    • Quad
    • Cubic
    • Quart
    • Quint
    • Expo
    • Circ
    • Back
    • Elastic
    • Bounce

    Animated examples of easings can be viewed from: http://easings.net/

    Note: Linear is not listed on that web site, but refers to an even transition speed, no slowing down or speeding up.

    Easings may appear at the start of the transformation "In", at the end of the transition "Out", or at both the start and end "InOut".

    Full list of easings:

    • easeLinearIn / easeLinearOut / easeLinearInOut
    • easeSineIn / easeSineOut / easeSineInOut
    • easeQuadIn / easeQuadOut / easeQuadInOut
    • easeCubicIn / easeCubicOut / easeCubicInOut
    • easeQuartIn / easeQuartOut / easeQuartInOut
    • easeQuintIn / easeQuintOut / easeQuintInOut
    • easeExpoIn / easeExpoOut / easeExpoInOut
    • easeCircIn / easeCircOut / easeCircInOut
    • easeBackIn / easeBackOut / easeBackInOut
    • easeElasticIn / easeElasticOut / easeElasticInOut
    • easeBounceIn / easeBounceOut / easeBounceInOut

    Note: I am not sure if there is a way to chain multiple easings together, such as "ExpoIn + BounceOut".


    loop

    Once the transition is finished, does it immediately repeat again from the start?

    True/False.


    reverse

    Once the transition is finished, does it then go backwards until it gets back to the start?

    True/False.

    Actions:
    Visibility

    Specify the percentage of visibility, 0-100.

    Note 1: Goes from 0.0% (fully invisible) to 100.0% (fully visibile).

    Note 2: Fractional is fine, e.g. "33.333" or "100/3".
    object:to(750, {Visibility = 0}, easeExpoIn, true, true)

    This will spend 3/4 seconds fading object to hidden, then 3/4 seconds fading back to visible, then keep repeating itself.
    Rotation

    First choose the centre point to use when rotating the image, such as:

    object.RotationCenter = {x = -1, y = -1}

    Note: Using -1, -1 for the coordinates will use the centre of the image.


    Next perform the rotation transformation:

    object:to(5000, {Rotation = math.rad(360)}, easeLinearInOut, false, false)

    This will spend 5 seconds rotating the object 360 degrees, using a constant / linear speed, then will stop.

    Note 1: Rotation degrees are specified in radians, use the math.rad() function to convert degrees to radians.

    Note 2: You can specify large amounts of rotation, such as 720 degrees, to rotate multiple times.

    Note 3: If you specify negative degrees, the object will rotate counter-clockwise.




    That's what I have so far.  I haven't tested everything above, mistakes likely... corrections welcome.  :-)

    Bažant

    18 Posts


  • #2, z afrlmeSaturday, 15. April 2017, 05:27 hodinky 8 years ago
    haha, bloody hell mate. At least someone is keen to sort out some more documentation. I lost the will ages ago - plus busy with other things.

    Any new Lua features that are added to the engine require SimonS to document them, but he's busy programming the engine most of the time & I don't know the inner workings of the engine or features, so I'm not able to document them myself.

    There's a lot of nice Lua features added over past few versions that have no documentation at all.

    As for to() function, I believe it is a simplified version of startTween() function, which was a little hard to understand. Basically you can create a fade transition with any scriptable VisObj data structure field that contains an integer or float value. i.e...
    game.CurrentScene:to(1000, {SceneMusicVolume = 0}) -- fade background music volume of current scene to 0%

    or maybe you want to fade the brightness value of the current scene out (basically fades to black)
    game.CurrentScene:to(1000, {SceneBrightness = 0})

    or maybe you want to slide in/out an interface with a bounceout easing.
    Interfaces["inventory"]:to(500, { InterfaceOffset = {x=0, y = Interfaces["inventory"].InterfaceOffset.y} }, easeBounceOut)

    Anyway, thanks for taking the time to research & write up about it. wink

    * edit: in regards to easing... no I believe you can only assign one. If you don't include an easing parameter then I belive it uses easeLinearInOut by default.

    So, by default...
    • easing = easeLinearInOut
    • loop = false
    • reverse (creates pendulum loop) = false

    Imperátor

    7285 Posts

  • #3, z Raven SingularitySaturday, 15. April 2017, 06:14 hodinky 8 years ago
    Visionaire-Studio needs good documentation to avoid frustrated developers!  I'm happy to help, but I don't know how to use Visionaire-Studio yet, lol.

    It seems most pages on the Wiki are empty, or overly technical descriptions with few practical examples. I would be happy to help improve documentation, and it helps me learning to use the app.  I can do Wiki formatting, proofing, testing of code, etc.


    Currently, I'm working on my game's title screen.  I'm starting with a distant tiny Earth rotating slowly, that then gets bigger until it zooms into a patch of clouds.  Then I was going to cut to another image below the cloud layer.  Play a sound of air rushing by.


    A simple but fun intro that requires I learn the basics of tweening animation in Visionaire-Studio: move, scale, rotate, opacity.

    Rotation and Opacity worked fine, but I got stuck with the movement.  I assume it's relative movement, which is good for in-scene animating and annoying for fullscreen cut-scenes.

    Can any of this tweening animation on images be done through the GUI?

    I was not able to get scaling my object to work, I assume because I was using an animation function.  I guess AnimationSize() doesn't work on image objects?

    Do I just stick the Scale() function into the object:to()?

    What does the Scale value represent?

    Is there some way to specify the new size of the image in pixels, either width or height?

    Also, out of curiousity, is it possible to change the aspect ratio of an object to stretch or squish it?

    This would be really useful for a lot of neat special effects.  :-)


    Edit:

    Things are making a lot more sense now, and I'm looking at the Data Structure page to see what object properties are available to manipulate using to().  Now my planet Earth is spinning and zooming with music now.  Thanks for your help.

    Bažant

    18 Posts

  • #4, z sebastianSaturday, 15. April 2017, 11:30 hodinky 8 years ago
    You should create a book out of this here: 

    Kapitán

    2346 Posts

  • #5, z ke4Saturday, 15. April 2017, 11:43 hodinky 8 years ago
    Okay, now Lua Draw Function HYPE grin
    What other big functions still remains undocumented?

    Zabiják klíčů

    810 Posts

  • #6, z sebastianSaturday, 15. April 2017, 11:45 hodinky 8 years ago
    "shaders" especially step by step stuff

    Kapitán

    2346 Posts

  • #7, z ke4Saturday, 15. April 2017, 12:08 hodinky 8 years ago
    Btw these books are a completely hidden thing or is there some link to access them which i overlooked? They also seems to be in german only.

    Zabiják klíčů

    810 Posts

  • #8, z sebastianSaturday, 15. April 2017, 12:21 hodinky 8 years ago
    Btw these books are a completely hidden thing or is there some link to access them which i overlooked? They also seems to be in german only.

    hmm e knew they were in the top navigation as "Books"... But now they're gone . Maybe because the only current available non finished book is german (with some english placeholders from the past).

    Kapitán

    2346 Posts

  • #9, z afrlmeSaturday, 15. April 2017, 12:45 hodinky 8 years ago
    The wiki is like that because I'm only 1 person & Simon is too busy programming the engine & also because I didn't want to bother wasting my time documenting the old editor (4.2.5 & below) because of 5.x editor coming out, which looks & works differently, which means I would have probably have had to redo everything again - too much hassle. If I were getting paid a monthly wage to work on the documentation, then maybe I wouldn't have minded so much, but the majority of us that help, do so for free.

    In regards to movement. I recommend using animations as they are much easier to move & manipulate compared to object sprites.
    ActiveAnimations["example"]:to(1000, { AnimationCurrentPosition = {x = 500, y = 500}, easeQuintOut)

    As for scaling, you can use either AnimationSize if it's an animation, or Scale if it's an object, though Scale should also work if it's an animation providing you apply scale to the scene object. Scale is done with decimals instead of percentage for some reason, so 1 or 1.0 = 100% whereas 0.5 = 50% & 2 = 200%.
    game.CurrentScene.SceneObjects["example"]:to(10000, {ObjectScale = 1.3}, easeLinearInOut, true, true) -- scale object up & down in a loop

    Imperátor

    7285 Posts

  • #10, z LebosteinFriday, 30. June 2017, 11:40 hodinky 7 years ago
    That easing thing is a very great feature. You can generate a bunch of cool animations without preparing different frames (clock pendulums, whater wheels, rotating things, swinging things, moving branches and grass in the wind....). I am sure that only 1 % of the Visionaire users are know of this possibility... because this feature is not documented in a user firendly way.

    My question: is it possible to forward the time, for example to start at 1000 ms in a 2000 ms period? I have some swinging blades of grass in the wind, but at the moment all blades are swinging in sync.

    local object = Objects["grass_1"]
    object:to(2000, {Rotation = math.rad(20)}, easeSineInOut, true, true)

    Zabiják klíčů

    621 Posts

  • #11, z afrlmeFriday, 30. June 2017, 12:18 hodinky 7 years ago
    No, I think you would have to control a few layers independently. You could use math.random maybe to change the delay/duration each loop though.

    Imperátor

    7285 Posts