check2d

For browser-based projects, you can import check2d directly using an ESM provider like esm.sh.

import { System } from 'https://esm.sh/check2d'

You can debug your collision system by drawing bodies or the internal BVH structure directly onto a HTML5 <canvas> context.

// Draw all bodies in the system
context.beginPath()
system.draw(context)
context.stroke()

// Draw the BVH bounding boxes
context.beginPath()
system.drawBVH(context)
context.stroke()

You can install check2d using yarn to add it to your project.

yarn add check2d

To begin using check2d, instantiate a System. The System manages the Bounding Volume Hierarchy (BVH) and handles collision detection logic.

const { System } = require('check2d')

const system = new System()

Both Circle and Polygon use a dirty flag to optimize performance. When a body's position, angle, scale, or points change, it is marked as dirty.

• markAsDirty(updateNow): If updateNow is true, the body is immediately updated in the collision system. If false, it is simply flagged to be updated during the next collision check.
• updateBody(updateNow): Synchronizes the body with the collision system (e.g., updating AABB or convex polygon positions).

Collision filtering is handled via a 32-bit integer group. The high 16 bits represent the category and the low 16 bits represent the mask.

• Use groupBits(category, mask) to generate a group value.
• Use ensureNumber(input) to handle both numeric and binary string inputs.
• Use canInteract(bodyA, bodyB) to determine if two bodies are allowed to collide based on their groups.

import { groupBits, canInteract } from './utils';

// Define categories and masks using binary strings
const playerGroup = groupBits('00000000_00000001', '11111111_11111111');
const wallGroup = groupBits('00000000_00000010', '00000000_00000001');

// Check if they can interact
const collisionAllowed = canInteract({ group: playerGroup }, { group: wallGroup });

The check2d library provides a comprehensive suite of tools for 2D collision detection, body manipulation, and raycasting. You can import all core functionality from the main entrypoint. The library is organized into several functional areas:

• Bodies: Geometric primitives including Circle, Ellipse, Polygon, Box, Point, and Line.
• System: Core engine logic and management.
• Intersect: Low-level intersection and collision detection algorithms.
• Utils: Helper functions for geometric and mathematical operations.
• Clock: Time-related utilities for managing simulation steps or animations.

import * as check2d from 'check2d';

// Accessing components via the main namespace
const circle = new check2d.Circle(...);
const intersection = check2d.intersectSomething(...);

Bodies in check2d support transformations including position, rotation, and scale. To optimize performance, changes are batched. When you modify a body, pass false as the last argument to prevent immediate updates, then call body.updateBody() once all transformations are complete to apply them in a single batch.

// Batching transformations for performance
box.setPosition(10, 5, false)
box.setAngle(Math.PI / 4, false)
box.setScale(2, 1, false)
box.move(1, false)

// Apply all changes at once
box.updateBody()

The System provides methods to check for collisions between bodies:

• system.checkAll(callback): Checks all bodies in the system and executes the callback for every collision result found.
• system.checkOne(body, callback): Checks a specific body against all other bodies in the system.
• system.separate(): An optional method to automatically handle separation of colliding bodies.

To find the exact points where two bodies are colliding, use system.getCollisionPoints(bodyA, bodyB).

// Check all collisions in the system
system.checkAll((result) => {
  console.log(result)
})

// Check collisions for a specific body
system.checkOne(box, (result) => {
  console.log(result)
})

// Automatically separate colliding bodies
system.separate()

// Get specific collision points from a result
const points = system.getCollisionPoints(result.a, result.b)

Use system.raycast to detect collisions along a line segment. The method takes a starting point, an end point, and an optional filter function. If a hit is detected, it returns an object containing the point of impact and the body hit.

const hit = system.raycast(
  { x: 0, y: 0 },      // Start point
  { x: 0, y: -10 },    // End point
  (body) => true       // Filter function (returns true to include body)
)

if (hit) {
  const { point, body } = hit
  console.log(point, body)
}

You can create various shape types such as Box, Circle, and Polygon. While some shapes can be instantiated directly, it is recommended to use the system.createBox method (or similar factory methods) to ensure they are properly integrated with the system. After creation, use system.insert(body) to add the body to the collision detection engine.

const { Box, Circle, Polygon } = require('check2d')

// Using a factory method from the system
const box = system.createBox({ x: 0, y: 0 }, 10, 10)

// Instantiating a shape directly
const circle = new Circle({ x: 5, y: 0 }, 5)

// Adding the body to the system for collision checks
system.insert(circle)