Overview

Patchwork is a multiplayer game engine shipped as source, made to be built with an agent.

A game is made by cloning the Patchwork repo. The engine and every plugin and addon are folders you can read, change and commit; nothing is published to npm. Each piece is described in the header of its own file and tested by the files beside it, and the repo's .claude/ folder holds the rules an agent such as Claude Code reads before it writes code.

#The model

• A scene is a file: how a world starts and which plugins it uses. Its world holds its fixed numbers, its prefabs what a new row of each kind starts as, and its actors the rows it starts with. A game's manager scene holds its scenes.
• A row is one thing in the world, and its kind is what it is. A kind's code is its actor: its rule, <kind>.sim.ts, run on the server every step, and its drawing, <kind>.client.ts, run in the page.
• A running world is a truth, and one tick of its time a step. Every step it sends each seat a packet of the rows it may see.
• A seat is a player's place in a truth. It plays as its own player row, and a press is a message asking that row to act.
• A plugin lives in the world or in the browser; an addon holds a truth. The engine, engine/, is frozen: everything new is a plugin, an addon, or a game's own kind.

#What you get

• 2D drawn with PixiJS through render2d, and 3D with three.js through render3d. Patchwork's three.js build returns the same math results on every JavaScript engine.
• Physics by Box2D v3 and Box3D as WebAssembly (box2d, box3d), the same bytes on the server and in every page.
• Multiplayer: the server holds the truth and sends each seat its rows every step. A page runs its scene ahead of the server (predict), so a press shows on the next frame, and the server puts a late press back on the step it was made on (rewind). One scene runs in one tab, over a WebSocket on node, or on a simulated bad network, with the same code.
• 57 plugins and 13 addons, each with a page under Modules.

#Requirements

• Node 22.6 or later.
• Yarn 1.
• To bake art, and only then: Blender, the library of raw parts the bakes read, the native gltfpack 1.3 or later (it packs WebP textures; the npm one cannot), and ImageMagick built with libwebp. Copy .env.example to .env and set BLENDER, PATCHWORK_LIBRARY, GLTFPACK and MAGICK where yours differ from the defaults it lists.

yarn health runs each of these tools and prints what passes, what fails and how to fix it. yarn bake <game> runs its checks of the baking tools first, stops when any fails, and then runs the game's games/<game>/assets/<game>.bake.ts, which writes the built art the game ships into its assets/.

#Getting started

git clone --origin upstream https://github.com/outsidedata/patchwork.git mygame
cd mygame
yarn install
yarn new-game mygame

--origin upstream names Patchwork's remote upstream, which leaves origin for your own repo.

yarn new-game <name> writes games/<name>/: one scene, main, on render2d, with a seat that starts at a start actor and moves a square with the arrow keys. Run it again with another name to make a second game.

Play it from games/<name>/index.html, or run its server and open client.html:

node --experimental-strip-types games/mygame/mygame.server.ts

The example games are in their own repo. Clone it as games/:

git clone https://github.com/outsidedata/patchwork-games.git games

#How the docs are laid out

The Modules tab has a page for every plugin and addon: its settings, its methods and what uses it. The Guide tab has these start pages, then the work of making a game in the order you do it, from Starting a game, then distributing it and making its assets.