# distributedlife-sat

> Library for performing 2D collision detection

Latest version **1.4.0** (published 2016-05-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install distributedlife-sat
pnpm add distributedlife-sat
yarn add distributedlife-sat
bun add distributedlife-sat
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.4.0 |
| Published | 2016-05-10 |
| First published | 2015-10-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | distributedlife |
| Keywords | collision detection, game, sat |

## Links

- npm: https://www.npmjs.com/package/distributedlife-sat
- Repository: https://github.com/distributedlife/sat
- Homepage: https://github.com/distributedlife/sat#readme
- Issues: http://github.com/distributedlife/sat/issues
- npm.io page: https://npm.io/package/distributedlife-sat

## Recent versions

- 1.4.0 (latest) — 2016-05-10
- 1.3.0 — 2015-12-06
- 1.2.1 — 2015-12-03
- 1.2.0 — 2015-12-03
- 1.1.0 — 2015-12-02
- 1.0.0 — 2015-10-12

## README

# distributedlife-sat

This project is a rewrite of [Jim Riecken's SAT.js](http://jriecken.github.io/sat-js/) library. I rewrote it on a flight back to see family in coding style that suites me. I also trimmed out stuff I don't think I need. It's not compatible due to API changes but all the tests still pass.

# About

SAT.js is a simple JavaScript library for performing collision detection (and projection-based collision response) of simple 2D shapes.  It uses the [Separating Axis Theorem](http://en.wikipedia.org/wiki/Hyperplane_separation_theorem) (hence the name)

It supports detecting collisions between:
 - Circles (using Voronoi Regions.)
 - Convex Polygons (and simple Axis-Aligned Boxes, which are of course, convex polygons.)

It also supports checking whether a point is inside a circle or polygon.

When a collision occurs your callback gets invoked.

It's released under the [MIT](http://en.wikipedia.org/wiki/MIT_License) license.

To use it in node.js, you can run `npm install distributedlife-sat` and then use it with `var SAT = require('distributedlife-sat');`

# Functions

I took a more functional approach than the original. All you have is functions and data. Functions return new versions of data, so through away your old stuff.

The original SAT.js library has a bunch of performance stuff around limiting reallocs, etc. I have stripped all that out as using this for high-performance stuff isn't an objective.


## Collisions
I collapsed the original set of functions that run different algorithms depending on whether you have one or two circles, polygons or points into a single function. This works out what structure you have and calls the appropriate algorithm.

- if you have a `radius`, you're a circle
- if you have an `x` and a `y`, you're a vector
- otherwise, you're a polygon

```
function callMeOnCollision () {
  console.log('ouch');
}

var test = require('distributedlife-sat').collisions.test;
test(a, b, callMeOnCollision)
```

At present we call your callback on collision and you get no further information about who was doing, what direction they were heading, etc.

## Shapes

Inside is a helper file with a bunch of shapes. These make it easier for you to create objects for colliding. These objects exist in your physics models. I make no promises about how easy it may be to render them. I like to keep my physics model and my rendering model separate.

Most shapes take a point that is their anchor in world space. For the circle, this will be the center. For the rectangles you have the option of a centre oriented `c` object or a top-left `tl` oriented one.
```
var shapes = require('distributedlife-sat').shapes;

var origin = {x: 0, y: 0};
var width = 25;
var height = 25;

circle(origin, 25);
tlSquare(origin, width);
tlBox(origin, width, height);
tlRectangle(origin, width, height);
cSquare(origin, width);
cBox(origin, width, height);
cRectangle(origin, width, height);
polygon(points, [{x: 0, y: 0}, {x: 100, y: 100}, {x: 0, y: 100}]);
triangle(origin, width);
```

The `box` and `rectangles` are synonyms.

## Useful Vector Functions

These functions return new vectors and without modifying the supplied vectors.

- **sub** (v1, v2) - subtract v2 from v1 and return the new vector
- **add** (v1, v2) - add v2 to v1 and return the new vector
- **dot** (v1, v2) - return the dot product of v1 and v2
- **len2** (v) - return dot product of the vector and itself
- **len** (v) - return the magnitude of the vector
- **normalise** (v) - return the normal of the vector
- **scale** (v, x, y) - scale v1 by x and y. If y is not supplied it scales v.x and v.y by the x value.
- **perp** (v) - return the vector perpendicular to the supplied vector
- **rotate** (v, angle) - return the vector that is a rotate of `angle` on `v`
- **reverse** (v) - return the reverse of the vector
- **project** (v1, v2) - project v1 on v2.
- **reflect** (v, axis) - reflect the vector along the supplied axis

## Useful Polygon Functions

All of these functions return new polygons and do not modify the supplied polygons.

- **rotate** (polygon, angle) - rotate polygon by angle
- **translate** (polygon, vector) - translate polygon by vector
- **setPoints** (polygon, points) - set the points of the polygon
- **setOffset** (polygon, offset) - change the offset of the polygon from it's world origin
- **setAngle** (polygon, angle) - set the angle of the polygon
- **getAABB** (polygon) - return the Axis-Aligned Bounding Box for the polygon

## Useful Circle Functions

- getAABB (circle) - return the Axis Aligned Bounding Box for the supplied circle.


# Tests

To run the tests from your console:

```
mocha
```

To install `mocha` you will need to have run `npm install` after cloning the repo.

---
_Source: https://npm.io/package/distributedlife-sat · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
