← All docs Games for Group · Architecture

The Live Channel

One page to understand the live channel and use it in a new feature. What it is, how a phone gets in, what it costs, and two worked examples.

⚡ The live channel is a side path next to the game. Convex still owns every real move. A tiny Cloudflare relay passes the "fine to lose" things between the phones in a room, like cursors in Figma, and stores no messages.

The one rule: if losing a message would be wrong, it cannot go on the relay.

The picture

Quick Draw, online. The same drawing travels two ways at once.

Fast path · the relay · the line while it is being drawn

Drawer's phonepen points, gathered

~10 msgs/s

Relay roomone per online room · stores no messages

stamped "from"

Guessers' phonesdraw the growing line

Sure path · Convex · the finished line

Drawer's phonepen lifts: one stroke action

a game move

Convexchecks the rules · saves it

room state

Everyonethe real stroke replaces the live one

The two paths side by side

	The relay (live channel)	Convex (the game)
Carries	Previews: a line being drawn, later a pointer	Moves: a finished stroke, a guess, a score
Saves	Nothing. A late joiner hears nothing from before	Everything, and replays it to anyone who arrives
Checks rules	No. It only checks who sent it, size and speed	Yes. The game's rules run on every action
If it is down	Nobody notices. Drawings appear a stroke at a time	The online game stops
Cost driver	Seconds a room is awake, plus message count	Function calls, stored data, subscriptions

Getting in: the room pass (ticket)

The relay never calls Convex. Convex hands the phone a signed pass, and the relay only checks the signature.

The phone asks Convex for a pass, with its room id and its device's session id.
Convex finds the player for that session in that room. No player row, no pass (the phone plays on without the channel).
Convex signs { room, player, signed at, expires in 2 minutes } with LIVE_SECRET. Nothing is written to the database.
The phone connects to wss://live.gamesforgroup.com/room/<roomId>?ticket=…
The relay checks the signature, the room and the time. A bad pass is turned away before the room even wakes.
The relay stamps from on every message that socket sends, using the player in the pass. A phone can never claim to be someone else.
The pass is read once, at connect. An open socket keeps working until it closes. Every new connect asks Convex for a fresh pass, so a player who is not in the room gets none. A player removed while connected is cut off at once by the kick below, and the passes they already hold stop working.

Why nothing is stored

A pass is worked out when asked and simply stops working after 2 minutes. No table, no clean-up job. It only has to last from Convex to the relay's front door.

Why it rides in the address

A phone's WebSocket cannot reliably send custom headers. So the pass goes in the link, which is fine for something that dies in 2 minutes.

One signing file

Convex and the relay import the same file to sign and to check. The two sides cannot drift apart.

How a removed player is cut off: the kick

The pass is checked only at connect, so removal has its own path. A removed player stops hearing the room at once, whatever feature holds the channel.

A player row is deleted. The host's Remove (lobby or mid-match), a guest's own Leave, and the host closing the room all go through one place, which also deletes presence.
That same place schedules one kick, which runs only if the removal is saved. One call per removed player. No table, no shared document.
Convex calls the relay: POST /room/<roomId>/kick with { playerId } and a signed kick pass (1 minute, bound to that room and player). A join pass is never accepted as a kick, and a kick pass never opens a socket.
The relay closes every socket that player holds in the room, with code 4003. The phone stays closed until its screen lets go of the channel and holds it again.
The room remembers the kick for 2 minutes, the life of a pass. A connect from that player with a pass signed at or before the kick is refused, so a pass fetched before the removal cannot reopen a socket after it. A player let back in gets a pass signed later, and connects as normal. After 2 minutes every such pass has expired anyway, so the room forgets the kick.

If	Then
The kick call fails, or the relay is down	Nothing errors. The removed phone keeps any open socket until it closes, and Convex gives it no new pass. A pass it already holds still opens a socket until that pass expires, within 2 minutes
The backend has no `LIVE_HTTP_URL` or `LIVE_SECRET`	No kick is scheduled at all. The dev backend runs in the cloud and cannot reach a relay on a laptop, so it leaves the address unset
The stale-room clean-up deletes a room's players	No kick. Those rooms have been silent for far longer than the relay's 3-minute idle close

Worth knowing Checking the pass only at connect is the price of never asking Convex on every message. The kick and the room's memory of it close that gap for removal. Everyone still in the room hears everything, so nothing secret goes here.

Inside a relay room

One Cloudflare "Durable Object" per online room: a tiny always-addressable room object, named by the Convex room id. It knows nothing about games. A topic is just a name.

A phone sends

{ topic: "pen", data: {…} }

Goes to every other player's sockets in the room. The sender does not hear its own message.

The others receive

{ topic: "pen", data: {…}, from: "playerId", at: 1757… }

from comes from the pass, at from the relay's clock. Trust both. Never trust data: check its shape.

Limit	Value	What happens past it
Message size	8 KB	Dropped, silently
Sockets in one room	40	The next one is turned away
Speed, per socket (one connection)	40 messages a second	The extra ones are dropped, silently
Flood, per socket	More than 80 messages in one second	The socket is closed (code `1008`). An honest phone never comes near it: the pen sends about 10 a second
Sockets per player	2 (two tabs, or a reconnect while the old socket is still closing)	A third closes that player's oldest socket (code `4001`). Neither socket hears that player's own messages
Topic name	64 characters	Dropped
Quiet room	3 minutes with no message passed on	The room closes its sockets (code `4000`). A phone still using it reconnects

Close code	Means	The phone
`4000`	The room went quiet	Reconnects if a screen still holds the channel
`4001`	Replaced by a newer socket of the same player	Stays closed until its screen lets go and holds the channel again, so two tabs never take turns knocking each other off
`4003`	Removed from the room (the kick)	Stays closed until its screen lets go and holds the channel again
`1008`	Flood: far too many messages	Retries, and its waits keep growing

What counts as activity A room has a single wake-up timer for the quiet-room check. A message passed on counts as activity, and so does the connect that opens an empty room. A dropped message does not, so a flood never keeps a room open. Nor does a phone joining a room that is already open, so a phone retrying its connection never keeps a silent room open.

An empty room keeps only its recent kicks When a room's last socket closes, the room deletes everything it stored: the quiet mark, the wake-up timer and every kick older than 2 minutes. A kick younger than that stays, with one timer set for when it stops mattering. When that timer fires on an empty room, the room deletes the rest and sets no other.

Sleeping, in plain words A room with open sockets but no messages hibernates: Cloudflare keeps the connections, unloads the room, and stops billing. The next message wakes it in an instant. Billing is for the time a room is busy, so a steady stream (a pen moving) costs the most. Closing the socket when nobody needs it keeps a room at zero. The numbers are in What features cost.

On the phone: the kit

A board gets the channel as an optional live prop and uses one hook. It never knows which mode it is in.

import { useLiveChannel } from '~/live'

// Open only while this is true. Returns { publish, subscribe }.
const pointer = useLiveChannel<{ x: number; y: number }>(live, 'pointer', state.phase === 'playing')

// Send (to everyone else; dropped if not connected)
pointer.publish({ x: 120, y: 480 })

// Hear
useEffect(() => pointer.subscribe((msg) => {
  // msg.from = who sent it (trust it). msg.data = anything (check it).
}), [pointer.subscribe])

Behaviour	What it means for you
Open only while held	The socket opens when the first screen passes `active = true` and closes when the last one lets go
2 second linger	Closing waits 2 s, so a quick hand-over between turns does not reconnect
Background closes it	The app going to the background closes the socket. Coming back reopens it if a screen still holds it
One socket per room	Every topic on screen shares it. Two hooks do not mean two connections
A fresh pass each connect	Every connect and reconnect asks Convex for a new pass. An open socket never asks again
Says when it opens	`onOpen` on the connection tells a listener every time a socket opens, a reconnect included (and at once if it is already open). The lobby uses it to ask what it missed
Silent retry	No pass, relay down, over the free allowance, no network: its first wait is 0.5 to 1 s, then it doubles, up to 60 s, always with a little randomness. The waits start over only once a socket has stayed open 10 s: every connect asks Convex for a pass, so a relay that lets a socket in and drops it is waited out like one that is down, never retried once a second by a whole room. After a kick (`4003`) or being replaced by a newer socket of the same player (`4001`) it does not retry. No error ever reaches the player

Mode	Has a channel?	Why
Online	✓	The online screen makes one relay connection for the room
Same device	—	One screen. Nobody else to show. `live` is left out
LAN (paused)	—	No internet by definition. The host phone's own socket could carry the same topics later

Without a channel, publish does nothing and subscribe hears nothing. So the board has no mode checks, and must play fully without it.

Worked example: Quick Draw's live pen

When it opens. Only during a drawing turn in a room of phones. The one-phone easel version has nobody to show. Between turns it closes.
The drawer sends in batches. Pen points are rounded, tiny moves are skipped, and what gathered goes out every 100 ms (about 10 messages a second, not 60). Lifting the pen sends the rest at once, marked "line ended". While the pen is down but held still, an empty "still drawing" message goes out about once a second.
Guessers ignore everyone but the drawer. A message whose from is not the current drawer is thrown away, and every batch's shape is checked.
Smooth, not jumpy. Each batch is revealed a little per frame across the next 100 ms, so the line grows instead of jumping.
Handover with no flicker. Each live line knows the place its real stroke will take. The same screen update that first paints the real stroke stops painting the live line. Never both, never neither.
Clean-up. A new turn starts empty. Clear or Undo drops every live line. A finished line whose real stroke never arrives is let go after 4 seconds. An unfinished line that hears nothing from the drawer for 3 seconds, neither points nor "still drawing", is let go too: the drawer has dropped.
Late joiners. They get every finished stroke from Convex. Of the line in progress they see only what is drawn after they arrived, until the real stroke lands.

The rules are plain functions with tests (quick-draw/ui/livePen.ts). The hook that wires them to the screen is quick-draw/ui/useLivePen.ts.

Worked example: who is where in the lobby

The online lobby is a room people walk about in. Where each of them stands is agreed between the phones on this channel and stored nowhere: a walk across the room is not a database write, and wakes nobody's subscription.

Topic	Says	Carries	Size sent (30 in the room)
`room.go`	My move	The scene, the place and its spot, my own count of my moves, and, when I came down a ride, which of the scene's rides it was (its number in the scene's own order, from one to eight). Never who: the relay's stamp is the only "who" there is, so nobody can move anybody else	75 bytes
`room.do`	Something short-lived I did	A hello or a bounce where I already am, or a toy used. A toy that keeps its state (the lamp) says how far it now is; one that does not (the popcorn) is seen once	60 to 75 bytes
`room.hello`	What did I miss?	The scene. Sent every time this phone's socket opens	50 bytes
`room.where`	The room as I hold it	Everybody's latest move as a short row each, the old move of whoever asked, and how each lasting toy was left	About 1.6 KB (0.5 KB for a room of 8). The relay passes 8 KB

Held while the room is looked at. The lobby holds the socket while its screen is in front and the app is in the foreground. A game starting, or another screen opened over it, lets it go.
A phone asks, and one phone answers. On every open a phone says hello and says its own place again. Every phone that knows the room waits its turn (the host first, then the order people came in, a quarter of a second apart, skipping whoever asked and whoever's phone is away) and stands down when it hears somebody else's snapshot. One answer, not twenty-nine.
The first move waits to be told. A phone makes no move of its own until a snapshot has come, or 1.2 seconds have passed since its socket opened. If the snapshot holds a move of its own it makes none: someone who reloads is back where they were. Otherwise what the move is depends on one thing. Somebody who has only just come into the room makes their way in, through the scene's door to a place that is free (down the slide at the pool): the one entrance there is, drawn by every phone, once. Anybody else was here already and only keeps the place the room had drawn them in. That is what happens when everybody opens the room at once (a game has just ended): thirty phones keeping thirty different spots never collide, and nobody is seen coming in who never left.
Another scene is another room to be told about. The host's pick of a scene is not on this channel: it is on the room, in the database, and every phone hears it from there. Each phone then starts its talk again for the new scene on the socket it already holds: it asks what it missed there, and from then on ignores whatever is said about the old scene (as a phone still in the old one ignores what is said about the new). Nothing has to be said for the change itself: everybody is simply there in the new scene, where it welcomes them, and that is read off the roster every phone already holds. Each phone's first move there is the same as after a game: it keeps the place it stands in.
A few moves a second, at the most. A storm of taps leaves the phone as its last one. A move made while the socket is down still moves that person on their own screen, and is said again when the socket opens.
A phone that knows more says so. When a snapshot is behind what a phone holds (a later move, or a move it does not carry, for someone in the room or for whoever asked), that phone sends a snapshot of its own, in its turn, at most once every twenty seconds. So whichever phone missed a message, the one that answers included, is level again after the next snapshot anybody sends.
A quiet room is told again. When no snapshot has passed for 150 seconds, the phone whose turn it is sends one. It brings phones level that nobody noticed had drifted, and it keeps the relay from closing a silent room after three minutes, which would make every phone reconnect and ask the backend for a pass.

What is promised, and what heals Two phones that have heard the same moves and hold the same roster draw the same room, whatever order those reached them in. Two things are not held, and heal instead: a phone that missed a message draws a different room until the next snapshot, and someone who comes back is where they were once a snapshot reaches their phone (until then their phone draws them where the room welcomes them). Being told is not seeing: when a snapshot puts people somewhere else they are simply there, and nobody is drawn walking, or riding the slide again, to a place they were already in. With no channel at all a phone draws everyone where the scene welcomes them, and its own taps still move it on its own screen.

Read as rubbish until it proves otherwise Everything off the wire is checked for shape, then checked against the scene; anything that does not fit is ignored, never thrown, and a snapshot is read no further than a room could hold. A second wave or bounce from one sender inside a moment is not played, one question is kept for each person however often they ask, and a phone sends a snapshot at most every third of a second. A snapshot does speak of other people (it is how someone who comes back learns where they were), so a tampered phone could put a made-up move in one, and that is all it could do: a snapshot's counter is believed no higher than 10,000 while a person's own move may be numbered far past it, so the friend's next tap puts them where they tapped on every phone. A lasting toy is guarded the same way: how far on the lamp is, is believed no more than 10,000 past what the phone itself holds, in a snapshot and in a tap alike, so a made-up count cannot leave it dead (the next real tap is one more, and is believed). And a ride is named by a number that must be a whole one from one to eight, or the message is no move; a number in that range that the scene has no ride for still moves its person, who is simply there with no ride drawn, so two phones never disagree about where somebody is because of how they got there. It is a friend's mascot in a waiting room, and the host can remove whoever does it.

The messages and whose turn it is are plain functions with tests (modes/online/roomWire.ts); the rules of who is where are the scene's own, tested (ui/scene/places.ts). The hook that wires them to the room is modes/online/useRoomPlaces.ts.

Using it elsewhere

Example: a teammate pointer in Spy Grid

While a team is guessing, each guesser's finger shows as a coloured dot on their teammates' screens, so "this one?" needs no words. This is an idea, not built.

// in Spy Grid's Board
import { createBatcher, useLiveChannel } from '~/live'
import { canReveal } from './game'

type Point = { x: number; y: number }   // 0..1000 across the grid, so every screen size agrees

const guessing = state.phase === 'playing' && state.turn.step === 'guess'
const pointer = useLiveChannel<Point>(live, 'cursor', guessing)

// SEND: only a guesser on the acting team. Keep the latest point, send ~8 a second.
const [batcher] = useState(() => createBatcher<Point>(120, (pts) => pointer.publish(pts[pts.length - 1]!)))
const onMove = (p: Point) => { if (canReveal(state, me)) batcher.push(p) }

// HEAR: one dot per guesser, at their latest point
const [dots, setDots] = useState<Record<string, Point & { at: number }>>({})
useEffect(() => pointer.subscribe((msg) => {
  if (!canReveal(state, msg.from)) return                 // only acting guessers
  const d = msg.data as Partial<Point>
  if (typeof d?.x !== 'number' || typeof d?.y !== 'number') return   // untrusted: check it
  setDots((old) => ({ ...old, [msg.from]: { x: d.x!, y: d.y!, at: msg.at } }))
}), [pointer.subscribe, state, me])

useEffect(() => { if (!guessing) setDots({}) }, [guessing])   // turn over: clear

Why the guess step, not the clue step Every socket in the room hears every message, the other team and spectators too. A spymaster's finger hovering over cards would leak the key. So only guessers publish, and only while guessing.

Reactions kit

Live-stream style emoji reactions: a player taps an emoji and it floats up every screen in the room, like hearts on a live video. Built once in ~/ui, so a game, a lobby or a results screen adds it in three lines. Quick Draw, Charades and Undercover use it. The eight emojis are Google's Noto 3D pictures bundled with the app (ReactionIcon, credits in assets/reactions/), never the phone's emoji font, so every phone shows the same ones. In Quick Draw reactions are for the people watching, never the one drawing. Everyone sees the emojis float up the canvas while a drawing is on and through its reveal. On a phone a watcher taps the drawer's mascot in the canvas's corner and the row opens above it, folding away four seconds after the last tap, and the emojis rise from just above the mascot and fan out up the paper; on a tablet or desktop the row always shows under the canvas, where the drawer's tools sit on the drawer's screen. The row is out wherever the screen has room, and behind a mascot only where it would cramp the screen: Quick Draw's phone has no room (the paper takes the width), Charades' acting screen has, so there the row sits at the foot of every watcher's screen, phone included, and the emojis rise from it over the clock. Undercover's unmasking has the room too: the row sits over the button and nobody's mascot is a button.

Reactions can belong to one match. A room running a tournament plays several matches at once, and a cheer is for the board someone is looking at. The hook takes a third argument, the topic: matchReactionTopic(key) makes one from the match's own name (react:r1m2), so only the screens holding that topic send and hear those emoji, on the room's same one socket. Left out, the reactions are the whole room's, which is what Quick Draw, Charades and Undercover use. Someone watching a tournament has the row out under the screen and the emoji rise across the whole board (side="across"); the two players of a match see none unless they switch them on, and then their screen holds the same topic (MatchReactions in modes/online/tournament/watch). With no live channel in the build the row is not there and everything else works.

import { FloatingReactions, ReactionBar, ReactionRow, useReactions } from '~/ui'

const reactions = useReactions(live, state.phase === 'drawing')   // holds the channel only while true
const cheers = useReactions(live, true, matchReactionTopic(matchKey)) // one match's own, in a room playing several

<FloatingReactions reactions={reactions.reactions} bottom={64} />   // over the area people cheer at (side="left" | "center" | "right")
<FloatingReactions reactions={…} corner={{ left: 6, width: 54 }} />   // or rising from a corner, fanning out (Quick Draw's phone: the mascot)
<ReactionBar reactions={reactions} />                                // a corner button that opens the row; hides with no channel
<ReactionRow reactions={reactions} />                                // or the row itself, always showing

const menu = useReactionMenu(reactions.available)                    // a trigger of your own (Quick Draw's mascot), from '~/ui/reactions/ReactionBar':
<ReactionMenuRow reactions={reactions} menu={menu} align="start" />   // the bar's row, fold-away and pause, opened by menu.toggle

Rule	Value	Why
Topic	`react`, sent as `{ r: 'fire' }`	An id, never the emoji, so every phone agrees on what it is
The pictures	Google's Noto 3D, bundled	Each screen shows the id as a picture shipped with the app (128px PNGs, Apache 2.0), so no phone's emoji font decides what the room sees
The set	👍 👎 ❤️ 😍 😂 🔥 👏 🤔	Tuned for a drawing game: thumbs up and thumbs down, a red heart, love it, so funny, on fire, nice one, and "what is it?" (all eight named by Karim). The heart is sent as the id `heart` and shown as Noto's red heart everywhere
The row	One line, never two	The buttons fit the width the row has: up to 40px in a phone's corner, up to 44px under a big screen's canvas, never under 36px. All eight show at 375px; only a narrower box scrolls sideways, and it comes to rest on whole emojis
Sending	At most 5 a second from one phone	Extra taps are ignored silently. Far under the relay's 40 a second and its 80 a second flood close
Spam pause	10 sent inside 10 s pauses that phone for 10 s	The emojis dim and send nothing, no message. A thin bar along the row (and a ring around the round corner button, none around Quick Draw's mascot) fills over the 10 s, then the emojis pop back. Cheering in bursts is fine, holding the room hostage is not
Hearing	Known ids only, at most 8 a second from one player	Anything else is thrown away, so one bad phone cannot fill the screen
On screen	At most 30, each floats about 2.4 s	A new one drops the oldest
Your own tap	Floats at once	The relay never sends a player's own message back

Mode	Reactions?	Why
Online	✓	Over the room's relay, while the screen holds it
Same device	—	No `live`, so the bar hides. One screen: the table cheers out loud
LAN (paused)	—	No `live`, so the bar hides

Cost A reaction is a few bytes and wakes the room only while people are tapping. The screen picks active, so the channel is held only for the moment worth cheering. In a room that already holds the channel (Quick Draw's pen) it adds almost nothing. The rules are plain code with tests in ui/reactions/reactionFeed.ts, and the /catalog shows it with a pretend crowd.

Good fit or not?

Idea	Fit	Why
"Karim is typing…"	✓	Missing one blip changes nothing
Emoji reactions floating up	✓	Decoration. Lost one, nobody knows. Built: the reactions kit
A pointer or finger position	✓	The next position replaces the last
A decorative host animation others watch	✓	The real result still comes from state
Buzzer: who pressed first	✗	Decides a score. Must be a Convex action, with Convex's clock
Chat history	✗	The relay keeps nothing. Refresh and it is gone
A player's secret answer or hand	✗	Everyone in the room can hear the socket
Something that changes once every few seconds	✗	A normal game action is simpler and already works everywhere

Before you put something on the live channel

If this message is lost, is the game still correct? If no, use Convex.
Does the game play fully with live missing (same device, relay down)?
Is it fine for everyone in the room to see it, spectators included?
Is active true only for the moment it is needed, not the whole match?
Is a fast stream batched (about 10 a second or less), and each message well under 8 KB?
Does the receiver check msg.data, filter by msg.from, and hand over to state without a flicker?

What features cost

What a live feature costs to run, per room and at scale. Prices from Cloudflare's pricing and limits pages (September 2026). The first-time reasoning is in decisions.

How the bill works

1 · Awake time

A room is billed as 128 MB for every second it is active. Features in the same room share one awake bill, so adding reactions to a Quick Draw room adds almost nothing.

2 · Incoming messages

20 messages a socket sends = 1 request. Passing a message on to the other phones is free. Each socket opening, and each kick, is also a request.

	Free plan	Workers Paid ($5 a month)
Awake time	13,000 GB-s a day	400,000 GB-s a month included, then $12.50 per million GB-s
Requests	100,000 a day	1 million a month included, then $0.15 per million
Going over	Calls fail until midnight UTC. Phones retry quietly, drawings fall back to a stroke at a time	Billed

Per room-hour

10 players, the feature keeps the room busy the whole hour. One awake room-hour is 3,600 s × 0.125 GB = 450 GB-s ≈ $0.0056. Messages add $0.15 per million requests on top, which is why the pen and the mascots cost a little more. The free day holds 13,000 ÷ 450 ≈ 29 awake room-hours.

Feature	Who sends, how often	Messages an hour	Paid, per room-hour	Free room-hours a day
Emoji reactions (lobby, results, in game)	About 1 reaction every 5 s, from anyone	720	$0.006	~29
Typing status	Each typer, at most 1 every 2 s	~9,000	$0.006	~29
Quick Draw live pen	The drawer, 10 a second	36,000	$0.006	~29
Places in the lobby, as built	Each person, a move when they tap (a few a second at the very most), and one snapshot when the room has been quiet 150 s	~3,600 for a lively room	$0.006	~29
Mascots roaming a lobby (Among Us style)	All 10 players, 10 a second while moving	360,000	$0.008	~5 (the request limit binds)
Same mascots at 5 a second, smoothed on screen	All 10 players, 5 a second	180,000	$0.007	~11

At scale, paid plan

Usage rates only, before the included amounts and the $5 plan fee.

Room-hours a month	Reactions or typing	Quick Draw pen	Mascots at 10 a second
1,000	≈ $5.70	≈ $5.90	≈ $8.30
10,000	≈ $57	≈ $59	≈ $83
100,000	≈ $570	≈ $590	≈ $830

Each is 1,000 room-hours × $0.0056 awake, plus that feature's messages: 36,000 an hour for the pen is 1,800 requests, about $0.27 per 1,000 room-hours.

Worked examples

Session	What it uses	Paid	Free
One Quick Draw game, 10 players, 3 rounds	30 turns × 82 s awake ≈ 2,460 s ≈ 310 GB-s. ≈ 1,500 room requests, ≈ 300 Worker requests	≈ $0.004	~42 such games a day (awake time binds)
A 2-hour party night, 10 players	Reactions + typing + the Quick Draw pen + a 20-minute mascot lobby	≈ 1 cent	A small slice of one day

Before you build one

Mascots are the only feature that burns the free plan fast: every phone sends all the time. Ship them at 5 updates a second, smoothed on screen.
Anything that changes the game (a mascot bumping someone, a buzzer, a win) goes through Convex, never the relay.
Open the channel only while the feature is on screen.

Assumptions

The tables are upper bounds. They count a room as awake for the whole hour, and idle rooms hibernate and are not billed.
Cloudflare's lifecycle page says a quiet room stays in memory about 10 s after its last message, then hibernates. But its pricing page says a room that can hibernate is not billed while idle, even before it hibernates. Its own hibernation example bills only the ~10 ms spent handling each message.
The relay can hibernate (it uses the hibernation socket API, an alarm, and no timers). So sparse features like reactions really cost far less than the table. A steady stream like the pen sits closer to it.
Each connect costs one Convex call for the pass. Quick Draw connects once per phone per drawing turn. Too small to change any number here.
Prices and limits as published in September 2026. Check the links before a big decision.

Why "open only when needed"

Awake seconds and requests are the bill. A quiet open socket costs nothing, but every message wakes the room. Closing the socket outside the moment that needs it keeps a room at zero.

Where the code lives

Piece	Where	What it does
Relay front door	`live/src/index.ts`	Carries out what the gate decides
Relay gate	`live/src/gate.ts`	Join or kick: checks the pass, refuses plainly when the relay has no secret. Tested in plain Node
Relay room	`live/src/room.ts`	Holds a room's sockets, sleeps, closes when quiet, closes a kicked or flooding socket, refuses a kicked player's old passes, keeps only recent kicks once empty
Relay rules	`live/src/relay.ts`	Limits, flood, sockets per player, which sockets a kick closes, which passes a kick refuses, stamping `from`. Tested in plain Node
The pass	`live/src/ticket.ts`	Sign and check join and kick passes. Bundled by Convex AND the relay, so a change ships only when both deploy
Pass issuer and kick	`convex/live.ts`	Finds the player and signs the join pass. Runs the scheduled kick
Kick on removal	`convex/lib/liveKick.ts`, `convex/lib/members.ts`	Every player removal schedules one kick. Skipped when the backend has no relay settings
Phone connection	`apps/app/src/live/connection.ts`	One socket per room: hold, linger, retry, pause
The lobby's places	`apps/app/src/modes/online/roomWire.ts`, `useRoomPlaces.ts`	The four messages and whose turn it is to answer (tested), and the hook that puts the wire round one phone's memory of the room
Reactions kit	apps/app/src/ui/reactions/	The feed rules (send limit, checks, cap), the hook, the floating overlay and the bar
Board hook	`apps/app/src/live/useLiveChannel.ts`	The one thing a board calls
Batcher	`apps/app/src/live/batcher.ts`	Turns a fast stream into a few messages a second
Relay address	`apps/app/src/live/config.ts`	`EXPO_PUBLIC_LIVE_URL`, or the local relay in dev
Online wiring	`apps/app/src/modes/online/useOnlineLive.ts`	Makes the connection, closes it in the background
The contract	`packages/engine` types	`BoardProps.live`, `LiveRoom`, `LiveMessage`

How it ships

Its own Cloudflare Worker, g4g-live, at live.gamesforgroup.com. Full steps in releasing (section 2b). In short: the same LIVE_SECRET on the Worker and on Convex production, LIVE_HTTP_URL=https://live.gamesforgroup.com on Convex production (for the kick), EXPO_PUBLIC_LIVE_URL=wss://live.gamesforgroup.com in release builds, Convex deployed first, then:

bun run deploy:live

A change to live/src/ticket.ts needs both deploys. Convex bundles that file, so the backend and the relay must both ship it, or passes stop matching.
A relay deploy closes every open socket. Cloudflare restarts the room objects. Phones reconnect quietly with a fresh pass, and nobody sees an error.
The relay refuses to run without its secret. Deploying with no LIVE_SECRET set fails and names it, and a relay whose secret is too short answers "relay not configured".

Running it locally

bun run live:dev

Runs the relay at ws://localhost:8787. A dev build uses it when no address is set.
The secret goes in live/.dev.vars (never committed), with the same value on the dev backend.
No secret on the backend means no pass, which means no live line and no error. Check that first.
The kick is not sent in dev: the dev backend runs in the cloud and cannot reach localhost, so LIVE_HTTP_URL stays unset there. Its tests cover both sides.

The stale-bundle trap After pulling or writing new live-channel code, reload the simulator and the browser. An app still running the old bundle has no channel at all, and looks exactly like a relay that is not working.

Decision log

2026-10-13A move says which ride. A scene may have several rides, so a move carries its ride's number in the scene's own order where it used to carry a plain yes. The number is held between one and eight where a message is read, and a number the scene has no ride for is no ride: the person is simply there, on every phone. The relay reads none of it. Why: decisions, 2026-10-13.
2026-10-12A change of scene starts the lobby's talk again. Which scene a room is in lives on the room, not here. When it changes, each phone asks about the new scene on the socket it has and ignores the old one; nobody comes in, everyone is simply there. And a toy's count is believed only a step past what a phone holds, so a made-up one cannot leave the lamp dead. Why: decisions, 2026-10-12.
2026-10-12The lobby's places ride the channel. Who is where in the online lobby is four messages between phones (a move, a short-lived deed, a hello, a snapshot), with one phone answering a hello, a snapshot when the room has been quiet 150 seconds, and no backend call for a move. The lobby is the first screen to hold the socket for as long as it is looked at. With that, a connection counts as good (and its retry waits start over) only after its socket has stayed open ten seconds. Why: decisions, 2026-10-12.
2026-10-04Reactions can belong to one match. A tournament's watchers cheer the match in front of them: the reactions hook takes a topic, one per match, on the room's one socket, and the overlay can spread across a whole board. The other games keep the room-wide topic. Why: decisions, 2026-10-04 (watching).
2026-10-01Undercover's unmasking keeps the row out. It sat behind the unmasked mascot on a phone that had room for it; it is now the same strip over the button on every screen. Its discussion chat (the chat topic) is drawn as a tray at the foot of the table and no longer carries "who voted" lines. Why: decisions, 2026-10-01.
2026-10-01The row is out when the screen has room. Charades' acting screen shows it all the time on a phone too; the mascot door stays only where the row would cramp the screen (Quick Draw's phone). Why: decisions, 2026-10-01.
2026-09-30The emojis are Google's Noto 3D pictures, and a corner can be where they rise. Our drawn set is replaced by bundled Noto 3D pictures; the overlay takes a corner to rise from, and Quick Draw's phone uses the mascot's. Why: decisions, 2026-09-30.
2026-09-30The emojis are drawn by the app, and a screen can bring its own trigger. The eight are pictures in the mascot's style; Quick Draw's phone opens the row from the drawer's mascot through the bar's own open-and-fold-away rule. Why: decisions, 2026-09-30.
2026-09-15The pause shows it is coming back. A recharge bar on the row and a ring on the corner button fill over the spam pause; the row fits its buttons to its width and always opens above the button.
2026-09-15Eight reactions. Thumbs down and a red heart join the set, and a phone's row tightens to fit all eight on one line.
2026-09-15A reactions kit rides the channel. Any screen can let players send emojis that float up every screen in the room, on the topic react, held only while the screen says so. Same device has none.
2026-09-15A kick outlives the passes it cancels. Each pass carries when it was signed, and the relay room refuses a kicked player's passes signed at or before the kick for their 2-minute life. The live pen sends a "still drawing" message about once a second while the pen is held still, so a guesser keeps the whole line.
2026-09-15A removed player is cut off at once. Every player removal makes Convex send the relay a signed kick, which closes that player's sockets (4003). The relay also closes a flooding socket (1008), holds at most 2 sockets per player (4001), and wipes a room's storage when its last socket goes (why).
2026-09-15Online rooms have a live channel. A small Cloudflare relay at live.gamesforgroup.com passes short-lived room messages beside Convex, first for Quick Draw's growing line. Convex signs a 2-minute pass, checked at connect. The channel is open only while a feature needs it, and the relay stores nothing (why, and what was rejected).

Last updated: 2026-10-13 · Maintained under the CLAUDE.md rule "Architecture docs, keep them in sync". If the code changed and this page did not, that is a bug. Fix the page.