Learn_System/plans/quantik-game/PLAN.md

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

Branch: feature/quantik-game Base branch: feature/sim-builder (движок P1–P3 и фазы sim-builder ещё не в master) Created: 2026-06-13 Status: ✅ Complete (merged to feature/sim-builder, 2026-06-14) 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

• Phase 0: Слой целей в движке (goal/HUD/result) [domain: frontend] → subplan
• Phase 1: Оболочка игры + 1 физ-уровень + прогресс [domain: fullstack] → subplan
• Phase 2: Карта-созвездие + мир физ-уровней + XP/скины [domain: fullstack] → subplan
• Phase 3: Граф-уровни (движение по f(x)) + зоны-препятствия [domain: fullstack] → subplan
• Phase 4: Квантовые способности + SR-комнаты [domain: fullstack] → subplan
• Phase 5: Авторинг уровней в sim-builder + раздача классу [domain: fullstack] → subplan
• Phase 6: Класс-лидерборд / живая гонка (classroom SSE) — REMOVED (см. Amendment 1) → subplan

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	✅ Done	✅	✅	✅
Phase 4: Квантовые способности + SR	fullstack	✅ Done	✅	✅	✅
Phase 5: Авторинг + раздача	fullstack	✅ Done	✅	✅	✅
Phase 6: Лидерборд / живая гонка	fullstack	❌ Removed (Amendment 1)	—	—	—

MVP boundary

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

Amendment Log

Amendment 1 — 2026-06-14

Type: Removed phase What changed: Phase 6 (Класс-лидерборд / живая гонка через classroom SSE) убрана из объёма по решению пользователя. Why: Пользователь решил не реализовывать соревновательный слой; переходим к полировке и финальному ревью после Ф5. Impact on existing phases: Нет. Фазы 0–5 самодостаточны и отгружаемы. game_progress.level_id (TEXT) уже готов под будущий лидерборд, если фичу вернут. Subplan phase-6-leaderboard-live.md сохранён как архив с пометкой REMOVED.

Final Review

• Comprehensive code review (final-reviewer) — ✅ READY TO MERGE, 0 блокеров (2026-06-14)
• Security review (новые API/ввод) — ✅ SECURE, 0 critical (2026-06-14)
• Polish-фиксы по ревью применены: game-блок санитизируется (был латентный XSS), prefers-reduced-motion guard, фикс комментария isUnlocked. Тесты 45/45 затронутых, lint 0.
• npm test без новых регрессий (8 = baseline: 3 auth + 5 jsdom)
• npm run lint:routes baseline 0
• Merged to feature/sim-builder — merge commit dabb370 (--no-ff), 2026-06-14. Post-merge: тесты = baseline, lint:routes 0.

Deferred / Backlog (не блокеры — из финального ревью)

• QuantikLevels.ensureCustom — N+1 customSimGet на загрузку /quantik; при росте числа авторённых уровней заменить на bulk-эндпоинт «список game-спек».
• Уровни 3/5/6 (отскок/орбита/манёвр): fail — только таймаут, «честная» механика не форсится. Точечно ужесточить fail-предикаты (контент-тюнинг).
• graph-exp-11 капстоун узковат (~36–42/625) — при жалобах на сложность чуть расширить gate.
• Три похожих starSvg/_starIcon в разных модулях — консолидация не стоит связывания движка с игрой (оставлено).
• Клиентские очки прогресса фальсифицируемы (ожидаемо для single-player). ⚠️ Если когда-нибудь вернут Ф6-лидерборд — валидировать на сервере (replay/подписанные токены).