Documentation

Boardweaver authoring reference. Sections are ordered for first-pass reading.

Building a game

The current framework: game rules in /src/game.ts, the board as a React client you write.

React frontends

Framework v2 overview: the two files a v2 game ships, the no-props default-export component contract, and the runtime surface that is deliberately unavailable (fetch/window/localStorage). Read first.

The match API

boardweaver/react reference: useMatch (state, click, pending, failures, online), the click lifecycle and onResult, and the derived hooks (useGameState, useSelf, usePlayers, useScores, useButtons, useAvailableActions, useImage, useSounds, useAudioSettings, useGameTheme, useViewport, useColorMode).

Accessible UI primitives

boardweaver/ui: the bundled Radix primitives (Dialog, AlertDialog, Tooltip, HoverCard, Popover, ContextMenu, DropdownMenu, VisuallyHidden and 25 more), how they map onto upstream Radix docs, and why to use them instead of hand-rolling menus, dialogs and tooltips.

Animation

boardweaver/motion: the bundled Motion (framer-motion) surface — layoutId for a piece moving between spaces, AnimatePresence for pieces entering and leaving after an array splice, animating opponent moves via useLastChange, and the reduced-motion floor.

Client state and undo

Everything the platform deliberately does NOT own: selection, hover, tentative arrangements, and undo/redo — built with React state plus boardweaver/immer. Covers the arrange-then-commit undo pattern, guarding stored ids, and the memoization contract.

The game source file

/src/game.ts: the required exports, the gameConfig object (spaces/pieces/pieceDefs/scoreLabels), where source files live, and the split between the rules and the client. Read alongside react-frontend.

Game logic hooks

Signatures and contracts for gameConfig, applyActions, getAvailableActions (and its intent taxonomy), getPlayerScores, isGameOver, getButtons, preGameInitialization — plus the Action union, the legacy getSelectableItems, and why these must stay pure (the client replays them locally).

Pieces, spaces, and state buckets

PieceDef and SpaceDef subclasses: kind, dimensions, the orientations field v2 still requires, kind registries, and the static / publicState / privateState buckets that decide who can see what.

GameState API

Reading and mutating game state: the selector rules (plural string = kind, singular = id), addPiece/addSpace, property setters, player- and space-scoped lookups, and activePlayerIds for turn order.

Images, fonts, and assets

Uploaded art (JPEG/PNG only, 5 MB, key rules, replace vs auto-uniquify, no delete), useImage, bulk upload via API token, vector art with inline SVG, Google Fonts as the one custom-font path, the frame CSP, and what does and does not count against the bundle cap.

Sounds

Uploaded music and sound effects (MP3/WAV/OGG/M4A, 10 MB, Designer or Professional plan to upload), the GameSound enum, useSounds().play with a music or effect type, what players' music and effect settings do, autoplay, and why synthesized Web Audio ignores those settings.

Build a React game (workflow)

End-to-end workflow for building a v2 game: what to write first, how to keep /src/game.ts authoritative, validating .tsx, and committing. The v2 counterpart to build-game-instructions.

Upgrade a game

Upgrade procedure for a framework v1 game: what is new (a React client draws the board, getAvailableActions lists actions), writing /src/frontend.tsx, replacing render() and getSelectableItems, and committing. Follow after upgrade_framework moves a game here.

BWSS page styling

The style object for the compiled page surfaces (rules and marketing): the BwssStyle allow-list, color and length grammar, and $theme-token refs. Does NOT apply to /src/frontend.tsx, which is ordinary React.

Build rules instructions

How to author styled rules pages (/src/rules/*.bwss): develop the theme first, align with the author on the page outline, the rules-surface BWSS nodes (incl. Anchor links), and committing to compile.

Build marketing page instructions

How to author a styled marketing/landing page (/src/marketing/*.bwss): develop the theme first, agree the page outline, the marketing-surface BWSS nodes (incl. the special PlayButton and RulesButton), and committing to compile.

Design theme instructions

How to collaborate with the author on a visual theme — recovering mood/voice from the game, three style-tile directions, the HTML/CSS rules, iteration, and saving the chosen theme to /src/theme.html.

Game themes

The /theme.json structured theme artifact: top-level shape, colors and semanticTokens reference grammar, optional background layers, and the validation rules that gate save.

Running events

For organizers: putting a game in front of a room, a class, or a blind playtest.

Events and tables

Run a game for a room, a class, or a blind playtest: an event of tables people join by code or QR, guests, start rules, presenting and printing codes, watching, pausing, and resetting.

Guest play

Let people join, and host, your game's matches without an account: the two switches, the plans that include them, and what a guest can do.

Playtest feedback

The form players answer after a playtest match: the default questions, the six answer types, how players step through it, and where the answers show up.

Framework v3 (admin-only preview)

An admin-only preview: game rules in Rust and a React client. Not yet open to other plans.

How a game works

Overview of Boardweaver and a game: what Boardweaver is and its platform words (game, commit, beta channel, studio, lobby, match), Rust game logic plus a React client, the words every section uses (seat, view, offer, intent, step, decision, draft, reveal), where to read the tic-tac-toe seed, and a map of the sections. Read first.

Build a game

Build procedure for a game, start to finish: create it, model the state, write the offers, moves and their unit tests, play a session, write the client, validate, commit and play it. Follow when starting or extending a game.

Upgrade a game

Upgrade procedure for a framework v1 or v2 game: what is new (Rust game logic, offers, pieces without ids, a new client API), replacing the game's own undo, move history, animations, bots and end screen with Boardweaver's, mapping the old state, porting the rules with tests, rewriting the client, deleting the TypeScript game logic and committing. Follow after upgrade_framework moves a game here.

The state

State of a match: players, spaces, pieces, how a piece is named by space and index, reading the state, your own serde types in maps with StateOf, the JSON the client sees, and the 1 MiB limit. Open when modelling a game or reading state in the game logic.

Data files

Data files: JSON in /src/data/ that the game logic reads with data! (as text or as a serde type) and the client imports, their paths and limits, what to keep out of the state, and their errors. Open when the game logic and the client need the same table, card list or text.

Hidden information

Hidden information: who sees each private part, collections that hide order, clicks on hidden pieces, marking reveals, game logic that also runs on a seat's view, and public log lines. Open for any game with hands, decks or secret choices.

The game functions

Game functions of a game, the six of the Game trait (setup, offers, apply_action, scores, score_labels, is_game_over): what each must do, refusing a move with Err, how scores rank seats, and export_game!. Open when writing or debugging the game logic.

Changing the state

State changes: every Table method by purpose (Table is the only way the game logic changes state), piece indexes after a change, turns, movements, log lines (any number per step, each with its player, kind, text and links) and allow_undo. Open when writing setup or apply_action.

Offers, intents and decisions

Offers and intents, the most important rule: actions, offers and labels, command inputs, tagging choice, confirm and cancel with the worked draft example and the common mistake, what ends a decision, and undo. Open whenever writing the offers function.

Randomness and determinism

Randomness: Rng's draws, why a draw ends the decision and cannot be undone, and keeping every result a function of state, action and seed (BTreeMap, not HashMap). Open when a game shuffles, rolls or draws.

Bots

Bots: the Bot trait, its profile limits, choose and BotTurn, looking ahead with simulate, listing bots in export_game!, what the platform does when a bot fails, and testing a bot with play_bots. Open when a game ships a computer opponent.

Testing a game

Testing a game: what validate_code checks (the game logic build, its unit tests, the client build and its strict type check, the pages) and what it cannot, how to write a unit test, the type errors to expect, playing a session with start_game, apply_action, inspect_state and set_state, and what to check in a match on the beta channel. Open before a commit, when writing tests, when validate_code answers a Type error or a failed test, or when a match goes wrong.

Builds, limits and errors

Build errors and limits: source paths, data files and modules, the three allowed crates, words the build refuses, reading a diagnostic, every tool error code, the limits of a unit test run, and the memory, fuel, time and state limits in a match. Open when validate_code, commit, a unit test or a match fails.

The React client

Client of a game: /src/frontend.tsx and what it may import, drawing the board from offers, taking one step or several from one event, commands and inputs, undo, pending steps, failures, log lines and movements, links in the game log with useLogLinks, the log drawn in the game with useHistory and History, other players' steps shown one at a time with their controls and pace, scores, a layout chosen from the client's size, music and sound effects with useSounds, GameOver and spectators. Open when writing or changing the board or adding sound.

Client libraries

boardweaver/motion (Motion), boardweaver/ui (Radix primitives such as Dialog, Tooltip and DropdownMenu), boardweaver/dnd (dnd-kit) and zod in a client: their versions, every name each exports, animating a move from useLastChange, and sending a drop with act. Open when animating, building a dialog or menu, or adding drag and drop.

Client types

Client types: Rust types the client also reads, defined in client_types!, what a field may hold and #[client(any)], importing each one's zod schema and TypeScript type from boardweaver/game, parsing a map with it, the JSON each Rust type becomes, the type check against them, and the errors. Open when the client reads a game's own map or type.

boardweaver/react reference

Reference of boardweaver/react: every hook with its exact return type, the lineText helper, every exported type, and every failure and refusal code. Open when you need an exact signature or code.

Write the rules pages

Rules pages procedure for a game: the page files, the nodes and styles a page may use, images, and checking with validate_code. Follow when writing or editing how-to-play pages.

Write the marketing page

Marketing page procedure for a game: the page file, its nodes, images, and checking with validate_code. Follow when writing the game's public page.

Design the theme

Theme procedure for a game: /theme.json and its fields, light and dark modes, and how the pages and the client read it. Follow when styling a game.

Framework v1

Deprecated

Deprecated. New games are created on the current framework, but v1 games keep running and their authors can keep editing them.

Core concepts

The render → select → action → applyActions → score loop in ~15 lines. Read first.

Source files

Required exports (gameConfig + hooks), GameStateConfigObject fields, the boardweaver import surface.

Pieces

PieceDef subclass: kind/width/height, orientations vs render(), state buckets, mouse handlers.

Spaces

SpaceDef subclass: kind/type/x/y/width/height, playerId, isPrivate, scrollable, nested pieces, render().

Actions

Action union dispatched into applyActions: SpaceClick, PieceClick, ButtonClick. Multi-step flows via metaData.

Game logic hooks

Signatures and contracts for applyActions, getSelectableItems, getPlayerScores, isGameOver, getButtons, preGameInitialization.

GameState API

GameState/Player/Piece/Space query and mutate methods, currentPlayer, activePlayerIds, addPiece/addSpace.

publicState, privateState, static, metaData

Where each data bucket lives, mutability, and viewer scrubbing for privateState.

Images

GameImageKey (string), upload flow, binding to orientations[].imageSrc, null = blank tile.

Layout and overlays

getLayout (RadialLayout | GridLayout) and renderOverlay (Overlay handle resolver, OverlayBwssNode[]).

BWSS styling

BWSS node types (Box/Image/Svg/Text/Pieces), style allow-list, color/length validators, $theme-token refs.

API reference

No-prose cheatsheet of every hook signature and every GameState/Player/Piece/Space method.

Build game instructions