);
};
export const characterSetup = defineWidget("character-setup", CharacterSetup);
```
Two things are worth pausing on:
- **Read through the hook, write through the entity.** `useGameEntity(hero)` is what
makes this component reactive; `hero.resolve += delta` is the write. Reading
`hero.resolve` directly in a component would show a stale value after the next
update, because nothing subscribed.
- **`defineWidget` receives the component, not an element.** A function passed to
`defineWidget` is always rendered as a React component, so hooks work even in
minified production builds.
## 4. Write the story passages
`defineStory` takes an id and a content callback. The callback runs every time the
passage is displayed, so it always reads current state, and any falsy entry in the
returned array is dropped — which is all you need for branching.
```ts title="src/game/passages/crossroads.ts"
import { defineStory } from "@react-text-game/core";
import { hero } from "../entities/hero";
export const crossroads = defineStory("crossroads", (h) => [
h.header("The crossroads at dusk", { level: 1 }),
h.text(`${hero.name} the ${hero.calling} stops where the road splits.`),
h.text(`Resolve ${hero.resolve} · Insight ${hero.insight}`, {
className: "font-mono text-sm text-muted-foreground",
}),
h.text(
"One fork is strung with lit lanterns. The other drops into black marsh water."
),
hero.insight < 3 &&
h.text("The marsh is unreadable to you. Insight 3 would change that.", {
className: "text-sm italic",
}),
h.actions(
[
{ content: "Follow the lanterns", action: h.jump("lantern-road") },
hero.insight >= 3 && {
content: "Wade into the marsh",
action: h.jump("marsh"),
color: "secondary",
},
{
content: "Rebuild your hero",
action: h.jump("character-setup"),
variant: "bordered",
color: "default",
},
],
{ direction: "vertical" }
),
]);
```
The two roads link back here, so `crossroads` reaches them by **id** rather than by
import — that keeps the module graph acyclic. Everywhere the engine asks for a
passage it accepts either a passage instance or a registered id; prefer the instance
when the import direction allows it, since a renamed passage then cannot become a
dead link.
```ts title="src/game/passages/lanternRoad.ts"
import { defineStory, Game } from "@react-text-game/core";
import { hero } from "../entities/hero";
import { crossroads } from "./crossroads";
import { ending } from "./ending";
export const lanternRoad = defineStory("lantern-road", (h) => [
h.header("The lantern road", { level: 1 }),
h.text("Every lantern is lit, and nobody is here to have lit them."),
hero.calling === "scholar"
? h.text("You count nineteen. Nineteen is the wrong number, and you know why.")
: h.text("You walk the verge instead of the road, where the light cannot reach."),
h.conversation(
[
{
content: "Late to be walking.",
who: { name: "Lamplighter" },
side: "left",
},
{
content: "Late to be lighting.",
who: { name: hero.name },
side: "right",
},
],
{ appearance: "byClick" }
),
h.actions([
{
content: "Take a lantern and walk on",
action: () => {
hero.lanternTaken = true;
Game.jumpTo(ending);
},
},
{
content: "Back to the crossroads",
action: h.jump(crossroads),
variant: "bordered",
color: "default",
},
]),
]);
```
```ts title="src/game/passages/marsh.ts"
import { defineStory, Game } from "@react-text-game/core";
import { hero } from "../entities/hero";
import { crossroads } from "./crossroads";
import { ending } from "./ending";
export const marsh = defineStory("marsh", (h) => [
h.header("Black water", { level: 1 }),
h.text("You read the water the way you would read a page, and it reads back."),
hero.resolve >= 4
? h.text("It finds nothing in you that flinches.")
: h.text("Something in you flinches, and the water keeps it."),
h.actions([
{
content: "Cross",
action: () => {
hero.marshTaken = true;
hero.resolve += 1;
Game.jumpTo(ending);
},
},
{
content: "Back to the crossroads",
action: h.jump(crossroads),
variant: "bordered",
color: "default",
},
]),
]);
```
```ts title="src/game/passages/ending.ts"
import { defineStory, Game } from "@react-text-game/core";
import { hero } from "../entities/hero";
export const ending = defineStory("ending", (h) => [
h.header("Morning", { level: 1 }),
h.text(`${hero.name} reaches the far town at first light.`),
hero.marshTaken &&
h.text("The marsh water dried in your boots and left a line of salt."),
hero.lanternTaken &&
h.text("The lantern is still burning, and it should not be."),
h.text(`Resolve ${hero.resolve} · Insight ${hero.insight}`, {
className: "font-mono text-sm text-muted-foreground",
}),
h.actions([
{
content: "Walk it again",
action: () => {
hero.lanternTaken = false;
hero.marshTaken = false;
Game.jumpTo("character-setup");
},
},
]),
]);
```
`h` is the story toolbox: `h.text`, `h.header`, `h.image`, `h.video`, `h.actions`,
`h.conversation` and `h.include` build components, `h.jump(target)` builds a
navigation handler, and `h.when(condition, value)` builds a conditional one. Each
builder takes its content first and one flat options bag second. The complete list
of components and options is in [Core concepts](/core-concepts#story-passages).
## 5. Register the game
Entities and passages register as their modules are imported, so export them all from
one barrel and import that barrel exactly once from your entry point. Without it a
production bundler is free to tree-shake a passage nobody imports by name.
```ts title="src/game/index.ts"
export * from "./entities/hero";
export * from "./passages/characterSetup";
export * from "./passages/crossroads";
export * from "./passages/lanternRoad";
export * from "./passages/marsh";
export * from "./passages/ending";
```
## 6. Mount GameProvider and PassageController
`GameProvider` owns the engine lifecycle: it awaits `Game.init()`, preloads assets,
runs the loading and splash phases, provides the component registry and the save/load
dialog, and mounts the dev tools. `PassageController` renders whatever passage is
current.
```tsx title="src/main.tsx"
import "./styles.css";
import "./game";
import { GameProvider } from "@react-text-game/ui";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { App } from "./App";
import { characterSetup } from "./game/passages/characterSetup";
const gameOptions = {
gameName: "The Lantern Road",
gameId: "lantern-road",
gameVersion: "0.1.0",
author: "you",
startPassage: characterSetup,
isDevMode: import.meta.env.DEV,
};
createRoot(document.getElementById("root")!).render(