A Go package

Party-game rooms in one import

Short join codes, phones as controllers, a shared big screen, and reconnects that keep your seat. You write the game. lobby runs the room.

Get started Play the demo

How it works

Big screen, small screens, one room

01

Someone opens a room

The TV or laptop gets a four-letter code. Codes use only consonants, so they can't spell words.

02

Everyone joins from their phone

Type the code and a name, no account needed. Refresh, lock the screen, lose signal: you keep your seat.

03

Your game gets the events

Joins, leaves and moves arrive one at a time on the room's own goroutine. No locks, no races, no websocket plumbing.

The whole game

A buzzer in 35 lines

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");
}

Read the guide

What you get

The boring parts, done properly

Seats, not sockets

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.

One goroutine per room

Every callback for a room runs in order, so game state is plain Go fields. Timers (r.After) run on the same goroutine.

Players and a display

Phones are players, and the TV is a display. The first player is VIP and can kick or lock the room.

Bots and tests, in-process

LocalConn is a full player over Go channels: no network, no JSON. Computer opponents and table-driven game tests use the same API.

Survives restarts

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.

Hard to abuse

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.

Compared with

Where it fits

If you've used Socket.IO or PartyKit, here's the short version.

lobbySocket.IOPartyKit
Runs onYour Go serverYour Node serverCloudflare (hosted)
Join by short codeBuilt inBuild itBuild it
Reconnect to the same seatBuilt inShort gaps (state recovery)Build it
Serialized per-room stateGoroutine per roomBuild itDurable Object per room
Host display + VIPBuilt inBuild itBuild it
PersistenceSQLite or your DBBuild itDurable storage
Many machinesOne process per room set; route by codeRedis adapterBuilt in
Benchmarks

Fast enough to forget about

From make bench on a laptop. A broadcast is encoded to JSON once, however many people receive it.

~1 µs

One move fanned out to 8 in-process players

~25 µs

Websocket round trip: send, game logic, reply

~52 µs

One move fanned out to 8 websocket players

Built for agents, too

Ask your coding agent for a game

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.