onboarding-project/CLAUDE.md

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

> Цей файл автоматично підвантажується в кожній сесії Claude Code. Тримай його
> в актуальному стані: онови статуси, коли щось зміниться, видали "Day 5" секцію
> коли вона остаточно перевірена і стабільна, додай нову секцію під наступний день.

## Стек і структура

- **Не Babylon.js** — це **three.js** (`three@0.185`) обгорнутий у пропрієтарний
  SDK `@hitplay/playable_template` (плейбл-реклама, HitPlay).
- Фізика: `cannon-es@0.20` + `cannon-es-debugger`. World піднятий через SDK
  (`Physics_internal.init(...)` в `src/templateConfig/beforeResourcesLoadedCb.ts:27`),
  дебаг-рендер тригериться прапорцем `Template.initConfig({ debug: { physics: false } })`
  в `src/index.ts` (поки `false` — увімкнути під час дебагу фізики).
  **SDK сам кличе `world.fixedStep()` кожен кадр** (`Physics_internal.update`,
  всередині пакету) — свій `world.step()`/`fixedStep()` НЕ викликати, це
  вже фіксований таймстеп з коробки.
- `UpdateController.Instance.onUpdate` — єдиний update-event, `delta` в
  секундах (з `THREE.Clock.getDelta()`), без фіксованого таймстепу на цьому
  рівні (фіксований степ — тільки всередині cannon, через `fixedStep()`).
- `ThreeC.removeFromScene(obj)` існує (просто `obj.removeFromParent()`) —
  використовувати для видалення спавнених/знищених мешів.

### Файли

```
src/controllers/
  PlayerC.ts         - джойстик-рух (nipplejs), AABB-колізії з "colliders",
                       бій: неперервний AoE-swing по всіх breakable-цілях в
                       зоні ураження, перебивається рухом
  TestSceneC.ts      - завантажує ZombiePunk_Map.glb, /collider/i -> hidden+colliders,
                       ставить cannon Wall-тіла на все, крім Lootable-крейтів
  CameraFollowC.ts   - камера-слідкувач, obstacle-avoidance через Raycaster
                       по тому ж масиву colliders (НЕ торкались)
  PhysicsC.ts        - PhysicsLayer enum, PhysicsBody (Box/Sphere+cannon Body
                       з коректним world-space size/rotation), PhysicsObjPair
  BreakablePropC.ts  - парсить групу "Lootable" в мапі, S1/S2/S3 damage-stages,
                       2 хіти на стейдж, hit() advance stage / повне
                       знищення (tween-джус, Day 6), дропає ресурси
  ResourceC.ts       - спавн ресурсів "розльотом" від цілі + автозбір
                       (Day 5, незмінно) — НЕ знає про Pay Zone/гравця;
                       візуал — клон реального "UI_Wood" з мапи
                       (fallback-куб про запас), createVisual() — публічний
                       доступ до цього візуалу для інших контролерів
  PayZoneC.ts        - Day 6: окремо зливає ResourceC.getCollectedCount() в
                       Pay Zone (вузол мапи "UI_Interactive_Zone_02"), по
                       одному ресурсу, тільки поки гравець стоїть в зоні;
                       зникає після RESOURCES_TO_CLOSE_ZONE доставлених
                       (зараз 20, підкручено після Day 6 — див. секцію
                       "прогрес-заповнення зони"); росте плаский
                       fill-overlay квад по мірі заповнення; політ депозиту
                       летить з HudC.getWorldAnchorPosition(), не з гравця
  HudC.ts            - лічильник ресурсу (іконка+число) у правому верхньому
                       куті, DOM-оверлей в #ui; володіє "світовою" точкою
                       (дитина камери), куди летять зібрані ресурси і
                       звідки стартує політ депозиту в Pay Zone
  ThreeC.ts/CameraC.ts - базовий сетап three.js/камери від SDK
resources/meshes/    - ZombiePunk_Map.glb, ZombiePunk_Character.glb
resources/images/    - icon_wood.webp (Icon_Wood, витягнутий з мапи), images.ts
```

`TriggerC.ts` (beginContact/endContact -> onEnter/onExit) і кінематичне
cannon-тіло гравця для тригерів — **були написані й видалені в межах цієї ж
сесії, ще до коміту**: перший дизайн ресурсів вимагав підходити до пікапа й
стояти в тригер-зоні; користувач уточнив, що гравцю підходити не треба
(ресурси самі розлітаються і зараховуються по таймеру), тож фізичні тригери
виявились непотрібні для Day 5. Якщо колись знадобиться proximity-based
тригер для чогось іншого (вода, зона урону, детект ворога) — писати заново,
але сам підхід (`world.addEventListener('beginContact'/'endContact')` +
мапа `body.id -> handlers`) вже перевірений робочим, просто не лишений в коді.

### Ключова знахідка: структура glb вже готова під breaking/loot

Мапа (`ZombiePunk_Map.glb`) містить групу **`Lootable`** (пряма дитина кореня
`Map`) з ~18 дітьми `Wooden_Box_XXX` (XXX = `000`..`017`). Кожен має:

```
Wooden_Box_XXX
  BoxCollider.NNN            <- obstacle-бокс, він же в загальному /collider/i списку
  Wooden_Box_States_XXX
    Wooden_Box_XXX_S1        <- найменше пошкоджений (не завжди є)
    Wooden_Box_XXX_S2
    Wooden_Box_XXX_S3        <- найбільш пошкоджений/уламки (завжди є хоча б цей)
```

Не всі крейти мають усі 3 стейджі — деякі стартують вже пошкодженими
(тільки S2/S3) або взагалі як декоративні уламки (тільки S3). `BreakablePropC`
сортує дітей `..._States_XXX` за номером у назві й показує лише перший —
кожен хіт просуває на наступний, а хіт по останньому стейджу знищує крейт.

Root-рівень gltf-сцени (`getObject("map")` = `gltf.scene`, НЕ сам "Map"-нод)
містить ще 3 сиблінги "Map": `UI_Tool_Zone`, `UI_Interactive_Zone_02`,
`UI_Wood`/`UI_Wood.001` — плоскі quad-меші на позиції origin. В грі це
видно як пунктирний білий квадрат, що лежить на дорозі біля крейтів
(скріншот при першому запуску) плюс текстуру дерева поверх нього.

**`UI_Wood` (mesh `Plane.002`) — це реальний іконка-ресурсу, не сміття.**
Матеріал `Material` (index 6) використовує текстуру з назвою **`Icon_Wood`**
(unlit, alphaMode BLEND, doubleSided) — художник підготував конкретно "іконку
дерева" саме для цього. Тепер підключено: `TestSceneC` бере цей нод,
віддає його в `ResourceC.setPickupTemplate()` (клонується на кожен спавн
ресурсу — `.clone()`) і ховає оригінал (`visible=false`, він більше не
статична декорація, а шаблон для клонування). `ResourceC.createPickupMesh()`
примусово виставляє `clone.visible = true`, бо `.clone()` копіює і
`visible:false` з прихованого оригіналу.

`UI_Wood.001` (mesh `Plane.008`, матеріал `M_Items`/текстура `T_items_icons`
— схоже на спрайт-атлас з кількома іконками) і `UI_Tool_Zone` — призначення
досі не зрозуміле, але користувач попросив прибрати їх як "зайві текстури"
навколо Pay Zone — тепер ховаються в `TestSceneC` (`visible=false`) поруч з
`UI_Wood`. `UI_Interactive_Zone_02` (пунктирний квадрат) — **тепер
підключений** в Day 6 як Pay Zone (див. нижче).

Ще одна знахідка (не сиблінг, а дитина `Map` -> `"UI"`): группа `UI`
(`UI_Background`/`UI_Foreground`/`UI_Middleground`, всі матеріал `_Part2`
— той самий атлас, що й крейти) — окремо повернута група (власний
quaternion), локально приблизно (0.31, 1.21, -1.9), тобто підвішена в
повітрі на висоті голови персонажа. Схоже на фейковий install-button
мокап (типовий playable-ad прийом), рендерився завжди, візуально
"прямокутна синя пластина над плей зоною" з якою скаржився користувач.
Теж ховається тепер (`map.getObjectByName("UI")`, `visible=false`).

## Day 5: Cannon.js — реалізовано (2026-08-11, доопрацьовано того ж дня)

Перша ітерація зробила всі 8 пунктів чек-листа буквально (single-target
дискретний свінг + proximity-тригери на ресурси). Користувач одразу дав
конкретні правки під реальний геймплей-дизайн (враховані в описі нижче) —
**фінальний стан коду відображає ці правки, не буквальний чек-лист**. Білд
(`vite build`) проходить чисто після кожної ітерації. Ручна перевірка в
браузері — **ще не підтверджена користувачем**; я зробив лише один короткий
automated прогін (Playwright, в scratchpad, не в репо) до першої ревізії —
рендер і консоль були чисті, а саме AoE/continuous-attack/resource-burst
поведінку (фінальну версію) користувач попросив перевірити самостійно.

### 1. Колайдери на об'єктах карти — ✅
`TestSceneC.createMap()`: всі `/collider/i` ноди, які НЕ належать `Lootable`,
отримують `PhysicsBody(node, false, 0, PhysicsLayer.Wall, Player|Enemy)`.
Lootable-крейти отримують свої Wall-тіла всередині `BreakablePropC` (щоб
можна було `destroy()` саме це тіло при знищенні крейта, без дублювання).

При ревайві `PhysicsC.PhysicsBody` знайшов і виправив реальний баг:
конструктор рахував size/rotation з `Box3` в world-space, обнуляючи лише
**власний** quaternion об'єкта — обертання батьків (напр. кожен
`Wooden_Box_XXX` root сам повернутий по Y) все одно потрапляло в bbox, тобто
box виходив перекошеним/більшим за реальний. Тепер: size — з
`mesh.geometry.boundingBox` (локальний, без жодних обертань) × world scale,
rotation — з `getWorldQuaternion()`. Коректно для будь-якої глибини вкладеності.

### 2. Колайдери на гравці й персонажах — ✅
Рух гравця **не переписаний** — досі ручний AABB `tryMove()`, як і був. Окреме
cannon-тіло гравця (яке було для тригерів) **видалено** разом з `TriggerC`
(див. вище) — зараз у гравця взагалі немає cannon `Body`, тільки AABB.

### 3–4. Тригери + start/stop events — ⚠️ зроблено, потім видалено
Був зроблений `TriggerC.ts` на `beginContact`/`endContact`, використовувався
для ресурсів. Після уточнення від користувача ("персонажу не потрібно
підходити для збору") ресурси більше не потребують proximity-тригера —
дивись секцію "Файли" вище. Формально пункт "invisible triggers" з
чек-листа Day 5 **не представлений в фінальному коді** — свідоме рішення
під конкретні вимоги гри, а не пропуск.

### 5. Розбиття пропсів — ✅ (AoE, не single-target)
Атака гравця (`PlayerC.updateCombat`) знаходить **усі** breakable-цілі в
зоні ураження (`findBreakableTargetsInZone` — та сама `INTERACTION_REACH`
AABB-аура навколо гравця, без обмеження кількості цілей) і при кожному
"пульсі" (раз на цикл анімації) хітає їх усі одразу через
`BreakablePropC.hit(prop)` для кожної.

`BreakablePropC.hit(prop)`: якщо є наступний stage — ховає поточний, показує
наступний, дропає 1-2 ресурси (`STAGE_HIT_RESOURCE_RANGE`); якщо це вже
останній stage — дропає 2-5 ресурсів (`DESTROY_RESOURCE_RANGE`), знищує
`physicsBody`, видаляє з `colliders`/`obstacles` (як і раніше) І **ховає
весь `prop.root`** (`root.visible = false`) — крейт зникає повністю, а не
лишається візуально на останньому stage-меші без колайдера.

### 6. Анімація атаки — ✅ (неперервна, перебивається рухом)
`Loot`-кліп — знову `LoopRepeat, Infinity` (НЕ `LoopOnce` — це був перший
варіант, користувач попросив назад неперервний свінг). Логіка в
`updateCombat`:
- Старт: гравець зупинений, є хоч одна breakable-ціль в зоні, і гравець
  дивиться на найближчу з них (`isFacing`).
- Поки атакує: рух повністю розблокований (`updateMovement` виконується
  щокадру незалежно від `isAttacking` — на відміну від першої версії, де рух
  заморожувався на час свінгу). Будь-який стік-інпут -> `stopped=false` ->
  атака миттєво скасовується (`equipPistol()`), без "дограти удар".
- Раз на цикл кліпу (на позначці `HIT_TIME_FRACTION`, тобто 50% циклу) —
  "пульс" хіта по всіх поточних breakable-цілях в зоні (жива вибірка щокадру,
  тож знищені цілі природно випадають з наступного пульсу).
- Зупиняється сама, коли `zoneTargets.length === 0` (усі цілі знищені) —
  окремого cooldown між атаками нема, це не дискретний свінг.

### 7–8. Спавн і збір ресурсів — ✅ (розліт + автозбір, без тригерів)
`ResourceC.spawnBurst(origin, count)` / `spawnBurstInRange(origin, min, max)`:
кожен ресурс — клон реального `UI_Wood` (іконка дерева з мапи, див.
"Ключова знахідка" вище; заглушка-куб лишилась тільки на випадок відсутності
цього ноду), що летить від точки спавну по випадковому
напрямку в XZ на `SCATTER_MIN/MAX_DISTANCE` (0.5–1.2) з невеликою дугою
вгору-вниз (`SCATTER_ARC_HEIGHT`) за `FLY_DURATION` (0.45с), потім чекає
`SETTLE_DELAY` (0.5с) на місці і зараховується (`collected++`,
`console.log`) та зникає. **Гравцю не треба підходити** — це чистий
visual+timer ефект, без cannon body/тригера взагалі. Лічильник поки лише в
пам'яті/консолі — немає UI/economy hookup, це прототип.

### Best practices — де застосовано
- **Low-poly shapes**: усюди `Box`/`Sphere`, ніколи трімеш з реальної геометрії.
- **Fixed timestep**: вже було з коробки (`Physics_internal` кличе
  `fixedStep()` без аргументів кожен кадр) — нічого додатково не робив.
- **Sync з рендером**: `PhysicsObjPair` (не використовується в Day 5 — нічого
  фізика не рухає, ані гравець ані ресурси більше не мають cannon-тіл).
- **Sleep**: НЕ налаштовував `allowSleep`/sleep-ліміти явно — cannon-es має
  дефолти (`allowSleep: false` за замовчуванням у `World`!), тобто зараз
  **нічого не спить**. З десятками статичних Wall-тіл (тільки для колізій
  карти/крейтів, п.1) це навряд чи проблема на цьому масштабі, але якщо буде
  помітний perf-хіт — увімкнути `world.allowSleep = true` і виставити
  sleep-ліміти на статичних тілах.
- **Debug visualizer**: не трогав прапорець (`debug.physics: false` в
  `src/index.ts`) — поставити `true` вручну, коли треба візуально звірити
  cannon-боксі з мапою.
- **Collision layers**: використаний існуючий `PhysicsLayer` enum без змін
  (хоча `Trigger` тепер ніде не використовується після видалення тригерів).

## Day 6: Tween Animations — реалізовано (2026-08-11, виправлено того ж дня)

`@tweenjs/tween.js` був установлений, але **ніде не використовувався** до
цього дня. SDK має готову обгортку `TweenC` (`@hitplay/playable_template`,
`import { TweenC } from "@hitplay/playable_template"`) з власною `Group` і
автопідпискою на `UpdateController` — **треба викликати `TweenC.init()`
один раз** (додано в `beforeResourcesLoadedCb.ts`, поруч з
`Physics_internal.init(...)`), інакше `TweenC.add()`/`.create()` тихо
нічого не анімують.

### ⚠️ Знайдений і виправлений баг: `.chain()` НЕ реєструє другу ланку в групі
Перша реалізація хіт-фідбеку й disappear-анімації використовувала
`tweenA.chain(tweenB); TweenC.add(tweenA); tweenA.start();` — і крейти
переставали зникати повністю (застигали розтягнутими на punch-фазі),
а флеш/нахил не виглядав як задуманий ефект (застигав на пікові й лишався).
Причина, перевірена читанням `tween.cjs`: `.chain()` каже tweenA лише
покликати `tweenB.start()` при завершенні — `.start()` ставить
`_isPlaying=true`, але **не додає tweenB в жодну `Group`**. `Group.update()`
ітерує тільки тіли, додані через `Group.add()`, тож tweenB ніколи не
отримує `.update()`, назавжди застигаючи "playing" в останньому кадрі
tweenA. **Виправлення: додавати кожну ланку ланцюжка в групу окремо**
(`TweenC.add(tweenA); TweenC.add(tweenB);` — обидва, до `tweenA.start()`).
Підтверджено repro+fix через Playwright у scratchpad (консоль показувала
`onUpdate` для другої ланки, що ніколи не спрацьовував до фіксу).

`Tween.stop()` **каскадно зупиняє весь `.chain()`**, навіть якщо зараз
виконується вже ланка ланцюжка, а не голова (`stop()` завжди спочатку
кличе `stopChainedTweens()`, до перевірки `_isPlaying`) — це підтверджено
і лишається правильним механізмом "always kill or reuse tweens": досить
тримати посилання на ГОЛОВУ ланцюжка і кликати на ній `.stop()` (саме
зупинку це чіпляє коректно; сама помилка була тільки в реєстрації в групі).

Перед реалізацією користувач попросив **питати по кожному з 4 пунктів**, а
згодом дав ще правки під час перевірки — відповіді й правки (важливі для
майбутніх сесій):
- "Гроші" з Day 6 = те саме дерево, що вже рахує `ResourceC` (не окрема валюта).
- Pay Zone: гейм-дизайн "що буде після" — **не важливо**, лише сам механізм.
- HUD не існує і Day 6 його НЕ додає.
- Hit-feedback: короткий білий флеш ін-аут + нахил у протилежну від удару
  сторону і повернення.
- (правка) Гроші мають летіти **прямо з персонажа в Pay Zone** — без
  проміжної "UI-точки", яка була в першій версії.
- (правка) Pay Zone потребує **100** зібраних ресурсів, щоб зникнути (не
  просто ">0", як було спочатку). (Пізніше значення `RESOURCES_TO_CLOSE_ZONE`
  підкручено до **20** — див. секцію "прогрес-заповнення зони" нижче;
  сам механізм — "N доставлених закриває зону" — не змінився.)
- (правка) Кожен damage-stage крейта потребує **2 хіти**, не 1.

### 1. Hit feedback + disappearing (крейти) — ✅
`BreakablePropC`: матеріал кожного stage-меша **клонується один раз при
білді** (`buildStageVisual`) — без цього флеш одного крейта підсвітив би
ВСІ 18 крейтів одразу, бо всі стейджі всіх крейтів шарять один Material
з glb (перевірено по індексу матеріалу в самому glb). `HITS_PER_STAGE = 2`
— `hit()` рахує `prop.hitsOnStage`, і тільки на 2-му хіті стейдж
просувається/крейт руйнується; **кожен** хіт (і 1-й, і 2-й, якщо не
руйнує) грає `playHitFeedback` — один `Tween<{t}>` ланцюжком (flash-in
90мс -> flash-out 150мс, **обидві ланки додані в `TweenC` окремо**, див.
баг вище), в `onUpdate` одночасно виставляє `root.rotation` як
`baseRotation + tilt*t` (`baseRotation` теж збережений один раз при білді,
щоб повторні хіти під час ще не завершеного нахилу не накопичували дрейф
кута) і, зараз, **опасіті окремого additive-оверлей-меша** (`flashMesh`,
не лерп `material.color` — це вже пізніша правка, `material.color` на цих
unlit-крейтах виявився тихим no-op, див. секцію "Розширений hit-feedback"
нижче за повним поясненням). `tilt` рахується з `hitDirection`, який
передає `PlayerC` (`hitDirectionTo()` — attacker->target, XZ, нормалізований).

На хіті, що руйнує крейт (2-й хіт останнього стейджу) — окремий ефект
замість флешу/нахилу: **(оновлено пізніше)** зараз це sink+topple —
`root.position.y` занурюється вниз (`DESTROY_SINK_DEPTH`, `Quadratic.In`,
`DESTROY_SINK_MS`) з одночасним нахилом від удару (`DESTROY_TILT_ANGLE`,
той самий `tilt`-принцип, що й у hit-feedback), `root.visible=false`
виставляється в `onComplete`, а НЕ миттєво — фізика/обстакл-клінап
(`physicsBody.destroy()`, видалення з масивів) лишились синхронними в
момент хіта (гравець вже не натикається на нього, поки крейт ще візуально
занурюється). Це заміна першої версії (punch-scale 1 -> 1.15 `Back.Out` ->
0 `Quadratic.In`) — коли й чому саме на sink+topple, в чаті цієї сесії не
зафіксовано; якщо матимеш контекст, допиши сюди.

### 2–3. Money flying out of the player into the Pay Zone — ✅ (два ОКРЕМІ механізми)
Проміжна версія об'єднала "збір ресурсу" і "передачу в Pay Zone" в один
конвеєр, гейтований стоянням в зоні (`ResourceC` мав стейт `holding`, що
чекав `inZoneCheck()` перш ніж рахувати ресурс — тобто лічильник взагалі
не рухався, поки гравець не заходив в зону). Це **зламало базовий збір**:
ресурси лежали на землі й не зникали, якщо гравець ламав ящики далеко від
зони. Користувач уточнив: **збір має працювати як і раніше** (Day 5,
нічого спільного з Pay Zone), а гейтинг по стоянню в зоні має стосуватись
**лише окремого механізму "передачі" вже зібраного в зону**.

Фінальний дизайн (на момент Day 6) — `ResourceC` і `PayZoneC` повністю
незалежні:
- **`ResourceC`** — Day 5 логіка збору (`scatter` -> settle) без жодної
  згадки про Pay Zone/гравця/зону — просто "зібрав ресурс". Що саме
  відбувається ПІСЛЯ settle (миттєво рахується, чи летить кудись) —
  контролюється ззовні через `setFlyTarget()` (додано пізніше, див.
  "HUD" нижче — спочатку тут стояв просто `collect()` без польоту).
  `createVisual()` — публічний метод, що віддає клон іконки-ресурсу для
  чужого використання (зараз юзає `PayZoneC`).
- **`PayZoneC`** — окремо "зливає" вже зібране (`ResourceC.getCollectedCount()`)
  в зону, по одному ресурсу за раз, **тільки поки гравець стоїть в зоні**
  і є "хвіст" (`collected - deposited > 0`): кожні `DEPOSIT_INTERVAL`
  (0.3с) — новий `ResourceC.createVisual()` летить в зону (`Quadratic.InOut`,
  500мс) і зникає, `deposited++`. Звідки саме стартує цей політ — теж
  змінилось пізніше (див. "HUD" нижче).

### ⚠️ Знайдений і виправлений баг: `isPlayerInside` мав фіксований радіус замалий за фактичний розмір зони
Перша версія `isPlayerInside` рахувала XZ-відстань до пивота ноду й
порівнювала з `ZONE_RADIUS = 2` (підібраним на око зі скріншота). За
фактом гравець міг зібрати 20+ ресурсів, зайти всередину видимого
пунктирного квадрата — і нічого не відбувалось, бо реальний розмір зони
значно більший за коло радіусом 2. Перевірено вимірюванням: `new
Box3().setFromObject(payZoneNode)` дав `size ≈ [5.96, 0.09, 4.60]` (X/Z),
тобто прямокутник ~6×4.6, з центром зсунутим від origin (`min.x≈-2.89,
max.x≈3.06` — не симетрично!). Коло радіусом 2 покривало тільки малу
частку видимого квадрата, переважно по X.

**Виправлення**: `isPlayerInside` тепер рахує `Box3` один раз в `init()`
(`new Box3().setFromObject(payZoneNode)` — бере фактичну геометрію з
урахуванням трансформів, а не вгадану цифру) і перевіряє просте
point-in-rectangle по X/Z (`min <= pos <= max`), ігноруючи Y. Ніяких
магічних констант радіуса більше нема — footprint завжди відповідає
реальній мапі, навіть якщо художник поміняє розмір/форму зони.
**Урок**: для будь-якої майбутньої "чи гравець в зоні X" перевірки —
рахувати `Box3().setFromObject()` з реального ноду, не вгадувати
радіус/розмір на око зі скріншота.

### 4. Payzone disappearing — ✅ (потребує `RESOURCES_TO_CLOSE_ZONE` *доставлених*, не просто зібраних)
`PayZoneC.update()`: коли `deposited >= RESOURCES_TO_CLOSE_ZONE` (значення
на момент Day 6 було 100, зараз в коді **20** — підкручено пізніше, див.
"прогрес-заповнення зони"; в будь-якому разі це "N ресурсів фактично
долетіли в зону", не просто зібрані десь на мапі) — одноразово (`closed`
флаг) запускає `playDisappear()`: `scale 1->0` (`Quadratic.In`, 400мс),
`visible=false` в `onComplete`. Одноразово, назавжди (немає ре-спавну/
циклу — "що буде після" лишається не реалізованим за проханням
користувача). Пізніше (див. "прогрес-заповнення зони") цей самий
`playDisappear` розширений — тепер синхронно стискає ще й fill-overlay
квад, не тільки сам маркер зони.

### Best practices — де застосовано
- **Sequences**: усюди `.chain()` замість ручного стейт-машину (flash in->out,
  punch->shrink) — але **обов'язково додавати кожну ланку в `TweenC` group
  окремо** (див. баг вище) — `.chain()` сам лише стартує наступну ланку,
  не реєструє її для update-тіків.
- **Kill or reuse tweens**: `BreakableProp.hitTween` зберігає голову
  ланцюжка; `.stop()` перед кожним новим хітом і при `destroy()` (каскадно
  зупиняє й активну ланку, це підтверджено робочим). `PayZoneC`'s
  disappear — одноразовий по флагу (`closed`), тому без явного kill.

## HUD-лічильник + перенаправлення анімацій (2026-08-12)

Користувач попросив: (1) справжню 2D UI-іконку ресурсу з лічильником у
правому верхньому куті, "як на скріні" (темна округла табличка + іконка в
круглій рамці зліва + число справа), (2) ресурс замість миттєвого
зникнення має анімовано летіти ДО цього лічильника, (3) політ у Pay Zone
має бути ВІД лічильника до зони (не від гравця).

### Іконка
Витягнув сам PNG/WebP з тієї ж текстури `Icon_Wood`, яку вже юзає 3D-меш
`UI_Wood` (`src/resources/meshes/ZombiePunk_Map.glb`, `bufferView` з
`images[6]`) — маленьким одноразовим Node-скриптом (парсинг glb JSON-чанка,
пошук `images[].name === "Icon_Wood"`, зріз байтів з BIN-чанка за
`bufferViews[bufferView]`). Зберіг як `src/resources/images/icon_wood.webp`
(webp з альфа-каналом, 512×512). Новий `src/resources/images/images.ts`
експортує `iconWoodSrc = ConvertToBase64WhenRelease("./icon_wood.webp")` —
**той самий паттерн, що і `meshes.ts`** (той же helper з `@hitplay/ads_common`,
викликаний з файлу в ТІЙ САМІЙ директорії, що й ассет — важливо: цей
хелпер в dev/build режимі просто рядково замінює провідний `.` на
`resources` (`ConvertToBase64WhenRelease.js`), а окремий AST-плагін
(`convertToBase64InAST`), підключений через `defineConfigTemplate` в
`vite.config.js`, на build-time переписує сам виклик у справжній inline
`data:...;base64,...` — це працює для ВСІХ режимів (dev/build/export), не
тільки для "export").

### HudC.ts — новий контролер
DOM-паттерн підглянутий у `InstallBanner` з SDK (немає спільного
DOM-builder helper-а в пакетах, усе руками через `document.createElement`
+ власний `<style>`, що вставляється в `<head>`): статичний клас, монтує
DOM-елемент у `#ui` (SDK-контейнер, `position:absolute`, зафіксований
9:16 blocks — `calc(100vh*9/16)` × `100vh`, центрований — це і є "екран
гри", не весь браузер, тож `top/right` у % рахуються відносно НЬОГО).
`.resource-hud { pointer-events:none }` — щоб не перехоплював тач/клік від
джойстика під ним. Стиль — власний CSS, вигаданий (в проєкті НЕ було
жодного готового "плата/банер" стилю для запозичення — перевірено, в
`ui.css`/`main.css` нуль хітів на `border-radius`).

Другий обов'язок `HudC` — **світова точка** (`worldAnchor`, порожній
`Object3D`, дитина камери через `CameraC_internal.getCamera().add(...)`,
локальний офсет — спочатку `(1.0, 0.8, -2.2)`, потім підкручено до
`(1.0, 1.2, -2.0)` (див. нижче, чому)), яка приблизно проєктується туди,
де візуально сидить DOM-іконка. **Це не точний screen-to-world розрахунок**
(FOV/aspect не враховані математично) — просто підібраний на око офсет;
якщо HUD переїде/зміниться розмір екрану, можливо треба підкрутити
координати ще раз. `getWorldAnchorPosition()` — це і є точка, куди тепер
летять ресурси (`ResourceC.setFlyTarget`) і звідки стартує депозит-політ
(`PayZoneC.playDepositFlight`).

### Що змінилось у ResourceC/PayZoneC
- `ResourceC`: `scatter` -> settle -> (якщо `flyTarget` заданий, а тепер
  він завжди заданий — `HudC.getWorldAnchorPosition`) новий стейт
  `toTarget` (0.5с, smoothstep + згасаюча дуга вгору, прямо до лічильника)
  -> `collect()`. Без `flyTarget` — стара миттєва поведінка (fallback).
  **На відміну від попередньої версії — НЕ телепортується на позицію
  гравця перед польотом** (той крок був заточений під "летить З гравця",
  зараз відповідь користувача про сам HUD не згадувала цей крок, тож
  прибрав його — політ іде прямо з місця, де ресурс осів, до лічильника).
- `PayZoneC.playDepositFlight`: `from` тепер `HudC.getWorldAnchorPosition()`
  замість позиції гравця — "від лічильника до пей зони", як попросив
  користувач. Тригер (proximity до зони) не змінився — усе ще потребує
  стояння гравця в зоні, змінилась лише точка ВИЛЬОТУ візуалу.

Перевірено в браузері (Playwright, scratchpad): іконка рендериться коректно
(512×512 webp, валідний `data:` URI, `naturalWidth`/`naturalHeight` не 0),
лічильник в DOM оновлюється синхронно з `console.log`-ами збору (звірено
скріншотом — "8" на екрані == 8-й `[ResourceC] gathered wood` в консолі).

### Доопрацювання: лічильник має бути "живим балансом", не lifetime-total (2026-08-12)
Спочатку `HudC` показував `ResourceC.getCollectedCount()` напряму — тобто
lifetime-суму, яка ТІЛЬКИ росте (депозит в Pay Zone на неї не впливав).
Користувач попросив: число має рости при зборі І **зменшуватись при
депозиті** — тобто показувати поточний "баланс", а не історичний тотал.

Розв'язання без нової мутабельної змінної (і без циклічного імпорту —
`PayZoneC` вже імпортує `HudC` для `getWorldAnchorPosition()`, тож
`HudC` імпортувати `PayZoneC` напряму означало б цикл):
- `PayZoneC.getDepositedCount()` — новий публічний гетер, повертає
  внутрішній `deposited` (лічильник, який і раніше рахував "скільки вже
  влетіло в зону", просто не був назовні доступний).
- `HudC.setBalanceGetter(fn)` — інжектований гетер (той самий паттерн, що
  й `ResourceC.setFlyTarget`/`onDestroyed` в `BreakablePropC`), замінив
  пряму залежність `HudC -> ResourceC`. `HudC` більше НЕ імпортує
  `ResourceC` взагалі.
- `TestSceneC` зв'язує: `HudC.setBalanceGetter(() =>
  ResourceC.getCollectedCount() - PayZoneC.getDepositedCount())` — чиста
  похідна величина, рахується на льоту щокадру в `HudC.update()`, без
  жодного окремого "decrement"-виклику. Росте коли `collected` росте
  (щось зібрали), падає коли `deposited` росте (щось долетіло в зону) —
  саме по собі, без спеціальної синхронізації.

Перевірено: зібрав 7 ресурсів (консоль: `gathered wood (7 total)`), весь
цей час стояв в Pay Zone -> усі 7 злились в зону протягом ~2.1с
(`DEPOSIT_INTERVAL=0.3` × 7) -> лічильник на екрані повернувся до **0**,
хоча `collected` лишився 7 — підтверджує, що баланс дійсно "живий", а не
lifetime-сума.

### Доопрацювання: точка вильоту ресурсів була занизько (2026-08-12)
`WORLD_ANCHOR_LOCAL_OFFSET` підняли з `(1.0, 0.8, -2.2)` до
`(1.0, 1.2, -2.0)` — більший Y (вище в camera-space) і трохи менший |Z|
(ближче до камери, тому той самий Y дає більше вертикальне зміщення на
екрані через перспективу) — все ще підібрано на око, не розраховано
математично з FOV/aspect. **Це найбільш "на око" підібрана частина
роботи — якщо після цього фіксу політ все ще не влучає точно в іконку,
підкрутити ці три числа ще раз** (в `HudC.ts`).

## Камера: прибрано `lookAt`, лінійне зміщення замість орбіти (2026-08-12)

Фідбек від ментора користувача: замість `lookAt`-based слідкування камери
за персонажем — краще визначити точку біля персонажа і зміщувати камеру
відносно неї, залежно від напрямку погляду персонажа. Уточнення від
користувача: **без orbit-behind** — це має бути суто лінійне зміщення
позиції, кут камери взагалі не повинен обертатись.

### Що було
`CameraFollowC.update()` щокадру: (1) демпінгував позицію камери до
`targetPosition + offset + lookAhead` (це вже було чисте лінійне
зміщення — `lookAhead` — той самий "зсув в напрямку погляду персонажа",
про який казав ментор, він вже існував), (2) **окремо** демпінгував
`smoothedLookAt`-точку і кожен кадр робив `camera.lookAt(smoothedLookAt)`
— тобто поворот перераховувався з нуля щокадру з двох незалежно
згладжених точок, а не одного узгодженого стану.

### Що зроблено (перша ітерація)
- Прибрано `smoothedLookAt`, `LOOK_DAMPING`, і сам виклик `camera.lookAt()`
  з `update()` повністю. Позиційна частина (`offset` + `lookAhead` +
  obstacle-avoidance raycast) лишилась незмінною — вона й раніше була
  чистим translation, без жодного обертання.
- Поворот камери відтепер **виставляється один раз** в `init()`:
  `camera.position.copy(target.position).add(offset); camera.lookAt(target.position);`
  — і після цього `update()` більше НІКОЛИ не торкається `camera.rotation`/
  `camera.quaternion`. Кут "заморожений" геометрично на старті й лишається
  таким назавжди, скільки б персонаж не розвертався.

### Доопрацювання: навіть без обертання камери відчувався рух "по колу" (2026-08-12)
Користувач: коли персонаж РОЗВЕРТАЄТЬСЯ (не рухаючись при цьому), камера
все ще відчутно "йде по колу". Причина — той самий `lookAhead`-вектор, що
лишили в першій ітерації: він рахувався з напрямку, куди персонаж
**дивиться** (`facing`, з `target.quaternion`), а не куди рухається.
Навіть згладжений (`LOOK_AHEAD_DAMPING`), він все одно ОБЕРТАЄТЬСЯ разом
з поворотом персонажа (наприклад, коли той розвертається на місці, щоб
глянути на ящик) — а що обертається, те й тягне позицію камери по дузі
навколо персонажа, хай і невеликій. Користувач хотів буквально "2 точки і
пряма між ними" — жодної залежності від напрямку погляду.

**Перша спроба**: прибрав `lookAhead` повністю (`desiredPosition =
targetPosition + offset`, без жодного додаткового вектора). Круговий рух
дійсно зник, але користувач одразу зауважив: зникло й саме зміщення —
"раніше зміщення було підходяще, єдина проблема була в тому, що воно йшло
по колу". Тобто магнітуда/факт панорамування був потрібен, просто НЕ
прив'язаний до повороту.

**Фінальне виправлення**: `lookAhead` вернув, але тепер рахується з
**реального зміщення позиції персонажа між кадрами**
(`targetPosition - previousTargetPosition`), а не з `target.quaternion`.
`previousTargetPosition` — нове поле, оновлюється щокадру. Якщо кадровий
рух менший за `MOVEMENT_EPSILON_SQ` (стоїть на місці — байдуже, як
розвернутий) — цільовий look-ahead = нульовий вектор; якщо рухається —
нормалізований напрямок руху × `LOOK_AHEAD_DISTANCE` (та сама магнітуда,
що й була). Обидва варіанти йдуть через той самий `smoothedLookAhead.lerp`
з `LOOK_AHEAD_DAMPING`, як і раніше — тільки джерело напрямку інше.
Результат: розворот на місці = нуль руху = камера взагалі не рухається;
ходьба = той самий пан вперед, що й був до всіх цих правок.
**Урок**: "згладжений вектор, що обертається з об'єктом" все одно
читається як орбітальний рух — згладжування прибирає різкість, а не
кривизну; правильний фікс — прив'язати джерело напрямку до РУХУ
(position delta), а не до facing/quaternion, а не просто видалити ефект.

Перевірено в браузері (Playwright) — рендер коректний з першого кадру і
після ходьби/бою, без console-помилок.

### Доопрацювання ×3: зовсім не відчувалось, тримати зсув, миттєвий розворот на 180° (2026-08-12)
Після руху-based lookahead користувач: "Немає зміщення взагалі". Причина —
не баг у логіці (перевірив логуванням, числа рахувались вірно), а те, що
**стара `lookAt`-версія давала подвійний ефект** (і зсув позиції, і
доворот камери в той же бік щокадру), а зараз лишився тільки зсув позиції
— і сама позиційна складова (`LOOK_AHEAD_DISTANCE=1.2`) була занадто
малою, щоб щось означати з відстані ~12.7 од. (`(0,9,-9)` риг). Підняв до
`4`, користувач сам потюнив назад до **`2`** (лишив цю зміну, не
відкатувати).

Ще дві правки в тому ж повідомленні:
- **"Камера після зсуву не має повертатись назад"** — `desiredLookAhead`
  тепер **окреме поле**, не локальна константа: оновлюється (`.copy(movement)...`)
  ТІЛЬКИ коли `movement.lengthSq() > MOVEMENT_EPSILON_SQ`, і просто НЕ
  чіпається, коли персонаж стоїть — замість `: new Vector3()` (нуль) в
  тернарному операторі, як було. Тобто пан тримається на місці, де
  зупинився, а не з'їжджає назад до центру, поки не з'явиться новий, ІНШИЙ
  напрямок руху.
- **"Зроби анімацію плавнішою"** — `LOOK_AHEAD_DAMPING` знижений з `2` до
  `1.2` (повільніший ease).
- **"Персонаж має розвертатись моментально, якщо ми змінюємо напрям на
  протилежний"** — це вже не про камеру, а про `PlayerC` (`updateMovement`):
  новий `OPPOSITE_TURN_THRESHOLD = Math.PI * (150/180)` (~150°). Якщо кут
  між поточним і цільовим facing (`quaternion.angleTo(...)`) перевищує цей
  порог — `quaternion.copy(facingRotation)` миттєво, інакше — старий
  капований `rotateTowards(facingRotation, MAX_TURN_SPEED * delta)`. Тобто
  тільки різкі розвороти "в протилежну сторону" миттєві, дрібні корекції
  курсу лишаються плавними, як і були.

### ⚠️ Знахідка: `camera_rotation_p`/`camera_rotation_l` (дизайнерський конфіг) виявився нежиттєздатним самостійно
Спочатку спробував залишити кут камери таким, яким його виставляє
`CameraC.setCamera()` з конфіг-параметрів `camera_rotation_p`/`_l`
(дизайнер може їх тюнити через UI) — просто прибравши `lookAt` і НІЧОГО
більше не додаючи. Результат: **порожнє темно-синє небо**, ні мапи, ні
персонажа в кадрі. Причина: цей конфіг-кут ніколи насправді не був
призначений працювати самостійно — `CameraFollowC` з першого ж комміту,
що його додав, миттєво перезаписував поворот через `lookAt()` щокадру,
тож ніхто й не міг помітити (чи потребу) тюнити `camera_rotation_p` під
реальний рух — він був "мертвим" параметром, що впливав щонайбільше на
один кадр до першого `update()`.

**Виправлення**: не покладатись на цей конфіг взагалі для follow-камери —
рахувати фіксований кут геометрично з реального `offset` (`(0,9,-9)`) в
момент `CameraFollowC.init()` (описано вище). Це гарантовано framing
персонажа з самого старту, незалежно від того, що зараз стоїть в
`camera_rotation_p`. **Урок**: значення з `configUIParams`/`globalSettings`
не завжди відображають те, що реально відбувається в грі — перевіряти,
чи щось інше (як тут `CameraFollowC`) не перезаписує їх одразу після
встановлення, перш ніж покладатись на них як на джерело правди.

Перевірено в браузері (Playwright): після фіксу сцена рендериться коректно
з самого старту (мапа/персонаж/крейти на місці, кут ідентичний
попередньому вигляду), і лишається так само коректно framed після
ходьби/бою/розвороту персонажа — камера просто зсувається лінійно, кут
не змінюється.

## Камера підлаштовується під facing-lock на крейт (2026-08-12)

Користувач: коли персонаж зупиняється біля ящика і "тригер збору"
(`PlayerC.faceTowards`, викликається з `updateMovement` коли `stopped &&
nearbyObstacle`) розвертає його лицем до цілі, камера має підлаштовуватись
під новий кут, а не лишатись байдужою. Це саме той кейс, який попередній
рух-based `lookAhead` **свідомо** ігнорував (розворот на місці = нульовий
`movement` = look-ahead не оновлюється) — правильна поведінка для
довільного розвороту, але користувач хотів виключення саме для facing-lock
на breakable-ціль.

**Рішення без повернення до facing/quaternion-залежності** (яка й дала
"рух по колу" раніше): `PlayerC` тепер зберігає, на яку саме ТОЧКУ (не
кут!) він зараз locked — `facingTarget: Vector3 | null`, виставляється в
`updateMovement()` в той самий момент, коли викликається `faceTowards()`
(і скидається в `null`, коли умова `stopped && nearbyObstacle` неправдива).
Публічний `PlayerC.getFacingTarget()`.

`CameraFollowC.setFacingTargetGetter(getter)` — injected getter (той самий
DI-паттерн, що й `ResourceC.setFlyTarget`), підключено в `TestSceneC.init()`
відразу після `CameraFollowC.init()`. В `update()`: якщо `facingTarget` не
`null` — `desiredLookAhead` рахується як напрямок від гравця ДО цієї точки
(XZ, нормалізований) × `LOOK_AHEAD_DISTANCE`, замість напрямку руху; інакше
— стара логіка (рух або hold). Ключове: джерело — фіксована ТОЧКА в
world-space (`nearbyObstacle.center`), а не обертовий вектор — поки гравець
і ящик обидва стоять на місці, цей напрямок сам по собі константний, тож
`smoothedLookAhead.lerp(...)` дає один плавний лінійний зсув до нової
позиції й ЗУПИНЯЄТЬСЯ там, а не описує дугу (на відміну від
facing/quaternion-based версії, яка оберталась разом з тілом персонажа).

Перевірено (Playwright, тимчасове логування `window.__dbgFacing`/
`__dbgLookAhead`, видалене після): після зупинки біля крейта
`facingTarget` стає non-null, і `smoothedLookAhead` плавно зсувається від
~`(-0.02, 1.46)` до нового значення (`(-1.03, 1.08)` і триває сходитись) —
камера реально підлаштовується, а не стоїть на місці.

## Два хіти за один цикл анімації атаки (2026-08-12)

Користувач: анімація "Loot" (удар битою) сама показує **2 фізичні удари**
за один цикл кліпу, але код досі рахував лише **1** damage-пульс за цикл
(`HIT_TIME_FRACTION=0.5`, раз на `attackAction.getClip().duration`) — тобто
`HITS_PER_STAGE=2` вимагав 2 повних циклу анімації на просування стейджа,
хоча мало вистачати одного.

**Виправлення**: `HIT_TIME_FRACTION` (одне число) замінено на
`HIT_TIME_FRACTIONS = [0.25, 0.75]` (масив — дві точки за цикл; підібрані
навмання як симетричний дефолт, можуть потребувати підстройки під реальний
тайминг замаху в кліпі, як і `LOOK_AHEAD_DISTANCE` раніше). Новий
`PlayerC.hitsThisAttack` (рахує ВСІ хіти за весь безперервний свінг, не
скидається щоцикл) + `hitTimeFor(hitIndex)` — рахує абсолютний час
(секунди від старту атаки) для N-го хіта: `duration * (повних_циклів +
HIT_TIME_FRACTIONS[hitIndex % 2])`, тобто коректно переходить через межу
циклу без дрейфу.

Перевірено (Playwright, тимчасове логування `[dbgHit]` з таймстемпом,
видалене після): хіти йдуть з рівним інтервалом ~780мс (замість колишніх
~2×780=1560мс), і стейдж (`prop.stageIndex`) просувається після кожних 2
хітів (`0,1` -> stage++), тобто рівно один цикл анімації = один
просунутий стейдж, як і треба.

## Розширений hit-feedback на крейтах: спарки, HP-бар, числа урону (2026-08-12)

Користувач показав референс-скріншоти з іншої гри (damage-numbers, HP-бар,
іскри в точці контакту) і сказав, що зараз у нас із фідбеку на хіт **лише
невеликий нахил** — флеш кольору, який мав бути з Day 6, візуально не
працює. Плейл поступово (по одному ефекту, з перевіркою між кроками).

### ⚠️ Знайдений і виправлений баг: флеш кольору був тихим no-op з самого Day 6
`playHitFeedback` лерпив `material.color` від `baseColor` до `FLASH_COLOR`
(білий) — але залогувавши реальний матеріал crate-мешів (`MeshBasicMaterial`,
`color: #ffffff`, без `emissive` — це не Standard/Phong), виявилось, що
**`baseColor` вже й був чистим білим**. Текстура дає весь реальний колір,
тінт-колір лишався на дефолтному білому — лерп "білий -> білий" не змінює
візуально НІЧОГО, tween виконувався справно (перевірено таймингом), просто
результат був непомітний. `MeshBasicMaterial` — unlit, `color` множиться на
текстуру, тож "яскравіше за білий" через цей канал взагалі неможливо.

**Виправлення**: замість лерпу `.color` — `StageVisual.flashMesh`, клон тієї
самої mesh-геометрії (`mesh.clone()`), покладений зверху з власним
`MeshBasicMaterial({ color: FLASH_COLOR, transparent: true, opacity: 0,
blending: AdditiveBlending, depthWrite: false })`. Флеш тепер анімує
`flashMesh.material.opacity` (0→1→0) замість кольору базового меша —
працює незалежно від того, який в оригінала колір/текстура, бо це
адитивний шар зверху, а не множник. **Побічний ефект**: `flashMesh` — це
ще один mesh під `map`, тож `TestSceneC`'s `ThreeC.setShadowsStateForChildren
(map, true, true)` (виконується ПІСЛЯ `BreakablePropC.init()`) увімкнув би
йому shadows теж — додано `BreakablePropC.disableFlashShadows()`, викликаний
з `TestSceneC` одразу після цього рядка, щоб вимкнути назад (даремний
shadow-caster на майже завжди прозорому оверлеї).

Перевірено (Playwright, серія скріншотів кожні 80мс під час бою): крейт у
кадрі точно на позначці очікуваного хіта помітно біліший/яскравіший, ніж у
кадрах до/після — флеш реально видно, на відміну від попередньої версії.

**Урок**: тінт-колір (`material.color`) на unlit-текстурованому меші не дає
"флешу", якщо колір вже білий (звичайний дефолт) — для видимого
hit-flash-у на такому матеріалі потрібен окремий адитивний оверлей-шар, а
не лерп самого кольору. Якщо десь ще знадобиться подібний ефект на
текстурованому unlit-меші — той самий підхід (clone + additive overlay).

### Іскри в точці контакту — v1 hand-rolled, замінено (2026-08-12)
Перша версія — новий `SparkFxC.ts`, ручно зібраний `ParticleSystem` (білі
квадратні частинки, `SphereEmitter(radius:0.05)`, звичайний `BillBoard`).
Технічно працював (Playwright підтвердив спалах у момент хіта), але
користувач подивився і сказав: **"Іскри не підходять, це мають бути як
промені. Саме такі як на скріні"** — потрібні тонкі промені-стріки, не
блоб з крапок. Перебудував рендер на `RenderMode.StretchedBillBoard`
(розтягує квад уздовж власної швидкості частинки — це і дає "промінь", а
не крапку) + `speedFactor`, `ColorOverLife`+`Gradient` для згасання альфи.
Це вже виглядало краще, але тут користувач відкрив `temp/VFX_Lootable_Destroy.json`
у редакторі й запитав, що в цих файлах — і виявилось, що це змінює все.

### ⚠️ Знахідка: в `temp/` лежали готові дизайнерські VFX-префаби, повністю невикористані
`temp/VFX_Lootable_Hit.json`, `temp/VFX_Lootable_Destroy.json` (+
`PassionOne-Black.otf` — шрифт, ще не використаний, ймовірно для майбутніх
чисел урону/HUD) — це **справжні експорти з редактора quarks.art**
(`Object3D.toJSON()` на `Group` з `ParticleEmitter`-дітьми, кожен зі своїм
готовим, підібраним дизайнером `ps` — shape/speed/color/behaviors, і
реальними текстурами, вбудованими як base64: `cfxr stretch smoke arc
dissolve.webp`, `novalines.webp` — назва "novalines" **буквально "лінії
нової" = промені-риски**, це саме те, що користувач мав на увазі скріном).
`VFX_Lootable_Hit` = 2 емітери ("StretchSmoke" + "SharpImpact" — це і є
ray-burst). `VFX_Lootable_Destroy` = 4 емітери (дим, уламки-Pieces,
Ground_Dirt як реальна 3D-mesh геометрія (`renderMode: Mesh`), пилова хмара).
**Жодного SDK/іншого коду проєкту ці файли не використовували взагалі** —
чисто сирі ассети, що чекали на підключення. Замінив увесь ручний
`SparkFxC` на завантаження цих реальних префабів — жодна власноруч
підібрана крива/швидкість не заміняє справжній дизайнерський ассет.

**Що таке VFX**: "visual effects" — тут конкретно означає one-shot
частинкові ефекти (спалахи/дим/уламки), авторовані окремо в
редакторі quarks.art і експортовані як самодостатній JSON (геометрія +
матеріали + текстури-base64 + вже налаштовані `ParticleSystem` параметри
для кожного емітера) — не код, чистий даних-ассет, який рушій (`three.quarks`)
вміє розпарсити назад у робочі `Object3D`.

### `PropVfxC.ts` — новий контролер, замінив `SparkFxC.ts`
Завантажує обидва префаби ОДИН РАЗ при `init()` через сирий
`QuarksLoader` (`three.quarks`) + `Template3d.manager` (`@hitplay/playable_template`),
**НЕ** через SDK-хелпер `quarksLoader()`/`ConvertToBase64WhenRelease`
(паттерн `meshes.ts`/`images.ts`) — свідомо, з причини:

**⚠️ Чому не той самий паттерн, що і images/meshes**: `quarksLoader(base64String)`
жорстко очікує рядок формату `data:...;base64,XXXX` (робить
`base64String.split(",")[1]` потім `atob(...)`). Це працює лише ПІСЛЯ
build-time AST-трансформації (`convertToBase64InAST`, підключена в
`vite.config.js`), яка й замінює виклик `ConvertToBase64WhenRelease()` на
реальний base64 рядок. У **звичайному `vite dev`** (як я весь час тестую
через Playwright!) сам хелпер — лише прохідний passthrough, що повертає
ГОЛИЙ ШЛЯХ (`"resources/vfx/....json"`) без коми — `.split(",")[1]` дав би
`undefined`, і `atob(undefined)` зламав би завантаження саме в dev-режимі,
хоча в build/export він працював би. Замість цього ризику — звичайний
Vite JSON-імпорт (`import json from "../resources/vfx/VFX_Lootable_Hit.json"`),
який Vite вміє інлайнити нативно в БУДЬ-ЯКОМУ режимі (dev/build/export)
без жодного fetch — і сирий `new QuarksLoader(Template3d.manager).parse(json)`
(синхронний, повертає `Object3D` напряму, `onLoad` callback не потрібен,
бо всі текстури вже base64 в самому JSON, немає мережевого чекання).
Додав `"resolveJsonModule": true` в `tsconfig.json` (був відсутній) — без
цього `tsc` (не сам vite/esbuild — ті й так все розуміють) скаржився б на
JSON-імпорт типами.

`PropVfxC.spawnHit(point)`/`spawnDestroy(point)` — клонують відповідний
завантажений шаблон (`.clone()` на `Group`), виставляють `position`,
форсують `QuarksUtil.setAutoDestroy(instance, true)` (в оригінальних
префабах `autoDestroy: false` — дизайнер, ймовірно, керував завершенням
вручну в своєму інструменті; нам потрібен чистий "one-shot і забути"),
`QuarksUtil.addToBatchRenderer(instance, renderer)` (реєструє КОЖЕН
`ParticleEmitter` в дереві з рендерером — без цього нічого не малюється),
`QuarksUtil.play(instance)`. Кожен `ParticleSystem` з `autoDestroy`
прибирає СЕБЕ (свій `ParticleEmitter`-нод) з дерева, коли його частинки
померли — але порожній корінь-`Group`, який я додав в сцену, сам не
видаляється (нема кому), тож прибираю його окремим `setTimeout`
(`CLEANUP_DELAY_MS=1500`, з запасом під найдовший `duration+life` в обох
префабах).

`BreakablePropC.playHitFeedback` кличе `PropVfxC.spawnHit(contactPoint)` на
кожному хіті (як і раніше з `SparkFxC`); `BreakablePropC.destroy()`
додатково кличе `PropVfxC.spawnDestroy(...)` в позиції крейта — цього не
було в hand-rolled версії взагалі (не було Destroy-ефекту), додав одразу,
бо це буквально друга половина того самого знайденого ассета.

### ⚠️ Знахідка (потребує рішення користувача, ще не виправлено): "StretchSmoke"-шар вилітає далеко від крейта і виглядає як артефакт
Перевірено в браузері (Playwright): "SharpImpact" (промені/nova-спалах,
`novalines.webp`) рендериться коректно ПРЯМО на крейті в момент хіта —
саме той ефект, що відповідає скріну користувача. Але другий емітер того
самого префаба, "StretchSmoke" (`startSpeed:14`, `worldSpace:true`, життя
0.2-0.3с — тобто до ~4 world units прольоту по прямій!), у нашій сцені
летить ДАЛЕКО від крейта (видно на скріні як сірувата паличка десь у
верхній частині екрана, повністю відірвана від точки удару) — швидше за
все, дизайнер тюнив цей ассет під інший масштаб сцени/камери. Це
відтворюється на КОЖНОМУ хіті (не витік/застигла частинка — просто кожен
новий хіт заново вилітає в приблизно те саме "неправильне" місце).
**Ще не виправлено** — варіанти: (а) лишити як є (автентичний ассет), (б)
притлумити цей конкретний емітер (зменшити `startSpeed`/життя клоном
префаба перед грою), (в) прибрати "StretchSmoke" зовсім і лишити тільки
"SharpImpact". Потребує візуальної перевірки користувачем — не вирішував
сам, це пряма зміна дизайнерського ассета.

Destroy VFX (`VFX_Lootable_Destroy`, 4 емітери включно з mesh-based
"Ground_Dirt") підключений і не кидає помилок в консолі, але **ще не
підтверджений візуально** — не вдалось надійно спричинити повне
знищення крейта в тестовому прогоні за відведений час.

### Наступні кроки (ще не реалізовано, чекає на пріоритети користувача)
HP-бар (потребує рішення: дискретні стейджі vs. реальний HP-пул?) і числа
урону (DOM чи sprite в 3D-просторі? теж потребує реального numeric HP,
якого зараз нема) — ще не почато. `PassionOne-Black.otf` (в `temp/`,
ще не імпортований) — ймовірно призначений саме для цього.

## PayZoneC: прогрес-заповнення зони + два реальні знайдені баги (2026-08-12)

Користувач попросив візуальний індикатор заповненості Pay Zone (скільки з
`RESOURCES_TO_CLOSE_ZONE` вже занесено). Три ітерації дизайну (кожна —
реальна правка коду, не просто обговорення):
1. Горизонтальний квад на землі, що росте вздовж world X — користувач:
   "заповнюється... з права на ліво" (не те, що хотів).
2. Box, що росте вгору по Y (буквально "як вода в басейні") — виявився
   концептуально хибним: верх/низ box-а завжди займають весь footprint
   незалежно від висоти, тож з ізометричної камери зона виглядала "одразу
   заповненою" на будь-якій висоті > 0.
3. **Фінал**: плаский квад на землі знову, але росте вздовж world Z (не X)
   — з цієї камери (`CAMERA_OFFSET=(0,9,-9)`, дивиться в +Z) рух вздовж +Z
   проєктується на екран як "знизу вгору", що і є тим "від краю до краю",
   про яке просив користувач. Пінінг біля min-Z (найближчий до камери
   край), колір `0x5ce65c` (зеленуватий).

### ⚠️ Знайдений і виправлений баг: депозит-політ інколи застигає в повітрі навіки
Користувач показав скріншот: статична текстура ресурсу, що просто висить
у повітрі. Трасував через тимчасове логування (spawn/complete ID на кожен
`playDepositFlight` — окремий `Tween`, не chain, коректно `TweenC.add()`-
нутий ПЕРЕД `.start()`) — підтвердив: рідко (не щоразу) `onComplete` просто
не спрацьовує, і клон застигає точно на прямій між HUD-точкою і зоною, на
довільному t. Причину всередині `tween.js`/`TweenC` не знайшов (це не той
самий баг з `.chain()` з Day 6 — тут узагалі нема chain). **Замість
подальшого копання — надійний дублюючий `setTimeout`**, що прибирає mesh
через `DEPOSIT_FLIGHT_DURATION_MS + 300мс` незалежно від того, чи
спрацював `onComplete`. Викликати `removeFromScene` двічі — нешкідливо
(другий викоик просто не знаходить батька для detach).

### ⚠️ Знайдений і виправлений баг: `"UI_Wood.001"` в коді не збігається з реальною назвою ноду
Користувач наполягав, що "текстура дерева" в центрі Pay Zone нікуди не
зникає, хоча по черзі виключив усі мої гіпотези (крейти всередині зони,
застиглий ресурс). Трасував живу сцену (`ThreeC.scene.traverse`, шукаючи
все з "UI_Wood" в імені, друкуючи ланцюжок `visible` від ноду до кореня) —
і ось воно: нод з raw glb JSON названий `"UI_Wood.001"` (з крапкою,
підтверджено прямим парсингом бінарника), але в ЖИВІЙ Three.js сцені після
завантаження він `"UI_Wood001"` (**без крапки** — щось у пайплайні
завантаження її стирає). `TestSceneC.createMap()` шукав
`map.getObjectByName("UI_Wood.001")` — рядок ніколи не збігався,
`getObjectByName` тихо повертав `undefined`, `if (woodIconAlt)` була
`false`, і `.visible=false` НІКОЛИ фактично не виконувався — попри те, що
код виглядав абсолютно правильним і "мав" би працювати. Виправлення:
рядок-літерал змінено на `"UI_Wood001"` (без крапки), підтверджено
трасуванням живої сцени, що тепер `visible=false` реально застосовується.
**Урок**: коли `if (identifiedNode)`-гард ЗАВЖДИ хибний (вузол ніби існує
в GLB, але код його "не бачить") — перевіряти РЕАЛЬНЕ ім'я в ЖИВІЙ сцені
(`scene.traverse` + лог імені), не тільки в сирому GLB JSON — завантажувач
може мовчки переписувати рядки (крапки, ймовірно, конфліктують з якоюсь
внутрішньою угодою іменування).

Побічно: під час полювання на цей баг зробив (і одразу відкотив на
прохання користувача) дві помилкові гіпотези-фікси — приховання
`UI_Interactive_Zone_02` (сам маркер зони) і видалення `Wooden_Box_016`/
`Wooden_Box_017` (2 крейти, що геометрично сидять майже точно в центрі
зони, ~0.18 і ~0.99 одиниць від центру — підтверджено обчисленням world
position прямо з GLB node transforms). Жодна з цих гіпотез не була
причиною — обидві повернуто як були. Крейти в зоні — це може бути окрема,
самостійна проблема левел-дизайну (вони справді там стоять), але це
свідоме рішення НЕ трогати без окремого прямого запиту користувача.

- Working tree на момент старту Day 5: `PlayerC.ts` мав незакомічені правки
  (accel/decel рух, рефакторинг attack-facing на helper-и) — вони увійшли в
  фінальну версію файлу (переписаний повністю, логіка руху збережена).
- Свідоме рішення: не рефакторити робочий AABB рух гравця під фізику; після
  видалення тригерів у гравця взагалі немає cannon `Body` — тільки AABB.
- `ResourceC`/`BreakablePropC` — нові файли. `PlayerC.ts`/`TestSceneC.ts`/
  `PhysicsC.ts` — модифіковані. `CameraFollowC.ts`/`ThreeC.ts` — не торкались.
  `TriggerC.ts` — був створений і видалений в межах цієї ж сесії (див. "Файли").
- Ще не закомічено в git (working tree) — користувач сам вирішує коли
  комітити.
- Якщо наступного разу знову треба буде правити combat: зона ураження —
  та сама `INTERACTION_REACH`-аура, що й раніше використовувалась для
  single-target пошуку (`findNearbyObstacle`, лишився для косметичного
  idle-facing), просто тепер є окремий `findBreakableTargetsInZone` без
  обмеження на кількість цілей.
- Day 6 (Tween): `TweenC.init()` викликається один раз в
  `beforeResourcesLoadedCb.ts` — якщо колись переносити фізику/tween-бутстрап
  в інше місце, не забути перенести й це, інакше всі `TweenC.add()` тихо
  ні на що не впливають (сама `Group` існує, просто ніхто її не `.update()`-ить).
- `PayZoneC.init(payZoneNode, target)` МАЄ викликатись після `PlayerC.init()`
  в `TestSceneC` (потребує реальний `PlayerC.object`, не просто позицію) —
  уже виправлено (виклик з `TestSceneC.init()`, не з `createMap()`), просто
  важливо не переносити назад.
- **Будь-який новий `.chain()` в цьому проєкті — додавай ОБИДВІ (усі) ланки
  в `TweenC` окремо** (`TweenC.add(a); TweenC.add(b); a.start();`), інакше
  повториться баг вище: друга ланка "грає" за прапорцем, але update() на
  неї ніхто не кличе, і вона застигає навічно.
- **Важливий урок з цієї сесії**: "збір ресурсу" (`ResourceC`) і "передача
  в Pay Zone" (`PayZoneC`) — два НЕЗАЛЕЖНІ механізми, і мають лишатись
  такими. Не гейтувати `ResourceC.collect()` жодною умовою про гравця/зону
  — це те, що вже одного разу зламало базовий збір (ресурси лежали на
  землі й не зникали). Будь-яку майбутню умову про "стояння в зоні" чіпляти
  тільки на стороні `PayZoneC` (він і так окремо стежить за
  `getCollectedCount()` — `deposited`, тобто "хвостом" з незданого).
- **Ще один урок**: не вгадувати розмір/радіус тригер-зони на око зі
  скріншота — рахувати з реальної геометрії (`Box3().setFromObject(node)`).
  Саме це зламало `PayZoneC.isPlayerInside` (радіус=2 замалий за фактичний
  прямокутник ~6×4.6, ще й не центрований на origin).
- Ручна перевірка (флеш/нахил крейтів, повне зникнення після 2 хітів на
  стейдж, базовий збір ресурсів без прив'язки до зони, злив ресурсів у Pay
  Zone тільки при стоянні там — тепер по реальному Box3, не вгаданому
  радіусу, зникнення зони після `RESOURCES_TO_CLOSE_ZONE` доставлених
  (100 на момент цього запису, зараз 20 — див. "прогрес-заповнення зони"),
  відсутність зайвих текстур навколо Pay Zone) — стан на кінець Day 5/6;
  усе, що сталось після (HUD, камера, VFX, прогрес-бар зони), має власні
  "Перевірено" нотатки нижче за текстом.