npm package: @rookoo/game
Description: Embed the Rookoo venue-manager game into any web application. The SDK provides full lifecycle control, an event system for reacting to in-game actions, and state queries.
Latest version: 1.0.0

# Rookoo Game SDK

Embed the Rookoo venue-manager game into any web application. The SDK provides full lifecycle control, an event system for reacting to in-game actions, and state queries.

## Installation

```bash
npm install @rookoo/game
```

## Serving Assets

The game loads tilesets, spritesheets, level configs, and other assets at runtime. You need to host the `public/assets/` folder from this repo and pass the URL when creating the game.

For example, if you copy the assets to your app's public directory at `/game-assets/`:

```
your-app/
  public/
    game-assets/
      venue.tmj
      character.png
      decoration.json
      fridge_white_sheet.png
      tilesets/
      levels/
```

## Quick Start

```js
import { createGame, Events } from '@rookoo/game';

const game = createGame({
  container: document.getElementById('game-area'),
  assetsBaseUrl: '/game-assets',
});

game.on('ready', () => {
  console.log('Game loaded');
});

game.on('levelComplete', ({ starRating, levelKey }) => {
  console.log(`Completed ${levelKey} with ${starRating} stars`);
});

game.on('gameOver', ({ reason }) => {
  console.log('Game over:', reason);
});
```

## API

### `createGame(options): RookooGame`

Creates and mounts a new game instance.

| Option | Type | Default | Description |
|---|---|---|---|
| `container` | `HTMLElement` | *required* | DOM element to render the game into |
| `assetsBaseUrl` | `string` | `'/assets'` | Base URL where game assets are hosted (no trailing slash) |
| `debug` | `boolean` | `false` | Enable Phaser physics debug rendering |

### Game Control

```js
game.startLevel('level1');                         // Start a level
game.startLevel('tutorial', { tutorialMode: true }); // Start tutorial
game.startLevel('level1', { rookooMode: true });   // AI handles emails

game.pause();    // Pause gameplay
game.resume();   // Resume gameplay
game.destroy();  // Destroy the game and clean up
```

### State Queries

```js
game.getActiveScene();  // 'TitleScene' | 'GameScene' | 'ResultScene' | ...
game.getCurrentLevel(); // 'level1' | null
game.isRunning();       // true if in GameScene, not paused, not game-over

game.getState();
// Returns:
// {
//   scene: 'GameScene',
//   level: { key, name, timeLimit, maxIgnored },
//   time: { elapsed, remaining },
//   placements: { placed, total, items: [{ id, label, placed }] },
//   emails: { answered, ignored },
//   boost: { focusCharge, fridgeActive, fridgeCooldownRemaining },
//   player: { x, y, frozen },
//   paused: false,
//   gameOver: false,
// }
```

### Events

Subscribe with `game.on(event, callback)`, `game.once(event, callback)`, or unsubscribe with `game.off(event, callback)`.

| Event | Payload | Description |
|---|---|---|
| `ready` | `{}` | Assets loaded, game is ready |
| `levelStart` | `{ levelKey, levelName, totalItems, timeLimit, maxIgnored }` | Gameplay begins |
| `levelComplete` | `{ levelKey, levelName, timeTaken, emailsAnswered, emailsIgnored, totalPlacements, starRating }` | All items placed — level won |
| `gameOver` | `{ reason, levelKey, levelName, timeTaken, placedCount, totalItems, emailsAnswered, emailsIgnored }` | Player lost (`reason`: `'time'` or `'emails'`) |
| `itemPlaced` | `{ itemId, label, placedCount, totalItems }` | An item was placed |
| `emailReceived` | `{ emailIndex, mode }` | Email popup shown (`mode`: `'sequence'` or `'factcheck'`) |
| `emailAnswered` | `{ answeredCount }` | Email answered correctly |
| `emailIgnored` | `{ ignoredCount }` | Email skipped or failed |
| `boostActivated` | `{ type, duration }` | Fridge energy boost used |
| `sceneChanged` | `{ from, to }` | Scene transition |
| `paused` | `{}` | Game paused |
| `resumed` | `{}` | Game resumed |

You can also use the `Events` constants instead of string literals:

```js
import { Events } from '@rookoo/game';

game.on(Events.GAME_OVER, (data) => { ... });
game.on(Events.LEVEL_COMPLETE, (data) => { ... });
```

### Available Levels

| Key | Description |
|---|---|
| `tutorial` | Tutorial level with guided steps |
| `level1` | Level 1 |
| `level2` | Level 2 |
| `level3` | Level 3 |
| `level4` | Level 4 |

## Development

```bash
npm install
npm run dev          # Standalone dev server at localhost:3000
npm run build        # Standalone production build → dist/
npm run build:lib    # Library build → dist-lib/
```

## Publishing

The package is published to npm automatically when a GitHub release is created. Make sure to bump the `version` in `package.json` before creating a release.

Manual publish:

```bash
npm run build:lib
npm publish --access public
```