God of Sparrow 太歲 — Developer Wiki · single source of truth for contributors (human or LLM)

Design & Test Pages

Architecture

Golden Rules (do these EVERY session)

1. Backup before editing: copy sparrow.html → revisions/MMddyyyyHHmm.html.
2. Every save: update changelog.txt (top, newest first) and the in-game tutorial if gameplay changed.
3. Deploy with sync-once.ps1 (or tools/deploy.bat) — pushes game→index.html, audio, wiki, images/ + audio/music/ diffs to W:\sparrow and SFTP.
4. NEVER sync imagegen/ to the web, copy API keys out of ~/.claude/openai-config.json, or echo keys anywhere.
5. Use the Tailscale IP 100.122.243.71:5502 (not localhost) in anything shown to the user.
6. After regenerating data (charms/bosses/etc.), run tools/build-wiki.bat so the player wiki stays in sync.

Tools (tools/)

In-game QA hooks

• 🤖 Auto + 🧪 Stress buttons on the landing screen — bot plays/stress-tests the game.
• Cheat menu (top-right on landing): boss viewer, tile builder, sigil/edition application, seed control.
• Seeded runs: 5-digit seed input on Run Setup → deterministic RNG (RNG object) for repro cases.
• Console: window.G, window._validate, window._findAutoOptions are exposed for debugging.

Asset pipelines (local, zero-cost)

IMAGES  imagegen server (port 5511, gpt-image; NEVER deploy this folder) → PNG → images/
MUSIC   tools/gen_music.py → MusicGen-large (audiocraft venv, RTX 5090) → seamless-loop WAV → ffmpeg → audio/music/*.ogg
SFX     procedural in audio.js (no files needed) — audition via audio-test.html

Rebuild From Scratch — full tech-stack spec

If this codebase were lost, or you are a new developer/LLM with no access to prior sessions, this section + wiki-data.json (all game data) + images/ + audio/ is enough to rebuild the game.

1. Stack (deliberately boring)

Runtime      Vanilla HTML + CSS + ES2020 JS. ONE file: sparrow.html (~14k lines). No framework, no build step, no npm deps.
Audio        Web Audio API (audio.js): procedural SFX synth + <audio>-element music rooms w/ WebAudio gain crossfade.
Persistence  localStorage only: save blob (gos_save), unlocks, volumes (gos_vol/gos_musicvol/gos_sfxvol/gos_muted).
Rendering    Absolutely-positioned DOM divs on a 1280×720 virtual canvas, scaled by scaleGameRoot(); NO <canvas>.
Desktop      Electron wrapper (electron/) — loads the same files unmodified. Target: Steam Deck-class HW.
Server       Any static file server. MUST serve .ogg as audio/ogg + support Range requests (see serve-mahjong.js).

2. Source-of-truth data (all exported to wiki-data.json)

JOKER_POOL[144]      {id, icon, name(EN 中文), rarity C|U|R|L, cost, col, desc, fx(ctx)…, bane?}   charms
CONSUMABLE_POOL[66]  {id, icon, name, type gem|scroll|rune|spirit, cost, col, desc, apply(G)}
VOUCHER_POOL[31]     {id, icon, name, cost, tier, requires?, desc, effect flags}
WALL_TYPES[8]        decks: {id, icon, name, col, desc, reward, mod flags}     STAKE_TYPES[8] additive difficulty
EDITION_TYPES / SIGIL_TYPES                                                    BOSS_POOL[39] {id, icon, name, minAnte, descFn, effect flags} + portraits images/boss_<id>.webp
MJ_SUITS/MJ_HONOURS/MJ_FLOWERS  tile definitions   ANTE_BASE[8] score targets  BLIND_NAMES

3. Core algorithms (the 20% that is the game)

RNG        Mulberry32 seeded (RNG object) — EVERYTHING random flows through it so runs are seed-reproducible.
Deal       Wall = 4×(suits+honours)+flowers, minus wall-type removals; Fisher-Yates shuffle w/ RNG.
Validate   validate(meldTiles): Pung=3 identical · Kong=4 · Chow=3+ consecutive same suit · wilds adopt meld identity.
           GUARD: [].every() returns TRUE — every all-X check must test length>0 first (bit us: 1.2B exploit).
Scoring    eat = Σ(meld baseChips + tile enhancements) × (mult from fan 番 table + charms).
           Fan table: HK classics (碰碰糊+3, 混一色+3, 清一色+7, 字一色/清老頭 limit=20…); min-fan gate rises w/ ante.
Blinds     8 antes × (Small ×1.0 · Big ×1.5 · Boss ×2.0 target from ANTE_BASE, stake-scaled). Boss applies its effect flags.
Economy    reward = base + $1/unused draw + interest floor(gold/5) cap $5 (voucher-raisable); shop = 2 charms+3 items+1 voucher, reroll cost escalates.
Charms     fx(ctx) hooks fire at named phases (onScore, onDraw, perMeld, blindStart/End…). Neighbor charms read the
           charm ROW ORDER — order is a mechanic (drag-to-reorder).
Save       JSON blob of full run state incl. RNG cursor; save each blind end; NEEDS saveVersion guard (top 0.1 risk).

4. Rebuild order (tested path, ~7 milestones)

1 tiles+deal+hand UI → 2 meld validate+eat scoring w/ fan table → 3 blind loop+antes+gameover
4 shop+economy+consumables → 5 charm fx engine (phase hooks) → 6 bosses+stakes+editions/sigils
7 audio+saves+landing/setup UI. At each step: add a smoke-test assertion; keep bilingual EN/繁中 strings.

5. Asset regeneration (no hand art needed)

Item icons   tools/gen-icons.py (PIL) → images/ic_<id>.webp — 265 tile-style cards from wiki-data.json. Deterministic.
Boss art     imagegen server (gpt-image) — prompts per boss in BOSSES.md style: HK Teddyboy manhua portrait 560×840.
Titles       white brush lettering on black → alpha-key + tint + outline (scratchpad scripts in changelog Jul 4).
Music        tools/gen-music.bat [room] → MusicGen-large prompts per room (genre table in gen_music.py). 8 rooms.
Steam art    tools/make_steam_art.py from a master poster → 8 capsule sizes + electron icon.