Jump to content
GreenSock

VelocityTracker.track()

VelocityTracker.track( target:Object, props:String, type:String ) : VelocityTracker

[static] Allows you to have the velocity of particular properties automatically tracked for you so that you can access them anytime using the VelocityTracker's getVelocity() method, like myTracker.getVelocity("y").

Parameters

target: Object

the target object whose properties will be tracked

props: String

(default = null) — a comma-delimited list of property names, like "y" or "x,y"

type: String

(default = num) — a comma-delimited list of property types (only helpful if they are rotation-based), "rad" for radian-based rotation or "deg" for degree-based rotation – this is only useful you’d like to have VelocityTracker compensate for artificial jumps in rotational values when the rotational midline is crossed, like when rotation goes from 179 to -178 degrees it would interpret that as a change of 3 instead of 357 degrees. Leave this blank unless you want the rotational compensation. You can use "num" to indicate normal numeric behavior (or leave it blank).

Returns : VelocityTracker

a VelocityTracker object that’s responsible for doing the tracking.

 

Details

Allows you to have the velocity of particular properties automatically tracked for you so that you can access them anytime using the VelocityTracker's getVelocity() method, likemyTracker.getVelocity("y"). For example, let's say there's an object that the user interacts with by dragging it or maybe it is being tweened and then at some point you want to create a tween that smoothly continues that motion and glides to a rest. Normally, you'd need to write your own tracking code that records that object's x and y properties (as well as time stamps) so that when it comes time to feed the velocity into the tween, you'd have the necessary data to calculate it. But let's face it: that can be cumbersome to do manually, and that's precisely why the track() method exists.

Just feed in the target and a comma-delimited list of properties that you want tracked like this:

var tracker = VelocityTracker.track(obj, "x,y");

Then every time the core tweening engine updates (at whatever frame rate you're running), the x and y values (or whichever properties you define) will be recorded along with time stamps (it keeps a maximum of 2 of these values and keeps writing over the previous ones, so don't worry about memory buildup). This even works with properties that are function-based, like getters and setters.

Then, after at least 100ms and 2 "ticks" of the core engine have elapsed (so that some data has been recorded), you can use the VelocityTracker's getVelocity() method to get the current velocity of a particular property.

//first, start tracking "x" and "y":
var tracker = VelocityTracker.track(obj, "x,y");

//then, after at least 100ms, we can get the velocity:
var vx = tracker.getVelocity("x");
var vy = tracker.getVelocity("y");

IMPORTANT: you should untrack() properties when you no longer need them tracked in order to maximize performance and ensure things are released for garbage collection. To untrack, simply use the untrack()
 method:

//stop tracking only the "x" property: 
VelocityTracker.untrack(obj, "x");

//stop tracking "x" and "y":
VelocityTracker.untrack(obj, "x,y");

//stop tracking all properties of obj:
VelocityTracker.untrack(obj);

What kinds of properties can be tracked?

Pretty much any numeric property of any object can be tracked, including function-based ones. For example, obj.x or obj.rotation or even obj.myCustomProp(). In fact, for getters and setters that start with the word "get" or "set" (like getCustomProp() and setCustomProp()), it will automatically find the matching counterpart method and use the getter appropriately, so you can track the getter or setter and it'll work. You cannot, however, track custom plugin-related values like "directionalRotation" or "autoAlpha" or "physics2D" because those aren't real properties of the object. You should instead track the real properties that those plugins affect, like "rotation" or "alpha" or "x" or "y".

Copyright 2017, GreenSock. All rights reserved. This work is subject to theterms of useor for Club GreenSock members, the software agreement that was issued with the membership.
×