# Pinball-Duel

Single-player пинбол vs 4 AI-личности (head-to-head формат, Williams Joust 1983).

**Stack:** Phaser 4 (beta) + TypeScript + Vite + Matter.js (bundled). Capacitor добавляется в Phase 1.5.

**Platforms:**
- **MVP:** Yandex Games (web only)
- **Phase 1.5** (post-MVP-launch): Google Play + RuStore (Android, через Capacitor)
- **Post-Phase 2:** iOS (если PMF подтвердится)

**Status:** Phase 0 (pre-production) в процессе. Концепт-пакет — `~/Knowledge/Projects/pinball-duel/` (19 файлов, 10 audit-раундов).

## Development

### Requirements
- Node.js 20+
- npm

### Setup
```bash
npm install
npm run dev          # localhost:5173
```

### Build & checks
```bash
npm run build        # type-check + production build → dist/
npm run preview      # serve build locally
npm run typecheck    # tsc --noEmit
npm run lint         # ESLint
npm run test         # Vitest
```

## Architecture

### Game stack
- **Phaser 4** — game engine + Matter.js physics (bundled)
- **TypeScript strict** — все типы из `src/types/index.ts` (схемы из data-contracts.md)
- **Vite** — bundler + dev server (с `base: './'` для YG)

### Platform Adapter
Game-код не знает о платформе через `PlatformAdapter` interface (`src/platform/`). Реализации:
- `MockPlatformAdapter` — local dev и unit tests
- `YgPlatformAdapter` — Yandex Games SDK (MVP)
- `CapacitorAdmobAdapter` — Phase 1.5 (Play)
- `RuStorePlatformAdapter` — Phase 1.5 (RuStore)

Detection и factory в `PlatformAdapter.ts::createPlatformAdapter()`.

### Структура папок
```
src/
  config/      Remote Config defaults, палитра, константы
  types/       SaveState, MatchResult, RemoteConfig, etc.
  platform/    PlatformAdapter interface + 4 реализации
  scenes/      Phaser scenes (Boot, Preload, MainMenu, Setup, Match, Result)
  game/        Game objects (Ball, Flipper, Bumper, Table, Match orchestration)
  ai/          AI personalities (Defensive, Aggressive, Trickster, Ghost) + heuristics
  scoring/     calculateScores + MatchTracker (defensive setup scoring + bumper points)
```

### Фазовый план
| Phase | Содержание |
|---|---|
| **0** (✅) | Vite + Phaser 4 + TS boilerplate; Platform Adapter |
| **1** (✅) | Core mechanics: матч, флипперы, мяч, last-touch, fixed bumpers, Defensive Easy AI |
| **2** (✅) | Setup-фаза, 4 BumperType, 4 AI-личности × 3 сложности |
| **3** (✅ partial, sprint-mode) | Бустер «Захват» player-side, Hard difficulty (config-driven), cloud-save, 15 achievements. AI cradle + Ghost adaptation вынесены в backlog — см. [`KNOWN_ISSUES.md`](./KNOWN_ISSUES.md) |
| **4** | Campaign + Tournament + визуальный polish (шейдеры), ассеты |
| **5** | YG SDK ads + payments + Remote Config |
| **6** | YG polish + submission + soft launch |
| **1.5** (post-MVP launch) | Capacitor: Google Play + RuStore mobile native |

## Operational docs (в репо)

- [`KNOWN_ISSUES.md`](./KNOWN_ISSUES.md) — toolchain vulnerabilities, плановые апгрейды, текущие game-side caveats
- [`playtest-protocol.md`](./playtest-protocol.md) — спека blind-attribution тестирования AI-личностей для закрытия Phase 2 DoD

## Документация (концепт-пакет)

`~/Knowledge/Projects/pinball-duel/` — 19 файлов:
- `index.md` — overview + decision-history (10 audit-раундов)
- `concepts/scope-lock.md` — что в каждой фазе (single source of truth)
- `concepts/data-contracts.md` — все schema'ы (Remote Config, MatchResult, SaveState, leaderboard formula)
- `concepts/definition-of-done.md` — DoD per фаза
- `concepts/telemetry-spec.md` — event map
- `concepts/development-roadmap.md` — план разработки
- `concepts/monetization.md` — IAP + Anti-A2W правило
- `concepts/bot-ai-design.md` — 4 AI-личности
- `player-guide.md` — narrative-руководство игрока

## License
Proprietary, all rights reserved.