Line-Circle Collision Detection

Common errors

• TypeError: collide is not a function

  cause Attempting to use named import syntax (`import { collide } from '...'`) for a CommonJS module that exports a single function as its `module.exports`.
  fix Use CommonJS `require` syntax (`const collide = require('line-circle-collision');`) or a default ESM import (`import collide from 'line-circle-collision';`) if your environment supports CJS-ESM interop.

• ReferenceError: require is not defined

  cause Using `require()` in an ECMAScript Module (ESM) file or a browser environment without a compatible bundler/runtime.
  fix If in an ESM context, change `const collide = require('line-circle-collision');` to `import collide from 'line-circle-collision';`. For browser use, ensure your build process bundles CommonJS modules.

• TypeError: a.map is not a function (or similar property access errors)

  cause Input parameters `a`, `b`, or `circle` are not correctly formatted as 2D arrays (e.g., `[x, y]`), leading to internal vector operations failing.
  fix Verify that all vector inputs are consistently `[number, number]` arrays. For example, `[5, 6]` for a point, not `{x: 5, y: 6}` or `[5]`.

Warnings

• gotcha The `nearest` output parameter is only updated if a collision (`hit` returns true) is detected. If `hit` is false, the contents of the `nearest` array should not be relied upon, as they might be stale or uninitialized from a previous call.
  Fix: Always check the boolean return value of `collide` before using the `nearest` array's contents.
• gotcha The `a`, `b`, and `circle` parameters are expected to be 2D vectors represented as arrays of two numbers (e.g., `[x, y]`). Providing objects, non-array types, or arrays with incorrect dimensions will lead to runtime errors.
  Fix: Ensure all vector inputs (`a`, `b`, `circle`) are consistently formatted as `[number, number]` arrays.

Install

• npm install line-circle-collision npm
• yarn add line-circle-collision yarn
• pnpm add line-circle-collision pnpm

Imports

• collide
  wrong:

  import { collide } from 'line-circle-collision';

  correct:

  const collide = require('line-circle-collision');

  This package is primarily a CommonJS module. Attempting named ESM imports will result in errors as it exports a single function as its module.exports.
• collide (ESM)
  wrong:

  import * as lineCircleCollision from 'line-circle-collision';
  const collide = lineCircleCollision.collide;

  correct:

  import collide from 'line-circle-collision';

  While primarily CommonJS, Node.js and bundlers often provide interoperability allowing a default ESM import. The `import * as` pattern would require accessing the `default` property, e.g., `lineCircleCollision.default`.

Quickstart

This quickstart demonstrates how to use the `collide` function to check for an intersection between a line segment and a circle, including how to retrieve the nearest collision point if a hit occurs.

const collide = require('line-circle-collision');

// Define the circle (center X, center Y) and its radius
const circleCenter = [50, 50];
const radius = 25;

// Define the line segment by its two endpoints (A and B)
const linePointA = [20, 30];
const linePointB = [80, 70];

// Optional: a vector to store the nearest collision point
const nearestPoint = [0, 0]; 

// Perform the collision test
const hit = collide(linePointA, linePointB, circleCenter, radius, nearestPoint);

if (hit) {
  console.log(`Collision detected!`);
  console.log(`Nearest collision point: [${nearestPoint[0]}, ${nearestPoint[1]}]`);
} else {
  console.log('No collision.');
}

// Example of no collision
const noHitLineA = [0,0];
const noHitLineB = [10,10];
const noHit = collide(noHitLineA, noHitLineB, circleCenter, radius);
console.log(`No collision example: ${noHit}`);