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 an Actor.element changes physical position outside of Popmotion.
pause() Pause collision detection. Collision detection is a background Process, 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 the Actor.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] (default CollisionDetector.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 with x of 0 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.

Usage no npm install needed!