# 🎳 Elf Bowling: Strikes Back (1999 Classic + 2027 3D Gauntlet)

![Elf Bowling: Strikes Back Hero Banner](./assets/images/hero-banner.jpg)

### 🎮 [Play Door 1: 1999 Classic](https://elf.npintech.com/) &nbsp;|&nbsp; 🚀 [Play Door 2: 2027 3D Gauntlet](https://elf.npintech.com/play-3d.html) &nbsp;|&nbsp; ✨ [AI Story Track](https://elf.npintech.com/story-track.html)

> **Zero build step / 100% static ESM (vendored Three.js r187 MIT) open-source Web & PWA reimagining of NStorm's viral 1998 North Pole arcade classic**—shipping **two distinct playable doors** in one static repo:
> - **🕹️ Door 1 ([`index.html`](./index.html)) — Authentic 1999 Classic (1999 HD Remaster):** Hand-painted North Pole Bowling Lodge backdrop (`lodge-backdrop-1999.jpg`) & chunky 3/4 rear-view Santa (`Big Nick`) vs. actively dodging union elves, 1999 sweeping red arrow, PG-13 mooning & pinsetter slapstick, lane critters, and the Windows 98 Excel Boss Key (`B`).
> - **🚀 Door 2 ([`play-3d.html`](./play-3d.html)) — 2027 WebGL2 Toy-Box 3D North Pole Gauntlet:** Instant-play GPU 3D vinyl-toy bowling powered by vendored Three.js r187 that morphs mid-run across *Sunlit 3-Lane North Pole Pavilion*, *Runaway Toy Ski-Jump*, and *Blizzard Sleigh Half-Pipe*—complete with cheering Spectator Elves, curved dotted aim beads, broadcast celebration stamps, *Balatro*-style Mutator Cards, `0.15x` Bullet-Time, Frame 10 Krampus Mech Boss, a **100-Elf Victory Lap Finale**, Daily Streak, and zero-backend **`?beat=Name:Score:Seed`** viral challenge links!
> - **🎙️ Hybrid Studio Audio:** Ships with **95 baked ElevenLabs v3 clips** (`59` `[audio tag]` taunts incl. 4 Big Nick Santa lines, `2` multi-speaker skits, `32` SFX v3 Foley effects, `2` composed music loops) with automatic 0 KB procedural Web Audio fallback.

[![License: MIT](https://img.shields.io/badge/License-MIT-10b981.svg)](./LICENSE)
[![Build Step: Zero](https://img.shields.io/badge/build_step-0_static_ESM-dc2626.svg)](./package.json)
[![Runtime: Pure ES Modules](https://img.shields.io/badge/ES_Modules-Three.js_r187_MIT-38bdf8.svg)](./js/vendor/)
[![PWA: Installable & Offline](https://img.shields.io/badge/PWA-Android_%26_Desktop-fbbf24.svg)](./manifest.webmanifest)

- 📊 **[Interactive Carbon AI Story Track (`story-track.html`)](./story-track.html)** — Live HTML5 `<canvas>` Multi-Agent Graph, Ice-Lane Hook Physics Sandbox, and Android Sensor Fusion Visualizer.
- 📐 **[2027 3D Architecture Blueprint (`vision-2027.html`)](./vision-2027.html)** — 4-panel visual infographic & WebGL2 architecture breakdown.
- 📖 **[Read the Engineering Narrative (`STORY_TRACK.md`)](./STORY_TRACK.md)** — How Gemini + Parallel Subagents researched, architected, illustrated, voiced, and built both doors with zero build step and 100% static ESM.

---

## ⚡ Quickstart, Testing & Cloudflare Deploy

Requires **Node.js 18+** (zero `npm install` needed!):

```bash
# Run locally (serves both Door 1 & Door 2 + prints LAN URL for mobile)
node server.mjs

# Run automated headless smoke & integration tests (v1 + v2)
npm test

# Deploy 100% static assets to Cloudflare (HTTPS unlocks Android Tilt + Swing sensors!)
npx wrangler deploy
```

> **Cloudflare Launch Tips:**
> - [`.assetsignore`](./.assetsignore) automatically blocks `.env`, `scripts/`, `tests/`, and `server.mjs` from uploading to Cloudflare's edge.
> - After your first deploy, swap the relative `./assets/images/og-card.jpg` in `og:image` across the 4 HTML files to your full `https://<your-domain>/assets/images/og-card.jpg` URL for guaranteed Slack/iMessage/X/LinkedIn previews, and toggle on free cookie-less **Cloudflare Web Analytics** in your dashboard!

Then open in your browser:
- **🕹️ Door 1 (1999 Classic):** `http://localhost:3000/index.html`
- **🚀 Door 2 (2027 3D Gauntlet):** `http://localhost:3000/play-3d.html`
- **✨ Interactive AI Story Track:** `http://localhost:3000/story-track.html`

---

## 🎮 Full Device & Controller Matrix

Every input device feeds into a single normalized `ThrowCommand` physics vector (`xPos`, `aimAngleDeg`, `speedMps`, `spinRadPerSec`), giving you identical dual-zone ice hook physics across both **Door 1 (1999 Classic)** and **Door 2 (2027 Toy-Box 3D Engine)**:

| Input Mode | How to Aim & Position | How to Throw & Apply Hook Spin | Special Perks |
| :--- | :--- | :--- | :--- |
| **🎯 Toy-Box 3D Unified Pull-Aim-Curve-Release Slingshot** *(Default in Door 2 `play-3d.html`)* | Drag anywhere on the lane (mouse or touch) to slide along the foul line and drag laterally to aim launch angle (`±10°`) along the live 3D curved dotted aim beads. | **Pull back** to charge power into the **88–95% Gold Sweet Spot**, dial hook spin via **Mouse Wheel / `Q`-`E` / 5-Pip Curve Bar (`↺↺ ↺ Straight ↻ ↻↻`)**, and **release** (or **upward snap-flick** for **+10% Overdrive**) to launch! | **Mid-Roll Aftertouch:** Drag or tap left/right while the ball glides down the ice for subtle mid-roll English steering, plus audio chime lock-in on the Gold Sweet Spot. |
| **🖱️ Mouse Flick** *(Optional Desktop / Touch in Door 1)* | Move cursor left/right along the foul line to position bowler. | Click & pull back slightly, then **flick forward** toward the pins. Forward speed sets ball velocity; lateral curve at release imparts hook spin! | Real-time curved trajectory preview ribbon. |
| **🎯 1999 Retro Oscillating Arrow** *(Default Desktop in Door 1)* | Click once to lock bowler board position on the ice. | Click a second time as the classic sweeping NStorm arrow oscillates across the lane (scroll wheel / `Q`-`E` / 5-Pip Curve Bar bends hook)! | Authentic 1998–1999 one-hand coffee-mug playability + visible curved arrow. |
| **⌨️ Keyboard + Body English / Aftertouch** | `A`/`D` or `←`/`→` to slide bowler; `Q`/`E` to angle aim guide; `Z`/`C` to pre-dial ornament hook spin across the **5-Pip Curve Bar**. | Hold `Space` (or `↑`) to charge the candy-cane Power Meter (hit the **88–95% Gold Sweet Spot**), release to hurl! | **Mid-Roll Aftertouch / Body English:** Tap `←`/`→` while the ball rolls down the ice to nudge spin ±5%! |
| **🎮 Gamepad (Xbox / DualSense / Switch)** | **Left Stick** slides bowler along the foul line; **`LB`/`RB`** adjust aim angle; **`LT`/`RT`** dial hook spin. | **Right Stick Down → Up** flick (or hold **`A`/`Cross`** to charge into the **88–95% Gold Sweet Spot** and release) bowls. | Dual-motor vibration rumble on release & Strike crashes. |
| **📱 Android Tilt + Swing ("Thumb-Hole Clutch")** | Tilt phone left/right (`DeviceOrientation` roll `γ` within `±25°`, `±3°` deadzone) + **1-Tap Recenter** button. | **Press & hold thumb** on the onscreen Thumb-Hole Clutch pad, swing arm forward in an underhand bowling arc, twist wrist for hook, and **lift thumb to release!** | Prevents phone drops; fuses 180ms `DeviceMotion` swing + gyro spin + `navigator.vibrate` haptics! |

### 📱 Setting Up Android Motion Sensors & Installing the PWA

Modern mobile browsers require a **Secure Context (`HTTPS` or `localhost`)** before granting `DeviceMotionEvent` and `DeviceOrientationEvent` sensor access. Pick any of these three zero-hassle ways to play with full motion controls on Android:

1. **USB Cable + `adb reverse` (Fastest Local Testing — Zero Certs Needed!):**
   Connect your Android phone with USB debugging enabled and map port `3000`:
   ```bash
   adb reverse tcp:3000 tcp:3000
   ```
   Now open `http://localhost:3000` in Chrome on your Android phone! Because Chrome treats `localhost` as a Secure Context, motion sensors, haptic rumble, and **"Add to Home Screen / Install App"** PWA installation all unlock immediately.
2. **GitHub Pages / Static HTTPS Hosting:**
   Push this repository to GitHub Pages, Netlify, Cloudflare Pages, or Vercel—zero build step required (publish root `./`). Opening the `https://` URL on Android unlocks sensors + full-screen standalone PWA installation.
3. **LAN Wi-Fi Play (Touch Flick Mode):**
   Visiting `http://<YOUR-LAN-IP>:3000` over plain HTTP automatically falls back cleanly to **Touch Drag/Flick Mode** if browser sensor APIs are restricted over unencrypted LAN.

---

## 🏆 Game Modes, Specialty Balls & 1999 Cubicle Features

### Bowler Roles & Game Modes
- **🎅 Classic Strike-Breaker Mode (1998 Canon):** Play as Santa Claus taking holiday revenge on 10 striking, picket-sign-waving, trash-talking Elf-pins (who occasionally panic-hop or sidestep incoming balls!).
- **🧝 Elf Toss / Roles-Reversed Mode:** Step onto the ice *as* an over-caffeinated Elf bowler heaving oversized holiday bowling balls with absurd tornado wind-ups and belly slides.
- **🐸 Critter Chaos & 1–4 Player Pass-and-Play:** Clip **Kalvin Kroaker** (Santa-hat frog) for bonus points, hit the **Ice Bunny's** slick speed patch (+25% velocity), or bank an errant gutterball off the **Peeking Reindeer's** antlers back onto the lane!

### 4 Physics-Tuned Holiday Bowling Balls
- **🍬 Candy Swirl (15 lb Balanced Pro):** Crisp, predictable hook transition from the 65% glazed front ice (`μ = 0.03`) onto the 35% frosted back deck (`μ = 0.19`).
- **🥮 40lb Fruitcake (Heavy Tank):** Shrugs off ice deflection (`0.48x` hook) and plows straight through sleeper pins with `1.65x` momentum carry.
- **🪩 Disco Ornament (11 lb High-Rev Curve Monster):** Extreme `1.55x` angular bite on the frosted pin deck—slice dramatic coast-to-coast hooks into the 1–3 pocket!
- **❄️ Avalanche Snowball (Growing Chaos Sphere):** Gathers frost as it rolls down the lane, expanding its collision radius by up to +28% before impact!

### Humor Toggle & The Iconic 1999 Boss Key
- **1999 Retro Spicy Mode (`PG-13` — Default) vs. Family-Friendly Cartoon (`PG` Toggle):** Launches in authentic late-90s NStorm **PG-13** mode with cheeky voice heckles, classic mooning taunts on gutterballs, slapstick mechanical pinsetter mishaps, and the **"Elf, Elf, Baby!"** dance break—or flip on the 1-click **PG** toggle anytime for family-friendly Looney-Tunes stars and snow puffs.
- **💼 Press `B` for the 1999 Boss Key:** Instantly mutes all audio and overlays a convincing **1999 Q4 Logistics & Supply-Chain Spreadsheet** so nobody in the next cubicle suspects a thing. Press `B` (or click **Resume Bowling**) to resume.

---

## 🗂️ Repository Structure

```text
elf-bowling-web/
├── index.html                 # Door 1: Authentic 1999 Classic arcade cabinet & HUD
├── play-3d.html               # Door 2: 2027 WebGL2 Toy-Box 3D North Pole Gauntlet
├── story-track.html           # Interactive Carbon AI Story Track (3 live <canvas> sandboxes)
├── vision-2027.html           # 2027 3D Architecture Blueprint & WebGL2 infographic
├── css/
│   ├── styles.css             # Door 1 North Pole arcade styling, CRT Jumbotron & Boss Key UI
│   └── v2-3d.css              # Door 2 Toy-Box 3D HUD, 5-Pip Curve Bar & Roguelite Card UI
├── js/                        # Static ES Modules (physics, controls, audio, 2D renderer)
│   ├── v2/                    # Door 2 Toy-Box 3D engine, Slingshot, Roguelite & Boss modules
│   └── vendor/                # Vendored Three.js r187 (MIT) for zero-build WebGL2 rendering
├── assets/
│   ├── audio/                 # Baked ElevenLabs v3 voices, dialogues, SFX v3, music & manifest.json
│   └── images/                # Custom AI-illustrated arcade banners, bowlers & Jumbotron art
├── scripts/                   # ElevenLabs v3 audio baker & asset tooling
├── tests/                     # Automated headless smoke & playtest suites (v1 + v2)
├── server.mjs                 # Static Node HTTP dev server + LAN & sensor headers
├── wrangler.jsonc             # Cloudflare Workers Static Assets deployment config
├── .assetsignore              # Excludes dev scripts, tests & .env from Cloudflare deploys
├── _headers                   # Security, COOP/COEP & cache headers for static edge hosting
├── manifest.webmanifest       # Standalone PWA manifest for Android & Desktop installation
├── sw.js                      # Network-first offline-capable Service Worker
├── PRD.md                     # Historical research & Product Requirements Document
├── STORY_TRACK.md             # 4-Act AI engineering & multi-agent orchestration narrative
├── package.json               # Static ESM manifest & test/deploy/audio scripts
└── LICENSE                    # MIT License
```

---

## 📦 Third-Party Attribution

- **[Three.js](https://threejs.org/) (`r187`, MIT License):** Vendored locally in [`js/vendor/`](./js/vendor/) so Door 2 (`play-3d.html`) runs as 100% static ES Modules with zero build step and zero external CDN requests. Full license terms are compatible with this project's MIT License.

---

## 📜 License & Historical Tribute

Released under the **[MIT License](./LICENSE)** (`Copyright (c) 2026 Open Source Contributors`).

*Elf Bowling: Strikes Back* is a clean-room open-source tribute inspired by the comedic spirit of the 1998 holiday shareware classic created by Dan Ferguson and Mike Bielinski at NVision Design / NStorm. All code, procedural audio synthesis, physics simulations, and custom illustrations in this repository are original open-source creations.
