Shipping a game

Getting a game to people, and keeping its repo alongside Patchwork.

A game is games/<game>/ inside a clone of Patchwork. It reaches players as index.html, the whole game in one tab, or as client.html against <game>.server.ts on node, one seat per page.

#Playing it from your machine

1. Run yarn tsc and each test file of the game with yarn vitest run <file>, or yarn test:view <file> for a .view.test.tsx. Then play index.html, and client.html against the server.
2. From the repository root, serve the pages: yarn vite --host --port <port> --strictPort. Give Vite a port other than 5173, which is the editor's. The pages are at http://<address>:<port>/games/<game>/index.html and client.html.
3. With --host, everyone on the network can read the whole repository except .env, .env.*, *.pem, *.key and .git. Use it only on a network whose people may.
4. On the same machine, from the root, run node --experimental-strip-types games/<game>/<game>.server.ts. It listens on scenemanager.port of <game>.scene.json; that port and Vite's must both be open to the players.
5. Hand out index.html at the network address for one player, or client.html for players together, one window each. The editor's address answers only on localhost, and dev.html is never handed out.

A new game takes one seat; raising it is in Going multiplayer. A player whose machine vanishes without closing the socket holds the seat until the operating system gives up on the connection.

#Going online

1. A static host (GitHub Pages, itch.io, a CDN) needs an export of the game, a site written from the game's files. The repository itself, or vite build's dist/, shows a blank page.
2. The export holds the pages' imports as JavaScript, every file the pages load while they run (each scene's sim, each <kind>.client.ts, the game's own plugins, each .actors.json), and every catalogue file at its path from the host's root, /games/<game>/assets/<game>.json.
3. Serve the site at the host's root, not a subpath, and send the .ts paths with a JavaScript content type.
4. For client.html, run the server on the machine that serves the pages, from a clone with yarn install, on Node 22.6 or later. The page dials ws:// on the host it came from, so a page served over https:// cannot reach it.

#Your repo and Patchwork

A game's repo is made with git clone --origin upstream https://github.com/outsidedata/patchwork.git <game>. upstream is Patchwork, which you read from. Add your own with git remote add origin <url> and git push -u origin master. games/<game>/ is committed like any other folder.

#Taking Patchwork's updates

1. git fetch upstream, then git switch -c update-core.
2. git merge upstream/master. On a conflict, write what the lines should be and commit, or git merge --abort. For yarn.lock, run git checkout --theirs yarn.lock and then yarn install.
3. Run yarn install and yarn tsc, then the test beside each file in git diff --name-only master update-core, then the game's tests.
4. If the pages changed, write the game's pages again in the new shape with the game's names. yarn tsc never checks a page, so play index.html and client.html.
5. git switch master, git merge update-core, git push origin master.

#Giving back

A plugin, addon, editor extension, script or edit to a Patchwork file that names no game can go back as a pull request. The engine itself is never a pull request; a feature that needs it is an issue.

1. Fork once: gh repo fork outsidedata/patchwork --clone=false, then git remote add fork <url>.
2. git fetch upstream, then git switch -c give-<name> upstream/master.
3. git checkout master -- <path> for each folder and file that goes, with its tests. Commit.
4. Run yarn install, yarn tsc and its tests on that branch, where no game is in the tree.
5. git push fork give-<name>, then gh pr create --repo outsidedata/patchwork --base master --head <you>:give-<name>.
6. Once it is merged, take Patchwork's updates and keep its version of each file the merge stops on.

#Checking it

1. yarn tsc and every test file of the game, including <game>.sim.test.ts, <game>.server.test.ts and <game>.predict.test.ts.
2. Played at the network address, not localhost: index.html, then client.html in two windows or on two machines, each player's thing moving on the frame after the key and each seeing the other move.
3. An export played from a static server that sends .ts as JavaScript.