# Scratchee Game Client Demo

Standalone demo showing the minified Scratchee scratch card game client with mock data.

## What This Shows

- Complete 3D scratch card experience with physics and animations
- All 5 callbacks wired up (onNewGame, onReady, onPlay, onReveal, onComplete)
- Mock winning card data + Fastlane asset pack
- Status bar logs callback flow in real time

## What's in This Archive

```
scratchee-game-client/
├── demo.html              ← runs the demo (open via HTTP — see below)
├── DEMO-README.md         ← this file
├── game-client/           ← the production library (copy to your webroot)
│   ├── game-client.js
│   ├── game-client.css
│   ├── game-client.d.ts
│   ├── code chunks (loaded on demand)
│   └── 645e83353a1ac.png, icon-info.png, icon-x.png — chrome defaults (overridable per pack)
└── demo-assets/           ← reference mock JSON (inline in demo.html, kept for inspection)
```

## How to Run

The bundle must be served over HTTP — opening via `file://` won't work. Browsers block ES module imports + cross-origin requests from `file://` origins.

### Option 1 — Node (recommended; works everywhere, no install)

```bash
cd scratchee-game-client
npx serve
# opens at http://localhost:3000 — append /demo.html
```

### Option 2 — Python (built-in on macOS/Linux, free on Windows via Microsoft Store)

```bash
cd scratchee-game-client
python3 -m http.server 8000   # macOS/Linux
python -m http.server 8000    # Windows
# open http://localhost:8000/demo.html
```

### Option 3 — VS Code Live Server extension

Install the *Live Server* extension by Ritwick Dey, then right-click `demo.html` → "Open with Live Server".

## How It Works

- **Self-Contained Bundle**: Svelte runtime, fonts, and styles are bundled into `game-client/game-client.js` + `game-client.css`. No external CDN dependencies.
- **Pack-Driven Theming**: All theme content (card backgrounds, cells, numbers, header, logos, splash artwork) is loaded at runtime from URLs supplied in the asset pack. Themes are 100% portable — same library, any visual identity. The library ships small chrome defaults (scratch brush mask, info/close icons) which packs can override by including the same role names; these are the only embedded image bytes (~3 KB total).
- **Mock Data**: Card and asset pack JSON are embedded inline in `demo.html`, so the demo itself doesn't need to fetch any mock JSON files (the runtime assets inside `game-client/` are still fetched normally).
- **Callbacks**: All 5 callbacks return mock data — swap these out for real API calls in your integration.

## Production Integration

Copy the entire `game-client/` directory to your webroot (or any subpath). The library auto-resolves its asset URLs from wherever you serve it — no path config needed.

### Vue 3 example

```vue
<script setup>
import { ref, onMounted } from 'vue';
import GameClient, { mount } from '/game-client/game-client.js';

const gameRef = ref(null);

onMounted(() => {
  mount(GameClient, {
    target: gameRef.value,
    props: {
      serial: 'CARD-001',
      onNewGame: async (serial) => {
        const res = await fetch(`/api/deal`);
        return await res.json(); // { token, asset_pack }
      },
      onPlay: async (serial, token) => {
        const res = await fetch(`/api/reveal/${serial}`, {
          headers: { 'Authorization': `Bearer ${token}` }
        });
        return await res.json(); // CardData
      },
      onComplete: async (serial, token) => {
        const res = await fetch(`/api/complete/${serial}`, {
          method: 'POST',
          headers: { 'Authorization': `Bearer ${token}` }
        });
        return await res.json();
      },
      onReady: async (serial) => console.log('Ready:', serial),
      onReveal: async (serial) => console.log('Reveal:', serial)
    }
  });
});
</script>

<template>
  <link rel="stylesheet" href="/game-client/game-client.css">
  <div ref="gameRef" style="width: 100vw; height: 100vh;"></div>
</template>
```

If your bundler can't import directly from a URL, copy `game-client/game-client.d.ts` into your TypeScript path and use a dynamic import or build-time alias. See `game-client/game-client.d.ts` for full types (`Props`, `CardData`, etc.).

### Path flexibility

Serve the directory at any URL — `/game-client/`, `/games/scratchcard/`, `/static/v2/sc/`. The library has no path dependencies; just point your `<script>`/`<link>` at the right files.

## Required Asset Pack Roles

The pack supplies all theme content. If any of the **required** roles is missing, the library renders an apology message instead of a half-themed card.

**Required (theme content — pack must supply):**
- **Card:** `card-unscratched`, `card-scratched`
- **Cells:** `cell-unscratched`, `cell-loss`, `cell-win`, `cell-major`, `cell-instant`
- **Numbers:** `number-unscratched`, `number-loss`, `number-win`, `number-major`

**Optional override (chrome — library ships defaults, pack can replace):**
- `brush-mask` — scratch brush shape
- `icon-info` — "?" how-to-play button
- `icon-x` — "×" close button

**Optional (no library default, just absent if not supplied):**
- `bg-image` (game-area background), `header`, `lockup-splash`, `logo-splash`, `logo-scratchee`, `logo-win`, `bonus-tile-*`, `how-to-play-*`, `prize-*`, etc.

## Files Included

### Library (`game-client/`)
- `game-client.js` — Minified library (Svelte runtime + components bundled)
- `game-client.css` — Styles + base64-inlined fonts (Inter, Archivo Black)
- `game-client.d.ts` + `index.d.ts` + `types/card.d.ts` — TypeScript definitions
- Additional chunks: `Scene-*.js`, `three.*.js`, `index-*.js`, etc. (loaded on demand)
- `645e83353a1ac.png`, `icon-info.png`, `icon-x.png` — chrome defaults (~3 KB total; packs override per-role if desired)

### Demo
- `demo.html` — Standalone demo (must be served over HTTP — see "How to Run")
- `DEMO-README.md` — This file
- `demo-assets/` — Reference mock JSON (for inspection; not used by `demo.html`)

**Total size:** ~12 MB uncompressed, ~4 MB gzipped

**Tip**: Check the browser console for detailed callback logs.