01
Someone opens a room
The TV or laptop gets a four-letter code. Codes use only consonants, so they can't spell words.
A Go package
Short join codes, phones as controllers, a shared big screen, and reconnects that keep your seat. You write the game. lobby runs the room.
The TV or laptop gets a four-letter code. Codes use only consonants, so they can't spell words.
Type the code and a name, no account needed. Refresh, lock the screen, lose signal: you keep your seat.
Joins, leaves and moves arrive one at a time on the room's own goroutine. No locks, no races, no websocket plumbing.
The first player to buzz wins and the VIP resets. This is the complete server for examples/quickstart.
// buzzer is the whole game. Its methods run one at a time on the room's
// goroutine, so plain fields are safe without locks.
type buzzer struct {
lobby.BaseGame
winner string // name of the first player to buzz, "" while open
}
func (b *buzzer) OnConnect(ctx context.Context, r *lobby.Room, c lobby.Client) {
r.Send(c.ID, "buzz", b.winner) // catch up anyone who (re)connects
}
func (b *buzzer) OnMessage(ctx context.Context, r *lobby.Room, c lobby.Client, m lobby.Message) {
switch {
case m.Type == "buzz" && b.winner == "" && c.Role == lobby.RolePlayer:
b.winner = c.Name
case m.Type == "reset" && c.ID == r.VIP():
b.winner = ""
default:
return
}
r.Broadcast("buzz", b.winner)
}
//go:embed index.html
var page []byte
func main() {
m := lobby.New(lobby.Config{
NewGame: func(code, kind string) (lobby.Game, error) { return &buzzer{}, nil },
})
http.Handle("/api/", http.StripPrefix("/api", m.Handler()))
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { w.Write(page) })
log.Println("open http://localhost:8080")
log.Fatal(http.ListenAndServe(":8080", nil))
}
The browser side uses the client the library serves:
import { createRoom, joinRoom, connect } from "/api/client.js";
const $ = (id) => document.getElementById(id);
$("join").onsubmit = async (ev) => {
ev.preventDefault();
const { code, name } = Object.fromEntries(new FormData(ev.target));
try {
const res = code ? await joinRoom("/api", code, { name }) : await createRoom("/api", { name });
play(res.code, res.client.id);
} catch (err) {
ev.target.querySelector("[role=alert]").textContent = err.message;
}
};
function play(code, me) {
$("join").hidden = true;
$("game").hidden = false;
$("title").textContent = `Room ${code}`;
const room = connect("/api", code, {
onMessage({ type, data }) {
if (type === "lobby.state") $("reset").hidden = data.vip !== me;
if (type === "buzz") $("winner").textContent = data ? `${data} buzzed first!` : "Waiting for a buzz…";
},
});
$("buzz").onclick = () => room.send("buzz");
$("reset").onclick = () => room.send("reset");
}
Identity is a token held in an HttpOnly cookie. Reconnecting reclaims your seat, and a second tab takes over from the first. Seats wait two minutes for you to come back.
Every callback for a room runs in order, so game state is plain Go fields. Timers (r.After) run on the same goroutine.
Phones are players, and the TV is a display. The first player is VIP and can kick or lock the room.
LocalConn is a full player over Go channels: no network, no JSON. Computer opponents and table-driven game tests use the same API.
SQLite persistence is built in (pure Go, no cgo). Rooms, seats and game state come back after a deploy, and phones reconnect on their own.
Joins are rate limited per IP, and messages per connection. Slow clients get dropped instead of stalling the room, and a panicking game doesn't take the server down.
If you've used Socket.IO or PartyKit, here's the short version.
| lobby | Socket.IO | PartyKit | |
|---|---|---|---|
| Runs on | Your Go server | Your Node server | Cloudflare (hosted) |
| Join by short code | Built in | Build it | Build it |
| Reconnect to the same seat | Built in | Short gaps (state recovery) | Build it |
| Serialized per-room state | Goroutine per room | Build it | Durable Object per room |
| Host display + VIP | Built in | Build it | Build it |
| Persistence | SQLite or your DB | Build it | Durable storage |
| Many machines | One process per room set; route by code | Redis adapter | Built in |
From make bench on a laptop. A broadcast is encoded to JSON once, however many people receive it.
One move fanned out to 8 in-process players
Websocket round trip: send, game logic, reply
One move fanned out to 8 websocket players
The repo ships an AGENTS.md covering the API, the rules that keep games correct, and the common mistakes. Point Claude, Codex or Cursor at it and ask for trivia with a 15-second timer.