infrapuzzle/projects/sasch40/AGENTS.md

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. Dual Game Modes & Dynamic Chassis Layout (GameBoyFrame.vue)

• The Decision: The GameBoy physical controls (D-Pad and A/B action buttons) MUST dynamically hide and show based on the active game mode.
• Why: The game alternates between arcade mini-games (Jump & Run, Party Express) and point-and-click / visual-novel adventure scenes (Prologue, Tavern, Finale Certificate). Displaying a chunky D-Pad and large A/B buttons during dialogue or tavern exploration wastes mobile screen space and ruins immersion.
• The Rule:
  • Arcade Acts (currentAct === 'platformer' or 'party_express'):
    • Show the GameBoy D-Pad and A/B action buttons (arcade-layout).
    • Display the arcade HUD with Korken, Helles, and 135 BPM counter.
  • Adventure / Dialogue Acts (currentAct === 'intro', 'prologue', 'tavern', or 'finale'):
    • Hide the D-Pad and A/B buttons completely (adventure-layout).
    • Display a sleek mini bottom bar with current Korken, Helles, and an inventory drawer button („🎒 Beutel“).
    • On currentAct === 'finale', hide even the mini bar so the certificate occupies the full screen.

---

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:

     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 (e.g. [O] I have to tell you, the glow-wurst is excellent!) into the scene.
• The Rule:
  • public/assets/scenes/tavern.jpg: The bottom area is cleaned with a seamless dark oak wood beam and floor texture.
  • 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 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 banner title is centered (ctx.textAlign = 'center'), and the progress bar has symmetrical 24px padding.

---

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 in Party Express: 300 pts each.
  • Gstanzl duel victory: 1,500 pts.
  • Discovered secrets (Bridgerton dialogue, 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 (sound.ts)

• The Decision: All sound effects, fanfares, 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 SoundService 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. Cellar Trapdoor & Easter Egg Invisibility Pattern (TavernView.vue)

• The Decision: Secret hotspots (the cellar trapdoor .trapdoor-hotspot in the Schankraum leading to the VIP Hinterzimmer) must be 100% invisible initially.
• Why: An Easter egg marked with a glowing button or text badge is not a secret; it invites immediate trivial clicking.
• The Rule:
  • The button must render with transparent background, no border, no outline, no box shadow, no hover change, and no tooltip (:title="undefined").
  • Only upon the user's first click does it reveal the door icon, label itself „Luke zum Hinterraum“, play a celebratory fanfare, unlock the Easter egg in the game store (+500 points), and transition to the secret room.

---

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 Hinterraum“ 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 the panoramic bench.
  5. Geheimes VIP-Hinterzimmer: 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. Must always include a visible [✕] close button so players are never trapped.
  • Wildschwein-Schnick-Schnack-Schnuck: Best-of-3 tactical duel against NAT. Rules: 🐗 Keiler bricht 🌿 Dickicht, 🌿 Dickicht fängt 🏹 Lanze, 🏹 Lanze erlegt 🐗 Keiler. First to 2 points wins (+10 Korken, 1 Helles, wildschwein_meister achievement). Includes [✕] close button.

---

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:

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:

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.