README
Popmotion Collision Detector
Collision detection for Popmotion Actors
In-built support for DOM and SVG elements. Customisable Roles allow you to create your own support for Three.js, canvas, etc.
Actors receive onCollisionEnter
, onCollisionExit
and onCollisionStay
events during the preRender
step of the Popmotion render loop.
Currently supports circular and rectangular, axis-aligned Actors only.
Install
In your project root:
$ npm install popmotion-collision --save
In your module:
// New hotness
import CollisionDetector from 'popmotion-collision';
// Old and busted
var CollisionDetector = require('popmotion-collision');
Use
new CollisionDetector(actors[, role]);
Track collisions between Actors
new CollisionDetector(Iterator || array);
The CollisionDetector
constructor accepts either a Popmotion Iterator or a plain array of Actors. Once created, all Actors are automatically checked for collisions.
Example: Track DOM elements
let elements = ui.select('div', {
onCollisionEnter: function (actor, otherActor) {
console.log('collision!')
}
});
let collisionDetector = new CollisionDetector(elements);
Track collisions between Actors of the same shape
Collision Detector currently supports collision detection between two shapes of the same type, rectangular and circular.
Set an Actor's shape
property for non-rectangular shapes:
new Actor({
element: yourElement,
shape: CollisionDetector.CIRCLE
});
Methods
sync()
Sync Actor collider models with their actual physical representations. Called on initialisation, and should be called whenever anActor.element
changes physical position outside of Popmotion.pause()
Pause collision detection. Collision detection is a backgroundProcess
, so it only runs during active frames. This means manually managing the collision detection process is not required under normal circumstances.resume()
Resume collision detection.
Actor properties
collider
[object] READ-ONLY CollisionDetector's calculated model of theActor.element
's physical representation. This can be used to calculate collision resolutions.onCollisionEnter
[function] Fired the first frame an Actor collides with another Actor.onCollisionExit
[function] Fired the first frame an Actor stops colliding with another Actor.onCollisionStay
[function] Fired every frame an Actor is colliding with another Actor.shape
[string] (defaultCollisionDetector.RECT
) The physical shape of the Actor.
Create a custom Role
By default, DOM and SVG Actors are automatically recognised and assigned appropriate Roles. However, a custom Role can be provided as an object of required methods as the final constructor argument.
Role methods
getAbsolutePosition(element, actor)
(Returns{x, y, width, height}
) Calculate the current absolute position of the element. Because Actor values are not neccessarily indicative of where the Actor's element physically resides (think two DOM elements withx
of0
yet floated next to each other), and every type of Actor (DOM, SVG etc) has a different method of calculating its absolute position, we use this method to abstract that calculation.