BezierPlugin

Included in TweenMax: YES

Animate virtually any property (or properties) along a curved Bezier path which you define as an array of points/values that can be interpreted 4 different ways (described as the Bezier's "type", like type:"soft"):

• "thru" (the default) - the plugin figures out how to draw the Bezier naturally through the supplied values using a proprietary algorithm. The values you provide in the array are essentially treated as anchors on the Bezier and the plugin calculates the control points. The target's current/starting values are used as the initial anchor. You can define a curvinessspecial property that allows you to adjust the tension on the Bezier where 0 has no curviness (straight lines), 1 is normal curviness, 2 is twice the normal curviness, etc. Since "thru" is the default Bezier type, you don't need to define a type at all if this is the one you want.
• "soft" - the values that you provide in the array act almost like magnets that attract the curve towards them, but the Bezier doesn't typically travel through them. They are treated as control points on a Quadratic Bezier and the plugin creates the necessary intermediate anchors. The target's current/starting values are used as the initial anchor.
• "quadratic" - allows you to define standard Quadratic Bezier data (Quadratic Beziers have 1 control point between each anchor). The array should start with the first anchor, then control point, then anchor, control point, etc. for as many iterations as you want, but obviously make sure that it starts and ends with anchors.
• "cubic" - allows you to define standard Cubic Bezier data (Cubic Beziers have 2 control points between each anchor). The array should start with the first anchor, then 2 control points, then anchor, 2 control points, anchor, etc. for as many iterations as you want, but obviously make sure that it starts and ends with anchors.

While it is most common to use x and y (or left and top) properties for Bezier tweens, you can use any properties (even ones that are function-based getters/setters).

Inside the bezier object, you must define at least a values property, and there are several other optional special properties that the BezierPlugin will recognize. Here is a list of them all:

• values : Array [REQUIRED] - the array of your Bezier values as generic objects. Each object in the array should have matching property names (like "x" and "y"). For example, the array might look like: [{x:100, y:250}, {x:300, y:0}, {x:500, y:400}]
• type : String (default:"thru") - Either "thru", "soft", "quadratic", or "cubic" as described above, indicating how the values should be interpreted.
• timeResolution : Number (default:6) - due to the nature of Beziers, plotting the progression of an object on the path over time can make it appear to speed up or slow down based on the placement of the control points and the length of each successive segment on the path, so BezierPlugin implements a technique that reduces or eliminates that variance, but it involves breaking the segments down into a certain number of pieces which is what timeResolution controls. The greater the number, the more accurate the time remapping but there is a processing price to pay for greater precision. The default value of 6 is typically fine, but if you notice slight pace changes on the path you can increase the timeResolutionvalue. Or, if you want to prioritize speed you could reduce the number. If you use a timeResolution value of 0, no length measurements will take place internally which delivers maximum processing speed, but you may notice changes in speed during the animation.
• curviness : Number (default:1) (only applies to type:"thru") - allows you to adjust the tension on the Bezier where 0 has no curviness (straight lines), 1 is normal curviness, 2 is twice the normal curviness, etc. Use any number, not just integers
• autoRotate : Boolean, Number, or Array (default:false) - to automatically rotate the target according to its position on the Bezier path, you can use the autoRotate feature. If your Bezier is affecting the "x" and "y" (or "left" and "top") properties of your target and you don't need to offset the rotation by a certain amount more than normal, then you can simply setautoRotate:true. Or if you want to offset the rotation by a certain amount (in degrees), you can define a number like autoRotate:90 (adding 90 degrees in this example). Or for more advanced controls, you can define autoRotate as an array. In order to adjust a rotation property accurately, the plugin needs 5 pieces of information:
  1. Position property 1 (typically "x" or "left")
  2. Position property 2 (typically "y" or "top")
  3. Rotational property (typically "rotation")
  4. Number of degrees (or radians) to add to the new rotation (optional - makes it easy to orient your target properly)
  5. Boolean value indicating whether or not the rotational property should be defined in radians rather than degrees (default is false which results in degrees)

  The autoRotate property should be an Array containing these values, like ["x","y","rotation",90*Math.PI/180,true]. And if you need to affect multiple rotational properties (like in 3D tweens where the Bezier is going through x,y,z points which could affect rotationX, rotationY, and rotationZ), you can use an array of arrays, like[["x","y","rotationZ",0,false], ["z","x","rotationY",0,false], ["z","y","rotationX",0,false]].

• correlate : String (default:"x,y,z,left,top,right,bottom,marginLeft,marginTop,marginRight,marginBottom,paddingLeft,paddingTop,paddingRight,paddingBottom") (only applies totype:"thru") - a comma-delimited list of property names whose relative distances should be correlated when calculating the Bezier that travels through the points. Since x, y, z, left, top, etc. are all spacial, it is almost always good to correlate them, but properties like scaleX, scaleY, etc. don't typically need to be correlated. It is rarely necessary to alter the defaultcorrelate value, so there's typically no need to even define one at all (let the plugin use its defaults).

IMPORTANT: if you are trying to do a bezier tween of css-related properties, make sure you load the CSSPlugin (it's already included inside TweenMax, but if you're using only TweenLite, you'll need to load the CSSPlugin and BezierPlugin separately)

SYNTAX

//tween the "left" and "top" css properties through the supplied values (notice we're passing the array directly to the bezier rather than creating an object with "values" because we're accepting the defaults)
TweenMax.to(document.getElementById("myDiv"), 5, {bezier:[{left:100, top:250}, {left:300, top:0}, {left:500, top:400}], ease:Power1.easeInOut});
 
//if we want to customize things, like the curviness and setting autoRotate:true, we need to define the bezier as an object instead, and pass our array as the "values" property
TweenMax.to(document.getElementById("myDiv"), 5, {bezier:{curviness:1.25, values:[{x:100, y:250}, {x:300, y:0}, {x:500, y:400}], autoRotate:true}, backgroundColor:"#f00", ease:Power1.easeInOut});
 
//let's define the type as "soft" instead of using the default "thru"
TweenMax.to(document.getElementById("myDiv"), 5, {bezier:{type:"soft", values:[{x:100, y:250}, {x:300, y:0}, {x:500, y:400}], autoRotate:true}, ease:Power1.easeInOut});
 
//now we'll do a cubic Bezier and make our target auto rotate but add 45 degrees to the rotation
TweenMax.to(document.getElementById("myDiv"), 5, {bezier:{type:"cubic", values:[{x:100, y:250}, {x:150, y:100}, {x:300, y:500}, {x:500, y:400}], autoRotate:["x","y","rotation",45,false]}, ease:Power1.easeInOut});
 
//NON-CSS, generic x/y property tween: animate obj through the points in the array (notice we're passing the array directly to the bezier rather than creating an object with "values" because we're accepting the defaults)
TweenMax.to(obj, 5, {bezier:[{x:100, y:250}, {x:300, y:0}, {x:500, y:400}], ease:Power1.easeInOut});

You can tap into BezierPlugin's Bezier drawing algorithm by passing its bezierThrough() method your array of points/objects and it will spit back and object with all the necessary data, either in Cubic Bezier form or in Quadratic Bezier form so that you could, for example, draw the path using the canvas's drawing API. It also has some useful static cubicToQuadratic() andquadraticToCubic() conversion methods.