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, local files through signed uploads, 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 (preview)

An opt-in preview for everyone: game logic in Rust and a React client. New games still default to v2.

How a game works

Overview of Boardweaver and a game: opting into this framework, 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 Hexbloom starter and its individual files, 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, structure the client, check transitions and layout, 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 five of the Game trait (setup, offers, apply_action, scores, is_game_over): what each must do, refusing a move with Err and a message from the game's catalogs, 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 a message from the game's catalogs with msg!, its values such as players, numbers and links, its player and kind) and allow_undo. Open when writing setup or apply_action.

Offers, intents and decisions

Offers and intents, the most important rule: actions, offers and their labels as messages from the game's catalogs, 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, playing against bots in the studio preview, testing a bot with play_bots and the fuel it shares among the bots, and testing one position with BotTurn::new and bot_choice. 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, driving a Match in a test (new, load, apply, the Evaluation's offers, each Refusal, seeds), the type errors to expect, durable client tests, a viewer and transition test matrix, browser checks, playing a session with start_game, apply_action, inspect_state and set_state, saving and restoring Studio checkpoints with save_checkpoint, 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: studio code editing and build feedback, 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, live versus replayed scores, client structure, directional animation endpoints, optional measured overlays, custom timing and cancellation, stable container layout, text in the player's language from /src/i18n catalogs with react-intl, music and sound effects with useSounds, GameOver and spectators. Open when writing or changing the board, adding sound, or writing the text a player reads.

Client libraries

boardweaver/motion (Motion), boardweaver/ui (Radix primitives such as Dialog, Tooltip and DropdownMenu), boardweaver/dnd (dnd-kit), zod and react-intl in a client: their versions, every name each exports, custom animations with useBoardTransition and useTransitionEffect, sending a drop with act, and formatting the game's messages from its catalogs. Open when animating, building a dialog or menu, adding drag and drop, or showing translated text.

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.

Translations

Translations of a game: where each kind of text is written and translated, catalogs in /src/i18n and their limits, messages from the game logic with msg! and the reserved {player}, react-intl in the client and why defaultMessage is not used, which locale a player sees and the fallback to the default locale, the en-XA pseudo-locale, translated names, descriptions and pages, the studio's Translations page and the catalog files it writes, checking a locale with start_game and render_game, and every check and code. Open when writing a catalog or a translation, or when a check names one.

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.

Translate a game

Translation procedure for a game: moving every word into the default catalog, writing a locale's catalog, translating the name, description and pages, rendering in the locale and in en-XA, fixing overflow and missing glyphs, and committing. Follow when adding a language to 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