Utility and polishing + bag fixes

docs/worklog/08-payzone-fill-progress.md

@@ -0,0 +1,110 @@
+# 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` — був створений і видалений в межах цієї ж сесії (див. "Файли").
+- Закомічено й запушено в `origin/master` 2026-08-12 (commit `4a22a9b`,
+  "Add physics/combat foundation, resource pickup flow, VFX polish, and
+  HUD") — усе, що описано в цьому файлі до Day 8 включно, вже в репо.
+  `stats.html` (rollup-visualizer, артефакт білда) свідомо НЕ закомічено —
+  не вихідний код, генерується заново при білді.
+- Якщо наступного разу знову треба буде правити 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, прогрес-бар зони), має власні
+  "Перевірено" нотатки нижче за текстом.