# Motion Component

#### Events

NewDirection [New direction = { x: -1 | 0 | 1, y: -1 | 0 | 1 }]
When entity has changed direction due to velocity on either x or y axis a NewDirection event is triggered. The event is triggered once, if direction is different from last frame.
MotionChange [Motion property name and old value = { key: String, oldValue: Number }]
When a motion property has changed a MotionChange event is triggered.

Component that allows moving an entity by applying linear velocity and acceleration. All linear motion values are expressed in pixels per second (e.g. an entity with `vx` of 1 will move 1px on the x axis each second).

Note: Several methods return Vector2D objects that dynamically reflect the entity's underlying properties. If you want a static copy instead, use the vector's `clone()` method.

## .ax

A property for accessing/modifying the linear acceleration in the x axis. The acceleration changes the velocity over time.

#### Example

``````var ent = Crafty.e("2D, Motion");

var ax = ent.ax; // retrieve the linear acceleration in the x axis
ent.ax += 1; // increase the linear acceleration in the x axis
ent.ax = 0; // reset the linear acceleration in the x axis``````

## .ay

A property for accessing/modifying the linear acceleration in the y axis. The acceleration changes the velocity over time.

#### Example

``````var ent = Crafty.e("2D, Motion");

var ay = ent.ay; // retrieve the linear acceleration in the y axis
ent.ay += 1; // increase the linear acceleration in the y axis
ent.ay = 0; // reset the linear acceleration in the y axis``````

## .dx

A number that reflects the change in x (difference between the old & new x) that was applied in the last frame.

#### Example

``````var ent = Crafty.e("2D, Motion");

var dx = ent.dx; // the change of x in the last frame``````

## .dy

A number that reflects the change in y (difference between the old & new y) that was applied in the last frame.

#### Example

``````var ent = Crafty.e("2D, Motion");

var dy = ent.dy; // the change of y in the last frame``````

## .acceleration()

Method for accessing/modifying the linear(x,y) acceleration. The acceleration increases the velocity over time, resulting in ever increasing speed.

`public Vector2D .acceleration()`
[Returns]

The acceleration Vector2D with the properties {x, y} that reflects the acceleration in the direction of the entity.

Returns the current acceleration. You can access/modify the properties in order to retrieve/change the acceleration.

#### Example

``````var ent = Crafty.e("2D, Motion");

var acc = ent.acceleration(); //returns the acceleration object
acc.x;       // retrieve the acceleration in the x direction
acc.x = 0;   // set the acceleration in the x direction
acc.x += 4   // add to the acceleration in the x direction``````

## .motionDelta()

`public Vector2D .motionDelta()`
[Returns]

A Vector2D with the properties {x, y} that reflect the change in x & y.

Returns the difference between the old & new position that was applied in the last frame.

#### Example

``````var ent = Crafty.e("2D, Motion");

var deltaY = ent.motionDelta().y; // the change of y in the last frame``````

## .resetMotion()

`public this .resetMotion()`
[Returns]

this

Reset all linear motion (resets velocity, acceleration, motionDelta).

## .velocity()

Method for accessing/modifying the linear(x,y) velocity. The velocity remains constant over time, unless the acceleration increases the velocity.

`public Vector2D .velocity()`
[Returns]

The velocity Vector2D with the properties {x, y} that reflect the velocities in the direction of the entity.

Returns the current velocity. You can access/modify the properties in order to retrieve/change the velocity.

#### Example

``````var ent = Crafty.e("2D, Motion");

var vel = ent.velocity(); //returns the velocity vector
vel.x;       // retrieve the velocity in the x direction
vel.x = 0;   // set the velocity in the x direction
vel.x += 4   // add to the velocity in the x direction``````

## .vx

A property for accessing/modifying the linear velocity in the x axis. The velocity remains constant over time, unless the acceleration changes the velocity.

#### Example

``````var ent = Crafty.e("2D, Motion");

var vx = ent.vx; // retrieve the linear velocity in the x axis
ent.vx += 1; // increase the linear velocity in the x axis
ent.vx = 0; // reset the linear velocity in the x axis``````

## .vy

A property for accessing/modifying the linear velocity in the y axis. The velocity remains constant over time, unless the acceleration changes the velocity.

#### Example

``````var ent = Crafty.e("2D, Motion");

var vy = ent.vy; // retrieve the linear velocity in the y axis
ent.vy += 1; // increase the linear velocity in the y axis
ent.vy = 0; // reset the linear velocity in the y axis``````

## .ccdbr()

`public Object .ccdbr([Object ccdbr])`
ccdbr

an object to use as output

[Returns]

an object with `_x`, `_y`, `_w`, and `_h` properties; if an object is passed in, it will be reused rather than creating a new object.

Return an object containing the entity's continuous collision detection bounding rectangle. The CCDBR encompasses the motion delta of the entity's bounding rectangle since last frame. The CCDBR is minimal if the entity moved on only one axis since last frame, however it encompasses a non-minimal region if it moved on both axis. For further details, refer to FAQ#Tunneling.

Note: The keys have an underscore prefix. This is due to the x, y, w, h properties being setters and getters that wrap the underlying properties with an underscore (_x, _y, _w, _h).