# AGENTS.md — Saschas Kronkorken Kreuzzug (sasch40)

> [!NOTE]
> **Domain**: Mobile-first 2.5D retro birthday adventure game for King Sascha I.'s 40th jubilee.  
> **Live Production URL**: `https://sasch40.haumdaucher.de`  
> **Kubernetes Manifest**: `k8s/web/sasch40.yaml` (Namespace: `web`)  
> **Source Code**: `projects/sasch40/frontend/`  
> **Reference Photos**: `projects/sasch40/source_photos/`

---

## 🏛️ Architectural Decisions & Non-Negotiable Rules

This document records the foundational design decisions, their rationale ("Why"), and constraints for future AI coding agents. **Do not regress or remove these patterns.**

### 1. QR-Code Landing & Atmospheric Prequel (`IntroScreen.vue`)
*   **The Decision**: The application MUST ALWAYS start with an informative, atmospheric intro/lore screen before any gameplay begins.
*   **Why**: Party guests scan a physical QR code on beer bottles or tables with their smartphones. They do not know what the link opens. Without an introductory landing page, users are confused when suddenly dropped into an arcade mini-game.
*   **Content Requirements**:
    *   Title: *„Saschas Kronkorken Kreuzzug: 40 Jahre Bass & Gerstensaft“*.
    *   Royal Avatar: King Sascha I. with sunglasses and golden crown.
    *   Lore: Explains the 40-year reign over Haumdaucher, 135 BPM techno culture, the theft of the 40 sacred Kronkorken, and a preview of the upcoming acts.
    *   CTA: Prominent button *„SPIEL STARTEN / RETTE DAS JUBILÄUM!“*.
    *   Audio prompt: *„Smartphone-Lautstärke aufdrehen für echten 135-BPM-Mittelalter-Techno!“*.

---

### 2. Full-Screen Mobile-First Web App (`GameBoyFrame.vue`)
*   **The Decision**: The GameBoy bezel chassis, D-Pad, and external A/B action buttons have been completely removed across the entire application in favor of a 100% full-screen responsive mobile layout.
*   **Why**: Mobile players interact directly with high-fidelity touch controls on modern smartphone screens. Virtual GameBoy bezels and D-Pads wasted over 40% of the viewport and degraded playability in arcade and visual-novel acts.
*   **The Rule**:
    *   The app container fills 100% of viewport height and width.
    *   **Header**: Line 1 displays `KÖNIG SASCHAS KRONKORKENKREUZZUG`, Line 2 displays the act badge (e.g. `AKT III`). The right side displays inventory counts (`👑`, `🍻`) and the persistent `⚙️` settings icon.
    *   **Controls**: Act II uses tap/touch screen halves (`left`/`right`) or arrow keys; Act IV uses full-width on-screen highway strum buttons (`[D LINKS]`, `[G MITTE]`, `[A RECHTS]`).


---

### 2b. Global Settings & Audio Control Modal (`GameBoyFrame.vue`)
*   **The Decision**: A persistent `⚙️` settings icon is available at the top-right of the GameBoy frame.
*   **Why**: Mobile players need a straightforward way to mute sound in public, pause during conversations, or cleanly restart the adventure.
*   **The Rule**: Clicking `⚙️` opens a modal that pauses game loops, provides toggleable audio (`🔊 Sound: AN / 🔇 Sound: AUS`), and offers a `🔄 Spielstand zurücksetzen` option with safety confirmation.

---

### 2c. Prologue Branching & Themed Game Overs (`PrologueView.vue`)
*   **The Decision**: Prologue choices can trigger humorous non-fatal Game Over screens with themed reset actions:
    *   🔥 **Flo Maier (*Feierdeifl*)**: Choosing to burn the castle leads to a fiery castle inferno and a `🚒 MIT DEM LÖSCHZUG NEU STARTEN` button.
    *   🧛 **Viktor (*Partyvampir*)**: Choosing the vampire bite turns Sascha into dust at sunrise and provides a `🧄 MIT KNOBLAUCH-KUR NEU STARTEN` button.
*   **Why**: Gives playful branching flavor without permanently penalizing the player.

---

### 2d. Akt II: Doodle Jump Schwesternrettung (`PlatformerView.vue`)
*   **The Decision**: Act II is a bottom-to-top vertical bouncing climber across 3 progressive levels to rescue King Sascha's three sisters:
    1.  **Level 1**: Rescue **Saskia** (+3 Kronkorken, 1 Helles)
    2.  **Level 2**: Rescue **Maja** (+3 Kronkorken, 1 Helles)
    3.  **Level 3**: Rescue **Miriam** (+4 Kronkorken, 1 Helles)
*   **Mechanics**:
    *   Continuous automatic upward bouncing upon landing on platforms.
    *   Spring platforms (`🌀`) for high-velocity boost with custom synthesizer audio.
    *   Seamless screen wrap-around (moving off the left edge wraps to the right and vice versa).
    *   Gentle fall protection: falling below the visible screen softly places Sascha onto a safe platform near his lower altitude rather than triggering a punitive death.

---

### 2e. Akt III: Raum „Hinter den Bergen“ & Liar's Dice (`TavernView.vue`)
*   **The Decision**: Akt III features a special mountain hideaway scene *„Hinter den Bergen“* accessible via Hinterland signpost or tab bar.
*   **Why**: Introduces Saschas father Papa Markus and his Taiwanese connection with Gaoliang drinking culture into the anniversary narrative.
*   **Mechanics**:
    *   Papa Markus sits at a table with 6 Taiwanese friends in an alpine valley nested with Taiwanese/Tokyo skyscrapers.
    *   Minigame **Liar's Dice (Chui Niu / 吹牛)**: 5 dice each, 1s are wild, sequential bidding, bluff-calling reveals, loser drinks a 58% Kinmen Gaoliang shot (`🍶`).
    *   Rewards: +10 Kronkorken, inventory item *58% Kinmen Gaoliang*, Easter Egg title `taiwan_dice_champion`.

---

### 2f. Akt IV: Beat-Only Metronom & Harmonische Lautenakkorde (`PartyExpressView.vue` & `synthAudio.ts`)
*   **The Decision**: During the Castle Stage rock concert in Act IV, the synthesizer BGM switches to `beat_only` mode (melody muted, playing solely the 135-BPM kick/hi-hat rhythm).
*   **Why**: Playing a rhythm game while a pre-recorded synthesizer melody plays in parallel creates cacophony and ruins the illusion that the player's notes compose the music.
*   **The Rule**: Successful hits on D, G, A trigger full 3-note harmonic medieval chords; misses trigger a muted plink. On act completion or exit, BGM restores to `full`.

---

### 3. Protagonist System & Extensibility (`characters.ts`)
*   **The Decision**: All character portraits are strictly 1:1 square pixel-art illustrations based directly on real-life friends and family photos, maintained in a centralized registry.
*   **Why**: Guests at the party must immediately recognize themselves and their friends. Previous attempts at generic AI portraits caused confusion because hair, beards, and styles did not match the actual people.
*   **Reference Photos**:
    *   Stored in `projects/sasch40/source_photos/` (`sascha_*.jpg`, `nat.jpg`, `lutz*.jpg`, `amelie.jpg`, `armend.jpg`, `moritz2.jpg`, etc.).
*   **In-Game Portraits**:
    *   Stored in `projects/sasch40/frontend/public/assets/characters/<id>/portrait.png`.
*   **How to Add or Modify Protagonists**:
    1.  Add a 1:1 square pixel-art portrait into `public/assets/characters/<id>/portrait.png`.
    2.  Register the protagonist in `projects/sasch40/frontend/src/config/characters.ts`:
        ```typescript
        export const CHARACTERS: Record<string, CharacterConfig> = {
          neuer_gast: {
            id: 'neuer_gast',
            name: 'Name (Spitzname)',
            title: 'Königlicher Hof-Titel',
            portrait: '/assets/characters/neuer_gast/portrait.png',
            quote: 'Charakteristischer Spruch'
          }
        }
        ```
    3.  Add an interactive hotspot or convoy sprite in `TavernView.vue` or `PartyExpressView.vue`.
*   **Portrait Display Rule**: Always use `aspect-ratio: 1 / 1` and `object-fit: cover` with rounded borders (`border-radius: 8px` or `50%` for badges). Never allow portrait stretching or horizontal letterboxing.

---

### 4. Background Art Integrity & Cleanliness
*   **The Decision**: Background scenes must remain clean of any AI-hallucinated pseudo-English text or stray UI elements.
*   **Why**: AI image generators often bake random adventure-game dialogue boxes or text into the scene.
*   **The Rule**:
    *   `public/assets/scenes/schankraum_v3.jpg`: Seamless warm dark oak wood floorboards with natural planks.
    *   Any scene footer navigation (like `.scene-bottom-nav`) must be styled as natural wooden wainscoting with clear German labels.

---

### 5. Mobile Canvas Safe-Zones & Responsive HUDs
*   **The Decision**: Critical game HUD elements (score, act title, instructions) must either be drawn as HTML/CSS overlays or placed within a minimum safe margin of 24px on canvas.
*   **Why**: Smartphones vary widely in screen aspect ratio (16:9, 19.5:9, 20:9). When a 360x480 canvas is rendered with `object-fit: cover`, the left and right (or top and bottom) edges can be cropped by 10–25px on narrow screens.
*   **The Rule**:
    *   In `PlatformerView.vue`: The Korken counter, sister progress, and level title are rendered via an absolute HTML overlay (`.platformer-hud-top`) so they are 100% immune to canvas cropping.
    *   In `PartyExpressView.vue`: The 3-lane strings, score counter, combo meter, and crowd meter use responsive percentages.

---

### 6. Royal Certificate & Competitive Highscore (`CertificateModal.vue`)
*   **The Decision**: The game concludes with a royal certificate featuring a competitive point breakdown and rank.
*   **Why**: Party guests compare scores at the bar to determine who is the ultimate party knight.
*   **Score Breakdown**:
    *   Kronkorken collected: `100 pts` each.
    *   Helles tapped: `250 pts` each.
    *   Guests served / Concert performance: up to `3,000 pts`.
    *   Gstanzl duel victory: `1,500 pts`.
    *   Discovered secrets (Bridgerton dialogue, Party Bunker, Zuluman mirror): `500 pts` each.
*   **Ranks**:
    *   `S-Rang (Legendär)`: >= 11,000 points (*„Unsterblicher Großfürst des Basses“*).
    *   `A-Rang (Erhaben)`: >= 9,500 points (*„Meister-Brauer der königlichen Garde“*).
    *   `B-Rang (Ritterlich)`: >= 7,500 points (*„Ehren-Ritter der Hopfen-Manufaktur“*).
    *   `C-Rang (Trinkfest)`: < 7,500 points (*„Kneipen-Knappe im Ausnüchterungs-Dienst“*).
*   **Call-to-Action**: Includes a screenshot / print button (*„📸 URKUNDE DRUCKEN / SCREENSHOT“*) and Queen Verena's secret postscript.

---

### 7. Zero-Dependency Web Audio Synthesizer (`synthAudio.ts`)
*   **The Decision**: All sound effects, fanfares, lute chords, and the 135 BPM techno bassline are synthesized in pure code using the Web Audio API.
*   **Why**: External audio files (.mp3/.wav) take megabytes of bandwidth, stutter on mobile cellular networks, and trigger browser autoplay blocks.
*   **The Rule**: The audio context initializes on the first user interaction (touch/click). Sound effects use oscillators and gain envelopes; 135 BPM kick and sub-bass use recurring periodic intervals.

---

### 8. Unhashed Asset Cache Invalidation (`nginx.conf`)
*   **The Decision**: Unhashed static files (`/assets/scenes/*.jpg`, `/assets/characters/*/*.jpg`) MUST be served with `Cache-Control: "no-cache, no-store, must-revalidate"` and `Expires: -1`.
*   **Why**: In mobile browsers (Safari iOS, Chrome Mobile), default caching headers (`expires 30d`) cause updated character portraits and scene backgrounds to remain stale for weeks on user devices.
*   **The Rule**: In `nginx.conf`, static media matches `\.(png|jpg|jpeg|gif|ico|svg|webp|mp3|wav|ogg)$` with `no-cache, no-store, must-revalidate`. Bundled JS/CSS matches `\.(js|css)$` with `public, immutable` for 1 year.

---

### 9. Party Bunker Trapdoor & Double-Tap Pattern (`TavernView.vue`)
*   **The Decision**: Secret trapdoor (`.trapdoor-hotspot` in Schankraum leading to the VIP Party Bunker) must be 100% invisible initially and requires a deliberate double-click or double-tap to unlock.
*   **Why**: A single accidental click on the floor should not whisk the player away into an Easter Egg bunker before they explore the tavern.
*   **The Rule**:
    *   Rendered with transparent background, no border, no outline, no box shadow, no hover change, and no tooltip (`:title="undefined"`).
    *   Double-click/double-tap detection combines `@dblclick` and timestamp delta (`now - lastTrapTap < 450ms`) to work flawlessly across desktop and mobile touchscreens.
    *   Upon double-tap, it reveals the wood trapdoor sprite, labels itself *„Luke zum Party Bunker“*, plays a celebratory fanfare, unlocks the Easter egg in the game store (+500 points), and transitions to the Party Bunker.

---

### 10. Multi-Room World Architecture & Tavern Minigames (`TavernView.vue`)
*   **The Decision**: Act III is structured as a spatial, interconnected five-room village hub rather than a cramped single screen:
    1.  **Gaststube (Schankraum)**: King Sascha's table, Queen Verena on the balcony, Armend at the forge, Lutz (ZTUL) at the fireplace, door to Nebenraum, door to Marktplatz, and the secret *„Luke zum Party Bunker“* in the floor.
    2.  **Königlicher Nebenraum (Kemenate & Atelier)**: Amy painting the royal *„Rave the Kingdom!“* banner at her easel in overalls, and the golden Zuluman magic mirror on the wall.
    3.  **Haumdaucher Marktplatz**: Mario acrobatically juggling chainsaws and hops on the cobblestones; NAT (Josef) on the wooden festival stage with wild boar banners telling stories of his girls and heroic deeds.
    4.  **Alpines Hinterland**: Mane (Ramona) hiking the alpine trail with walking stick; Hansi on his departure journey towards Münchanien.
    5.  **Geheimes VIP-Party-Bunker**: Secret rave with disco chandelier, stroboscope, Pü's crystal staff, DJ Flo Maier, and Viktor the night-guard.
*   **Minigames & Exit Safety**:
    *   **Bayerisches Gstanzl-Fechten**: Multi-round insult rhyming duel. Preceded by an explanatory rules modal. Must always include a visible `[✕]` close button so players are never trapped.
    *   **Wildschwein-Schnick-Schnack-Schnuck**: Best-of-3 tactical duel against NAT. Preceded by an explanatory rules modal (🐗 Keiler bricht 🌿 Dickicht, 🌿 Dickicht fängt 🏹 Lanze, 🏹 Lanze erlegt 🐗 Keiler). Includes `[✕]` close button and active button blur to prevent mobile sticky hover states.

---

### 10b. Akt IV: Mittelalter Guitar Hero — Hansis Abschiedskonzert (`PartyExpressView.vue`)
*   **The Decision**: Act IV is a 3-lane medieval lute rhythm game set on an epic castle festival stage in front of 12,000 cheering fans.
*   **Why**: Perfectly bridges the story from Hansi's departure in the Hinterland to a grand musical send-off before the royal coronation.
*   **The Rule**:
    *   3 color-coded lanes (`🔴 Saite 1`, `🟡 Saite 2`, `🔵 Saite 3`).
    *   Notes spawn synchronized to 135 BPM audio clicks and melodic riffs.
    *   Three large, finger-friendly touch buttons positioned comfortably at the lower screen for thumb play.
    *   Combo multiplier increases up to 4x with unbroken streaks.
    *   Generous hit window for fun, non-punishing festival gameplay.

---

### 11. LocalStorage Persistence & Clean Game Reset (`gameStore.ts`)
*   **The Decision**: Game state automatically synchronizes to `localStorage` (`sasch40_game_save_v1`) on every mutation and is cleanly wiped when clicking *„🔄 NOCHMAL SPIELEN“*.
*   **Why**: Mobile users frequently refresh or switch apps to snap photos. Without persistence, a browser reload resets their progress back to Act I.
*   **The Rule**:
    *   `useGameStore` automatically initializes from `localStorage` if valid data exists.
    *   `store.$subscribe` writes the state to `localStorage` whenever any value changes.
    *   `resetGame()` clears `localStorage.removeItem(...)`, sets all stats to zero, and returns to the Prequel Intro.

---

## 🛠️ Build, Test & Deployment Workflow

### Fast Docker Packaging (Local ARM64 Compile)
To avoid 10-minute QEMU emulation hangs when building `linux/amd64` images on Apple Silicon Macs, the frontend is compiled locally on the host machine before Docker copies the static output:

```bash
cd projects/sasch40/frontend

# 1. Compile natively (< 2 seconds)
npm run build

# 2. Package, push & deploy to k8s (< 10 seconds total)
make all
```

The `Makefile` targets:
*   `compile`: Runs `npm run build` (`vue-tsc -b && vite build`).
*   `build`: Runs `docker build --no-cache --platform linux/amd64 -t sasch40:latest .` (copies `dist/` directly into `nginx:alpine`).
*   `tag`: Tags as `registry.haumdaucher.de/sasch40:latest`.
*   `push`: Pushes to the Haumdaucher registry.
*   `deploy`: Executes `kubectl rollout restart deployment/sasch40 -n web` and monitors rollout status.

---

### Automated Headless Chrome Playtest
Before considering any change complete, run the automated Puppeteer playtest script:

```bash
cd projects/sasch40/frontend
node scripts/playtest.mjs
```

This script:
1.  Navigates to `https://sasch40.haumdaucher.de`.
2.  Verifies the Intro Screen and clicks Start.
3.  Simulates dialogue options on the Castle Balcony (Prologue).
4.  Tests movement and jump controls in Act II (Hopfen-Pfade).
5.  Interacts with all 5 rooms, hotspots, dialogue modals, Zuluman mirror, Luke zum Hinterraum, Gstanzl duel, and the Wildschwein duel in Act III (Taverne).
6.  Tests reload persistence in `localStorage`.
7.  Advances through the Party Express (Act IV) and reaches the Royal Certificate (Act V).
8.  Tests the `🔄 NOCHMAL SPIELEN` button and verifies return to Intro.
9.  Captures 25 screenshots to verify zero visual regressions.
10. Asserts zero console errors, zero failed HTTP requests, and zero broken images.