Flit Physics MCP server

Flit

Flit is a tiny little physics engine for 3js. It doesn't do much yet! but I believe!

Spheres, collisions, raycasts, gravity, and a spatial-hash broadphase — nothing more, on purpose. All simulation state lives in flat Float32Arrays (structure-of-arrays), so the CPU path doubles as the reference implementation for a future WebGPU compute backend: same buffers, same kernels, no re-architecting.

What's in the box

impulse + positional-correction contact solver, infinite ground plane.

• World — point-sphere particles, semi-implicit Euler integration,

cell codes. This is the Euclidean cousin in the LSH family: MinHash buckets documents by Jaccard similarity; this buckets positions so nearby points collide in the same bucket. Morton keys are bijective (no hash-collision pair bloat), invertible (no side table), and locality-ordered for a future sorted-array GPU backend.

• SpatialHash — uniform grid broadphase keyed by Morton (Z-order)

chi-square/KL distances (ported from FLANN), Morton (Z-order) keys, float bit-flips for radix sorting, octagonal approximate distance. See THIRDPARTYNOTICES.md for provenance and licenses.

• Distance & bit utilities — squared Euclidean/L1/Minkowski/L∞/Hellinger/

For agents

Building a little three.js game or demo? Two ways in:

your agent's skills path (e.g. .claude/skills/, ~/.code_puppy/skills/). It carries the 30-second integration recipe, the MCP option, measured performance envelope, and contributor rules.

• Skill: skills/flit/SKILL.md — copy the skills/flit/ directory into

• MCP server (no code needed): npm run mcp, or point your client at it:

{
  "mcpServers": {
    "flit": {
      "command": "npx",
      "args": ["vite-node", "mcp/server.ts"],
      "cwd": "<path-to-this-repo>"
    }
  }
}

Tools: flitinfo, flitreset, flitspawn (rain/explosion/grid/fountain presets), flitaddparticles, flitstep, flit_state — the last two return flat xyz positions shaped for InstancedMesh syncing.

Usage

npm i flit-physics

import { World } from 'flit-physics';

const world = new World({ restitution: 0.4 }); // gravity and a floor at y=0 included

const ball = world.addParticle({ position: [0, 10, 0], radius: 0.5, mass: 1 });

// fixed timestep, e.g. from your rAF loop
world.step(1 / 60);

// sync to three.js: positions is a live Float32Array, 3 floats per particle
mesh.position.set(
  world.positions[ball * 3],
  world.positions[ball * 3 + 1],
  world.positions[ball * 3 + 2],
);

Develop

npm install
npm test        # vitest
npm run build   # tsc -> dist/
npm run bench   # broadphase + full-step micro-benchmarks
npm run demo    # three.js demo scene (vite dev server)

Benchmarks

Deterministic seeds; numbers from a local dev machine, recorded at commit time (see commit messages for the full series, including rejected designs).

Shortened. The full README is on GitHub.