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

Made with nape-js

Shipped games running on nape-js physics — play them in the browser, or grab the native build.

Bamboo Roll — a panda rolling down a grassy hill through a bamboo grove Bamboo Roll Cozy one-button physics — hold to curl a panda into a ball and roll down the hills, let go to sit and stop — 40 levels in four worlds. Free in browser Three.js newkrok.com/gamer-zone → Impossible Wheels — a black-and-white monster truck flipping through the air above jagged hills, chasing a grey ghost truck Impossible Wheels Side-view physics driving — balance a monster truck over impossible hills, gaps and wobbly bridges and race an opponent’s ghost on six levels. Ported from Haxe nape to nape-js. Free in browser Canvas 2D newkrok.com/gamer-zone → Big Wheel Cup — monster trucks kicking up snow as they race along a dirt track through a pine-dotted snowy valley Big Wheel Cup Top-down monster truck racing — jumps, whoops and drifts against five rivals on 12 tracks in 4 locations, raced both ways round, with four cups and ghost time trials. Free in browser Three.js newkrok.com/gamer-zone → Scarecrow’s Revenge — a scarecrow with a pumpkin slingshot facing a crow fort on a farm at dusk Scarecrow’s Revenge 3D slingshot siege — launch pumpkins at crow forts of straw, wood, glass and stone across 40 levels, with fire, powder kegs and six trick pumpkins. Free in browser Three.js newkrok.com/gamer-zone → Next Stop! — an articulated bus driving down a narrow street between colourful town houses Next Stop! Bendy-bus driving — swing an articulated bus through narrow streets, pull in to the kerb and beat the timetable across 24 runs in 4 towns. Free in browser Three.js newkrok.com/gamer-zone → Grave Bounce — glowing souls bouncing through a ring of bone pegs in a haunted graveyard Grave Bounce Halloween physics puzzler — release souls from a gargoyle’s mouth and bounce them off bones to light every pumpkin, with a new Daily Haunt every day. Free in browser Three.js newkrok.com/gamer-zone → Last Lantern — a lantern-bearer at a graveyard crossroads, ringed by the risen dead Last Lantern Survivor roguelite with a physical horde — carry the last fire of a stolen sun through five nights of the dead, bowling monsters into each other. Free in browser Three.js newkrok.com/gamer-zone → Hitch & Park — a red car towing a boat trailer down a tree-lined lane Hitch & Park 3D trailer-parking puzzler — 48 levels in 8 chapters, from a box trailer to caravans, boats, a semi and a tank on a low loader. Free in browser Three.js newkrok.com/gamer-zone → Life of a Fish — a voxel fish swimming over a coral reef Life of a Fish A pixelated underwater dive — swim, dash and dodge through caves, with multi-phase boss fights and a daily descent. iOS Web demo Three.js loaf.newkrok.com → MX Dash — a voxel motocross rider mid-jump over rolling terrain MX Dash Side-view motocross arcade — an articulated rider on live suspension, big air, flips and slow-motion crash replays. iOS Web demo Three.js mxdash.newkrok.com → Dust Kings — a voxel monster truck throwing up dust on a dirt track Dust Kings Voxel monster-truck racing — hand-built dirt circuits, quick races and a daily challenge. Currently in closed beta. Beta Web demo Three.js dustkings.newkrok.com →

Curious how a demo grows into one of these? The games page walks the ladder from a single mechanic to a complete game, all in one file each.

Shipped something with nape-js? Open an issue and it can land here.

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.