Skip to content

Drawing package

pi-roundtable-drawing adds tools that draw PNGs on the host with node-canvas and attach them to the agent’s reply. It makes relationship maps, magic circles, sigils, and sacred geometry, plus card spreads when you provide a deck. It does not call an image service or need an API key.

Terminal window
bun add pi-roundtable-drawing

Use Bun 1.4.4 or newer and the pi-roundtable peer range >=0.50.0 <0.51.0. canvas is a native dependency; supported platforms use a prebuilt binary, while other platforms need the Cairo, Pango, JPEG, GIF, and SVG development libraries and a compiler. See the package README for platform commands.

import { drawing } from "pi-roundtable-drawing";
export default {
// ...your roundtable settings...
plugins: [drawing({ deckDir: "./decks" })],
};
Option Default Purpose
deckDir none Directory containing one subdirectory per deck. Without it, no draw_cards tool is registered.
random Math.random Random source for map layout and card draws. seededRandom(seed) is exported for repeatable results.
minTier member Lowest speaker tier allowed to use the tools; host toolTiers can override it.
cardPresentation package captions Trusted heading(draw, turn) returns {title, subtitle} using deck/count/question and host speaker/channel; reversedSuffix localizes the default " (reversed)" on the picture.
mapLimits 80 and 60 { title?, text? }: longest relationship-map title and node/edge label in characters; each is a whole number of at least 1.
permissive false Accept invalid requests that a looser host already sends: exclude a card not in the deck, share spread positions, repeat or leave empty map nodes, or use unparseable colors; by default each is refused with a correctable message.

The package reads nothing from the environment and needs no database. For card draws, provide your own deck.json manifests and card art; the package includes no card faces. A missing or invalid deck stops startup. The manifest accepts only its documented fields, and image paths must stay inside the deck directory.

The tools are relationship_map, magic_circle_generate, sigil_generate, sacred_geometry_generate, and optionally draw_cards. Each call attaches one image. A reply can carry at most 10 files, each at most 10 MiB, and 50 MiB total; a stricter surface limit may also apply. A refused call attaches nothing. The host delivers each image after the agent’s text, using the same speaker identity. See reply attachments for the core contract.

For the full tool arguments, limits, deck manifest, native dependency instructions, and testing example, see the pi-roundtable-drawing README.