window.patch is there when your game plays on Patch. Opened anywhere else it isn’t, so check for it and keep the game playable without it.
Before it’s out
Once Patch has checked a version’s files, it has a test link: its play page with?release=, which plays that version on Patch, sign-in and rooms included, before you publish it. Anyone signed in who has the link can play it, so send it to friends to try multiplayer together. Your game’s players never get it: it plays at its own address, with rooms of its own, and stops once the version is turned down. Publishing answers with test_link, and its invite links keep you on that version. A test link reaches the game’s own files, Patch’s rooms and direct links: your own server’s hosts apply once Patch has looked at them and the version is published.
Who’s playing
{ id, handle, name, picture }:
On Patch, everyone signs in before they play, so
getPlayer() has who’s playing. Where nobody has, ask:
signIn() resolves with null and your game plays on. window.patch.player is the player Patch last said, and playerchange fires on window.patch when it changes.
Rooms
Players in your game together. Patch passes their messages on and keeps who’s in the room, its host and its data. There’s no server to run and nothing to declare.patch.rooms.create({ max, listed, data, keep, anyRelease })makes a room with a 6-character code of capital letters and digits,room.code, to show and type.maxis 1 to 100 players (8 by default).listed: truelets quick matches find it.keepis how many minutes an empty room waits for its players to come back with its data: 2 by default, up to 1440 (a day) for turn-based games.anyRelease: truelets players on other versions in. Anything out of range, or an option a room doesn’t take, throwsbad_options: Patch makes every room’s code, so a game can’t choose one. Rooms are for browser games; a PC game or a mod brings its own server.patch.rooms.join(code)joins one, andpatch.rooms.quickMatch({ max, data, keep })joins the fullest listed room with space and the samemax, or makes one: a Play online button. A room nobody’s in waits for its own players and isn’t offered to strangers. The host’sroom.setListed(false)takes the room off quick matches once a match starts.patch.getLaunch()gives{ room }: the room of the invite link your game was opened from, or the room this tab was in before a reload. Join it at the start.room.playersis everyone, in the order they joined:{ id, name, handle, host }, each by their Patch name: everyone playing on Patch has signed in.- The host.
room.hostis the host’s id, androom.isHostsays whether that’s you. Patch picks the first player, and when the host leaves, or its page has been hidden for 5 seconds, whoever has been in the room longest and is still on screen (thehostevent, with their id). Let the host run what everyone shares, such as the world, the clock or the bots, and send it to the others. - The room’s data. The host’s
room.setData(data)replaces it. Every other player gets it (room.data, and thedataevent), and so does anyone who joins later: the map, the mode, whose turn it is. It’s up to about 16 KB as JSON, and more throwstoo_bigat once: keep a big world in messages, or rebuild it from a seed. The host’s ownroom.datais the new data straight away. - Messages.
room.send(message, { to })sends any JSON up to 16 KB, in order, to everyone else or to one player. Each player sends at most 30 a second, bursts of 60, room data included: past that a message is dropped and the sender getstoo_fast. Send state 10 to 20 times a second and smooth it on the others’ screens. - The room’s clock.
room.now()is the room’s time, the same on every screen: start countdowns and race clocks from it. It keeps counting while the room waits empty. - Testing. Patch’s own test opens the game alone with
?patch-test=1: with it and no room, play alone. To try several players before it’s out, open its test link and send its invite link to others, or open it in several browser profiles. - Late joiners. A message reaches only who’s in the room when it’s sent, so a player who joins late gets the room’s data and nothing sent before. Have the host send them what they missed when they join, with
{ to: player.id }. - Leaving.
room.leave()leaves, andclosefires when the room’s connection ends. A player who reloads comes back as the same player: join the same code again. - Versions. Only players on the same version of your game share a room. Someone on an older page gets
room_needs_update, and should reload. - Errors carry a
code:room_not_found,room_full,room_needs_update,code_taken,bad_code,bad_options,not_host,too_big,too_fast,room_unreachable, orno_patch(not on Patch). - To test with several players, open the play page in several browser profiles. Opening it with
?patch-test=1opens your game with it.
Direct links
For fast games, where every hundredth of a second shows: two players in a room link directly, and a message that arrives late can be skipped instead of holding up the rest. Patch relays the link and sets it up through the room, so there’s nothing to run, declare or pay for, and it works at a test link.room.link(id)resolves once the link with that player is open. Their room fireslinkwith it, so make links from one side, such as the host to each player as they join, or from both: two players linking at once make one link.link.send(message, { reliable })sends any JSON up to 64 KB. By default it arrives, in order. Withreliable: falseit goes at once or not at all, in no order: for state you send many times a second. Past what the link can carry it’s dropped, and a reliable message throwstoo_fast.link.on("message", fn)andlink.on("close", fn);link.close()ends it. A link ends when either player leaves the room, and when the room closes: link again after rejoining.- Through Patch. Links go through Patch’s relay, near each player, so players never see each other’s addresses and it connects on any network. Only players signed in to Patch get links, as on Patch’s play page.
- Your own WebRTC. An engine with its own WebRTC code can use the relay:
new RTCPeerConnection({ iceServers: await room.iceServers() }), with the room carrying its messages. Patch keeps the page’s connections to the relay. - Errors carry a
code:no_direct_links(not on Patch, or not signed in),link_failed(couldn’t link, or the player left),link_closed,too_bigortoo_fast.
Your own server
Rooms cover most games. A game whose rules no player’s browser may decide, such as checking a lap before it counts, or that keeps what players do, can bring its own server. Know who’s connecting.getPlayerToken() gives a token, signed by Patch for your game, that says who’s playing. Send it to your server and check it there:
- Tokens last 15 minutes, so call
getPlayerToken()each time you connect. audis your project’s id,subthe player’sid. The token also carriesgame,handle,nameandpicture.- Treat a token like a password: don’t log it, and send it only to your own server.
- Each host is
https://orwss://, a host name and an optional port, with no path.*.example.comcovers one level of subdomains. - Your next version takes them as it’s published, and a person at Patch looks at the hosts before it goes out.
- Your server sees requests from your game’s own address on Patch,
https://<id>-production.patchusercontent.com.