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'
| Face | Character | Good for |
|---|---|---|
DMSans | clean geometric sans | body text, UI, HUD |
Piazzolla | sturdy text serif | narrative, prose-heavy decks |
CourierPrime | monospace typewriter | code, terminals, typewriter effects |
Tektur | condensed squarish techno | sci-fi, arcade, HUD numerals |
Bore | very heavy wide grotesque | headlines, scores, big titles |
Synco | light wide geometric | retro-modernist titles |
Glacier | slanted condensed italic | informal, energetic display |
HelicoCentrica | blackletter-flavored roman | medieval, fantasy |
YatraOne | high-contrast brushy display, also Devanagari | bold 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
PARAMSonly the handful of values you'd actually tweak between playtests. - Write each value as a plain number (
0.333, not1 / 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_METAis optional. It can setmin,max,step,unit,options(a dropdown),file(a file picker for'image','audio','video'or'any') andhint.
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
CastleErrorwhosecodeisUNKNOWN_COMMAND. Catch it and keep the deck working. CastleError lists which commands need which app version.
Next: Multiplayer · Back to Kits