iio Kinematics Engine

Kinematics is a branch of mechanics that deals with the motion of objects without consideration of causal forces.

iio provides an attachment called the 'iio Kinematics Engine' that implements many of the basic functions that a kinematics driven application will need.

Put simply, this framework makes it easy to get objects moving, rotating, and colliding.

The framework attaches to the Shape class, so all iio Shape classes can access its properties and functions.

The attachment does not happen by default. You must call the enableKinematics function to trigger an attachment.

Kinematics properties will only take effect if a framerate has been set on the shape or the canvas that contains the shape.

//create an new Rect and enable kinematics
var box = new iio.Rect(0,0,50).enableKinematics();

//we can now use the kinematics functions
box.setVel(0,4);

//Kinematics properties are not defined by default
//you must call a 'set' function or define them directly
var t = box.torque //will be 'undefined'
var v = box.vel //returns a vector, since we used
                //setVel already

//Must set a framerate for things to move
io.setFramerate(60);
 

Properties

Kinematics properties are 'undefined' by default.

 

vel :: Vec

Available to: Shape

- This objects velocity vector.

- This property can be set with the setVel function.

//set the vel property directly
shape.vel = new iio.Vec(4,5);

//change the vel properties directly
shape.vel.x = -4;
shape.vel.y = -5;

//change the property with its set function
shape.setVel(5,4);
 

acc :: Vec

Available to: Shape

- This objects acceleration vector.

- This property can be set with the setAcc function.

//set the acc property directly
shape.acc = new iio.Vec(4,5);

//change the vel properties directly
shape.acc.x = -.04;
shape.acc.y = -.05;

//change the property with its set function
shape.setAcc(.05,.04);
 

torque :: Number

Available to: Shape

- Sets the speed and direction of an objects rotation. This value is measured in radians.

- This property can be set with the setTorque function.

//set the torque property directly
shape.torque = .01;

//change the property with its set function
shape.setTorque(.02);
 

bounds :: Object

Available to: Shape

- An object that holds this shapes boundaries and boundary callback functions.

- bounds has the following structure:

: bounds.top.val :: Number :: the top bound y coordinate

: bounds.top.callback :: Function :: the top bound callback function

: bounds.right.val :: Number :: the right bound y coordinate

: bounds.right.callback :: Function :: the right bound callback function

: .... identical for bottom and left

: bounds.callback :: Function :: the bounds callback function

- If an object crosses a 'bound' and that bounds callback exists, the callback will be called. If no callback is specified, the primary bounds.callback function will be called. If that function doesn't exist, the object will remove itself. If you want to remove the object in your custom bound callback code, return false.

//create a square that will move down from canvas center
//and remove itself when it hits the bottom of the screen
var square = new iio.Rect(io.canvas.center,50)
                  .enableKinematics()
                  .setVel(0,1)
                  .setBound('bottom', io.canvas.height);

//create a square that will move down from canvas center
//and reverse its direction when it hits the bottom of the screen
var square = new iio.Rect(io.canvas.center,50)
                  .enableKinematics()
                  .setVel(0,1)
                  .setBound('bottom', io.canvas.height
                    ,function(obj){
                      obj.vel.y = -1;
                      return true;
                     });
 

Functions

Kinematics functions are attached to a shape when you call enableKinematics.

The function enableKinematics is attached by default.

All kinematics functions return a reference to the object that called them.

 

.enableKinematics()

Available to: Shape

- Attaches all of the following kinematics functions to the object.

//create a new box with kinematics
var box = new iio.Rect(0,0,100).enableKinematics();
 

.update()

Available to any kinematics enabled object

- Translates this object by its velocity vector and rotates it by its torque value.

- This function is automatically called by your AppManager when you set a framerate on either the object, or the canvas that hold the object.

 

.setVel( Vector v )

.setVel( Number: vX, vY )

Available to any kinematics enabled object.

- Sets this objects velocity. The default value for both parameters is 0.

//change an objects velocity
myObj.setVel(2,5);
 

.setAcc( Vector v )

.setAcc( Number: vX, vY )

Available to any kinematics enabled object.

- Sets this objects acceleration. The default value for both parameters is 0.

//change an objects acceleration
myObj.setAcc(.05,-.04);
 

.setTorque( Number t )

Available to any kinematics enabled object.

- Sets this objects torque to the given value.

//set an objects torque
myObj.setTorque(.01);
 

.setBound( String boundName, Number boundCoordinate, Function callback )

Available to any kinematics enabled object.

- Sets a bound property on this object. Refer to this page for more info about bounds.

- If a callback function is not specified, the object will remove itself when it reaches the bound.

- Available bound names are: top, right, bottom, and left.

//set a bound on an object
myObj.setBound('bottom', io.canvas.height);

//set a bound with a callback function
myObj.setBound('bottom', io.canvas.height
                    ,function(obj){
                      //perform some action
                      return true;//keep the object
                     });
 

.setBounds( Number: top, right, bottom, left, Function callback )

Available to any kinematics enabled object.

- Sets up to 4 bounds on an object at once, and allows you to set one callback function for all the bounds.

- If a callback function is not specified, the object will remove itself when it reaches a bound.

- You can leave a bound out by passing null in its place.

//set one bound function for the top and bottom
myObj.setBounds(0, null, io.canvas.height, null
                    ,function(obj){
                      //perform some action
                      return true;//keep the object
                     });