# Newbury Nights — Ghost Roster (Phase 1 Data)

Standalone ghost-roster data + seed for the AR ghost-hunting loop. This is the
**data foundation** — no hunt logic yet. It builds a separate SQLite DB so it
doesn't touch the live app DB (the Free Hunt pool) until you choose to merge.

## Contents

| File | What it is |
|------|------------|
| `ghosts.json` | 111 ghosts: name, slug `id`, colour, rarity, pip stats, health/damage, `abilityId`, plus null placeholders for asset paths + AR stats |
| `abilities.json` | 36 abilities (17 Common + 19 Boss): charges, cooldown, effect |
| `locations.json` | AR-anchor stub (one generic plane). Extend with real sets in Phase 2/3 |
| `seed-ghosts.js` | `better-sqlite3` seed → builds `ghost-roster.db` |
| `verify.js` | Quick read-back / integrity check |

## Run

```bash
npm install better-sqlite3        # needs build-essential (already on hal-blackpearl)
node seed-ghosts.js               # writes ./ghost-roster.db
node verify.js                    # prints counts + sample joins
```

Re-runnable — the seed drops and rebuilds the `roster_*` tables each time.

## Schema (roster_* tables, namespaced)

- `roster_ghosts` — one row per ghost. PK = name slug (`nagging-nathan`).
- `roster_abilities` — PK = ability slug. `roster_ghosts.ability_id` → FK.
- `roster_locations` — AR anchors (plane / image-target / qr).
- `roster_ghost_locations` — many-to-many spawn affinity (wired in Phase 3).

## Decoded mapping (source of truth)

- **Rarity** ← `GhostRarity` enum: Common=1, Rare=2, Epic=3, Legendary=4.
- **Colour** ← `GhostColor` enum: Red, Blue, Yellow — drives the colour-wheel lure.
- **Pips** ← `UISpeedPips` / `UIRangePips` / `UIChargePips` (int 0–5).
- **health_max / damage_max** ← Digital Game stats (from the roster wiki).

## Placeholders to fill later

Per-ghost fields left `null`, filled from asset/data-table exports:

- `faceSprite`, `fullbodySprite`, `webmPath`, `webpPath` — **Phase 2** asset pipeline.
- `arHealth`, `hauntValue`, `isBoss` — from the **`ARGhostData` TextAsset** export.
- `locations[]` — from **`MetaGhostData.LocationsArray`**, set in Phase 3.

## Asset rights

Ghost assets/stats used under direct permission from the rights holder; app
delivery is original (web). LEGO and Hidden Side **logos are excluded**. Sets
used only as generic AR anchors/backdrops. See `PERMISSIONS.md` once the grant
doc is digitised. Not legal advice.