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: 🟡 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

• 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) [domain: fullstack] → 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	⬜ 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