# Feature: Квантик — Законы Мира (образовательная 2D-игра)

**Branch:** `feature/quantik-game`
**Base branch:** `feature/sim-builder` (движок P1–P3 и фазы sim-builder ещё не в master)
**Created:** 2026-06-13
**Status:** 🟡 In Progress
**Strategy:** Incremental
**Mode:** Automated
**Execution:** Orchestrator

## Summary
2D физика-головоломка-платформер поверх движка **SimForge** (`_sim_engine.js`). Герой —
**Квантик** (существующий питомец `PetSprite`): в уровне он светящаяся точка с glow и
кометной трассой (P2), на карте/в диалогах — SVG-блоб `PetSprite.render`. Игрок не рулит
героем напрямую, а **чинит «закон мира»**: задаёт скорость/угол/гравитацию (физ-уровни на
`SimPhysics`), собирает `f(x)` для движения по кривой (граф-уровни на `plot`/`SimExpr`),
открывает «ворота» уравниванием реакций/дробей. **Условие победы — булев блок `goal`
(SimExpr) в спеке** — это «атом», переиспользуемый всеми типами уровней.

Уровень = спека SimForge + блок `game/goal` → авторится в sim-builder, хранится в
`custom_sims`, открывается тем же конвейером, что и обычные симуляции. Всё новое —
**аддитивно и безопасно** (без `eval`/`Function`; нет блока `goal` → движок ведёт себя
как раньше).

Мета-слой: карта-созвездие, XP/скины Квантика, разблокировка по звёздам, класс-лидерборд
через classroom SSE. Квантовые способности: суперпозиция, коллапс/пауза, туннелирование
(энергия из быстрого SR-повторения флешкарт).

**MVP играбелен после Фазы 2.**

## Build & Test Commands
- **Build:** нет (vanilla JS, без бандлера; статика через Express)
- **Test:** `npm test` в `backend/` (`node --test tests/*.test.js`)
- **Lint:** `npm run lint:routes` в `backend/`
- ⚠️ После роутов/миграций: `npm run migrate` (живая БД `backend/data/learnspace.db`) + рестарт сервера.
- ⚠️ baseline: 3 pre-existing fail (`auth.test.js` — bcrypt/JWT в тест-окружении) + 5 page-тестов (`jsdom` не установлен). Хук толерантен.

## Project Constraints (соблюдают ВСЕ агенты)
- ⛔ Никаких эмодзи в коде — только inline SVG `.ic`.
- ⛔ Никакого `eval`/`new Function`. Выражения — ТОЛЬКО через `SimExpr` (безопасный парсер).
- Поиск по коду: `ast-index` (символы/usages/callers) + `vex` (semantic). НЕ Grep tool.
- БД — встроенный `node:sqlite` (`DatabaseSync`), НЕ better-sqlite3.
- Frontend — vanilla JS, `window.LS.*` (js/api.js), без бандлера.
- Стейджить файлы **поимённо** (НЕ `git add -A` — в репо много мусорных untracked + чужой WIP sim-builder).
- Аддитивность: новые блоки/типы в спеке не ломают существующие симуляции и каталог.
- Ассеты: база — in-house (PetSprite + canvas/SVG + встроенный FLUX `/api/imggen`).
  Разрешены внешние **CC0/открытые** ассеты (звук/арт) с указанием источника/лицензии.

## Reuse Map (что переиспользуем)
- `frontend/js/labs/_sim_engine.js` — рантайм (SimPhysics, plot, glow/trails, zoom/pan, drag).
- `frontend/js/labs/_sim_expr.js` — `SimExpr.compile/evalSafe` для `goal`/`stars`.
- `frontend/js/pet-sprite.js` — `PetSprite.render(...)` Квантик + палитры → скины/нарратор.
- `custom_sims` + `customSimController.validateSpec` — хранение уровней + серверный гейт.
- `sim-builder.html`/`sim-builder.js` — авторинг уровней (Фаза 5).
- Флешкарты Tier-1 SR (мигр.074) — энергия туннелирования (Фаза 4).
- classroom SSE + мост `sim_state`/`apply_sim_state` (Ф7 sim-builder) — живая гонка (Фаза 6).
- Паттерн раздачи классу + `pushNotif` + `lab_sim_links` (Ф6 sim-builder).

## Phases

- [x] Phase 0: Слой целей в движке (goal/HUD/result) [domain: frontend] → [subplan](./phase-0-objective-layer.md)
- [x] Phase 1: Оболочка игры + 1 физ-уровень + прогресс [domain: fullstack] → [subplan](./phase-1-shell-first-level.md)
- [x] Phase 2: Карта-созвездие + мир физ-уровней + XP/скины [domain: fullstack] → [subplan](./phase-2-map-world-xp.md)
- [ ] Phase 3: Граф-уровни (движение по f(x)) + зоны-препятствия [domain: fullstack] → [subplan](./phase-3-graph-levels.md)
- [ ] Phase 4: Квантовые способности + SR-комнаты [domain: fullstack] → [subplan](./phase-4-quantum-abilities-sr.md)
- [ ] Phase 5: Авторинг уровней в sim-builder + раздача классу [domain: fullstack] → [subplan](./phase-5-authoring-sharing.md)
- [ ] Phase 6: Класс-лидерборд / живая гонка (classroom SSE) [domain: fullstack] → [subplan](./phase-6-leaderboard-live.md)

## Phase Progress Log

| Phase | Domain | Status | Review | Build | Committed |
|-------|--------|--------|--------|-------|-----------|
| Phase 0: Слой целей в движке | frontend | ✅ Done | ✅ | ✅ | ✅ |
| Phase 1: Оболочка + 1 уровень + прогресс | fullstack | ✅ Done | ✅ | ✅ | ✅ |
| Phase 2: Карта + мир + XP/скины | fullstack | ✅ Done | ✅ (1 🟡 fixed) | ✅ | ✅ |
| Phase 3: Граф-уровни + зоны | fullstack | ⬜ Not Started | ⬜ | ⬜ | ⬜ |
| Phase 4: Квантовые способности + SR | fullstack | ⬜ Not Started | ⬜ | ⬜ | ⬜ |
| Phase 5: Авторинг + раздача | fullstack | ⬜ Not Started | ⬜ | ⬜ | ⬜ |
| Phase 6: Лидерборд / живая гонка | fullstack | ⬜ Not Started | ⬜ | ⬜ | ⬜ |

## MVP boundary
После **Phase 2** игра играбельна и отгружаема: один полный мир физ-уровней с картой,
прогрессом, XP и скинами. Фазы 3–6 — расширение (новые типы уровней, способности,
авторинг, мультиплеер).

## Final Review
- [ ] Comprehensive code review (final-reviewer)
- [ ] Security review (новые API: прогресс/лидерборд, user-input)
- [ ] `npm test` без новых регрессий (поверх baseline)
- [ ] `npm run lint:routes` baseline 0
- [ ] Merged to `feature/sim-builder`