Game Lobbies

A game lobby is a smart product in the GAME domain, of product type game-lobby. One lobby is one table: one contract that hosts a series of matches, each played by two seats for a pot. Tic-Tac-Boom and Drop Four are both built on it; the protocol does not know which game an app is, only which board the lobby was deployed with.

The model

A lobby is created from the smart-lobby recipe (rtClient.games.createDraft). Opening one requires the CREATE_GAMES entitlement, which only Admin holds today, so the tables that exist are opened by the Rising Tide team. Lobbies are scoped by sourceAppId: an app lists its own tables.

The protocol names each domain's thing in the user's words at the app layer. A caller builds against the left-hand column; an app's copy uses the right.

What a lobby guarantees

These hold on chain, whatever client calls the contract.

• The terms freeze at the first seat. While anyone holds a seat, the lobby's price and product info cannot be changed, and its contribution split was fixed at deploy. A player who sits down pays what they were shown.
• Every buy-in splits the moment it lands. poolPct of it stays in the contract as the kitty; the rest settles to the lobby's frozen contributions, the way a mint does. Their percentages sum to 100 - poolPct. A seated creator of the lobby does not pay their own share to themselves.
• A seat is refundable until the match starts. leave returns the seat's recorded pool share to the player who left; the contribution legs stay paid. When the first seat leaves, the second moves up. Once the match starts, neither seat can leave.
• Only the winner can claim the kitty, and the claim is the trophy. A won match pays the kitty to the winner and mints the match to them as a numbered edition. A draw pays each seat half and mints nothing.
• A spectator item comes only from a spectator. The bomb is refused on chain for either seated player, so only a signed-in viewer who holds no seat can use it. gameLobbyDetails.itemAudience says who an item is for; the contract enforces it. An item's payment splits like a buy-in, so its pool share grows the kitty; an item priced at 0 moves nothing and leaves the kitty as it was.
• A stalled match can be closed, but not by a player. If no move lands for 144 Bitcoin blocks, the lobby's creator can close the match as a draw - unless they hold a seat in it.

The match picture

Each game's lobbies draw their result through a style set owned by the app, drawn to its own scene. The picture is rendered when the match is decided, before anyone claims, so a draw has one too. To draw one from a sample match instead, see rtClient.gameStyles.generateLivePreview on rtClient.games. Read a real match's picture the way any instance image is read: rtClient.productImages.list("product_instance", [instanceId]), with the instanceId from a match row. The style set's artist is a contributor on the lobby, paid from every buy-in.

See also

• rtClient.games - reading lobbies and matches, opening a table, and the game-action command
• Games API - the routes
• Capabilities - the bomb, and what an item is
• How a Lobby Works - the same rules, as a player reads them