nape-js

Fully typed 2D physics engine for TypeScript & JavaScript — modern rewrite of Nape

Rigid bodies • Circles, Polygons & Capsules • Constraints • Fluid simulation • Collision callbacks • Raycasting & spatial queries • Fracture • Soft body • Deterministic multiplayer • Serialization • Web Worker support — zero dependencies, ~175 KB gzip.

v3.43.5 ~175 KB gzip
npm install @newkrok/nape-js

Interactive Demos

Click/drag on the canvas to interact. Pick a demo below. Physics Game

Loading engine…
FPS: — Bodies: — Step: —
Source Code

Latest complete game demos

The newest multi-system games built on the engine — AI, waves, cameras and 3D rigs, each in a single file you can open on CodePen.

Hitch & Park — gameplay screenshotPlay →

Complete gameHitch & Park

A trailer-parking game seen from above: five sites — supermarket, parking deck, marina slipway, high street, campsite — each with one bay the trailer must end up in, nose out, square and stopped. Parked cars can be shoved (their hazard lights tell on you), cones topple, pillars, hedges and trees don't budge; every bump costs points against a par time. ↑ ↓ drive / reverse, ← → steer, SPACE brake, G path guide; on touch, hold and drag. Physics: the car is a chassis plus four wheel bodies — rear ones on WeldJoints, front ones on PivotJoints steered by Ackermann AngleJoints — and only the front wheels drive, so the steered wheels pull the car round; the trailer hangs on a PivotJoint at the tow ball and folds if you reverse it wrong. In 3D: shadowed sites, spinning and steering wheels, brake and reversing lights, a reversing-camera inset.

GameplayVehicleJointsTop-downListenersMobile
Flipper Fray — gameplay screenshotPlay →

Complete gameFlipper Fray

A four-player pinball brawl: one round table, four pockets, a pair of flippers guarding each. The playfield is a dome: everything rolls outward from the centre, so every ball becomes somebody's problem; bumpers, slingshots and lane posts throw the balls around, and every ball that gets past your flippers costs you a life — five lives, last pocket standing wins, or the most lives when three minutes run out. You hold the bottom pocket against three AI keepers; multiball drops extra balls on a schedule and a bomb ball rolls out every half minute — two lives if it drains, a blast if nobody swallows it. ← → / A D flip, SPACE both; on touch, hold the left or right half of the screen. Physics: the flippers are kinematic bodies driven with setVelocityFromTarget, so a slap carries real angular speed into the ball; balls are bullet-flagged circles, so nothing tunnels through the thin ring walls; bumper and slingshot kicks and goal credit come through InteractionListeners. In 3D a neon arena with chrome balls, glowing pockets and lane lights, seen from behind your own pocket.

GameplayPinballAIKinematicCCDListenersMobile
Swarm Night — gameplay screenshotPlay →

Complete gameSwarm Night

A survivor roguelite in the Vampire Survivors mould: five minutes in a walled graveyard, and you only steer — every weapon fires on its own. Kills drop XP gems; a full bar pauses the night for three upgrade cards drawn from six weapons (whip, wand, knives, ward, orbs, lightning) and eight passives. Six monster types arrive on a schedule, plus charging grave knights that carry treasure and a bone colossus at 4:00 whose slam throws the whole crowd. Dawn at 5:00 is the win. WASD / arrows to move, 1 / 2 / 3 or click to pick a card; on touch, hold anywhere to steer. Physics: up to 420 monsters are dynamic circles in a zero-gravity Space, so the horde crowds and streams around the stones with no flocking code; knockback is a mass-scaled impulse, and bolts, knives, spit and orbs are sensor bodies delivered through InteractionListeners with sensor-mask side filtering. In 3D a moonlit graveyard where every monster is an instanced low-poly rig.

GameplayRogueliteAICameraSensorsPerformanceMobile

All games →

Why nape-js?

nape-js is one of the few 2D physics engines for JavaScript and TypeScript that ships rigid body dynamics, joints (PivotJoint, DistanceJoint, WeldJoint, AngleJoint, MotorJoint, LineJoint, PulleyJoint, SpringJoint), fluid buoyancy, fracture, soft body, raycasting and convex sweeps, a built-in character controller, deterministic stepping for multiplayer rollback, binary serialization, replay recording, and an off-thread Web Worker bridge — all in a single ESM package (~175 KB gzip), with full TypeScript types and zero DOM dependencies.

Looking for an alternative to Box2D, Matter.js, Planck.js, or Rapier? Run the in-browser benchmark to compare them head-to-head, or jump into the interactive examples — physics demos and playable mini-games (platformer, MOBA, tower defense, slingshot, pinball, top-down shooter).

Built for AI-assisted development

Coding agents work best against a library they can read, type-check and actually run. nape-js ships all three.

llms.txt, served

The whole API in one plain-text file at /llms.txt, plus a complete reference at /llms-full.txt — the emerging standard for feeding docs to a model. Paste the URL into your agent instead of scraping HTML.

Types the model can trust

Hand-written TypeScript throughout with strict: true, shipped as generated declarations. Your agent gets real signatures and TSDoc on hover, so it invents fewer methods that don’t exist.

Runs headless in Node

Zero DOM dependencies: an agent can import the engine, step a simulation and assert on the result in a terminal — no browser, no canvas, no mocking.

Deterministic, so tests hold

With space.deterministic = true the same inputs give the same output on the same platform. An agent-written regression test stays green for the right reason.

Documented pitfalls

An anti-patterns guide and a troubleshooting guide spell out the mistakes models most often make with physics APIs.

Task-shaped recipes

The cookbook is organised by goal — platformer, ragdoll, fluid, replay — which is the shape a prompt usually arrives in.

Benchmarks

Measured in your browser right now. Each test runs the physics step() in a tight loop and reports the median time per step.

Press the button to start.

API at a Glance

Core

  • Space — physics world
  • Body — rigid body
  • Vec2 — 2D vector
  • AABB — bounding box

Shapes

Support nape-js

nape-js is MIT-licensed and built in the open. If it saves you time — or ships your game — a sponsorship keeps the demos, guides and releases coming.