npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

detect-collisions

v9.24.0

Published

Points, Lines, Boxes, Polygons (also hollow), Ellipses, Circles. RayCasting, offsets, rotation, scaling, bounding box padding, flags for static and ghost/trigger bodies

Downloads

11,470

Readme

Detect-Collisions

Introduction

Detect-Collisions 💫 is a lightning-fast ⚡️ TypeScript library built to detect collisions between diverse shapes like Points, Lines, Boxes, Polygons (including concave), Ellipses, and Circles. Utilizing Bounding Volume Hierarchy (BVH) and the Separating Axis Theorem (SAT), it offers rapid and accurate collision detection. The library supports RayCasting, offsets, rotation, scaling, and optimizations for: bounding box, flags for non-moving and ghost/trigger bodies and collision groups filtering - making it an ideal choice for high-speed applications in gaming and simulations.

Demos

Installation

npm i detect-collisions --save

API Documentation

For detailed documentation on the library's API, refer to the following link:

Detect-Collisions API Documentation

Usage

Step 1: Initialize Collision System

Initialize a unique collision system using Detect-Collisions:

const { System } = require("detect-collisions");
const system = new System();

Step 2: Understand Body Attributes

Bodies possess various properties:

  • Position: Use setPosition(x: number, y: number) for teleport and move(speed: number) for moving forward in direction of its angle.
  • Scale: Use setScale(x: number, y: number) for setting and scale: Vector for getting scale
  • Rotation: Use setAngle(radians: number) for setting and angle: number for getting and deg2rad(degrees: number) to convert to radians.
  • Offset: Use setOffset(offset: Vector) for setting and offset: Vector for getting offset from the body center.
  • AABB Bounding Box: Use aabb: BBox for inserted or getAABBAsBBox(): BBox for non inserted bodies to get the bounding box.
  • Padding: Use padding: number and set to nonzero value to reduce costly reinserts on attributes' change.
  • Collision Filtering: Use group: number for collision filtering, with a range within 0x0 ~ 0x7fffffff.
  • Body Options: Read more in BodyOptions documentation

Step 3: Create and Manage Bodies

Create bodies of various types and manage them:

const {
  Box,
  Circle,
  Ellipse,
  Line,
  Point,
  Polygon,
} = require("detect-collisions");

// Example: Create and insert box1 body
const box1 = system.createBox(position, width, height, options);
// Example: Create box2 body
const box2 = new Box(position, width, height, options);
// Example: Insert box2 body
system.insert(box2);

Step 4: Manipulate Bodies

Manipulate body attributes and update the collision system:

// if omitted updateNow is true
const updateNow = false;
// this should be time scaled, 1 for example
const speed = 1;

// teleport
box.setPosition(x, y, updateNow);
box.setScale(scaleX, scaleY, updateNow);
box.setAngle(angle, updateNow);
box.move(speed, updateNow);
box.setOffset({ x, y }, updateNow);
console.log(box.dirty); // true

box.updateBody(); // Update the body once, when all manipulations are done
console.log(box.dirty); // false

box.group = group; // Immediate effect, no body/system update needed
console.log(box.dirty); // false

Step 5: Collision Detection and Resolution

Detect collisions and respond accordingly:

if (system.checkAll(callback)) {
  // Do something yourself
}

if (system.checkOne(body, callback)) {
  // Do something yourself
}

// Or separate bodies based on isStatic/isTrigger
system.separate();

Step 6: Cleaning Up

Remove bodies when they're no longer needed:

system.remove(body);

And that's it! You're now ready to utilize the Detect-Collisions library in your project.

Visual Debugging with Rendering

To facilitate debugging, Detect-Collisions allows you to visually represent the collision bodies. By invoking the draw() method and supplying a 2D context of a <canvas> element, you can draw all the bodies within a collision system. You can also opt to draw individual bodies.

const canvas = document.createElement("canvas");
const context = canvas.getContext("2d");

context.strokeStyle = "#FFFFFF";
context.beginPath();
// draw specific body
body.draw(context);
// draw whole system
system.draw(context);
context.stroke();

To assess the Bounding Volume Hierarchy, you can draw the BVH.

context.strokeStyle = "#FFFFFF";
context.beginPath();
// draw specific body bounding box
body.drawBVH(context);
// draw bounding volume hierarchy of the system
system.drawBVH(context);
context.stroke();

Raycasting

Detect-Collisions provides the functionality to gather raycast data. Here's how:

const start = { x: 0, y: 0 };
const end = { x: 0, y: -10 };
const hit = system.raycast(start, end, (body, ray) => {
  // if you don't want the body to be hit by raycast return false
  return true;
});

if (hit) {
  const { point, body } = hit;

  console.log({ point, body });
}

In this example, point is a Vector with the coordinates of the nearest intersection, and body is a reference to the closest body.

Usage in Browsers

Just do what I did here, import from proper cdn as module, and v'oila:

https://code.pietal.dev/#/boilerplate/detect-collisions?pans=html,console

Contributing to the Project

We welcome contributions! Feel free to open a merge request. When doing so, please adhere to the following code style guidelines:

  • Execute the npm run precommit script prior to submitting your merge request
  • Follow the conventional commits standard
  • Refrain from using the any type

Additional Considerations

Why not use a physics engine?

While physics engines like Matter-js or Planck.js are recommended for projects that need comprehensive physics simulation, not all projects require such complexity. In fact, using a physics engine solely for collision detection can lead to unnecessary overhead and complications due to built-in assumptions (gravity, velocity, friction, etc.). Detect-Collisions is purpose-built for efficient and robust collision detection, making it an excellent choice for projects that primarily require this functionality. It can also serve as the foundation for a custom physics engine.

Benchmark

This will provide you with the results of both the insertion test benchmark and a headless Stress Demo benchmark, featuring moving bodies, with increasing amounts in each step.

git clone https://github.com/Prozi/detect-collisions.git
cd detect-collisions
npm i && npm run build # will build & run tests & run benchmarks

License

MIT

You can buy me a coffee

https://paypal.me/jacekpietal