Build an engine game

src/games/stack-tower/
├── StackTower.tsx           # screen: engineGame + useEngineGame + EngineGameScreen
├── StackTowerConstants.ts   # tuning, timings, colours, layout, light
├── StackTowerGame.ts        # rules, no React: createGame / start / reset / tick / tap
└── StackTowerScene.ts       # cached meshes, spawning, animation, theme repaint
# Larger games add <Name>Rules.ts (pure, testable) and <Name>Meshes.ts (cached models)

import { type Camera, World } from '@nayan-ui/engine';
import type { GameTheme } from '../../services/ThemeService';
import type { HudFeedback } from '../shared/EngineHud';
import type { GamePhase } from '../shared/useEngineGame';
import { POINTS, TIME_LIMIT } from './MyGameConstants';
import { buildScene, setSceneTheme, type Scene } from './MyGameScene';

export type GameEvent = 'hit' | 'miss';

export function createGame(theme: GameTheme) {
  const world = new World(400);
  const camera: Camera = { eye: [0, 0, 240], target: [0, 0, 0], fov: 1, ortho: 1 };
  const g = {
    world, camera, theme,
    scene: null as Scene | null,
    phase: 'ready' as GamePhase,
    won: false,
    get score() { return world.scoreboard.score; },
    onPhase: (_p: GamePhase) => {},   // assigned by useEngineGame
    onEvent: (_e: GameEvent) => {},   // assigned by useEngineGame
    hudFeedback: {} as HudFeedback
  };
  world.scoreboard.reset(0, TIME_LIMIT);
  world.scoreboard.handlers = { onTimeUp: () => g.phase === 'playing' && end(g, true) }; // rules only
  return g;
}
export type Game = ReturnType<typeof createGame>;

export const setLayout = (g: Game, width: number, height: number) => { g.scene = buildScene(g.world, width, height, g.theme); };

export function setTheme(g: Game, theme: GameTheme) {
  g.theme = theme;
  if (g.scene) setSceneTheme(g.world, g.scene, theme); // repaint, keep progress
}

export function start(g: Game) {
  if (g.phase !== 'ready') return;
  g.phase = 'playing';
  g.world.scoreboard.reset();
  g.world.scoreboard.startCountdown(TIME_LIMIT);
  g.onPhase('playing');
}

export function reset(g: Game) {
  g.world.cancelTimers();
  // ...despawn this run's entities
  g.world.scoreboard.reset(0, TIME_LIMIT);
  g.won = false;
  g.phase = 'ready';
  g.hudFeedback.message = undefined;
  g.onPhase('ready');
}

export function tick(g: Game, dt: number) {
  // ...this frame's movement; the world steps after
}

export function tap(g: Game, x: number, y: number) {
  if (g.phase !== 'playing') return;
  g.world.scoreboard.add(POINTS);
  g.onEvent('hit');
}

function end(g: Game, won: boolean) {
  g.world.scoreboard.stop();
  g.won = won;
  g.phase = 'over';
  g.onPhase('over'); // the hook reports win / lose once
}

import { HapticType } from '../../services/HapticsService';
import { GAME_SOUNDS } from '../../services/SoundsService';
import { GAME_IDS } from '../../services/UtilsService';
import { engineGame, EngineGameScreen } from '../shared/EngineGameScreen';
import { scoreColumn, timerColumn } from '../shared/EngineHud';
import { useEngineGame } from '../shared/useEngineGame';
import { LIGHT } from './MyGameConstants'; // e.g. frontLight([-0.45, 0.6, 1], 0.5)
import { createGame, reset, setLayout, setTheme, start, tap, tick } from './MyGameGame';

const SOUNDS = GAME_SOUNDS.MY_GAME;

export const MyGame = engineGame(GAME_IDS.MY_GAME, (props) => {
  const { board, theme, status, screen, gameOver } = useEngineGame(props, {
    gameId: GAME_IDS.MY_GAME,
    create: createGame,
    start, reset, tick, setTheme,
    resize: (g, width, height) => setLayout(g, width, height),
    tap: (g, x, y) => tap(g, x, y),
    sounds: SOUNDS,
    events: {
      hit: { sound: SOUNDS.HIT, haptic: HapticType.LIGHT },
      miss: { sound: SOUNDS.MISS, haptic: HapticType.ERROR }
    },
    onStart: (fx) => fx(SOUNDS.START, HapticType.SUCCESS),
    onOver: (fx, s) => fx(s === 'win' ? SOUNDS.WIN : SOUNDS.GAME_OVER, s === 'win' ? HapticType.SUCCESS : HapticType.ERROR)
  });

  return (
    <EngineGameScreen
      {...screen}
      light={LIGHT}
      columns={[scoreColumn(board.score), timerColumn(board.seconds, theme)]}
      subtext="Tap to play!"
      gameOver={gameOver({
        title: status === 'win' ? 'AMAZING!' : 'GAME OVER',
        scoreLabel: 'Final Score',
        score: board.score,
        buttonText: 'Play Again!'
      })}
    />
  );
});

import { effects, extrude, merge, Path, quat, type Entity, type World } from '@nayan-ui/engine';
import { createGameMesh, meshCache } from '../shared/EngineMeshes';

const cached = meshCache('my-game/MyGameScene:'); // folder-prefixed key
const block = () =>
  cached('block', () =>
    createGameMesh(merge([{ geometry: extrude(new Path().addRoundedRect(-20, -10, 40, 20, 4), { depth: 16 }) }]), { shine: 0.4 })
  );

export const spawnBlock = (world: World, x: number, y: number, color: string): Entity =>
  world.spawn({ mesh: block(), position: [x, y, 0], color }); // CSS string or 0..1 tuple

export function moveBlocks(world: World, blocks: { entity: Entity; x: number; y: number; angle: number }[]) {
  const t = world.transforms; // allocation-free, applied when the world steps
  for (const b of blocks) {
    const [qx, qy, qz, qw] = quat.z(b.angle);
    t.transform(b.entity, b.x, b.y, 0, qx, qy, qz, qw);
  }
}

export const celebrate = (world: World, x: number, y: number) =>
  effects.confetti(world, { position: [x, y, 10], colors: ['#FFD43B', '#FF6BD6'], size: 4, speed: 160, count: 40, lifetime: 1.2, gravity: -300 });

export async function clearPiece(world: World, entity: Entity, color: string) {
  await effects.pop(world, entity, { scale: 1, color });
  world.despawn(entity); // safe no-op after disposal
}

// services/UtilsService.ts
export enum GAME_IDS { /* ... */ MY_GAME = 'my-game' }

// services/GamesMetadata.ts
[GAME_IDS.MY_GAME]: { id: GAME_IDS.MY_GAME, title: 'My Game', description: 'One sentence.', instructions: ['Tap to drop.'], categories: ['arcade'] },

// services/GamesService.ts
[GAME_IDS.MY_GAME]: { ...GAMES_METADATA[GAME_IDS.MY_GAME], component: MyGame },

// services/GameLoaders.ts
[GAME_IDS.MY_GAME]: () => require('../games/my-game/MyGame').MyGame,

// services/SoundsService.ts
MY_GAME: { START: { sfx: '...' }, WIN: { sfx: '...' } /* ... */ },

// src/index.tsx
export * from './games/my-game/MyGame';

bun run games:test
bun check -p packages/games/tsconfig.build.json
bun run games:build