Skip to main content

How Cauldron decks run

A Cauldron deck is a web page, but it doesn't run like an ordinary website. Players open it inside a card in the feed, in the Castle app on iOS and Android and in castle.xyz's web player. The rules on this page apply to every deck, whatever kit it uses. Operator follows them for you, but knowing them explains why your deck behaves the way it does.

The card​

A deck plays inside a 5:7 portrait card, not the full window. The ratio never changes, but Castle scales the card to fit the screen, up to about 450×630 pixels. Anything outside the card's edges is clipped, and the card doesn't scroll.

Design the whole layout to fit inside that box. Size UI relative to the card (percentages, flexbox or grid, min() and clamp()) rather than with fixed tall panels, and let the playfield shrink on smaller screens. The SDK's setup() mounts the card, and CARD_RATIO is the exact ratio.

A deck that draws into its own <canvas> should size the canvas for the screen's devicePixelRatio, or it will look blurry on phones. The kits do this for you. Pixel art is the exception: a fixed low-resolution canvas with image-rendering: pixelated keeps it crisp.

Touch controls​

Most players are on a phone, so a deck has to work by touch. Prefer touching the game itself (tapping, dragging) over on-screen buttons, and add buttons only where the game really needs them. A game with no directional movement shouldn't have a d-pad. Keyboard controls are fine to add on top for desktop players.

Assets​

When you publish, Castle bundles the deck's code and assets into a single page. Images, sounds, video and 3D models of 64 KB or more are stored on Castle's servers and loaded from there; smaller files are built into the page. The page itself, its code plus every file built into it, can be at most 50 MB. Each file stored on Castle's servers can be at most 50 MB too, and one Castle won't store is built into the page instead. Separately, the deck's source files, compressed, can be at most 100 MB. That has a few consequences.

Load assets through the bundler, not with fetch. Import an image or sound, or use import.meta.glob. A fetch('drawings/hero.svg') of a loose file works while you edit, then fails silently once published.

Use the supported media formats. Published decks keep images (.png, .jpg, .jpeg, .gif, .webp, .svg), audio (.mp3, .wav, .m4a) and video (.mp4, H.264), plus any file types the deck or its kit declares for its own editors. Convert anything else, such as a .mov, before you add it.

Bundle media with the deck. A published deck can't load images, audio or video from other sites. Put them in the deck's files, or create them in code as data: or blob: URLs.

Expect almost no network access. A deck's fetch can reach only the deck itself, esm.sh, cdnjs.cloudflare.com and Castle's own image and audio servers. The SDK's multiplayer connection can reach Castle's multiplayer servers, and stylesheets and fonts can load from Google Fonts. Iframes are blocked. The Play panel applies the same limits as a published deck, and shows what it blocks in Logs as [csp] blocked lines: each blocked address once, and at most 20 per page load.

To show another deck's title, creator and cover, use Portal.info, since a deck can't call Castle's API or load remote images itself.

To add an npm package, add it to the deck's package.json dependencies and install it. Operator can do both.

Fonts​

The fonts from Castle's classic editor come with every Cauldron deck as web fonts. They're bundled into the deck, so they work offline and show on the first frame. Import the faces you want by name from castle-web-fonts:

import { installTektur } from "castle-web-fonts";

installTektur(); // now: font-family: 'Tektur'
FaceCharacterGood for
DMSansclean geometric sansbody text, UI, HUD
Piazzollasturdy text serifnarrative, prose-heavy decks
CourierPrimemonospace typewritercode, terminals, typewriter effects
Tekturcondensed squarish technosci-fi, arcade, HUD numerals
Borevery heavy wide grotesqueheadlines, scores, big titles
Syncolight wide geometricretro-modernist titles
Glacierslanted condensed italicinformal, energetic display
HelicoCentricablackletter-flavored romanmedieval, fantasy
YatraOnehigh-contrast brushy display, also Devanagaribold headlines, South Asian text

Each face has one weight and one style. Import each face you use by its own name: if your code picks faces at runtime from a table of all nine, all nine get bundled and the deck gets bigger.

When drawing text on a <canvas>, wait for the face to load before the first frame (await installTektur()), because a canvas doesn't wait for fonts on its own. CSS text needs no such care.

To use a face that isn't one of these, install it from npm as @fontsource/<face> so it's bundled the same way.

Tunable values and the Parameters panel​

The Parameters panel lets you tune a deck while it runs, without editing code. It lists every JavaScript or TypeScript file with a PARAMS object and turns each value into a control: a number becomes a scrubber you drag (or a slider, if you give it a min and max), a boolean a toggle, and a '#rrggbb' string a color picker. Your changes are written back into the file.

export const PARAMS = { jumpHeight: 4.2, coyoteTime: 0.08, trail: "#ffcc00" };

export const PARAMS_META = {
jumpHeight: { min: 0, max: 10, step: 0.5, hint: "Peak height in tiles." },
coyoteTime: { unit: "s" },
};
  • Put in PARAMS only the handful of values you'd actually tweak between playtests.
  • Write each value as a plain number (0.333, not 1 / 3).
  • Read values where they're used (PARAMS.jumpHeight) rather than copying them out when the file loads, so a tuned value reaches the running deck.
  • PARAMS_META is optional. It can set min, max, step, unit, options (a dropdown), file (a file picker for 'image', 'audio', 'video' or 'any') and hint.

Custom editors​

A deck can add its own visual editor for a kind of file it uses a lot, such as levels, dialogue or item lists. Declare the file type in castle.json under editor.fileTypes, write a React component for it in editors/, and the Files panel opens those files in your editor. The Scene Editor kit's scene and sprite editors are built the same way. When editing a file by hand gets tedious, ask Operator to build an editor for it.

What works where​

Some features depend on where the deck is running: the editor's Play panel, castle.xyz, or the Castle app.

  • Microphone and camera are blocked in the Play panel and on castle.xyz: asking for them fails without showing the player a prompt. Published decks can use them in the Android app, once the player gives Castle permission.
  • Buying passes and collecting snapshots work only in the Castle app. Elsewhere they report unavailable.
  • Copying to the clipboard isn't allowed on castle.xyz or in the app. If it fails, show the text so the player can copy it by hand.
  • Older versions of the app don't know about SDK commands added after them, and reject them with a CastleError whose code is UNKNOWN_COMMAND. Catch it and keep the deck working. CastleError lists which commands need which app version.

Next: Multiplayer · Back to Kits