Send player actions
API
| Hook | Contract |
|---|---|
useOffers() |
Offer[]: the seat's offers on that board. |
useAct() |
(action: Action | Action[]) => Outcome: takes one step on the board of this render, or a list of steps from one event. |
useDraft() |
DraftView: { steps: { action, intent, lines: FormattedLine[] }[]; reopenedSteps: number }. |
useUndo() |
{ available: "draft" | "server" | "none"; undo: () => Outcome }. |
Taking a step
act(action) takes one step and answers at once:
type |
Means |
|---|---|
applied |
A choice or cancel step joined the draft. The board already shows it. |
sent |
The step ended the decision, which is on its way to Boardweaver. |
failed |
The step was not taken. reason.code says why. |
act belongs to the board of the render that created it. Call it once per event. A second act call in the same handler, or one from a timer or after an await, fails as STALE.
To take several steps from one event, such as a form that collects several values, pass them as a list: act([first, second, third]). Each step applies to the board the step before it left, each joins the decision as its own step, and only the last may end it. When a step fails, the steps before it stay in the decision, the rest are not taken, and the failed outcome's applied says how many joined.
Commands, confirm and cancel
The client draws a control for each offer that is not a board click:
- A
Commandoffer: a button with the offer'slabel, written withuseMessageText(). - A
confirmoffer: the button that ends the decision, such as "Take". - A
canceloffer: a switch or take-back, such as clicking another staged card. - An offer with an
input: a field. ForText, offer thesuggestionsand accept up tomaxLencharacters. ForInteger, acceptmintomaxonstep. Send the value in the action:act({ ...offer.action, value }).
useDraft() lists the draft's steps, so the client can show what the seat chose so far.
Undo
const undo = useUndo();
<button onClick={() => undo.undo()} disabled={undo.available === "none"}>Undo</button>
available is draft (takes back the last draft step at once), server (asks Boardweaver to take back the last committed step) or none. The game logic decides what may be taken back (Changing the state).