Spectators
A spectator joins a table to watch it, with no seat and no actions. Spectators get live updates like players do, but only what the game shows to everyone who holds no seat.
Join as a spectator
Section titled “Join as a spectator”Ask for the spectator role when you join:
const table = await client.join(tableId, { as: 'spectator' });
console.log(table.you.role); // 'spectator'console.log(table.doc?.spectators); // how many people are watchingIn React, pass the same option to useTable:
import { useTable } from 'shoehive/react';
export function Watch({ tableId }: { tableId: string }) { const { status, view, meta, you } = useTable(tableId, { as: 'spectator' }); if (status !== 'ready') return <p>Joining...</p>; return ( <p> {you?.role} sees a {meta?.status} table: {JSON.stringify(view)} </p> );}A spectator can watch any number of tables, and can sit down later with table.sit() (or
sit() from useTable). Once seated, you.role becomes 'player' and the view becomes the
seat's view. Calling act without a seat fails with NOT_SEATED.
What spectators see
Section titled “What spectators see”Everyone without a seat at a table gets one shared view: the game's view() function runs once
for the spectator viewer, and every spectator receives that result. The viewer has
kind: 'spectator', no seat (seat: null, seats: []) and no player id.
This is the same rule that hides a hand from the other seats. A game that already uses
seatView for hidden information needs no extra code, because a spectator holds no seat, so
every hidden value stays hidden:
import { defineGame } from 'shoehive';
export const game = defineGame({ id: 'watch-demo', seats: { min: 2, max: 2 }, setup: () => ({ hands: [ ['A', 'K'], ['Q', 'J'], ], moves: 0, }), turns: { order: 'round-robin' }, view: ({ state, viewer }) => ({ moves: state.moves, // Seats see their own hand. Spectators see only how many cards each holds. hands: state.hands.map((hand, seat) => (viewer.seats.includes(seat) ? hand : hand.length)), // To change what spectators see, branch on the viewer: watching: viewer.kind === 'spectator', }),});Two limits to know about:
- The view is shared. Shoehive v1 has no per-spectator view, for example "a coach who sees one seat's hand". If you need it, that is a protocol extension, not a setting.
- An unseated player who joined as a
playeralso gets the spectator view. Theasoption only labels the role inyou.roleand in the spectator count. Hidden information is decided by whether the viewer holds a seat.
Ephemeral events can target spectators too: ctx.emit('reveal', payload, { to: 'spectators' })
reaches only the people without a seat, and to: 'all' reaches everyone.
Spectator counts
Section titled “Spectator counts”Each table document has a spectators number: the count of distinct players with a connection
joined to the table and no seat. Seated players and the same person's extra tabs do not count.
The lobby lists the same number for each table, so you can show "12 watching".
const lobby = await client.lobby({ filter: { status: ['active'] } });
for (const t of lobby.doc?.tables ?? []) { console.log(`${t.id}: ${t.seats.taken}/${t.seats.total} seated, ${t.spectators} watching`);}Find tables to watch
Section titled “Find tables to watch”A lobby subscription takes an optional filter by game and by table status. Use it to list only tables that are running:
import { useLobby } from 'shoehive/react';
export function LiveTables() { const lobby = useLobby({ filter: { games: ['holdem'], status: ['active'] } }); return ( <ul> {lobby?.tables.map((t) => ( <li key={t.id}> {t.id} ({t.spectators} watching) </li> ))} </ul> );}There is one lobby subscription per client. The last filter you pass wins, for every component that uses it. Every game is always listed, and the filter narrows only the tables. See Wire protocol section 6.3 for the lobby document.
