Skip to main content

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();