Skip to main content

Setup

Startup, editor-mode check, and a file-write call for editor UI.

setup()​

Call this once at the start of the deck, before any other SDK call. setup() initializes the SDK so the rest of the API is usable and mounts a 5:7 Castle card around whatever the deck renders into #root in play mode. The SDK preserves the card aspect ratio; Castle hosts own the card's max size, placement, and surrounding padding. While running locally with castle-web serve, it also forwards console output to the CLI and reloads the page when castle-web restart runs.

setup() also keeps history.pushState and history.replaceState from throwing in a deck published on castle.xyz. There the deck's frame has no origin of its own, and a call that passes a URL throws a SecurityError; after setup() the call adds or replaces the history entry with its state but leaves the address as it was. A router that keeps its route in the address won't see it change; keep the route in the state or in the deck's own variables. localStorage throws there too; use LocalCache for things the deck can rebuild and Store for everything else.

import { setup } from "castle-web-sdk";

setup();

initCard(): HTMLDivElement​

Use this when the deck draws into a <canvas> (or anything else) rather than into the React tree at #root. Returns a <div> with the standard Castle 5:7 card aspect ratio. The div resizes itself when the window resizes. In Castle-hosted iframes/WebViews it fills the host's available card frame.

import { setup, initCard } from "castle-web-sdk";

setup();
const card = initCard();

const canvas = document.createElement("canvas");
canvas.style.cssText = "width: 100%; height: 100%; display: block;";
card.appendChild(canvas);

If the deck mounts a React tree into #root instead, you don't need initCard() — setup() already wraps #root's children in a card.

Host-specific layout flags such as CastleEmbed.feed are deprecated. New code should let Castle hosts provide the frame and let the SDK infer whether it is running standalone or embedded.

CARD_RATIO​

The card aspect ratio (5 / 7). Use this if you need to size something to match the card.

isEdit(): boolean​

true when the deck is being edited, false when it's being played. Use this to show editor UI only in edit mode.

import { isEdit, setup } from "castle-web-sdk";

setup();
if (isEdit()) {
mountEditor();
} else {
startGame();
}

writeFile(path, contents): Promise<void>​

Writes a file in the deck directory. path is relative to the deck root, contents is a string. Use this from editor UI to save scenes, drawings, or generated source.

import { writeFile } from "castle-web-sdk";

writeFile("scenes/main.scene", JSON.stringify(scene, null, 2));

The write is durable: the newest contents per path are held until the dev server confirms them, retried if it is briefly unreachable, and written as soon as it is back — including across a page reload. A dev server connection drops more often than it looks (a sleeping laptop or phone, a network change, a restarted serve), and an editor that treated those moments as failures would show work as saved that never landed.

Because of that, the returned promise settles with the FIRST attempt: it rejecting means "not yet", not "lost". Don't drive a "saved" indicator off it — use onSaveState below.

Only works while editing locally with castle-web serve. Calls from a published deck fail.

onSaveState(listener): () => void​

Subscribe to what is still waiting to reach disk. The listener gets { pending, error } — pending lists the paths the dev server hasn't confirmed, and error is why, while writes are failing. Fires on every change and once immediately; returns an unsubscribe.

import { onSaveState } from "castle-web-sdk";

onSaveState(({ pending, error }) => {
banner.hidden = !(error && pending.length);
});

hasPendingSave(path) answers the same question for one file — useful for ignoring a file-change event that is only the echo of your own write still in flight. flushSaves() gives everything queued an immediate attempt and resolves once they have all settled, whatever the outcome; reach for it just before a reload.

writeFileOnce(path, contents): Promise<void>​

One attempt, over the connection as it is right now, failing when it fails. Almost nothing wants this — a rejection here means the write is gone, and the caller owns what happens next. Use it only when a failure genuinely means give up, and writeFile when a person's work is at stake.

fileUrl(path): string​

A URL that serves a deck file as raw bytes. Point an <img>, <audio>, or <video> at it when editor UI has to show a file the browser renders natively — writeFile's counterpart reads text, which is nothing an image or a sound can be read as.

import { fileUrl } from "castle-web-sdk";

<img src={fileUrl("assets/logo.png")} alt="" />;

Like writeFile, this only means anything while editing locally with castle-web serve — a published deck has no serve to ask, and should load its assets through the bundler instead.