useScene

useScene provides scene navigation and status. It reads from the scene store managed by SceneManager.

tsx
import { useScene } from "@carverjs/core/hooks";

Quick Start #

tsx
import { useScene } from "@carverjs/core/hooks";

function MenuScene() {
  const { go } = useScene();

  return (
    <World>
      <Actor
        type="primitive" shape="box" color="#facc15"
        onClick={() => go("gameplay", { level: 1 }, { type: "fade", duration: 0.8 })}
      />
    </World>
  );
}

Return Value (UseSceneReturn) #

PropertyTypeDescription
go(name, data?, transition?)(string, unknown?, TransitionConfig?) => voidNavigate to a scene, clearing the stack
push(name, data?, transition?)(string, unknown?, TransitionConfig?) => voidPush a scene onto the stack (current scene sleeps)
pop(transition?)(TransitionConfig?) => voidPop the top scene, return to previous
replace(name, data?, transition?)(string, unknown?, TransitionConfig?) => voidReplace the current scene
currentstring | nullName of the current active scene
stackreadonly string[]Full navigation stack (last = current)
isTransitioningbooleanWhether a transition is in progress

Go (clear stack) #

tsx
const { go } = useScene();
go("gameplay", { level: 1 });

Destroys all scenes in the stack (unless persistent), navigates to the target.

Push (overlay) #

tsx
const { push } = useScene();
push("pause");

Current scene sleeps, new scene pushes on top. Use for pause menus, inventories, dialogs.

Pop (return) #

tsx
const { pop } = useScene();
pop({ type: "fade", duration: 0.3 });

Destroys the top scene, wakes the previous one.

Replace (swap) #

tsx
const { replace } = useScene();
replace("level2", { score: 500 });

Replaces the current scene without changing stack depth. Use for level progression.

Transition Config #

All navigation methods accept an optional TransitionConfig:

FieldTypeDefaultDescription
type"none" | "fade" | "custom""none"Transition type
durationnumber0.5Duration in seconds
colorstring"#000000"Fade color (for "fade" type)
fragmentShaderstring—Custom GLSL fragment shader (for "custom" type)
vertexShaderstring—Custom vertex shader (for "custom" type)
uniformsRecord<string, { value: unknown }>—Additional shader uniforms (for "custom" type)

useSceneData

Access the data passed to the current scene and cross-scene shared data.

tsx
import { useSceneData } from "@carverjs/core/hooks";

Return Value (UseSceneDataReturn<T>) #

PropertyTypeDescription
dataT | undefinedData passed to the current scene via navigation
setShared(key, value)(string, unknown) => voidSet cross-scene shared data
getShared<V>(key)(string) => V | undefinedGet cross-scene shared data

Usage #

tsx
function GameplayScene({ data }: { data?: { level: number } }) {
  const { setShared, getShared } = useSceneData<{ level: number }>();
  const highScore = getShared<number>("highScore") ?? 0;

  const handleWin = (score: number) => {
    if (score > highScore) setShared("highScore", score);
  };

  return <World>{/* ... */}</World>;
}

useSceneTransition

Read-only access to the current transition state. Use for UI effects like dimming during transitions.

tsx
import { useSceneTransition } from "@carverjs/core/hooks";

Return Value (UseSceneTransitionReturn) #

PropertyTypeDescription
activebooleanWhether a transition is in progress
progressnumberTransition progress (0-1)
fromstring | nullSource scene name
tostring | nullTarget scene name

useSceneLifecycle

Register lifecycle callbacks for a specific scene. Uses the callback-ref pattern so the latest closures are always called.

tsx
import { useSceneLifecycle } from "@carverjs/core/hooks";

Signature #

ts
function useSceneLifecycle(
  sceneName: string,
  callbacks: SceneLifecycleCallbacks
): void;

Callbacks #

CallbackWhen
onEnterScene transitions to "running" for the first time. Return a cleanup function.
onExitScene leaves "running" (sleep, pause, or destroy)
onSleepScene transitions to "sleeping"
onWakeScene transitions from "sleeping" to "running"
onPauseScene transitions to "paused"
onResumeScene transitions from "paused" to "running"

Usage #

tsx
function GameplayScene() {
  useSceneLifecycle("gameplay", {
    onEnter: () => {
      console.log("Gameplay started");
      return () => console.log("Cleanup");
    },
    onSleep: () => console.log("Game paused/sleeping"),
    onWake: () => console.log("Game resumed"),
  });

  return <World>{/* ... */}</World>;
}

Type Definitions #

See Types for UseSceneReturn, UseSceneDataReturn, UseSceneTransitionReturn, SceneLifecycleCallbacks, TransitionConfig, TransitionType, and SceneStatus.