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.