ThrowPropsPlugin

ThrowPropsPlugin is a plugin for TweenLite and TweenMax that allows you to simply define an initial velocity for a property (or multiple properties) as well as optional maximum and/or minimum end values and then it will calculate the appropriate landing position and plot a smooth course based on the easing equation you define (Quad.easeOut by default, as set in TweenLite). This is perfect for flick-scrolling or animating things as though they are being thrown.

For example, let's say a user clicks and drags content and you track its velocity using an ENTER_FRAME handler and then when the user releases the mouse button, you'd determine the velocity but you can't do a normal tween because you don't know exactly where it should land or how long the tween should last (faster initial velocity would mean a longer duration). You need the tween to pick up exactly where the user left off so that it appears to smoothly continue moving in the same direction and at the same velocity and then decelerate based on whatever ease you define in your tween.

Oh, and one more challenge: maybe you want the final resting value to always lie within a particular range so that things don't land way off the edge of the screen. But you don't want it to suddenly jerk to a stop when it hits the edge of the screen; instead, you want it to ease gently into place even if that means going past the landing spot briefly and easing back (if the initial velocity is fast enough to require that). The whole point is to make it look smooth.

No problem.

Flick-scrolling example

Get Adobe Flash player

Rotation example

Get Adobe Flash player

Note: ThrowPropsPlugin is a membership benefit of Club GreenSock ("Shockingly Green" and corporate levels). If you're not a member yet, you can sign up here. Once you join you'll get access to several plugins like this which can be downloaded from your GreenSock account.

One of the fundamental problems ThrowPropsPlugin solves is when you need to start tweening something at a particular velocity but you don't necessarily know the end value (most tweens require that you know the end value ahead of time). Another tricky part of building a tween that begins at a particular velocity and looks fluid and natural (particularly if you're applying maximum and/or minimum values) is determining its duration. Typically it's best to have a relatively consistent level of resistance so that if the initial velocity is very fast, it takes longer for the object to come to rest compared to when the initial velocity is slower. You also may want to impose some restrictions on how long a tween can last (if the user drags incredibly fast, you might not want the tween to last 200 seconds). The duration will also affect how far past a max/min boundary the property can potentially go, so you might want to only allow a certain amount of overshoot tolerance. That's why ThrowPropsPlugin has a few static helper methods that make managing all these variables much easier. The one you'll probably use most often is the to() method which is very similar to TweenLite.to() except that it doesn't have a duration parameter and it adds several other optional parameters. Read the ASDocs for details. The demo video covers this method in the 2nd half too.

Documentation

View the full ASDocs here.

Sample AS3 code

import com.greensock.*;
import com.greensock.plugins.*;
import com.greensock.easing.*;

TweenPlugin.activate([ThrowPropsPlugin]);

//simplest syntax, start tweening mc.x at 200 pixels/second and mc.y at -30 pixels/second so that they both come to a stop in exactly 5 seconds using the Strong.easeOut ease
TweenLite.to(mc, 5, {throwProps:{x:200, y:-30}, ease:Strong.easeOut});

//to define max and/or min values, use the object syntax like this:
TweenLite.to(mc, 5, {throwProps:{x:{velocity:200, min:100, max:600}, y:{velocity:-30, min:0, max:150}}, ease:Strong.easeOut});

//to have ThrowPropsPlugin automatically determine the duration based on the initial velocity and resistance, use the static to() method like so:
ThrowPropsPlugin.to(mc, {throwProps:{x:{velocity:200, min:100, max:600}, y:{velocity:-30, min:0, max:150}, resistance:50}, ease:Strong.easeOut});

FAQ

  1. Where can I get ThrowPropsPlugin? It isn't in the public downloads!ThrowPropsPlugin is a membership benefit of Club GreenSock ("Shockingly Green" and corporate levels) so it isn't in the public downloads. If you're not a member yet, you can sign up here. Once you join you'll get access to several plugins like this which can be downloaded from your GreenSock account.
  2. Is ThrowPropsPlugin only for tweening the x and y properties?Absolutely not. You can tween ANY numeric property of ANY object. For example, you could tween mc.rotation like this:
    TweenLite.to(mc, 2, {throwProps:{rotation:150}, ease:Quad.easeOut});
    

    Or you can tween a custom property of a custom object like this:

    TweenLite.to(myCustomObject, 2, {throwProps:{myCustomProperty:600}, ease:Back.easeOut});
    
  3. Does ThrowPropsPlugin completely automate flick-scrolling and tracking the velocity of the mouse, etc.?Nope. The plugin was meant to be relatively small, efficient, and flexible. There are many ways you could track mouse movement, touch events, dragging, etc. so the plugin doesn't impose a particular method on you. The example in the Plugin Explorer demonstrates one way to track the velocity of the mouse, so feel free to use that as a reference. You simply feed the velocity (and optionally other values like max, min, and resistance) to the plugin and it takes it from there.
  4. Why would I want to use a tween to do this type of motion rather than an ENTER_FRAME or Timer that manually applies deceleration iteratively?Using a solution that is integrated with a tweening engine like TweenLite or TweenMax allows you to do sequencing much more easily and you get better control because you can pause(), resume(), reverse(), jump to any time in the tween, use onComplete/onUpdate callbacks, change timeScale, and more. Overwrite management is built-in too. Plus most other solutions don't give you the smooth handling of the maximum/minimum values. They are typically frame-based too, so they slow down if the frame rate drops and it can be difficult to predict exactly when the object will come to rest.
  5. What is that BlitMask object that's used in the interactive example and where can I get it? Is it necessary?BlitMask isn't necessary at all, but it can significantly improve scrolling performance. It's just another GreenSock tool that aims to make your life easier, your apps run better, and your clients happy. See the dedicated BlitMask page for details.
  6. Can I get the FLA from the video with the code that made the dial rotate?Sure. You can get it here (CS4).
  7. Can I use any ease that I want?Technically yes, but generally only easeOut eases look good. Quad.easeOut, Cubic.easeOut, Sine.easeOut, Expo.easeOut Strong.easeOut, Back.easeOut, etc. are all good options. If you need a detailed explanation as to why other eases don't work well, please ask in the forums or below.
  8. What about panel-based flick-scrolling like when flicking through photos on the iPhone/iPad? Can ThrowPropsPlugin help with that?Actually, that's much simpler than you might think and it doesn't require ThrowPropsPlugin. The logic is as follows:
    1. Sense the direction of the flick movement (right or left)
    2. If the velocity is more than a particular (relatively low) threshold, do a simple easeOut tween to the next (or previous) panel. Maybe 0.5 seconds or so.
    3. If the velocity is below that threshold, just do an easeOut tween to the current panel (to snap it back into position)

    I whipped together a sample set of files that demonstrates panel-based flick scrolling. Get it here. It looks like this:

    Get Adobe Flash player

  9. Is the API locked-down or might it change?No changes are planned to the API right now, but this is a brand new plugin and I'm committed to making improvements and enhancements if the need arises as it gets out into the wild and folks provide feedback. So yes, there could be some changes down the road. Please feel free to submit your feedback and suggestions.

Need help?

Feel free to post your question on the forums. You'll increase your chances of getting a prompt answer if you provide a brief explanation and include a simplified FLA file (and any class files) that clearly demonstrates the problem.

Get GSAP

Version: 1.19.0 updated 2016-07-18

Core

    Extras

      Plugins

        By using GreenSock code, you agree to the terms of use.

        For an all-access pass to premium content

        Join Club GreenSock