Collision

Component to detect collision between any two convex polygons.

If collision checks are registered for multiple component and collisions with multiple types occur simultaniously, each collision will cause an individual event to fire.

Note: All data received from events is only valid for the duration of the event's callback. If you wish to preserve the data, make a copy of it.

For a description of collision event data (hitData above), see the documentation for .hit().

Events

HitOn [Data: { hitData }]
Triggered when collisions occur. Will not trigger again until collisions of this type cease, or an event is requested once more (using resetHitChecks(component)).
HitOff [Data: { componentName }]
Triggered when collision with a specific component type ceases

See Also

Back to top

.init

Set up collision handling.

By default, the collision hitbox will match the dimensions (x, y, w, h) and rotation of the object.

Note: If the entity this component is applied to does not have its dimensions set the default hit area will not be set properly.

Back to top

.collision

public this .collision([Crafty.polygon polygon])

polygon
Crafty.polygon object that will act as the hit area.

public this .collision(Array point1, .., Array pointN)

point#
Array of [x, y] coordinate pairs to generate a hit area polygon.

Constructor that takes a polygon or array of points to use as the hit area, with points being relative to the object's position in its unrotated state.

The hit area must be a convex shape and not concave for collision detection to work properly.

If no parameter is passed, the x, y, w, h properties of the entity will be used, and the hitbox will be resized when the entity is.

If a hitbox is set that is outside of the bounds of the entity itself, there will be a small performance penalty as it is tracked separately.

Example

Crafty.e("2D, Collision").collision(
    new Crafty.polygon([50,0], [100,100], [0,100])
);

Crafty.e("2D, Collision").collision([50,0], [100,100], [0,100]);

Events

NewHitbox [Data: Crafty.polygon]
when a new hitbox is assigned

See Also

Back to top

.hit

public Boolean/Array hit(String component)

component
Check collision with entities that have this component
applied to them.

[returns]
false if there is no collision. If a collision is detected,
returns an Array of collision data objects (see below).

Tests for collisions with entities that have the specified component applied to them. If a collision is detected, data regarding the collision will be present in the array returned by this method. If no collisions occur, this method returns false.

Following is a description of a collision data object that this method may return: The returned collision data will be an Array of Objects with the type of collision used, the object collided and if the type used was SAT (a polygon was used as the hitbox) then an amount of overlap.

[{
   obj: [entity],
   type: ["MBR" or "SAT"],
   overlap: [number]
}]

obj: The entity with which the collision occured. type: Collision detection method used. One of:

  • MBR: Standard axis aligned rectangle intersection (.intersect in the 2D component).
  • SAT: Collision between any two convex polygons. Used when both colliding entities have the Collision component applied to them. overlap: If SAT collision was used, this will signify the overlap percentage between the colliding entities.

See Also

Back to top

.onHit

public this .onHit(String component, Function hit[, Function noHit])

component
Component to check collisions for.
hit
Callback method to execute upon collision with component. Will be passed the results of the collision check in the same format documented for hit().
noHit
Callback method executed once as soon as collision stops.

Creates an EnterFrame event calling .hit() each frame. When a collision is detected the callback will be invoked. Note that the hit callback will be invoked every frame the collision is active, not just the first time the collision occurs. If you want more fine-grained control consider using .checkHits or .hit.

See Also

Back to top

._createCollisionHandler

public void .checkHits(String component, Object collisionData)

component
The name of the component for which this handler
checks for collisions.

collisionData
Collision data object used to track collisions with
the specified component.

This is a helper method for creating collisions handlers set up by .checkHits(...). Do not call this directly.

See Also

Back to top

.checkHits

public this .checkHits(String componentList)

componentList
A comma seperated list of components to check for collisions with.
public this .checkHits(String component1[, .., String componentN])
component#
A component to check for collisions with.

Performs collision checks against all entities that have at least one of the components specified when calling this method. If collisions occur, a "HitOn" event containing the collision information will be fired for the entity on which this method was invoked. See the documentation for .hit() for a description of collision data contained in the event. When a collision that was reported ends, a corresponding "HitOff" event will be fired.

Calling this method more than once for the same component type will not cause redundant hit checks.

Note: Hit checks are performed upon entering each new frame (using the EnterFrame event). It is entirely possible for object to move in said frame after the checks were performed (even if the more is the result of EnterFrame, as handlers run in no particular order). In such a case, the hit events will not fire until the next check is performed in the following frame.

Example

Crafty.e("2D, Collision")
    .checkHits('Solid') // check for collisions with entities that have the Solid component in each frame
    .bind("HitOn", function(hitData) {
        console.log("Collision with Solid entity occurred for the first time.");
    })
    .bind("HitOff", function(comp) {
        console.log("Collision with Solid entity ended.");
    });

See Also

Back to top

.ignoreHits

public this .ignoreHits()

public this .ignoreHits(String componentList)

componentList
A comma seperated list of components to stop checking
for collisions with. public this .ignoreHits(String component1[, .., String componentN])
component#
A component to stop checking for collisions with.

Stops checking for collisions with all, or certain, components. If called without arguments, this method will cause all collision checks on the entity to cease. To disable checks for collisions with specific components, specify the components as a comma separated string or as a set of arguments.

Calling this method with component names for which there are no collision checks has no effect.

Example

Crafty.e("2D, Collision")
    .checkHits('Solid')
    ...
    .ignoreHits('Solid'); // stop checking for collisions with entities that have the Solid component
Back to top

.resetHitChecks

public this .resetHitChecks()

public this .resetHitChecks(String componentList)

componentList
A comma seperated list of components to re-check
for collisions with. public this .resetHitChecks(String component1[, .., String componentN])
component#
A component to re-check for collisions with.

Causes collision events to be received for collisions that are already taking place (normally, an additional event would not fire before said collisions cease and happen another time). If called without arguments, this method will cause all collision checks on the entity to fire events once more. To re-check for collisions with specific components, specify the components as a comma separated string or as a set of arguments.

Calling this method with component names for which there are no collision checks has no effect.

Example

// this example fires the HitOn event each frame the collision with the Solid entity is active, instead of just the first time the collision occurs.
Crafty.e("2D, Collision")
    .checkHits('Solid')
    .bind("HitOn", function(hitData) {
        console.log("Collision with Solid entity was reported in this frame again!");
        this.resetHitChecks('Solid'); // fire the HitOn event in the next frame also, if the collision is still active.
    })