# MyGamePlayable — контекст проєкту

Playable ad на three.js + пропрієтарний SDK HitPlay. Цей файл вантажиться в
кожну сесію — тримай його **інструкцією, а не щоденником**.

---

## ПРАВИЛА ВЕДЕННЯ ЦЬОГО ФАЙЛУ

**Стеля — 300 рядків.** Перевищив — перенеси найстаріше й уже усталене в
`docs/worklog/`. Історія розробки живе там, не тут.

### Що ДОДАВАТИ сюди

- правило або конвенцію, що змінює майбутні рішення («використовуй утиліту X,
  не пиши формулу заново»);
- граблі, які **вкусять ще раз** (поведінка SDK/бібліотеки/тулчейна, а не
  разовий баг у власному коді);
- зміну структури: новий контролер, нова утиліта, новий конфіг-параметр;
- нову команду або публічний API SDK, який не очевидний з коду.

### Що НЕ додавати

- «сьогодні зробив…», «Day N», хронологію, цитати з чату;
- «перевірено в браузері / білд пройшов» — це не знання, це подія;
- підібрані числа (`CAMERA_OFFSET`, тривалості, відсотки) — вони живуть у коді
  й там же змінюються; сюди — тільки *де* важіль, не його поточне значення;
- переказ того, що й так видно з коду за 10 секунд.

### Куди що писати

| Знання | Місце |
|---|---|
| Пояснює один файл/рядок | коментар у коді |
| Перетинає кілька файлів або є політикою проєкту | `CLAUDE.md` |
| «Чому ми дійшли саме до цього» | `docs/worklog/` |

### Коли граблі усунені в корені

Якщо гочтя закрита утилітою — **заміни розповідь одним рядком** з посиланням на
утиліту. Приклад: `.chain()`-баг → `src/utils/tweenChain.ts`. Довга версія
лишається в `docs/worklog/02-day6-tween-animations.md`.

### Новий запис у worklog

`docs/worklog/NN-коротка-англійська-назва.md`, `NN` — наступний номер.
Додай рядок у `docs/worklog/README.md`. Один H1 на файл.

---

## Стек

- **three.js `0.185`** (НЕ Babylon), обгорнутий у SDK `@hitplay/playable_template`
  + `@hitplay/ads_common` (приватні пакети HitPlay).
- Фізика: `cannon-es`. **SDK сам кличе `world.fixedStep()` щокадру**
  (`Physics_internal.update`) — свій `step()`/`fixedStep()` НЕ викликати.
  Ініт — `Physics_internal.init(...)` у `beforeResourcesLoadedCb.ts`.
- Твіни: `@tweenjs/tween.js` через SDK-обгортку `TweenC`. **`TweenC.init()`
  треба покликати один раз** (є в `beforeResourcesLoadedCb.ts`), інакше
  `TweenC.add()` тихо нічого не анімує.
- VFX: `three.quarks` — дизайнерські префаби з quarks.art (`.json`).
- Звук `howler`, ввід `nipplejs`, дебаг-панель `lil-gui`, аналітика `bytebrew-web-sdk`.
- Тулчейн: Vite 6 + TypeScript 7.

`UpdateController.Instance.onUpdate` — **єдиний** update-івент, `delta` в секундах.
`ThreeC.removeFromScene(obj)` — видалення спавнених мешів.

## Команди

| Команда | Що робить |
|---|---|
| `npm start` | vite dev-сервер |
| `npm run export` | single-file HTML → `export/output_export_browser_en.html` |
| `npm run build` | zip для платформи 24ADS → `zip/` |
| `npm run update` | оновити `@hitplay/ads_common` + `playable_template` |

Перевірка змін — `npx vite build` (у проєкті прийнято верифікувати саме білдом).
`stats.html` — rollup-visualizer, дивитись коли розпухає бандл.

## Структура

```
src/index.ts              точка входу, Template.initConfig({...})
src/controllers/*C.ts     одна система = один файл, суфікс C, плоский список
src/configUIParams/       категорії конфігу, які рендерить платформа 24ADS
src/templateConfig/*Cb.ts лайфсайкл-колбеки SDK
src/utils/                спільні формули (див. нижче)
src/resources/            meshes/images/fonts/vfx/sounds
src/css/                  main.css, ui.css, health-bar.css
docs/worklog/             архів історії розробки
```

Підпапки в `controllers/` **свідомо не зроблені** — SDK сам плаский, вигоди нуль.

### Утиліти — використовувати, не переписувати

- `perspectiveScale.ts` — компенсація перспективи при польоті до/від камери.
- `screenWorldProjection.ts` — world↔screen в обидва боки.
- `tweenChain.ts` — коректна реєстрація ланцюжка твінів.
- `flashOverlayMaterial.ts` — адитивний флеш-оверлей.

### DI-патерн

Контролери не імпортують одне одного напряму, коли це створить цикл — інжектиться
геттер/колбек, а зв'язує `TestSceneC`:
`ResourceC.setFlyTarget()`, `HudC.setBalanceGetter()`,
`CameraFollowC.setFacingTargetGetter()`, `BreakablePropC.onHit/onDestroyed`.

## Конфіг платформи ↔ код

Платформа 24ADS рендерить ліву панель із категорій. Частина — наші
(`src/configUIParams/`), частина — стандартні від SDK.

| Вкладка на платформі | Джерело |
|---|---|
| Analytics params | `analytics.ts` |
| Install Banner Settings | `installBanner.ts` |
| **Scene settings** | `globalSettings.ts` (id категорії — `global`) |
| Gameplay tuning | `gameplay.ts` |
| Audio Settings | `sounds.ts` |
| Screen Orientation | `orientation.ts` |
| Filter scene, Redirect Settings, Loader Settings, Font Settings | SDK, не наш код |

Читати значення в коді — `Template.getCategory("<id категорії>")["<id параметра>"]`
(приклад — `DebugConfigC.init()`).

**Scene settings** (`globalSettings.ts`): `light_intensity`, `light_color`,
`camera_fov_p/l`, `camera_position_p/l`, `camera_rotation_p/l`.

**Формат `configUIParams` ≠ формат рантайму.** У визначенні кожна вісь масивного
параметра — це `[min, max, default]`; у грі `Template.getCategory()` віддає
готовий `[x, y, z]`. Не переплутати: `[-20, 70, -6]` — це не координати.

**Камера: рівно один писар на `camera.rotation` — `CameraFollowC`.**
`camera_position_*` — це офсет **відносно гравця** (не абсолютна позиція, камера
слідкує), `camera_rotation_*` — фіксований кут у градусах, `camera_fov_*` — FOV.
Розподіл власності: FOV застосовує `CameraC.setCamera()`, риг —
`CameraFollowC.applyRigFromConfig()`. Не повертати position/rotation у
`CameraC.setCamera()`: він перезапускається на кожну зміну будь-якого `camera_*`
поля, і два писарі на кут ламали камеру назавжди до кінця сесії.
`CAMERA_OFFSET` у `TestSceneC` лишився тільки як фолбек.

**Gameplay tuning** (`gameplay.ts`) дублює те, що дев-панель `DebugConfigC`
(клавіша `C`, тільки lil-gui, не потрапляє в білд) показує локально. Панель
сідить свої дефолти з цієї категорії при старті — один раз, без live-sync.

## Живі граблі

Кожна вже кусала. Довгі розбори — в `docs/worklog/`.

**glTF-завантажувач стирає крапки з імен нодів.** У сирому GLB `UI_Wood.001`, у
живій сцені — `UI_Wood001`. `getObjectByName()` тихо повертає `undefined`, гард
`if (node)` завжди хибний, код «виглядає правильним». Перевіряти реальне ім'я
через `scene.traverse`, не через GLB JSON.

**Матеріали шаряться між усіма нодами з GLB.** Хочеш змінити матеріал одного
об'єкта — клонуй його один раз при білді, інакше зачепиш усі 18 крейтів.

**`material.color` на `MeshBasicMaterial` не дає флешу.** Матеріал unlit, колір
множиться на текстуру, дефолт уже білий — лерп «білий → білий» невидимий.
Для hit-flash — окремий адитивний оверлей-меш (`flashOverlayMaterial.ts`).

**«Чи гравець у зоні X» — тільки через `Box3().setFromObject(node)`.** Радіус на
око зі скріншота не збігається з реальним футпринтом (і центр може бути
несиметричний відносно пивота).

**Перспектива сама змінює видимий розмір.** Об'єкт, що летить до камери,
«росте» без жодного дотику до `.scale`. Треба явно компенсувати —
`perspectiveScale.ts`.

**Ціль польоту пере-семплювати щокадру.** Камера рухається разом з гравцем;
взята один раз позиція HUD-анкера застигає й політ промахується.

**`tween.onComplete` зрідка не спрацьовує** (причина всередині tween.js не
знайдена) — для критичного клінапу дублювати `setTimeout` на тривалість + запас.
`removeFromScene` двічі — нешкідливо.

**screen↔world рахувати від `renderer.domElement.getBoundingClientRect()`**, не
від `window.innerWidth/Height` — SDK рендерить у letterboxed 9:16 бокс.

**nipplejs `force` не обмежений радіусом зони** — за краєм кільця росте далі,
хоч точка вже запінена. Клампити один раз при записі, не в кожному `calc()`.

**`Math.atan2` і CSS `conic-gradient` мають різний нуль** (схід vs північ) —
різниця рівно 90°.

**Дві CSS-анімації на одному елементі не живуть разом** — перемикання класу,
що чіпає `animation-name`, перезапускає анімацію. Розділяти на вкладені div.

**Анімувати RGB, не альфу**, якщо треба «згасання до базового кольору» — інакше
на нулі отримаєш прозору дірку замість кольору.

**У CSS — `--lvh`/`--lvw`, не сирі `vh`/`vw`/`vmin`** (ротація/адаптивність).

**Експорт — це gzip-блоб, а не текст. НЕ грепати `export/*.html` напряму.**
`npm run export` пакує весь бандл у base64+gzip (`decompressString("H4sIA...")`,
розпаковується `pako` в рантаймі). Будь-який пошук по цьому файлу дасть **0
збігів** — для всього, включно з класами самого SDK. Прочитати цей нуль як
«purgecss вирізав наш CSS» — легка й дуже дорога помилка (перевірено: після
розпаковки всі кастомні класи й `@font-face` на місці, кількість збігається з
`vite build`). Перевіряти тільки після gunzip.

**purgecss справді вирізає `.bannerButton`** — але саме його, точково (клас
призначається всередині мінифікованого SDK-бандла). У розпакованому експорті:
`.bannerButton{` — 0, `.bannerLogo{` — 1, `.bannerButtonText{` — 1. Не писати
CSS-правила під `.bannerButton`, це мертвий код. На решту класів не поширюється.

**`Template.setUpFont()` працює тільки коли `!release`** — тобто шрифт через
`customFont.ts`/`formFontFamily` реєструється для **прев'ю платформи**, а не для
експорту. У реальному білді шрифт малює наш власний `@font-face` з `main.css`
(інлайн base64). Це два незалежні механізми на дві різні поверхні — потрібні
обидва, і поломка одного не видна з іншого.

**Інлайн ассетів:** картинки — `ConvertToBase64WhenRelease("./file.webp")`, і
викликати обов'язково **з файлу в тій самій директорії**, що й ассет. Шрифти —
нічого не треба, `assetsInlineLimit` у конфігу SDK інлайнить `url()` у CSS сам.

## Ігрові дані

`ZombiePunk_Map.glb`, група **`Lootable`** → ~18 × `Wooden_Box_XXX`:
```
Wooden_Box_XXX
  BoxCollider.NNN            obstacle-бокс
  Wooden_Box_States_XXX
    Wooden_Box_XXX_S1..S3    стейджі пошкодження, не в усіх є всі три
```
Крейти можуть стартувати вже пошкодженими (тільки S2/S3) — `BreakablePropC`
рахує стартовий HP з реальних номерів `_SN`, не з припущення про 3 стейджі.

`UI_Wood` — реальна іконка ресурсу (текстура `Icon_Wood`), клонується на кожен
спавн. `UI_Interactive_Zone_02` — Pay Zone. `UI_Tool_Zone`, `UI_Wood001`, група
`UI` — приховані як зайва декорація.

## Поточний стан

- Working tree брудний, багато незакомічених змін.
- `DebugConfigC.ts` і `configUIParams/gameplay.ts` — нові, ще не в git.
- **Відомі борги** (відкладені свідомо, за рішенням користувача):
  - `ui.css` / `health-bar.css` — досі на `vh`, без landscape-медіазапиту;
  - VFX-емітер `StretchSmoke` у `VFX_Lootable_Hit` вилітає далеко від крейта
    (дизайнерський ассет тюнили під інший масштаб сцени) — рішення за
    користувачем: лишити / притлумити / прибрати емітер;
  - Destroy-VFX підключений, але візуально не підтверджений.