Collisions
Collisions is a JavaScript library for quickly and accurately detecting collisions between Polygons, Circles, and Points. It combines the efficiency of a Bounding Volume Hierarchy (BVH) for broad-phase searching and the accuracy of the Separating Axis Theorem (SAT) for narrow-phase collision testing.
\n
\n
\n
Installation
npm install collisions\n
\n
\nNote: This library uses the native ECMAScript Module syntax. Most environments support native modules, but the following exceptions apply:
\n\nBundling solutions such as Webpack or Rollup.js make native modules compatible with all environments.
\n
\n
\n
Documentation
View the documentation (this README is also there).
\n
\n
Demos
\n
\n
Usage
import Collisions from 'collisions';\n\n// Create the collision system\nconst system = new Collisions();\n\n// Create a Result object for collecting information about the collisions\nconst result = system.createResult();\n\n// Create the player (represented by a Circle)\nconst player = system.createCircle(100, 100, 10);\n\n// Create some walls (represented by Polygons)\nconst wall1 = system.createPolygon(400, 500, [[-60, -20], [60, -20], [60, 20], [-60, 20]], 1.7);\nconst wall2 = system.createPolygon(200, 100, [[-60, -20], [60, -20], [60, 20], [-60, 20]], 2.2);\nconst wall3 = system.createPolygon(400, 50, [[-60, -20], [60, -20], [60, 20], [-60, 20]], 0.7);\n\n// Update the collision system\nsystem.update();\n\n// Get any potential collisions (this quickly rules out walls that have no chance of colliding with the player)\nconst potentials = player.potentials();\n\n// Loop through the potential wall collisions\nfor(const wall of potentials) {\n // Test if the player collides with the wall\n if(player.collides(wall, result)) {\n // Push the player out of the wall\n player.x -= result.overlap * result.overlap_x;\n player.y -= result.overlap * result.overlap_y;\n }\n}\n
\n
\n
Getting Started
\n
1. Creating a Collision System
Collisions provides functions for performing both broad-phase and narrow-phase collision tests. In order to take full advantage of both phases, bodies need to be tracked within a collision system.
\n
Call the Collisions constructor to create a collision system.
\n
import Collisions from 'collisions';\n\nconst system = new Collisions();\n
\n
\n
2. Creating, Inserting, Updating, and Removing Bodies
Collisions supports the following body types:
\n
\n- Circle: A shape with infinite sides equidistant from a single point
\n- Polygon: A shape made up of line segments
\n- Point: A single coordinate
\n
\n
To use them, import the desired body class, call its constructor, and insert it into the collision system using insert().
\n
import {Collisions, Circle, Polygon, Point} from 'collisions';\n\nconst system = new Collisions();\n\nconst circle = new Circle(100, 100, 10);\nconst polygon = new Polygon(50, 50, [[0, 0], [20, 20], [-10, 10]]);\nconst line = new Polygon(200, 5, [[-30, 0], [10, 20]]);\nconst point = new Point(10, 10);\n\nsystem.insert(circle)\nsystem.insert(polygon, line, point);\n
\n
Collision systems expose several convenience functions for creating bodies and inserting them into the system in one step. This also avoids having to import the different body classes.
\n
import Collisions from 'collisions';\n\nconst system = new Collisions();\n\nconst circle = system.createCircle(100, 100, 10);\nconst polygon = system.createPolygon(50, 50, [[0, 0], [20, 20], [-10, 10]]);\nconst line = system.createPolygon(200, 5, [[-30, 0], [10, 20]]);\nconst point = system.createPoint(10, 10);\n
\n
All bodies have x and y properties that can be manipulated. Additionally, Circle bodies have a scale property that can be used to scale their overall size. Polygon bodies have scale_x and scale_y properties to scale their points along a particular axis and an angle property to rotate their points around their current position (using radians).
\n
circle.x = 20;\ncircle.y = 30;\ncircle.scale = 1.5;\n\npolygon.x = 40;\npolygon.y = 100;\npolygon.scale_x = 1.2;\npolygon.scale_y = 3.4;\npolygon.angle = 1.2;\n
\n
And, of course, bodies can be removed when they are no longer needed.
\n
system.remove(polygon, point);\ncircle.remove();\n
\n
\n
3. Updating the Collision System
Collision systems need to be updated when the bodies within them change. This includes when bodies are inserted, removed, or when their properties change (e.g. position, angle, scaling, etc.). Updating a collision system is done by calling update() and should typically occur once per frame.
\n
system.update();\n
\n
The optimal time for updating a collision system is after its bodies have changed and before collisions are tested. For example, a game loop might use the following order of events:
\n
function gameLoop() {\n handleInput();\n processGameLogic();\n\n system.update();\n\n handleCollisions();\n render();\n}\n
\n
\n
4. Testing for Collisions
When testing for collisions on a body, it is generally recommended that a broad-phase search be performed first by calling potentials() in order to quickly rule out bodies that are too far away to collide. Collisions uses a Bounding Volume Hierarchy (BVH) for its broad-phase search. Calling potentials() on a body traverses the BVH and builds a list of potential collision candidates.
\n
const potentials = polygon.potentials();\n
\n
Once a list of potential collisions is acquired, loop through them and perform a narrow-phase collision test using collides(). Collisions uses the Separating Axis Theorem (SAT) for its narrow-phase collision tests.
\n
const potentials = polygon.potentials();\n\nfor(const body of potentials) {\n if(polygon.collides(body)) {\n console.log('Collision detected!');\n }\n}\n
\n
It is also possible to skip the broad-phase search entirely and call collides() directly on two bodies.
\n
\nNote: Skipping the broad-phase search is not recommended. When testing for collisions against large numbers of bodies, performing a broad-phase search using a BVH is much more efficient.
\n
\n
if(polygon.collides(line)) {\n console.log('Collision detected!');\n}\n
\n
\n
There is often a need for detailed information about a collision in order to react to it appropriately. This information is stored using a Result object. Result objects have several properties set on them when a collision occurs, all of which are described in the documentation.
\n
For convenience, there are several ways to create a Result object. Result objects do not belong to any particular collision system, so any of the following methods for creating one can be used interchangeably. This also means the same Result object can be used for collisions across multiple systems.
\n
\nNote: It is highly recommended that Result objects be recycled when performing multiple collision tests in order to save memory. The following example creates multiple Result objects strictly as a demonstration.
\n
\n
import {Collisions, Result, Polygon} from 'collisions';\n\nconst system = new Collisions();\nconst my_polygon = new Polygon(100, 100, 10);\n\nconst result1 = new Result();\nconst result2 = Collisions.createResult();\nconst result3 = system.createResult();\nconst result4 = Polygon.createResult();\nconst result5 = my_polygon.createResult();\n
\n
To use a Result object, pass it into collides(). If a collision occurs, it will be populated with information about the collision. Take note in the following example that the same Result object is being reused each iteration.
\n
const result = system.createResult();\nconst potentials = point.potentials();\n\nfor(const body of potentials) {\n if(point.collides(body, result)) {\n console.log(result);\n }\n}\n
\n
\n
6. Negating Overlap
A common use-case in collision detection is negating overlap when a collision occurs (such as when a player hits a wall). This can be done using the collision information in a Result object (see Getting Detailed Collision Information).
\n
The three most useful properties on a Result object are overlap, overlap_x, and overlap_y. Together, these values describe how much and in what direction the source body is overlapping the target body. More specifically, overlap_x and overlap_y describe the direction vector, and overlap describes the magnitude of that vector.
\n
These values can be used to "push" one body out of another using the minimum distance required. More simply, subtracting this vector from the source body's position will cause the bodies to no longer collide. Here's an example:
\n
if(player.collides(wall, result)) {\n player.x -= result.overlap * result.overlap_x;\n player.y -= result.overlap * result.overlap_y;\n}\n
\n
\n
Lines
Creating a line is simply a matter of creating a single-sided polygon (i.e. a polygon with only two coordinate pairs).
\n
const line = new Polygon(200, 5, [[-30, 0], [10, 20]]);\n
\n
\n
Concave Polygons
Collisions uses the Separating Axis Theorem (SAT) for its narrow-phase collision tests. One caveat to SAT is that it only works properly on convex bodies. However, concave polygons can be "faked" by using a series of Lines. Keep in mind that a polygon drawn using Lines is "hollow".
\n
Handling true concave polygons requires breaking them down into their component convex polygons (Convex Decomposition) and testing them for collisions individually. There are plans to integrate this functionality into the library in the future, but for now, check out poly-decomp.js.
\n
\n
Rendering
For debugging, it is often useful to be able to visualize the collision bodies. All of the bodies in a Collision system can be drawn to a <canvas> element by calling draw() and passing in the canvas' 2D context.
\n
const canvas = document.createElement('canvas');\nconst context = canvas.getContext('2d');\n\n// ...\ncontext.strokeStyle = '#FFFFFF';\ncontext.beginPath();\n\nsystem.draw(context);\n\ncontext.stroke();\n
\n
Bodies can be individually drawn as well.
\n
context.strokeStyle = '#FFFFFF';\ncontext.beginPath();\n\npolygon.draw(context);\ncircle.draw(context);\n\ncontext.stroke();\n
\n
The BVH can also be drawn to help test Bounding Volume Padding.
\n
context.strokeStyle = '#FFFFFF';\ncontext.beginPath();\n\nsystem.drawBVH(context);\n\ncontext.stroke();\n
\n
\n
Bounding Volume Padding
When bodies move around within a collision system, the internal BVH has to remove and reinsert the body in order to determine where it belongs in the hierarchy. This is one of the most costly operations in maintaining a BVH. In general, most projects will never see a performance issue from this unless they are dealing with thousands of moving bodies at once. In these cases, it can sometimes be beneficial to "pad" the bounding volumes of each body so that the BVH doesn't need to remove and reinsert bodies that haven't changed position too much. In other words, padding the bounding volume allows "breathing room" for the body within it to move around without being flagged for an update.
\n
The tradeoff is that the slightly larger bounding volumes can trigger more false-positives during the broad-phase potentials() search. While the narrow phase will ultimately rule these out using Axis Aligned Bounding Box tests, putting too much padding on bodies that are crowded can lead to too many false positives and a diminishing return in performance. It is up to the developer to determine how much padding each body will need based on how much it can move within a single frame and how crowded the bodies in the system are.
\n
Padding can be added to a body when instantiating it (see the documentation for each body) or at any time by changing its padding property.
\n
const padding = 5;\nconst circle = new Circle(100, 100, 10, 1, padding);\n\n// ...\n\ncircle.padding = 10;\n
\n
\n
Only using SAT
Some projects may only have a need to perform SAT collision tests without broad-phase searching. This can be achieved by avoiding collision systems altogether and only using the collides() function.
\n
import {Circle, Polygon, Result} from 'collisions';\n\nconst circle = new Circle(45, 45, 20);\nconst polygon = new Polygon(50, 50, [[0, 0], [20, 20], [-10, 10]]);\nconst result = new Result();\n\nif(circle.collides(polygon, result)) {\n console.log(result);\n}\n
\n
\n
FAQ
Why shouldn't I just use a physics engine?
Projects requiring physics are encouraged to use one of the several physics engines out there (e.g. Matter.js, Planck.js). However, many projects end up using physics engines solely for collision detection, and developers often find themselves having to work around some of the assumptions that these engines make (gravity, velocity, friction, etc.). Collisions was created to provide robust collision detection and nothing more. In fact, a physics engine could easily be written with Collisions at its core.
\n
Why does the source code seem to have quite a bit of copy/paste?
Collisions was written with performance as its primary focus. Conscious decisions were made to sacrifice readability in order to avoid the overhead of unnecessary function calls or property lookups.
\n
Sometimes bodies can "squeeze" between two other bodies. What's going on?
This isn't caused by faulty collisions, but rather how a project handles its collision responses. There are several ways to go about responding to collisions, the most common of which is to loop through all bodies, find their potential collisions, and negate any overlaps that are found one at a time. Since the overlaps are negated one at a time, the last negation takes precedence and can cause the body to be pushed into another body.
\n
One workaround is to resolve each collision, update the collision system, and repeat until no collisions are found. Keep in mind that this can potentially lead to infinite loops if the two colliding bodies equally negate each other. Another solution is to collect all overlaps and combine them into a single resultant vector and then push the body out, but this can get rather complicated.
\n
There is no perfect solution. How collisions are handled depends on the project.
\n