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
- ._cascade()
- ._cascadeRotation()
- .area()
- .attach()
- .contains()
- .detach()
- .intersect()
- .isAt()
- .mbr()
- .move()
- .offsetBoundary()
- .origin()
- .pos()
- .shift()
- .within()
._globalZ
When two entities overlap, the one with the larger _globalZ will be on top of the other.
.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
.ox
The x position on the stage of the origin. When modified, will set the underlying x value of the entity.
See Also
.oy
The y position on the stage of the origin. When modified, will set the underlying y value of the entity.
See Also
.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.
See Also
.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
.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
._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.
.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
.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
._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.
.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.
.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, _hvalues as properties.
Determines if the rectangle is within the current entity. If the entity is rotated, its MBR is used for the test.
.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.
.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, _hvalues as properties
Determines if this entity intersects a rectangle. If the entity is rotated, its MBR is used for the test.
.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.
.mbr()
public Object .mbr([Object mbr])- mbr
an object to use as output
- [Returns]
an object with
_x,_y,_w, and_hproperties; 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
.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.
.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.
.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});.pos()
public Object .pos([Object pos])- pos
an object to use as output
- [Returns]
an object with
_x,_y,_w, and_hproperties; 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).
.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.
.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, _hvalues as properties
Determines if this current entity is within another rectangle.
google groups
starwed@gmail.com
github