Build your first game

npx @nayan-ui/cli new my-game -t games   # copy examples/games into ./my-game
cd my-game                               # go into the project
bun install                              # install the apps and @nayan-ui/engine from npm
bun run web                              # play in the browser at http://127.0.0.1:5173
bun run ios                              # or: bun run android (a development build, not Expo Go)

my-game/
├── shared/                     # the game, used by both apps
│   ├── index.ts                # exports CarRacing, GameProps, DEFAULT_GAME_SETTINGS
│   └── src/
│       ├── games/car-racing/   # the Car Racing game
│       ├── games/shared/       # the game screen: scoreboard, buttons, loading, results
│       ├── helpers/            # the settings modal and themes
│       ├── services/           # GameProps, game ids, themes, sounds
│       └── assets/             # car models, textures, sounds, font
├── mobile/src/                 # Expo app (Expo Router)
│   ├── app/index.tsx           # route /: the list of games
│   ├── app/[id].tsx            # route /car-racing: the game, full screen
│   └── examples.ts             # the list of games
└── web/src/                    # Vite app (React Router)
    ├── Home.tsx                # route /: the list of games
    ├── GamePage.tsx            # route /car-racing: the game, full screen
    └── examples.ts             # the list of games

// The game: a component that takes GameProps.
export { CarRacing } from "./src/games/car-racing/CarRacing";
// Its props and default settings.
export { DEFAULT_GAME_SETTINGS, type GameProps, type GameSettings } from "./src/services/UtilsService";
// Theme colours, so an app can paint its header to match.
export { resolveGameTheme } from "./src/services/ThemeService";

let car: Promise<CarMeshes> | undefined; // Loaded once, then shared by every run.

export function loadCarMeshes(): Promise<CarMeshes> {
  car ??= Promise.all([ // Start loading only on the first call.
    // White paint: each car tints it.
    loadModel(require("../../assets/models/car/car_body.glb"), { center: false, shine: 0.85 }),
    // Windows, glossier.
    loadModel(require("../../assets/models/car/car_glass.glb"), { center: false, shine: 0.95 }),
    // Tyres, lights, mirrors in their own colours.
    loadModel(require("../../assets/models/car/car_trim.glb"), { center: false, shine: 0.25 }),
  ]).then(([body, glass, trim]) => ({ body, glass, trim })); // One object with the three models.
  car.catch(() => (car = undefined)); // If loading fails, try again next time.
  return car; // Every caller gets the same promise.
}

export function spawnCar(world: World, a: Assets, paint: Color, position: Vec3, night: boolean) {
  const model = a.car; // The loaded body, glass and trim.
  const root = world.spawn({ mesh: "none", position }); // An invisible root: the game moves this.
  // The models sit with their wheels on the ground.
  const offset: Vec3 = [0, -model.size[1] / 2, 0];
  // The paint, in this car's colour.
  const body = world.spawn({ mesh: model.body, parent: root, position: offset, color: paint });
  const glass = world.spawn({ mesh: model.glass, parent: root, position: offset }); // The windows.
  // Tyres, lights and the rest.
  const trim = world.spawn({ mesh: model.trim, parent: root, position: offset });
  // Everything the game needs to move or restyle it.
  const car = { root, body, glass, trim, lights: [] as Entity[] };
  // At night, glowing headlights and a tail-light bar.
  setCarNight(world, car, night, model.size[1]);
  return car;
}

<EngineGameScreen
  gameId={GAME_IDS.CAR_RACING} // Picks the game's title, loading scene and sounds.
  settings={settings} // Sounds, haptics, theme and where the scoreboard starts (from the app).
  onSettingsChange={onSettingsChange} // The settings modal saves its changes here.
  source={game.world} // The engine world this run draws.
  camera={game.camera} // The chase camera behind the player's car.
  light={night ? NIGHT_LIGHT : DAY_LIGHT} // Day or night lighting.
  background={night ? NIGHT_SKY : SKY} // The sky colour.
  onUpdate={onUpdate} // Runs the rules every frame (tick).
  onDrag={onDrag} // Dragging steers the car.
  // The scoreboard.
  columns={[scoreColumn(score), livesColumn(lives, LIVES), textColumn("TRACK", `${left} m`)]}
  playing={phase === "playing"} // Shows Start or Stop.
  onStart={handleStartGame} // Start pressed.
  onStop={handleStopGame} // Stop pressed: report a cancel and start a fresh run.
  // The results card.
  gameOver={
    showResults // After the crash or the finish has been seen:
      ? { title: won ? "FINISHED!" : "CRASHED!", score, buttonText: "Race Again!", onPlayAgain: handleResetGame }
      : null // No results card during the race.
  }
/>

const { id } = useLocalSearchParams<{ id: string }>(); // The route's id: "car-racing".
const example = findExample(id); // The game for that id, from examples.ts.
const headerHeight = useHeaderHeight(); // The header's height, status bar included.
// What the game reads.
const [settings, setSettings] = useState<GameSettings>({ ...DEFAULT_GAME_SETTINGS, theme: deviceTheme });

return (
  <example.Screen
    settings={{ ...settings, offset: headerHeight }} // The scoreboard starts below the header.
    onSettingsChange={setSettings} // The settings modal saves its changes here.
    // No swipe-back mid-race.
    onPlayingChange={(playing) => navigation.setOptions({ gestureEnabled: !playing })}
  />
);

const example = findExample(useParams().id); // The game for this route's id.
// Scoreboard below the toolbar.
const [settings, setSettings] = useState<GameSettings>({ ...DEFAULT_GAME_SETTINGS, offset: 70 });

useEffect(() => {
  // Arrow keys and A/D drag, so they steer.
  const keyboard = createKeyboardInput(surface.current!, { mode: "drag" });
  return () => keyboard.dispose(); // Stop listening when the page closes.
}, []);

return (
  <div ref={surface} tabIndex={0}> {/* The game draws here; tabIndex lets it take the keys. */}
    <Suspense fallback={<p>Loading…</p>}> {/* Shown while the game's code downloads. */}
      {/* The same component as on mobile. */}
      <example.Screen settings={settings} onSettingsChange={setSettings} />
    </Suspense>
  </div>
);

resolve: {
  // React Native components render as HTML.
  alias: [{ find: /^react-native$/, replacement: "react-native-web" }],
  // A file's .web.ts version wins in the browser.
  extensions: [".web.tsx", ".web.ts", ".tsx", ".ts", ".js"],
},
// Plus a small plugin: require("./engine.wav") becomes a URL that Vite copies into the build.

1. Write the game in shared/src/games/<id>/ (copy car-racing as a starting point).
2. Add its id to GAME_IDS in shared/src/services/UtilsService.ts.
3. Add its title and instructions to GAMES_METADATA in shared/src/services/GamesMetadata.ts.
4. Export its component from shared/index.ts.
5. Add { id, title, description, Screen } to mobile/src/examples.ts and web/src/examples.ts.
6. Run bun run typecheck, then bun run web and bun run ios.

[ ] The list shows Car Racing; opening it shows the loading scene, then the race
[ ] Start: the car drives; drag (or arrow keys / A D) to steer
[ ] Pass a car: the score goes up
[ ] Hit a car from behind: one heart is lost; side swipes only slow you down
[ ] Settings: Dark Mode switches to the night city with lit windows and headlights
[ ] Finish the 2000 m track, or lose all lives: the results card shows; Race Again starts over
[ ] Back (header arrow, toolbar button or browser back): returns to the list