# Mobile Animation Studio: Production Playbook

This playbook defines our studio's standardized 5-phase production framework for creating complete, tactile, animation-rich mobile games using autonomous coordinator and specialist subagents.

---

## 1. The 5-Phase Mobile Animation Lifecycle

Every mobile game in our studio is developed through five auditable phases. Each phase requires multi-agent review (Animation Director, Mobile UX Auditor, Performance QA) and an atomic Git commit.

```mermaid
flowchart TD
    P1["Phase 1: Mobile Viewport, High-DPI Canvas & Touch Spine"] --> P2["Phase 2: Procedural Kinematics & Animation Rig"]
    P2 --> P3["Phase 3: Adversarial Ecosystem & Touch Gameplay Loop"]
    P3 --> P4["Phase 4: Thumb-Zone Roguelite Draft & Progression"]
    P4 --> P5["Phase 5: Sensory WebAudio, Haptics & Mobile Juice"]
    P5 --> SHIP["Ship & Register in Mobile Device Simulator Launcher"]
```

---

### Phase 1: Mobile Viewport, High-DPI Canvas & Touch Spine
* **Objective:** Establish the bedrock mobile container, responsive scaling, safe areas, pointer gestures, and fixed-timestep clock.
* **Deliverables:**
  * Fixed 60Hz accumulator loop bounded against thermal frame spikes (`maxAccumulator = 0.2s`).
  * Canvas resize orchestrator:
    * High-DPI scaling with devicePixelRatio capped at `min(window.devicePixelRatio, 2.0)`.
    * Safe area insets (`env(safe-area-inset-top)`, `env(safe-area-inset-bottom)`) for notches and home bars.
    * Orientation detection (Portrait 9:16 or Landscape 16:9) with graceful responsive reflow.
  * Pointer event abstraction (`pointerdown`, `pointermove`, `pointerup`, `pointercancel`) with multi-touch tracking and deadzones.
  * Mobile CSS resets: `touch-action: none; user-select: none; -webkit-tap-highlight-color: transparent; overflow: hidden;`.

---

### Phase 2: Procedural Kinematics & Animation Rig
* **Objective:** Craft the core character or interactive object so that it feels intrinsically delightful to move and touch before any enemies exist.
* **Deliverables:**
  * Procedural animation system:
    * Squash & stretch deformation matrix ($S_x \times S_y \approx 1$) triggered by acceleration, launch velocity, and wall impact.
    * Damped harmonic spring physics for position, rotation, and elastic settling.
    * Secondary animation (wobbly eyes, trailing ribbons, reactive gelatinous contour, or ragdoll joints).
  * Tactile touch interaction:
    * Responsive drag, fling, slingshot, or virtual joystick mechanics.
    * Predictive trajectory or intent lookahead visualization.
    * Kinesthetic release response (elastic snap, kinetic boost, recoil).

---

### Phase 3: Adversarial Ecosystem & Touch Gameplay Loop
* **Objective:** Introduce animated threats, responsive obstacles, and escalations tailored for mobile screens.
* **Deliverables:**
  * 3–4 hostile archetypes with distinct animation profiles:
    * **Telegraphed Spawn:** Flash / scale-up anticipation before becoming lethal.
    * **Impact Reaction:** Distinct stagger, color flash, and directional squash when struck.
    * **Death Dissolve / Shatter:** Visceral kinetic explosion into bouncing shards.
  * Mobile collision resolution and boundary bounce physics.
  * Dynamic wave director scaling intensity over survival time or distance milestones.

---

### Phase 4: Thumb-Zone Roguelite Draft & Progression
* **Objective:** Build an addictive reward cycle and upgrade tree designed for one-handed mobile grip ergonomics.
* **Deliverables:**
  * Resource drop collection:
    * Kinetic pop on enemy defeat with magnetic curved arc towards the player avatar.
  * Level-up trigger and pause transition with spring-damped ease-in.
  * Bottom-drawer 3-card upgrade draft modal:
    * Positioned within the natural lower thumb reach zone.
    * Minimum card touch height of 56px with generous tap padding.
    * 10–12 synergistic perks across distinct trees (e.g., Elasticity, Shockwave, Piercing, Mitosis) + Capstone synergy.
    * Smooth card entry cascade with staggered spring bounce.

---

### Phase 5: Sensory WebAudio, Haptics & Mobile Juice
* **Objective:** Layer on sensory richness that makes every touch vibrate and sing without external asset downloads.
* **Deliverables:**
  * Pure procedural WebAudio synthesizer:
    * Mobile audio context unlock on the very first touch gesture (`pointerdown`).
    * Dynamic sound design: juicy squishes, kinetic snaps, crystalline combo arpeggios, and lowpass sweep on slow-mo.
    * Ephemeral voice garbage collection (`osc.onended = () => { osc.disconnect(); gain.disconnect(); }`).
  * Mobile Haptic Engine:
    * `navigator.vibrate` integration with fallback checks.
    * Distinct vibration patterns: Light tap (`15ms`), Sling release (`25ms`), Hard impact (`[35, 20, 35]`), Level-up buzz (`[50, 40, 80]`).
  * Mobile visual juice:
    * Quadratic trauma-squared screen shake ($T^2$) with an accessibility slider (0%–150%).
    * Floating kinetic combat text popups ($< 30$ active max).
    * Bounded particle pools with velocity decay.
  * Focus safety:
    * Auto-pause on `document.visibilitychange` or `window.blur`.
    * Pointer release flushing on tab switch.

---

## 2. Fast Scaffolding of a New Mobile Title

To create a new game in this studio:

1. **Run the Scaffolding Script:**
   ```bash
   ./scripts/new-game.sh <slug> "<Game Title>"
   ```
2. **Review Scaffolding Files:**
   * `games/<slug>/index.html`
   * `games/<slug>/PLAN.md`
   * `games/<slug>/README.md`
   * `games/<slug>/src/`
3. **Register in Manifest:**
   * Automatically registered in `launcher/games-registry.js` and `GAMES.md`.
4. **Execute Phases 1 through 5:**
   * Work strictly inside `games/<slug>/`.
   * Reference `LESSONS_LEARNED.md` for mobile formulas and WebAudio recipes.