swift-collider v0.1.0

Table of Contents

• Geometry
  • Vector
  • Circle
  • Box
  • Polygon
• Collisions
  • pointInCircle
  • pointInPolygon
  • testPolygonPolygon
  • testPolygonCircle
  • testCircleCircle
  • testCirclePolygon

Prologue

Note, this project uses https://github.com/jriecken/sat-js as a foundation and builds on it. I will actively send updates that I find useful to the original repository as I find it to be a great resource still.

If you find swift-collider useful please check out the original repository and give credit to the author.

Install

To install swift-collider, use:

$ npm install swift-collider

Initialization

If you're using swift-collider in a browser environment, you can use the swift-collider.js file found in the root directory or just a reference to the package if you're using webpack.

browser

// Non-webpack environment:
import SwiftCollider from '../node_modules/swift-collider/swift-collider.js';

// Webpack/other bundler environment:
import SwiftCollider from 'swift-collider';

and in a Node environment, you can imply require the module:

node

const SwiftCollider = require('swift-collider');

lastly you just have to make a new instance of SwiftCollider like so:

const sc = new SwiftCollider();

Geometry

swift-collider revolves around points and shapes, more specifically vectors, circles, and polygons.

Vector

A vector is a point in 2D space that has a x and y position.

example:

const vec1 = sc.vector(10, 25);

To see the full list of properties and methods for circles, check out the vector documentation.

Circle

A circle consists of a center position and a radius.

example:

const circle = sc.circle(sc.vector(5, 5), 10);

To see the full list of properties and methods for circles, check out the circles documentation.

Polygon

A polygon consists of a convex shape with any number of points (specified in a counter-clockwise order).

example:

const polygon = sc.polygon(sc.vector(0, 0), [
  sc.vector(0, 0),
  sc.vector(40, 0),
  sc.vector(40, 40),
  sc.vector(0, 40)
]);

To see the full list of properties and methods for polygons, check out the polygon documentation.

Box

A box represents an axis-aligned bounding box with a width and a height.

example:

const box = sc.box(sc.vector(5, 10), 100, 250);

To see the full list of properties and methods for boxes, check out the box documentation.

Collisions

There are three different types of collisions: point, circle, and polygon collisions.

Some collisions (testCircleCircle, testPolygonPolygon, testPolygonCircle, testCirclePolygon) have a details parameter that can be used to return extra details about the collision, if there is one.

The structure of the collision details object looks like:

Note that if you pass in true for the detail parameter and there is a collision, there will not be a boolean returned but the collision details object instead. If there is no collision then it will still return false.

Point Collisions

pointInCircle

Checks to see if a point is inside of a circle.

Returns true if the point is in the circle or false otherwise.

example:

const circle = sc.circle(sc.vector(100, 100), 20);

const collision = sc.pointInCircle(sc.vector(110, 110), circle); // true

pointInPolygon

Checks to see if a point is inside of a convex polygon.

Returns true if the point is in the polygon or false otherwise.

example:

const triangle = sc.polygon(sc.vector(30, 0), [
  sc.vector(0, 0),
  sc.vector(30, 0),
  sc.vector(0, 30)
]);

const collision = sc.pointInPolygon(sc.vector(35, 5), triangle); // true

Polygon Collisions

testPolygonPolygon

Checks whether polygons collide.

Returns true if the circles collide or false otherwise. If details is set to true and a collision occurs then a collision details object will be returned instead of true.

example:

const polygon1 = sc.polygon(sc.vector(0, 0), [
  sc.vector(0, 0),
  sc.vector(40, 0),
  sc.vector(40, 40),
  sc.vector(0, 40)
]);

const polygon2 = sc.polygon(sc.vector(30, 0), [
  sc.vector(0, 0),
  sc.vector(30, 0),
  sc.vector(0, 30)
]);

// No details
const collided = sc.testPolygonPolygon(polygon1, polygon2); // true

// Details
const collidedDetails = sc.testPolygonPolygon(polygon1, polygon2, true);
console.log(collidedDetails.overlap); // 10

testPolygonCircle

Check if a polygon and a circle collide.

Returns true if the circles collide or false otherwise. If details is set to true and a collision occurs then a collision details object will be returned instead of true.

example:

const circle = sc.circle(sc.vector(50, 50), 20);

const polygon = sc.polygon(sc.vector(0, 0), [
  sc.vector(0, 0),
  sc.vector(40, 0),
  sc.vector(40, 40),
  sc.vector(0, 40)
]);

// No details
const collided = sc.testPolygonCircle(polygon, circle); // true

// Details
const collidedDetails = sc.testPolygonCircle(polygon, circle, true);
console.log(collidedDetails.overlap.toFixed(2)); // 5.86

Circle Collisions

testCircleCircle

Check if two circles collide.

Returns true if the circles collide or false otherwise. If details is set to true and a collision occurs then a collision details object will be returned instead of true.

example:

const circle1 = sc.circle(sc.vector(0, 0), 20);
const circle2 = sc.circle(sc.vector(30, 0), 20);

// No details
const collided = sc.testCircleCircle(circle1, circle2); // true

// Details
const collidedDetails = sc.testCircleCircle(circle1, circle2, true);
console.log(collidedDetails.overlap); // 10

testCirclePolygon

Check if a circle and a polygon collide.

NOTE: This is slightly less efficient than polygonCircle as it just runs polygonCircle and reverses everything at the end.

Returns true if the circles collide or false otherwise. If details is set to true and a collision occurs then a collision details object will be returned instead of true.

example:

const circle = sc.circle(sc.vector(50, 50), 20);

const polygon = sc.polygon(sc.vector(0, 0), [
  sc.vector(0, 0),
  sc.vector(40, 0),
  sc.vector(40, 40),
  sc.vector(0, 40)
]);

// No details
const collided = sc.testCirclePolygon(circle, polygon); // true

// Details
const collidedDetails = sc.testCirclePolygon(circle, polygon, true);

Tests

To run the tests available for swift-collider use:

$ npm run test

License

MIT