Port

Make a game multiplayer (port)

A port is done when strangers who press Play land in the same live room, each browser renders the game itself, bots fill the empty seats, rounds end and restart, the controls mean the same thing every second on a phone and a computer, and the checks below pass on the live site. Take as long as it needs; quality is the bar, not speed. Never call it done on a guess: the checks say, or you say plainly what still fails.

The person should not have to type anything after asking. Find what you need, decide, and keep going. Stop only for something only they can give: the one Cloudflare approval, a licence question, or a game that is not a fit.

Finish in this turn. A port takes a long time; stay with it until it is live and checked. Never end your turn, schedule a wake-up, or hand back "it is running" while a check, a build or a deploy is still going: wait for it by polling (a short sleep then tail of its log, repeated) and keep working. When your turn ends, the processes you started (the dev server, a running check) end with it, and a half-ported game is left behind.

0. Find the game and the studio

• The game is the folder they named, or the current folder if it holds an index.html. Otherwise look one level down for the only folder with one.
• The studio is the folder with studio.json: here or above, else next to the game (find .. -maxdepth 2 -name studio.json). One found: use it. None: set one up first with the studio-setup skill (name it after the person's game), then come back. Several: use the one the person named, or ask which.
• The toolkit. In the studio, npx --no-install homie-studio port plan <game> must work. If it says unknown command, the studio's @homie-rocks/studio is older than the port toolkit: call the Homie MCP tool game_port for the pinned package and install it exactly as it says, then run npm install. Without the connector, npx -y @homie-rocks/studio@latest upgrade says what to change (the studio-setup skill, "An existing studio that is behind").

1. Read it and grade it (before changing anything)

npx --no-install homie-studio port plan <game folder>

The plan is a draft from reading files: engine, loop, input, camera, physics, storage, audio, size, licence, risks, and a grade. Now read the code yourself: the main loop, where input is read, what the state is (player, enemies, pickups, level, score), how the camera moves, what "game over" is. Then write PORT.md in the game (template: references/PORT-TEMPLATE.md) with:

• the grade — easy, medium, hard (fast physics, precise timing, huge state), or not a fit — and one paragraph of why, in plain words;
• the multiplayer design: what a round is, what the host owns, what each browser owns, what bots do, how a late joiner comes in, what the big screen shows;
• the movement mode: owner for action games (each browser moves its own body at once, the host bounds it), host for turn-based and grid games (the host's rules move bodies from intents);
• controls on keys and on touch, and the camera rule (below).

Tell the person the grade and why in two or three lines, then go on. If it is not a fit (it needs its own server, WebAssembly threads, or its licence forbids it), stop there and explain what would make it portable. The port toolkit is in beta: a game that is not a fit today, or a port the checks cannot judge, is worth a port request at https://github.com/homie-rocks/homie/issues/new/choose (the game's public address and licence, the grade and why; no keys or private addresses).

Licence: a game you did not make must carry a licence that allows changing and publishing it (MIT, Apache-2.0, BSD, ISC...). Keep the licence file with the game. No licence, or a licence that forbids it: port it for private testing only and say so.

2. Bring it into the studio

npx --no-install homie-studio port import <game folder> --id <id> [--name "<Name>"]

It copies the game to games/<id>/ untouched except: the port toolkit loads first in <head> (sandbox shims, first-touch audio, window.HomiePort) and the viewport is phone-safe. game.json says how it builds: static (the folder as it is, for plain <script> games), bundle (an ES-module entry bundled by esbuild), or command (its own Vite/webpack build; set its base to ./). The id is the game's address: lowercase, digits, hyphens.

3. Port it

Follow references/RECIPE.md: it has the worked example (a single-player canvas game turned multiplayer with createRoom), the patterns for turn-based, 2D action, platformer/physics and 3D games, and what goes in snapshots, keyed state and checkpoints. The rules that people's hands and real phones taught, with the bugs behind them, are in references/LESSONS.md. Read both before writing code.

Non-negotiable, every port:

1. Instant start. The first visitor is playing within seconds, with bots. No title screen, no "press Space", no waiting for players, no "tap for sound".
2. Rounds. A single-player "game over" becomes a round: a clock (60–180 s), a score race or a goal, results for a few seconds, then the next round by itself. Death respawns; it never ends a person's round.
3. Bots fill every empty seat, play by the same rules through the same inputs, and are beatable. An arriving person takes a bot's body where it stands. Make your bots honour the skill dial (servers, NETPLAY.md section 17): give BotBrain skill: () => room.skillOf(body) (reaction, aim and commitment follow the party's vote) and use jitter, engages and standoff for the rest of a bot's choices. createRoom keeps a hybrid server's AI seats and labels them AI. For guides that talk (a beginner server), give the game a vocabulary and useAgents (the game skill's "Write the guide vocabulary"; NETPLAY.md section 18). For AI that picks the bots' tactics or a director's call, room.net.decide per beat, never per frame, opt-in and with the game's own floor (the game skill's "Let the game decide with AI"; NETPLAY.md section 20). Room chat needs nothing from a port (the play page has it); draw speech bubbles over characters with createBubbles / paintBubbles from net.on('say') (NETPLAY.md section 19).
4. Host handoff. Everything the rules need is in the checkpoint; a promoted browser continues the SAME round (clock, scores, world).
5. Controls mean the same thing every second. Input is read on the camera's screen axes, never the character's facing. Tank/rotate controls become screen-relative (a direction held = go that way on screen). The camera never turns by itself while a direction is held.
6. Phones. A floating stick where the thumb lands, a few small see-through buttons at the edge shown only when useful, nothing opaque in the middle, UI under 12% of the screen, no touch UI on computers. Use the touch kit; do not write your own touch code. The world fills a phone held upright: a fixed arena letterboxed into a strip of a portrait screen looks broken. Follow your own body with a camera (your body about 14% of the screen's height) or lay the arena out for portrait. For a flat (top-down) world the kit's fitView does it: the whole world where it reads, else the world fills the screen and follows your body, never past its edge but for the HUD's margins. Names drawn over bodies pile up when they crowd: place them with createLabels (yours first, never covered; the rest move or fade). Both starters show the pattern. Your own body is unmistakable at a glance (a ring or highlight plus "You").
7. The big screen (/<id>/tv) is a spectator: no body, no personal prompts, an overview or director camera, readable from across a room. A watcher (/<id>/watch) follows one player: point the camera at room.viewBody() (your own local body when it is your seat) and the HUD at its numbers, and fall back to the overview when it is null (the recipe's section 8).
8. The probe. Call exposePort (see the recipe): the checks cannot judge a game that does not report where its player is. In its extra, set the state hooks the playtest and perf read by name, whichever the game has (PortExtra in the port kit types them): alive, mode, loadout, touchHeld, and in a 3D game drawCalls and triangles from renderer.info.render. The round needs no hook (createRoom gives it).
9. Randomness that changes the world happens on the host only. Names people type are drawn as text, never as HTML.
10. It is still their game: keep its look, its renderer, its feel and its name (add "Race", "Arena", "Party" if you like). The port adds multiplayer; it does not remake the game, and never rewrites something only to pass a check.