{"id":13513189,"url":"https://github.com/jriecken/sat-js","last_synced_at":"2025-05-15T14:03:28.748Z","repository":{"id":2749027,"uuid":"3745414","full_name":"jriecken/sat-js","owner":"jriecken","description":"A simple JavaScript library for performing 2D collision detection","archived":false,"fork":false,"pushed_at":"2021-04-05T03:46:46.000Z","size":599,"stargazers_count":778,"open_issues_count":7,"forks_count":111,"subscribers_count":30,"default_branch":"master","last_synced_at":"2025-04-15T03:52:16.216Z","etag":null,"topics":["collision-test","javascript"],"latest_commit_sha":null,"homepage":"http://jriecken.github.io/sat-js/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jriecken.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-03-17T04:06:40.000Z","updated_at":"2025-03-27T15:39:27.000Z","dependencies_parsed_at":"2022-07-21T12:03:02.520Z","dependency_job_id":null,"html_url":"https://github.com/jriecken/sat-js","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jriecken%2Fsat-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jriecken%2Fsat-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jriecken%2Fsat-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jriecken%2Fsat-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jriecken","download_url":"https://codeload.github.com/jriecken/sat-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249003955,"owners_count":21196794,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["collision-test","javascript"],"created_at":"2024-08-01T04:00:43.417Z","updated_at":"2025-04-15T03:52:20.652Z","avatar_url":"https://github.com/jriecken.png","language":"JavaScript","funding_links":[],"categories":["Uncategorized","Geometric Algebra"],"sub_categories":["Uncategorized","Collision Detection"],"readme":"# SAT.js\n\n - [Classes](#classes)\n - [Collision Tests](#collision-tests)\n - [Examples](#examples)\n\n## About\n\nSAT.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)\n\nIt supports detecting collisions between:\n - Circles (using Voronoi Regions.)\n - Convex Polygons (and simple Axis-Aligned Boxes, which are of course, convex polygons.)\n\nIt also supports checking whether a point is inside a circle or polygon.\n\nIt's released under the [MIT](http://en.wikipedia.org/wiki/MIT_License) license.\n\nCurrent version: `0.9.0`.\n\nNicely compresses with the [Google Closure Compiler](https://developers.google.com/closure/compiler/) in **Advanced** mode to about 6KB (2KB gzipped)\n\nTo use it in node.js, you can run `npm install sat` and then use it with `var SAT = require('sat');`\n\n## Classes\n\nSAT.js contains the following JavaScript classes:\n\n### SAT.Vector (aliased as SAT.V)\n\nThis is a simple 2D vector/point class.  It is created by calling:\n```javascript\n// Create the vector (10,10) - If (x,y) not specified, defaults to (0,0).\nvar v = new SAT.Vector(10, 10)\n```\n\nIt has the following properties:\n\n - `x` - The x-coordinate of the Vector.\n - `y` - The y-coordinate of the Vector.\n\nIt contains the following methods:\n\n - `copy(other)` - Copy the value of another Vector to this one.\n - `clone()` - Return a new vector with the same coordinates as this one.\n - `perp()` - Change this vector to be perpendicular to what it was before.\n - `rotate(angle)` - Rotate this vector counter-clockwise by the specified number of radians.\n - `reverse()` - Reverse this Vector.\n - `normalize()` - Make the Vector unit-lengthed.\n - `add(other)` - Add another Vector to this one.\n - `sub(other)` - Subtract another Vector from this one.\n - `scale(x,y)` - Scale this Vector in the X and Y directions.\n - `project(other)` - Project this Vector onto another one.\n - `projectN(other)` - Project this Vector onto a unit Vector.\n - `reflect(axis)` - Reflect this Vector on an arbitrary axis Vector.\n - `reflectN(axis)` - Reflect this Vector on an arbitrary axis unit Vector.\n - `dot(other)` - Get the dot product of this Vector and another.\n - `len2()` - Get the length squared of this Vector.\n - `len()` - Get the length of this Vector\n\n### SAT.Circle\n\nThis is a simple circle with a center position and a radius.  It is created by calling:\n```javascript\n// Create a circle whose center is (10,10) with radius of 20\nvar c = new SAT.Circle(new SAT.Vector(10,10), 20);\n```\n\nIt has the following properties:\n\n - `pos` - A Vector representing the center of the circle.\n - `r` - The radius of the circle\n - `offset` - Offset of center of circle from `pos`.\n\n It has the following methods:\n\n - `setOffset(offset)` - Set the current offset\n - `getAABB()` - Compute the axis-aligned bounding box. Returns a new Polygon every time it is called.\n - `getAABBAsBox()` - Compute the axis-aligned bounding box. Returns a new Box every time it is called.\n\n### SAT.Polygon\n\nThis is a **convex** polygon, whose points are specified in a counter-clockwise fashion.  It is created by calling:\n```javascript\n// Create a triangle at (0,0)\nvar p = new SAT.Polygon(new SAT.Vector(), [\n  new SAT.Vector(),\n  new SAT.Vector(100,0),\n  new SAT.Vector(50,75)\n]);\n```\n\nNote: The points are counter-clockwise *with respect to the coordinate system*. If you directly draw the points on a screen that has the origin at the top-left corner it will _appear_ visually that the points are being specified clockwise. This is just because of the inversion of the Y-axis when being displayed.\n\nYou can create a line segment by creating a `Polygon` that contains only 2 points.\n\nAny identical consecutive points will be combined. (this can happen if you convert a `Box` with zero width or height into a `Polygon`)\n\nIt has the following properties:\n\n - `pos` - The position of the polygon (all points are relative to this).\n - `points` - Array of vectors representing the original points of the polygon.\n - `angle` - Angle to rotate the polgon (affects `calcPoints`)\n - `offset` - Translation to apply to the polygon before the `angle` rotation (affects `calcPoints`)\n - `calcPoints` - (Calculated) The collision polygon - effectively `points` with `angle` and `offset` applied.\n - `edges` - (Calculated) Array of Vectors representing the edges of the calculated polygon\n - `normals` - (Calculated) Array of Vectors representing the edge normals of the calculated polygon (perpendiculars)\n\nYou should _not_ manually change any of the properties except `pos` - use the `setPoints`, `setAngle`, and `setOffset` methods to ensure that the calculated properties are updated correctly.\n\nIt has the following methods:\n\n - `setPoints(points)` - Set the original points\n - `setAngle(angle)` - Set the current rotation angle (in radians)\n - `setOffset(offset)` - Set the current offset\n - `rotate(angle)` - Rotate the original points of this polygon counter-clockwise (around its local coordinate system) by the specified number of radians. The `angle` rotation will be applied on top of this rotation.\n - `translate(x, y)` - Translate the original points of this polygon (relative to the local coordinate system) by the specified amounts. The `offset` translation will be applied on top of this translation.\n - `getAABB()` - Compute the axis-aligned bounding box. Returns a new Polygon every time it is called. Is performed based on the `calcPoints`.\n - `getAABBAsBox()` - Compute the axis-aligned bounding box. Returns a new Box every time it is called. Is performed based on the `calcPoints`.\n - `getCentroid()` - Compute the [Centroid](https://en.wikipedia.org/wiki/Centroid#Centroid_of_a_polygon) of the polygon. Is performed based on the `calcPoints`.\n\n### SAT.Box\n\nThis is a simple Box with a position, width, and height.  It is created by calling:\n```javascript\n// Create a box at (10,10) with width 20 and height 40.\nvar b = new SAT.Box(new SAT.Vector(10,10), 20, 40);\n```\n\nIt has the following properties:\n\n - `pos` - The bottom-left coordinate of the box (i.e the smallest `x` value and the smallest `y` value).\n - `w` - The width of the box.\n - `h` - The height of the box.\n\nIt has the following methods:\n\n - `toPolygon()` - Returns a new Polygon whose edges are the edges of the box.\n\n### SAT.Response\n\nThis is the object representing the result of a collision between two objects.  It just has a simple `new Response()` constructor.\n\nIt has the following properties:\n\n - `a` - The first object in the collision.\n - `b` - The second object in the collison.\n - `overlap` - Magnitude of the overlap on the shortest colliding axis.\n - `overlapN` - The shortest colliding axis (unit-vector)\n - `overlapV` - The overlap vector (i.e. `overlapN.scale(overlap, overlap)`).  If this vector is subtracted from the position of `a`, `a` and `b` will no longer be colliding.\n - `aInB` - Whether the first object is completely inside the second.\n - `bInA` - Whether the second object is completely inside the first.\n\nIt has the following methods:\n\n- `clear()` - Clear the response so that it is ready to be reused for another collision test.\n\nNote: The `clear`ed value for a `Response` has what may seem to be strange looking values:\n\n```javascript\n{\n  a: null,\n  b: null,\n  overlap: 1.7976931348623157e+308,\n  overlapV: Vector(0, 0),\n  overlapN: Vector(0, 0),\n  aInB: true,\n  bInA: true\n}\n```\n\nThese just make calculating the response simpler in the collision tests. If the collision test functions return `false` the values that are in the response should not be examined, and `clear()` should be called before using it for another collision test.\n\n## Collision Tests\n\nSAT.js contains the following collision tests:\n\n### `SAT.pointInCircle(p, c)`\n\nChecks whether a given point is inside the specified circle.\n\n### `SAT.pointInPolygon(p, poly)`\n\nChecks whether a given point is inside a specified convex polygon.\n\n### `SAT.testCircleCircle(a, b, response)`\n\nTests for a collision between two `Circle`s, `a`, and `b`.  If a response is to be calculated in the event of collision, pass in a `clear`ed `Response` object.\n\nReturns `true` if the circles collide, `false` otherwise.\n\nIf it returns `false` you should not use any values that are in the `response` (if one is passed in)\n\n### `SAT.testPolygonCircle(polygon, circle, response)`\n\nTests for a collision between a `Polygon` and a `Circle`.  If a response is to be calculated in the event of a collision, pass in a `clear`ed `Response` object.\n\nReturns `true` if there is a collision, `false` otherwise.\n\nIf it returns `false` you should not use any values that are in the `response` (if one is passed in)\n\n### `SAT.testCirclePolygon(circle, polygon, response)`\n\nThe same thing as `SAT.testPolygonCircle`, but in the other direction.\n\nReturns `true` if there is a collision, `false` otherwise.\n\nIf it returns `false` you should not use any values that are in the `response` (if one is passed in)\n\n*Note: This is slightly slower than `SAT.testPolygonCircle` as it just calls that and reverses the result*\n\n### `SAT.testPolygonPolygon(a, b, response)`\n\nTests whether two polygons `a` and `b` collide. If a response is to be calculated in the event of collision, pass in a `clear`ed `Response` object.\n\nReturns `true` if there is a collision, `false` otherwise.\n\nIf it returns `false` you should not use any values that are in the `response` (if one is passed in)\n\n*Note: If you want to detect a collision between `Box`es, use the `toPolygon()` method*\n\n## Examples\n\nTest two circles\n```javascript\nvar V = SAT.Vector;\nvar C = SAT.Circle;\n\nvar circle1 = new C(new V(0,0), 20);\nvar circle2 = new C(new V(30,0), 20);\nvar response = new SAT.Response();\nvar collided = SAT.testCircleCircle(circle1, circle2, response);\n\n// collided =\u003e true\n// response.overlap =\u003e 10\n// response.overlapV =\u003e (10, 0)\n```\n\nTest a circle and a polygon\n```javascript\nvar V = SAT.Vector;\nvar C = SAT.Circle;\nvar P = SAT.Polygon;\n\nvar circle = new C(new V(50,50), 20);\n// A square\nvar polygon = new P(new V(0,0), [\n  new V(0,0), new V(40,0), new V(40,40), new V(0,40)\n]);\nvar response = new SAT.Response();\nvar collided = SAT.testPolygonCircle(polygon, circle, response);\n\n// collided =\u003e true\n// response.overlap ~\u003e 5.86\n// response.overlapV ~\u003e (4.14, 4.14) - i.e. on a diagonal\n```\n\nTest two polygons\n```javascript\nvar V = SAT.Vector;\nvar P = SAT.Polygon;\n\n// A square\nvar polygon1 = new P(new V(0,0), [\n  new V(0,0), new V(40,0), new V(40,40), new V(0,40)\n]);\n// A triangle\nvar polygon2 = new P(new V(30,0), [\n  new V(0,0), new V(30, 0), new V(0, 30)\n]);\nvar response = new SAT.Response();\nvar collided = SAT.testPolygonPolygon(polygon1, polygon2, response);\n\n// collided =\u003e true\n// response.overlap =\u003e 10\n// response.overlapV =\u003e (10, 0)\n```\n\nNo collision between two Boxes\n```javascript\nvar V = SAT.Vector;\nvar B = SAT.Box;\n\nvar box1 = new B(new V(0,0), 20, 20).toPolygon();\nvar box2 = new B(new V(100,100), 20, 20).toPolygon();\nvar collided = SAT.testPolygonPolygon(box1, box2);\n\n// collided =\u003e false\n```\n\nHit testing a circle and polygon\n```javascript\nvar V = SAT.Vector;\nvar C = SAT.Circle;\nvar P = SAT.Polygon;\n\nvar triangle = new P(new V(30,0), [\n  new V(0,0), new V(30, 0), new V(0, 30)\n]);\nvar circle = new C(new V(100,100), 20);\n\nSAT.pointInPolygon(new V(0,0), triangle); // false\nSAT.pointInPolygon(new V(35, 5), triangle); // true\nSAT.pointInCircle(new V(0,0), circle); // false\nSAT.pointInCircle(new V(110,110), circle); // true\n```\n\n## Tests\n\nTo run the tests from your console:\n\n```\nnpm install\nnpm run test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjriecken%2Fsat-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjriecken%2Fsat-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjriecken%2Fsat-js/lists"}