Skip to main content

Meta (Room Info)

Beta

This feature is in beta. Core behavior is stable, but some APIs or configuration may change 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.

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

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

The underlying HTTP API is:

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

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.