react-waiting-game

A tiny one-button mini-arcade for filling the void while a long task runs (LLMs, builds, uploads, you name it). Every game is monocolor, pure 1-bit pixel art, single canvas, zero runtime dependencies, and shares the same combo / power-up / high-score / achievement framework.

• Pick a game with a single prop: <WaitingArcade game="runner" />
• One button: keyboard, pointer, and touch all map to the same primary action
• Tints to any colour via the color prop (defaults to currentColor)
• SSR-safe; auto-pauses when the tab is hidden
• Optional localStorage-backed best score and achievements, namespaced per game
• Same component still ships as <WaitingGame /> for backward compatibility

The games

All five games share the same set of features: combo multiplier, near-miss bonus (or its game-specific equivalent), milestone flashes, tier ramp, screen shake, parallax background, three power-ups, and a five-achievement set. Death model varies: most games are one-hit, rhythm uses 3 lives.

Install

npm install react-waiting-game

Quick start

import { WaitingArcade } from 'react-waiting-game';

function LoadingScreen() {
  return <WaitingArcade game="runner" autoStart />;
}

Use it while waiting on an LLM

import { useState } from 'react';
import { WaitingArcade } from 'react-waiting-game';

function Chat() {
  const [loading, setLoading] = useState(false);

  async function ask() {
    setLoading(true);
    await fetch('/api/chat', { method: 'POST', body: '...' });
    setLoading(false);
  }

  return (
    <div>
      <button onClick={ask} disabled={loading}>Ask</button>
      {loading && (
        <WaitingArcade
          game="runner"
          autoStart
          persistHighScore
          persistAchievements
        />
      )}
    </div>
  );
}

Controls

Every game uses the same single-button input.

• Jellyfish — hold to thrust upward, release to sink under gravity. Walls catch you gently; only obstacles end the run.
• Runner — tap to jump, hold to jump higher (variable height). Land before the next obstacle.
• Gravity — tap to flip gravity. The player accelerates toward the active surface; flip mid-arc to thread between floor and ceiling spikes.
• Invaders — your turret auto-fires bullets to the right at a fixed cadence. Tap to swap between the upper and lower lane. Aliens that escape past you break your combo; aliens that touch you while in your lane end the run.
• Rhythm — short tap notes scroll right-to-left into the hit zone; tap when one is centred. Long notes are hold notes — keep the button down while the bar passes through the cursor and release at the end. Missing a note, breaking a hold, or false-tapping costs one of your three lives.

<WaitingArcade /> props

Achievements

Every game unlocks five achievements per run.

Jellyfish (jellyfish)

Runner (runner)

Gravity (gravity)

Invaders (invaders)

Rhythm (rhythm)

Skins

<WaitingArcade game="jellyfish" skin="octopus"  />
<WaitingArcade game="runner"    skin="ninja"    />
<WaitingArcade game="gravity"   skin="triangle" />
<WaitingArcade game="invaders"  skin="saucer"   />
<WaitingArcade game="rhythm"    skin="dot"      />

Use GAMES[game].skins for the full list at runtime, or import the per-game constants:

import {
  SKIN_IDS,
  RUNNER_SKIN_IDS,
  GRAVITY_SKIN_IDS,
  INVADERS_SKIN_IDS,
  RHYTHM_SKIN_IDS,
} from 'react-waiting-game';

Backward compatibility — <WaitingGame />

The original <WaitingGame /> jellyfish-only component still ships unchanged:

import { WaitingGame } from 'react-waiting-game';

<WaitingGame autoStart skin="paperBoat" persistHighScore />

It uses the original storage key waiting-game:hi, so existing high scores carry over. New projects should prefer <WaitingArcade game="jellyfish" />.

Adding a new game

Each game is just a GameModule registered in src/games/index.ts:

import type { GameModule } from 'react-waiting-game';

export const myGame: GameModule<MyState, MySkin, MyAch> = {
  id: 'mygame',
  defaultWidth: 600,
  defaultHeight: 150,
  skins: ['default'],
  defaultSkin: 'default',
  achievements: [...],
  init, tick, draw,
  selectScore, selectHiScore, selectPhase,
  selectScreenShake, selectDeathFlash,
  selectAchievements, selectNewAchievements,
  idlePrompt: 'Tap to start',
  deadPrompt: 'Press to retry',
};

The shared useGameLoop, input bus, persistence helpers, pixel/digit drawing, screen-shake decay, and feedback types all live under src/shared/.

Development

npm install
npm test          # 151 unit tests across all five game engines
npm run lint      # tsc --noEmit
npm run build     # tsup → dist/ (ESM + CJS + .d.ts)

Try the example

cd example
npm install
npm run dev

The example simulates an LLM call, lets you switch between games and skins live, shows combo/pickup callbacks, and lists unlocked achievements.

License

MIT