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

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

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

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

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:

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

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:

npm run build:lib
npm publish --access public