@
feat(quantik-game): фаза 0 — слой целей в движке (goal/HUD/result) Декларативный блок goal в спеке SimForge (булево SimExpr-условие победы), вычисляемый каждый кадр: фиксация результата (победа/время/попытки/звёзды), callback onGoal, HUD-оверлей (цель/звёзды/подсказка/баннер, inline SVG). API инстанса: onGoal/getResult/resetResult. Серверный validateSpec пропускает goal/game (длина выражений + escape текста, без исполнения). Аддитивно: спека без goal ведёт себя как раньше. Смоук 40/40; npm test 238 pass/8 baseline; lint:routes 0. План фичи (7 фаз) + CONTEXT. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> @
This commit is contained in:
Maxim Dolgolyov
@@ -0,0 +1,135 @@
|
||||
# Phase 0: Слой целей в движке (goal / HUD / result)
|
||||
|
||||
**Status:** ✅ Done (reviewed — PASS, committed)
|
||||
**Parent plan:** [PLAN.md](./PLAN.md)
|
||||
**Domain:** frontend
|
||||
|
||||
## Objective
|
||||
Ввести в `_sim_engine.js` **«атом» игры** — декларативный блок `goal` (условие победы как
|
||||
булево SimExpr-выражение), вычисляемый каждый кадр, с фиксацией результата (победа/время/
|
||||
попытки/звёзды), callback'ом и HUD-оверлеем. Расширить серверный гейт `validateSpec`, чтобы
|
||||
блок проходил валидацию. Всё аддитивно: спека без `goal` ведёт себя как раньше.
|
||||
|
||||
## Спека (контракт, документировать в шапке `_sim_engine.js`)
|
||||
```
|
||||
goal: {
|
||||
when: '<bool expr>', // SimExpr: победа, когда станет истинным (≠0)
|
||||
hint?: 'текст подсказки', // показывается в HUD (escape на сервере)
|
||||
title?: 'Цель уровня', // краткая формулировка цели для HUD
|
||||
hold?: 0.0, // сек, сколько условие должно держаться (деф. 0 = мгновенно)
|
||||
stars?: [ // 0..3 доп.условий-«звёзд» (бонусы)
|
||||
{ when:'<bool expr>', label?:'...' }
|
||||
],
|
||||
fail?: '<bool expr>' // опц.: мгновенный проигрыш (вышел за поле/задел шип)
|
||||
}
|
||||
```
|
||||
- `when`/`stars[].when`/`fail` — компилируются ОДИН раз при mount (как все выражения), env тот же.
|
||||
- Доп. env-поля для целей: `t` (время), `tries` (число reset с начала), плюс всё что уже в env
|
||||
(`<obj>.x/.y/.vx/.vy`, params, w/h, xmin..ymax). НЕ вводить новых небезопасных идентификаторов.
|
||||
- Звезда «залипает»: однажды истинное условие звезды остаётся засчитанным до reset (накопитель).
|
||||
|
||||
## Tasks
|
||||
- [x] Task 1: В шапке `_sim_engine.js` задокументировать блок `goal` (формат v1, как сделано для physics/plot).
|
||||
- [x] Task 2: В `prepare`/mount компилировать `goal.when`, `goal.fail`, каждое `stars[].when`
|
||||
через `SimExpr.compile` (хранить fn + error; кривое выражение → никогда не бросает).
|
||||
- [x] Task 3: Добавить состояние результата на инстанс: `_goalState = { won, failed, timeMs,
|
||||
attempts, starsGot:[], firstWinT }`. Сбрасывать в `reset()` (attempts++ на reset, кроме первого).
|
||||
- [x] Task 4: В rAF-цикле (`_renderFrame`/`_stepPhysics`-соседство) после построения env и шага:
|
||||
вычислить звёзды (накопить), `fail` (→ мягкий проигрыш-оверлей, не победа), `when`
|
||||
(учесть `hold` — таймер удержания) → при победе зафиксировать `timeMs` (мировое t или
|
||||
wallclock от старта play), выставить `won=true`, остановить (`pause`) и вызвать `onGoal` callback.
|
||||
- [x] Task 5: HUD-оверлей (DOM, поверх canvas, как слой readout): строка цели (`title`),
|
||||
индикатор звёзд (inline SVG звезда — заполненная/контур), подсказка (`hint`),
|
||||
баннер «Победа»/«Ещё раз» с кнопкой Reset. Стиль — тёмная плашка как у readout; без эмодзи.
|
||||
HUD появляется ТОЛЬКО при наличии `goal` в спеке.
|
||||
- [x] Task 6: Публичное API инстанса: `onGoal(cb)` (cb получает `getResult()`), `getResult()`
|
||||
→ `{ won, failed, timeMs, attempts, stars:{got,total} }`, `resetResult()`.
|
||||
- [x] Task 7: `destroy()` снимает HUD-узлы/слушатели кнопок (нет утечек).
|
||||
- [x] Task 8: Сервер `backend/src/controllers/customSimController.js` `validateSpec`:
|
||||
разрешить ключ `goal` (объект) и `game` (объект, см. Phase 1/5) на верхнем уровне спеки;
|
||||
проверять `when`/`fail`/`stars[].when` через `checkExpr` (длина ≤ MAX_EXPR_LEN);
|
||||
`hint`/`title`/`stars[].label` — `sanitizeText` (escape + обрезка); `stars` ≤ 3; `hold` число.
|
||||
НЕ исполнять выражения. Обновить whitelist при необходимости.
|
||||
- [x] Task 9: Headless-смоук (vm + ручной DOM/canvas-стаб + РЕАЛЬНЫЕ `_sim_expr.js`+`_sim_engine.js`,
|
||||
как в P1–P3): (а) спека с `goal.when` достигает победы → `getResult().won`, `timeMs>0`;
|
||||
(б) звёзды накапливаются и не сбрасываются до reset; (в) `fail` ставит failed без won;
|
||||
(г) `hold` требует удержания; (д) спека БЕЗ goal — поведение без изменений, HUD не создан;
|
||||
(е) `onGoal` зовётся один раз; (ж) destroy снимает HUD-слушатели (баланс add/remove).
|
||||
Удалить temp-смоук после прогона. → 40/40 PASS, удалён.
|
||||
|
||||
## Files to Modify/Create
|
||||
- `frontend/js/labs/_sim_engine.js` — блок goal: документация, компиляция, eval в цикле, HUD, API.
|
||||
- `backend/src/controllers/customSimController.js` — `validateSpec`: разрешить `goal`/`game`.
|
||||
- (temp) headless-смоук — создать, прогнать, удалить.
|
||||
|
||||
## Acceptance Criteria
|
||||
- Спека с `goal` показывает цель/звёзды/победу; `getResult()` корректен; `onGoal` срабатывает.
|
||||
- Спека без `goal` рендерится и ведёт себя ровно как раньше (нет HUD, нет накладных вычислений побед).
|
||||
- `validateSpec` пропускает корректный `goal`, режет переразмер/длинные выражения, экранирует текст.
|
||||
- `node --check` обоих файлов OK; headless-смоук зелёный; эмодзи нет; `eval`/`new Function` нет.
|
||||
- `cd backend && npm test` — без новых регрессий; `npm run lint:routes` — без новых ошибок.
|
||||
|
||||
## Notes
|
||||
- Время победы: предпочесть **мировое `t`** (детерминизм, headless-тест), плюс можно хранить wallclock.
|
||||
- `attempts` = число `reset()` (первый mount/авто-reset не считать попыткой; считать пользовательские).
|
||||
- HUD не должен перехватывать pan/drag сцены вне своих интерактивных элементов (pointer-events: none
|
||||
на контейнере, auto — на кнопках), как сделано с overlay-панелью в P1.
|
||||
- Не вводить новые env-идентификаторы помимо `t`/`tries` — безопасность контракта выражений.
|
||||
|
||||
## Review Checklist
|
||||
- [x] Все задачи выполнены
|
||||
- [x] Код следует конвенциям движка (хелперы модульного уровня `_truthy`, инстанс-методы, без рисования по canvas — HUD это DOM-оверлей как readout)
|
||||
- [x] Аддитивность: существующие симуляции/каталог не затронуты (нет goal → `_goal=null`, HUD не создаётся, в rAF ветка `if (self._goal)` пропускается)
|
||||
- [x] Без эмодзи; без eval/Function (звёзды/иконки — inline SVG; выражения только через `SimExpr.compile`)
|
||||
- [x] Build (node --check) и тесты проходят (смоук 40/40; `npm test` 238 pass / 8 baseline fail; lint:routes 0)
|
||||
|
||||
## Handoff to Next Phase
|
||||
|
||||
### Движковое API цели (для Phase 1)
|
||||
Всё в `frontend/js/labs/_sim_engine.js`. `var inst = SimEngine.mount(host, spec)`:
|
||||
|
||||
- **`inst.onGoal(cb)`** — подписка. `cb` получает `getResult()` и вызывается РОВНО ОДИН РАЗ при
|
||||
первой победе (после `pause()`). Возвращает `inst` (chainable). Можно подписать несколько cb.
|
||||
- **`inst.getResult()`** → `{ won:bool, failed:bool, timeMs:number, attempts:number, stars:{got:number, total:number} }`.
|
||||
Для спеки БЕЗ `goal` возвращает **`null`** — проверяйте на null перед использованием.
|
||||
- **`inst.resetResult()`** — сбросить результат как новый уровень (won/failed/звёзды/таймер обнуляются),
|
||||
но **НЕ считается попыткой** (attempts сохраняется). Для перезапуска уровня используйте `inst.reset()`
|
||||
(это И сбрасывает физику/время И инкрементит attempts как пользовательскую попытку).
|
||||
|
||||
### Как включить «игровой режим» / HUD
|
||||
HUD появляется **автоматически**, как только в спеке есть верхнеуровневый блок `goal`. Отдельного
|
||||
флага «game mode» в движке НЕТ. Никакого вызова не нужно — `mount()` сам создаёт HUD при наличии `goal`.
|
||||
HUD = DOM-оверлей внутри `inst.el` (контейнер `pointer-events:none`, кнопка «Ещё раз» — `pointer-events:auto`,
|
||||
дёргает `inst.reset()`). Спрятать HUD = убрать `goal` из спеки.
|
||||
|
||||
### Как измеряется timeMs
|
||||
**Мировое время** `t` от старта уровня (детерминизм для headless/реплеев): при победе
|
||||
`timeMs = max(1, round(t*1000))`. Это НЕ wallclock — паузы/тротлинг rAF не влияют. `firstWinT`
|
||||
(сырое мировое `t` победы) хранится внутри в `_goalState`, наружу отдаётся только `timeMs`.
|
||||
|
||||
### Форма блока goal/game (что сервер теперь принимает)
|
||||
`validateSpec` (`backend/src/controllers/customSimController.js`) пропускает на верхнем уровне:
|
||||
```
|
||||
goal: {
|
||||
when: '<bool SimExpr>', // ≤500 симв., НЕ исполняется на сервере
|
||||
title?: '...', hint?: '...', // sanitizeText: escape & < > + обрезка (title≤120, hint≤300)
|
||||
hold?: 0, // число (сек удержания when); не-число → 400
|
||||
fail?: '<bool SimExpr>', // ≤500 симв.
|
||||
stars?: [ { when:'<bool SimExpr>', label?:'...' } ] // ≤3 (иначе 400); label sanitizeText ≤120
|
||||
}
|
||||
game?: { ... } // зарезервирован под мета-слой Ф1/5; проходит как есть
|
||||
// (под общими лимитами размер/глубина), НЕ исполняется
|
||||
```
|
||||
Категория `cat='game'` уже в `CATS` (math/phys/chem/bio/game) — расширять не нужно.
|
||||
|
||||
### Env-контракт цели (безопасность)
|
||||
Выражения `goal.when`/`fail`/`stars[].when` видят ВЕСЬ env кадра (params, `t`, `w/h`, `xmin..ymax`,
|
||||
`<obj>.x/.y/.vx/.vy`) ПЛЮС единственный доп.идентификатор **`tries`** (= `attempts`). НЕ вводить
|
||||
новых идентификаторов в env цели — это контракт безопасности шаренных выражений.
|
||||
|
||||
### Гочи для Phase 1
|
||||
- Победа ставит `pause()` внутри rAF-кадра; следующий queued-кадр выходит по `if (!self._running) return`
|
||||
→ `onGoal` не задвоится. НЕ вызывайте `play()` в `onGoal`-колбэке без `resetResult()`/`reset()`.
|
||||
- `goal.when` без `hold` срабатывает на ПЕРВОМ же кадре, где условие истинно (мгновенно).
|
||||
- Звёзды «залипают»: засчитываются и во время play (rAF), и на паузе/предпросмотре (`_renderFrame`).
|
||||
- Истинность булева = `_truthy`: конечное ненулевое число (SimExpr возвращает 0 при NaN/∞/ошибке).
|
||||
Reference in New Issue
Block a user