Scene

Scene declaratively registers a scene configuration with the SceneManager. It does not render scene content — the SceneManager handles rendering based on navigation state.

tsx

import { Scene } from "@carverjs/core/components";

Quick Start #

tsx

<SceneManager initial="menu">
  <Scene name="menu" component={MenuScene} />
  <Scene name="gameplay" component={GameplayScene} transition={{ type: "fade" }} />
  <Scene name="hud" component={HUDScene} persistent />
</SceneManager>

Props Reference #

Prop	Type	Default	Description
`name`	`string`	—	Required. Unique scene identifier used in navigation calls
`component`	`ComponentType<{ data?: T }>`	—	React component to render as scene content
`loader`	`() => Promise<{ default: ComponentType }>`	—	Lazy loader for code-splitting (overrides `component`)
`transition`	`TransitionConfig`	—	Default transition when navigating to this scene
`persistent`	`boolean`	`false`	Keep scene mounted (sleeping) when navigated away

Scene Component Contract #

Scene components receive an optional data prop containing whatever was passed during navigation:

tsx

function GameplayScene({ data }: { data?: { level: number } }) {
  const level = data?.level ?? 1;
  return (
    <World>
      {/* level content */}
    </World>
  );
}

Lazy Loading #

Use loader instead of component for code-split scenes:

tsx

<Scene
  name="editor"
  loader={() => import("./scenes/EditorScene")}
/>

The scene module must have a default export:

tsx

// scenes/EditorScene.tsx
export default function EditorScene({ data }: { data?: unknown }) {
  return <World>{/* ... */}</World>;
}

Type Definitions #

See Types for SceneConfig, TransitionConfig, and SceneProps.