Have more questions? Join our

This documents framework v1, which is deprecated. Games already on it keep running and their authors can keep editing them, but new games are created on the current framework — start with React frontends.

Images

GameImageKey is string. Image keys are dynamic — generated per game from uploaded media, not an enum baked into the framework.

class XToken extends PieceDef {
  readonly kind = "x-token";
  readonly width = 110;
  readonly height = 110;
  readonly orientations = [
    { imageSrc: "XPiece" },                            // GameImageKey string
    { imageSrc: null },                                // blank tile
  ];
}

Where images bind

PieceDef.orientations[i].imageSrc: GameImageKey | null — primary use. The current orientation's imageSrc is rendered as the piece.
BWSS Image node src: GameImageKey — used inside render() returns. See styling.

Upload flow

Image keys are created when an author uploads media to the game (via the Boardweaver editor's Images panel). Each upload produces a stable string key (e.g. "XPiece", "CardBack"). The author then references that key by string in imageSrc / Image.src.

Authors writing code in this package do not invent image keys — they reference ones the game already has.

`null` vs missing

`imageSrc` value	Rendered as
`null`	Blank tile (transparent at the piece's `width`×`height`).
`"ValidKey"`	The uploaded image.
`"UnknownKey"`	Nothing (renders empty). Never as a URL the author chose — the renderer resolves through the game's images map.

Don't rely on the missing-key fallback to communicate UI state — use null explicitly so intent is clear.

In render mode

A render() function that uses an image uses the Image BWSS node:

readonly render: PieceRenderFn = (piece) => ({
  type: "Image",
  src: "XPiece",
  style: { width: piece.width, height: piece.height },
});

Same key resolution — unknown keys render nothing.

Gotchas

GameImageKey is string at the type level — the compiler can't tell you a key is wrong. Typos resolve to "renders nothing."
Per-orientation width / height (on a PieceOrientation) override the PieceDef class default for that orientation. Use this when the same piece has multiple sizes per face.
A piece can mix image and shape mode across orientations: [{ imageSrc: null }, { imageSrc: "FlippedCard" }] is valid.
For dynamic visuals that depend on state (a counter, an animated highlight), use render mode — image keys are static lookups.