Skip to main content

Meta (Room Info)

Beta

This feature is in beta. Core behavior is stable and ready to try, but some APIs or configuration may still evolve before general availability.

room.meta is the public-safe description of a room.

It is separate from authoritative room state so you can show room cards, matchmaking previews, or pre-join summaries without exposing internal game state.

What Belongs in Meta​

  • mode or ruleset
  • player count
  • public title or label
  • whether a match is open, full, or in progress

Do not put secrets, tokens, email addresses, or private user data in metadata.

Client Surface​

room.meta.get() can be used before or after join.

On the JavaScript/TypeScript web SDK, room.meta.summary() adds live occupancy counts on top of the metadata payload, client.getRoomSummary(namespace, roomId) provides the same HTTP helper without creating a room instance first, and client.getRoomSummaries(namespace, roomIds) batches multiple room cards into one request.

Assume room is an authenticated room client created with client.room(...).

const meta = await room.meta.get();
console.log(meta.mode, meta.playerCount);

const summary = await room.meta.summary();
console.log(summary.occupancy.activeMembers);

The underlying HTTP API is:

GET /api/room/metadata?namespace={ns}&id={roomId}

For lobby cards and room lists, the occupancy-aware companion endpoint is:

GET /api/room/summary?namespace={ns}&id={roomId}

For list UIs that need multiple room cards at once, use:

POST /api/room/summaries

Server Surface​

rooms: {
  game: {
    handlers: {
      lifecycle: {
        onCreate(room) {
          room.setMetadata({ mode: 'classic', playerCount: 0 });
        },
        onJoin(_sender, room) {
          const meta = room.getMetadata();
          room.setMetadata({ ...meta, playerCount: (meta.playerCount as number) + 1 });
        },
        onLeave(_sender, room) {
          const meta = room.getMetadata();
          room.setMetadata({ ...meta, playerCount: Math.max(0, (meta.playerCount as number) - 1) });
        },
      },
    },
  },
}

The server APIs are:

  • room.setMetadata(data)
  • room.getMetadata()

Access Control​

Metadata fetches are controlled separately from join:

  • access.metadata(auth, roomId)

That means a room can expose a public lobby card while still requiring auth or custom checks for the actual join.

See Access Rules.

Meta vs State​

  • Use State for authoritative gameplay or collaborative state.
  • Use meta for pre-join or publicly readable room summary data.
  • Use summary when you also need a live count of active members or connections without joining.