Documentation

React frontends

Framework v2 overview: the two files a v2 game ships, how writing /src/frontend.tsx upgrades a game to v2, 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, 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) and the GameSound enum each sound becomes.

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.

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.

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)

Framework v3 overview, an admin-only preview: game logic in Rust compiled to WebAssembly and run by the game runner, the Game trait, hidden information, captions, and intents (the most important rule, with the worked example and the common mistake). Read first.

Build a v3 game (admin-only preview)

Workflow for a v3 game while v3 is an admin-only preview: until Boardweaver builds Rust, a v3 game is the tic-tac-toe seed and cannot be committed. Read tic-tac-toe-rust, write and test a game with walk_intents, and play the seed.

Rules, marketing pages and themes on v3

Rules pages, the marketing page and the theme work on v3 as on v2: which v2 sections to follow, and why a v3 game cannot commit them yet.

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

How to implement a Boardweaver game from a design: structure, hooks, state buckets, and the incremental build workflow.

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.