@zakkster/lite-sat

💥 What is lite-sat?

@zakkster/lite-sat is a zero-allocation convex polygon collision detector using the Separating Axis Theorem.

It gives you:

• 💥 Convex polygon vs polygon collision
• 📐 MTV (Minimum Translation Vector) for resolution
• 0️⃣ Zero allocations — module-scoped Float32Array scratchpads
• 🔺 Handles triangles, quads, and any convex N-gon
• 🛡️ Degenerate polygon guard (< 3 vertices rejected)
• 🪶 < 1 KB minified

Feed it flat [x1,y1,x2,y2,...] arrays — the same format as your SoA engine.

Part of the @zakkster/lite-* ecosystem — micro-libraries built for deterministic, cache-friendly game development.

🚀 Install

npm i @zakkster/lite-sat

🕹️ Quick Start

import { testPolygonPolygon } from '@zakkster/lite-sat';

const polyA = new Float32Array([0,0, 10,0, 10,10, 0,10]);
const polyB = new Float32Array([5,5, 15,5, 15,15, 5,15]);
const mtv = new Float32Array(2);

if (testPolygonPolygon(polyA, polyB, mtv)) {
    // Collision! Push A away from B:
    polyA[0] += mtv[0]; polyA[1] += mtv[1];
    polyA[2] += mtv[0]; polyA[3] += mtv[1];
    // ... for all vertices
}

🧠 Why This Exists

Existing SAT libraries allocate a Response object per test. lite-sat uses module-scoped Float32Array caches — the same 4 arrays are reused across every call.

📊 Comparison

| Library | Size | Allocations | MTV | Install | |---------|------|-------------|-----|---------| | sat | ~4 KB | Response object per test | Yes | npm i sat | | collisions | ~8 KB | High | Yes | npm i collisions | | lite-sat | < 1 KB | Zero (Float32Array caches) | Yes | npm i @zakkster/lite-sat |

⚙️ API

testPolygonPolygon(polyA, polyB, outMTV)

| Parameter | Type | Description | |-----------|------|-------------| | polyA | Float32Array \| number[] | Flat vertex array [x1,y1,x2,y2,...] | | polyB | Float32Array \| number[] | Flat vertex array | | outMTV | Float32Array(2) | Pre-allocated push vector (written on collision) |

Returns true if overlapping. MTV always pushes A away from B.

🧪 Benchmark

100,000 polygon pair tests:
  sat.js:     12ms (Response object per test)
  lite-sat:    4ms (module-scoped Float32Array caches)

📦 TypeScript

Full TypeScript declarations included in testPolygonPolygon.d.ts.

📚 LLM-Friendly Documentation

See llms.txt for AI-optimized metadata and usage examples.

License

MIT