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

npm install
npm run dev          # localhost:5173

Build & checks

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
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 — toolchain vulnerabilities, плановые апгрейды, текущие game-side caveats
• 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.