2D Component

Component for any entity that has a position on the stage.

Events

Move [Old position = { _x:Number, _y:Number, _w:Number, _h:Number }]
when the entity has moved
Invalidate
when the entity needs to be redrawn
Rotate [Rotation in degrees = { rotation:Number}]
when the entity is rotated
Reorder
when the entity's z index has changed
Resize [Data = { axis: 'w' | 'h', amount: Number }]
when the entity's dimensions have changed

Properties

Methods

Back to top

._globalZ

When two entities overlap, the one with the larger _globalZ will be on top of the other.

Back to top

.h

The height of the entity. When modified, will automatically be redrawn. Is actually a getter/setter so when using this value for calculations and not modifying it, use the ._h property.

Changing this value is not recommended as canvas has terrible resize quality and DOM will just clip the image.

See Also

Back to top

.ox

The x position on the stage of the origin. When modified, will set the underlying x value of the entity.

See Also

Back to top

.oy

The y position on the stage of the origin. When modified, will set the underlying y value of the entity.

See Also

Back to top

.rotation

The rotation state of the entity, in clockwise degrees. this.rotation = 0 sets it to its original orientation; this.rotation = 10 sets it to 10 degrees clockwise from its original orientation; this.rotation = -10 sets it to 10 degrees counterclockwise from its original orientation, etc.

When modified, will automatically be redrawn. Is actually a getter/setter so when using this value for calculations and not modifying it, use the ._rotation property.

this.rotation = 0 does the same thing as this.rotation = 360 or 720 or -360 or 36000 etc. So you can keep increasing or decreasing the angle for continuous rotation. (Numerical errors do not occur until you get to millions of degrees.)

The default is to rotate the entity around its (initial) top-left corner; use .origin() to change that.

Back to top

.x

The x position on the stage. When modified, will automatically be redrawn. Is actually a getter/setter so when using this value for calculations and not modifying it, use the ._x property.

See Also

Back to top

.z

The z index on the stage. When modified, will automatically be redrawn. Is actually a getter/setter so when using this value for calculations and not modifying it, use the ._z property.

A higher z value will be closer to the front of the stage. A smaller z value will be closer to the back. A global Z index is produced based on its z value as well as the GID (which entity was created first). Therefore entities will naturally maintain order depending on when it was created if same z value.

z is required to be an integer, e.g. z=11.2 is not allowed.

See Also

Back to top

._cascade()

public void ._cascade(e)
e

An object describing the motion

Move the entity's children according to a certain motion. This method is part of a function bound to "Move": It is used internally for ensuring that when a parent moves, the child also moves in the same way.

Back to top

.w

The width of the entity. When modified, will automatically be redrawn. Is actually a getter/setter so when using this value for calculations and not modifying it, use the ._w property.

Changing this value is not recommended as canvas has terrible resize quality and DOM will just clip the image.

See Also

Back to top

.y

The y position on the stage. When modified, will automatically be redrawn. Is actually a getter/setter so when using this value for calculations and not modifying it, use the ._y property.

See Also

Back to top

._cascadeRotation()

public void ._cascade(deg)
deg

The amount of rotation in degrees

Move the entity's children the specified amount This method is part of a function bound to "Move": It is used internally for ensuring that when a parent moves, the child also moves in the same way.

Back to top

.area()

public Number .area(void)

Calculates the area of the entity

Back to top

.attach()

public this .attach(Entity obj[, .., Entity objN])
obj

Child entity(s) to attach

Sets one or more entities to be children, with the current entity (this) as the parent. When the parent moves or rotates, its children move or rotate by the same amount. (But not vice-versa: If you move a child, it will not move the parent.) When the parent is destroyed, its children are destroyed.

For any entity, this._children is the array of its children entity objects (if any), and this._parent is its parent entity object (if any).

As many objects as wanted can be attached, and a hierarchy of objects is possible by attaching.

Back to top

.contains()

public Boolean .contains(Number x, Number y, Number w, Number h)
x

X position of the rect

y

Y position of the rect

w

Width of the rect

h

Height of the rect

public Boolean .contains(Object rect)
rect

An object that must have the _x, _y, _w, _h values as properties.

Determines if the rectangle is within the current entity. If the entity is rotated, its MBR is used for the test.

Back to top

.detach()

public this .detach([Entity obj])
obj

The entity to detach. Left blank will remove all attached entities

Stop an entity from following the current entity. Passing no arguments will stop every entity attached.

Back to top

.intersect()

public Boolean .intersect(Number x, Number y, Number w, Number h)
x

X position of the rect

y

Y position of the rect

w

Width of the rect

h

Height of the rect

public Boolean .intersect(Object rect)
rect

An object that must have the _x, _y, _w, _h values as properties

Determines if this entity intersects a rectangle. If the entity is rotated, its MBR is used for the test.

Back to top

.isAt()

public Boolean .isAt(Number x, Number y)
x

X position of the point

y

Y position of the point

Determines whether a point is contained by the entity. Unlike other methods, an object can't be passed. The arguments require the x and y value.

The given point is tested against the first of the following that exists: a mapArea associated with "Mouse", the hitarea associated with "Collision", or the object's MBR.

Back to top

.mbr()

public Object .mbr([Object mbr])
mbr

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 a copy of this entity's minimum bounding rectangle. The MBR encompasses a rotated entity's bounds. If there is no rotation on the entity it will return its bounds (.pos()) instead.

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).

See Also

Back to top

.move()

public this .move(String dir, Number by)
dir

Direction to move (n,s,e,w,ne,nw,se,sw)

by

Amount to move in the specified direction

Quick method to move the entity in a direction (n, s, e, w, ne, nw, se, sw) by an amount of pixels.

Back to top

.offsetBoundary()

Extends the MBR of the entity by a specified amount.

Events

BoundaryOffset
when the MBR offset changes
public this .offsetBoundary(Number dx1, Number dy1, Number dx2, Number dy2)
dx1

Extends the MBR to the left by this amount

dy1

Extends the MBR upward by this amount

dx2

Extends the MBR to the right by this amount

dy2

Extends the MBR downward by this amount

public this .offsetBoundary(Number offset)
offset

Extend the MBR in all directions by this amount

You would most likely use this function to ensure that custom canvas rendering beyond the extent of the entity's normal bounds is not clipped.

Back to top

.origin()

public this .origin(Number x, Number y)
x

Pixel value of origin offset on the X axis

y

Pixel value of origin offset on the Y axis

public this .origin(String offset)
offset

Alignment identifier, which is a combination of center, top, bottom, middle, left and right

Set the origin point of an entity for it to rotate around.

The properties ox and oy map to the coordinates of the origin on the stage; setting them moves the entity. In contrast, this method sets the origin relative to the entity itself.

Events

OriginChanged -- after the new origin is assigned

Example

this.origin("top left")
this.origin("center")
this.origin("bottom right")
this.origin("middle right")

The origin should be set before changing the rotation, since it does not apply retroactively. Additionally, setting the origin via an alignment identifier works only after the entity's dimensions have been set. These points are shown in the following example:

Example

Crafty.e("2D")
      .attr({w: 100, h: 100})
      .origin('center')
      .attr({x: 25, y: 25, rotation: 180});
Back to top

.pos()

public Object .pos([Object pos])
pos

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 a copy of this entity's bounds (_x, _y, _w, and _h values).

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).

Back to top

.shift()

public this .shift(Number x, Number y, Number w, Number h)
x

Amount to move X

y

Amount to move Y

w

Amount to widen

h

Amount to increase height

Shift or move the entity by an amount. Use negative values for an opposite direction.

Back to top

.within()

public Boolean .within(Number x, Number y, Number w, Number h)
x

X position of the rect

y

Y position of the rect

w

Width of the rect

h

Height of the rect

public Boolean .within(Object rect)
rect

An object that must have the _x, _y, _w, _h values as properties

Determines if this current entity is within another rectangle.