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.42.1 ~175 KB gzip
GitHub Try the Demos
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.

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.

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
Tin Legion — gameplay screenshotPlay →

Complete gameTin Legion

A lane-siege army builder on one large battlefield: gold trickles in, five troop cards wait at the bottom of the screen, and each one you play drops a squad of tin figurines that marches off on its own. You never steer a soldier — you choose what to field, where to drop it and when; hold a card and the road that squad would take is drawn on the ground, and the side of your gate you drop on picks its lane. Three roads run between the two keeps, a watchtower guards each centre road, and two gold mines sit on the flanks behind neutral camps. A captured mine pays gold and pushes your drop zone forward; a keep is shielded until its own watchtower falls. Ten cards, a free commander, and three difficulty levels for the opposing one. Physics: every figurine is a dynamic circle in a zero-gravity Space, so crowds shove and flow for free; shot is a sensor body delivered by InteractionListeners, with friendly fire ruled out by sensor groups and masks rather than an if-statement; kegs detonate with a real radial impulse, and flyers have their own collision group. In 3D it is a grassy plateau floating in mist, with a jointed low-poly rig per troop type.

GameplayAIWaypointsSensorsGroupsCameraMobile
Blade Waltz — gameplay screenshotPlay →

Complete gameBlade Waltz

A Tales-style action-battle gauntlet on a round arena: ten waves of monsters, a party of four, and you control the swordsman only. Run freely, land 3-hit combos (J / click), spend TP on artes (K — neutral for the Demon Fang ground wave, toward the target for the Sonic Thrust dash, away for the launching Tiger Blade), guard with L, and unleash the Mystic Arte with SPACE once the Overlimit gauge fills from dealing and taking hits. Normal hits refill TP; guards only cover your front; stone golems and bosses shrug off single hits. Your AI party plays its roles: the lancer brawls and chains thrusts, the archer kites and volleys, the sage heals, revives and casts fire and stone with interruptible cast times. The tenth wave is a drake with claws, a tail spin, fire breath, a roar and wisp summons. Every combatant is a dynamic puck inside a ring of static wall segments; melee is resolved from arcs, while arrows, bolts, fireballs and waves are sensor bodies delivered by InteractionListeners with side filtering done by sensor masks. In 3D a side-on chase camera frames the player–target line over a stone arena in a meadow, with jointed low-poly rigs for every combatant.

GameplayAICameraSensorsCallbacksMobile

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.

Prompts for building a game Point your agent at /llms.txt

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

Constraints

Callbacks

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.

Sponsor on GitHub Support me on Ko-fi ★ Star on GitHub