Lifecycle
Lifecycle tells the host when the deck has painted its first frame, so
the Castle feed can reveal it right away instead of waiting out a fixed
delay — and carries state across an unload, so a deck the player leaves
mid-play and comes back to picks up where it was.
Lifecycle.ready()
Signal that the deck has painted its first presentable frame. Idempotent — only the first call has any effect.
Kits already wire this up to fire as soon as the first frame paints; if you change how the deck first renders, make sure it still fires there. If nothing calls this, the feed reveals the deck on its own after a brief timeout.
If you call it right after kicking off your initial render, wait for the next paint first so the host doesn't reveal a blank frame:
createRoot(root).render(<App />);
requestAnimationFrame(() => requestAnimationFrame(() => Lifecycle.ready()));
Resuming across an unload
The host can unload a deck's page mid-play and mount it again later, and by default the deck starts over when it does. Resume state closes that: the host asks the deck for a snapshot of its current state, keeps it in memory, and offers it back the next time the deck mounts.
It is pause, not save. The host holds the snapshot briefly and in
memory only: it does not outlive the app, and the player restarting the
deck clears it. Anything that should outlive the app goes in
Store or Storage.
Reach for resume state when:
- the state must NOT persist by design — a daily-challenge attempt in progress, a roguelike run, an anti-farm timer;
- the state is too big or too churny for
Store; - the state only needs to survive the player leaving and coming back.
Don't substitute localStorage: it outlives the app and the host cannot
clear it, so the deck could never be restarted cleanly.
Not every host keeps resume state. Where one doesn't, restoreState()
resolves null and the provider is never called, so a deck written for
it works unchanged.
Lifecycle.provideState(provide): () => void
Register a function returning the deck's current state, for the host to hand back if it unloads and remounts this deck. Returns a function that unregisters it; registering again replaces the provider.
The host calls it whenever it might need a snapshot: at arbitrary
moments while the deck plays on, and often. A call does not mean the deck
is about to unload, so treat it as a read of your state and nothing more
— it must be synchronous, cheap and side-effect-free. Return
undefined to decline; the deck then starts fresh the next time it
mounts.
Whatever you return is JSON.stringify'd, so keep it small — tens of
kilobytes, not megabytes. A value over 1 MB is dropped with a warning.
import { Lifecycle } from "castle-web-sdk";
Lifecycle.provideState(() => ({ level, score, elapsedMs: clock.elapsed() }));
Lifecycle.restoreState<T>(): Promise<T | null>
The state this deck last provided, or null — nothing kept, the player
restarted the deck, or the host doesn't keep resume state. It never
throws for any of those, so there is nothing to catch. Reading doesn't
consume it.
Call it before your first paint and before ready(), so a deck that is
resuming doesn't flash its fresh state first:
const saved = await Lifecycle.restoreState();
startGame(saved ?? newGame());
Lifecycle.ready();