Tabletop

Server only. A table for a board or card game: a board of rows and columns at a place in the world, pieces that stand on its cells and move between them, seats with a turn order, bets and save/load. You write the game's rules; the table does the rest. Every player of the table's dimension sees the pieces (they are props), and a player who joins later sees the board as it is. Near a free seat a player gets a 'Sit down' hint (U); seated, they point at a cell with the crosshair, or, with a camera shot of the table's or their seat's own, with the mouse pointer over the board as the game's dice players do, and click with mouse 1 or Enter; the arrow keys move the pointed cell as the player sees the board. The game's combat actions are held off while seated. The table's controls: { pointer: 'cursor' | 'crosshair' | 'keys', block: [game action names] } choose otherwise. Their game only sends the request: picking a piece raises tabletopPieceSelect and a move tabletopMoveRequest, which your handlers may refuse, and only then does the server move the piece. A player who stands up or leaves during a game forfeits it. Rows run along the table's y axis and columns along its x axis, both from 0. A resource's tables go when it stops.

tabletop.create()

Tabletop.create(options = {})

Makes a table. `position` is the middle of the board's top, where pieces stand; `rotation` turns it about the vertical axis (degrees, or a Quaternion); `dimension` defaults to the shared one. `board`: `rows` and `columns` (1 to 32, default 8), `cellSize` in metres (default 0.06), `height` (where pieces stand above `position`, default 0), `stackHeight` (how much higher each piece of a stack stands, default 0.01) and an optional `model` (a prop drawn as the board, with `scale`). `seats`: up to 8, each `{ position, rotation, side, animation, camera, chair }`, where `animation` is `{ fragment, tags }` played while the player sits, `camera` a shot of the seat's own, and `chair: true` means the game's own seat stands there (a chair or bench from SmartObject.spawn, or the level's): the player sits on it with the game's E and its walk up and sit-down, the table seats them when their game reports them seated within 0.9 m of `position`, and getting up from it stands them up; such a seat takes no `animation` and shows no Sit hint; while seated there W, A, S and D move the pointed cell instead of getting the player up, until Stand up (U) gives them back. `turnSeconds` (0, the default, for no limit) and `camera`, a shot as Camera.startShot takes it, shown to a seated player. A shot with `look` turns with the mouse within its limits: the crosshair then points and the game's own mouse look is held off.

tabletop.all()

Tabletop.all(dimension)

Every table, or those of one dimension.

tabletop.getById()

Tabletop.getById(id)

The table with this id, or null.

tabletop.id

id

The table's id, unique while the server runs.

tabletop.exists

exists

Whether the table is still there (destroy, or its resource stopped, removes it).

tabletop.position

position

Where the middle of the board's top is.

tabletop.rotation

rotation

How the table is turned.

tabletop.dimension

dimension

The dimension the table is in; only its players see and use it.

tabletop.rows

rows

How many rows the board has.

tabletop.columns

columns

How many columns the board has.

tabletop.cellSize

cellSize

A cell's size in metres.

tabletop.pieces

pieces

The pieces on the board, in the order they were added.

tabletop.seats

seats

The seats, as { index, side, player }, with player null for a free one.

tabletop.state

state

'playing' while a game is on (start to finish), else 'idle'.

tabletop.turn

turn

The seat whose turn it is, -1 when no game is on. While a game is on, only that seat's player can pick and move pieces.

tabletop.pot

pot

How much bets put on the table, in units of their item.

tabletop.cellPosition()

cellPosition(cell)

Where a cell's middle is in the world. Throws a RangeError for a cell off the board.

tabletop.cellAt()

cellAt(position)

The cell under a position, or null when it is off the board.

tabletop.addPiece()

addPiece(options = {})

Puts a piece on a cell, on top of any already there. `model` is a prop model (the game's or one your resource ships, see Props); `side` and `data` are yours (whose piece, a king's crown, a card's value); `rotation` turns it on the board (degrees); `scale` sizes it; `visibleTo` shows it to one player or a list only (a hand of cards). At most 256 pieces on a table.

tabletop.piecesAt()

piecesAt(cell)

The pieces on a cell, bottom first.

tabletop.pieceAt()

pieceAt(cell)

The top piece of a cell, or null for an empty one.

tabletop.highlight()

highlight(cells, options = {})

Marks cells, for some players (`players`) or everyone, in a colour (`color`, 0xAARRGGBB, a soft gold by default) and a `style`: 'frame' (the default), a border with a faint inside; 'fill', the whole cell tinted; 'dot', a round dot in the middle, as for the cells a piece may go to. The players' games draw the marks flat on the board. A table keeps at most 64 `highlight` calls' marks; the table marks a player's picked piece by itself.

tabletop.clearHighlight()

clearHighlight(players)

Removes the marks for these players, or every mark.

tabletop.sit()

sit(player, seat)

Seats a player, as their own request from the 'Sit down' hint does: they move to the seat, its animation plays and the table's camera shot starts. False for a taken seat, a player who already sits at the table, one in another dimension, or a tabletopSit handler that refused.

tabletop.stand()

stand(player)

Stands a player up, as the 'Stand up' hint does. A player who stands during a game forfeits it. False for one who does not sit here.

tabletop.seatOf()

seatOf(player)

The seat a player sits on, -1 for none.

tabletop.playerAt()

playerAt(seat)

The player on a seat, or null.

tabletop.start()

start(options = {})

Starts a game: the turn goes to `turn` (default the first taken seat), with tabletopStart and tabletopTurn. Throws when nobody sits.

tabletop.nextTurn()

nextTurn()

Passes the turn to the next taken seat, with tabletopTurn, and starts its timer. Returns that seat. Throws when no game is on.

tabletop.finish()

finish(winner = null, reason = 'won')

Ends the game with tabletopEnd: the winner (a seat or a Player) takes the pot; with none (null) everyone gets back what they bet.

tabletop.bet()

bet(amount, options = {})

Takes `amount` of an item (`item`, default 'money') from every seated player for the pot: all or nothing, so if one cannot pay, all get theirs back and it answers false.

tabletop.clear()

clear()

Takes every piece off the board, for a new game.

tabletop.save()

save()

The board as data, JSON you can store: its pieces (model, cell, side, data, turn and who sees them) and the turn.

tabletop.load()

load(saved)

Puts the board back as save() gave it, in place of the pieces it has now.

tabletop.destroy()

destroy()

Removes the table: its players stand up (reason 'removed'), a game ends without a winner and its pieces and board go.