RUBLOX_LUA_API_CHANGELOG.md

@@ -8,6 +8,82 @@ Roblox-играми. Цель — потом продублировать тот
 
 ---
 
+## 2026-06-08 — Итерация 4: Spawn-fix + философия импорта
+
+**Контекст:** МИН подтвердил после ROBLOX Battle: 100% покрытие Lua-скриптов
+из Roblox не получится (наш wasmoon не yield'ит из JS C-call boundary,
+старый Roblox-pattern WaitForChild через ChildAdded:wait тривиально вешает
+страницу). **Цель импорта сменилась**: показать геометрию и базовые
+интеракции, а не полную скриптовую логику.
+
+### Spawn fix (карта проекта 2853)
+
+После переимпорта одной из карт игрок появлялся **внутри Anchored
+геометрии** (стена/пол), не мог двигаться. Причина: SpawnLocation в старых
+.rbxl ставится впритык к плите (Y+0.5), наш отступ +1.5 не спасал от
+толстых Floor'ов 2-3 units high. Anchored=True (наш force-fix) не давал
+выпрыгнуть.
+
+Фиксы в `converter.py`:
+1. **SpawnLocation +5** вместо +1.5. Если spawn внутри толстого пола —
+   гравитация уронит обратно за 1 кадр, не страшно. Если выше — отлично.
+2. **Auto-fallback** если SpawnLocation в карте НЕ был (или дефолт остался
+   `(0, 2, 0)`):
+   ```python
+   max_top = max(p['y'] + p['sy']/2 for p in primitives)
+   scene['spawnPoint'] = {x: 0, y: max_top + 5, z: 0}
+   ```
+   Игрок появляется над самой высокой Part'ой → падает на крышу.
+
+### Философия импорта (зафиксировано как принцип)
+
+**Цель импорта .rbxl** = показать геометрию и сцену, а не воспроизвести
+скриптовое поведение. Что работает (важно):
+- ✅ Все примитивы (Part/Wedge/CornerWedge/Truss/Union/MeshPart)
+- ✅ Цвета через BrickColor (расширенная палитра 120 цветов)
+- ✅ Anchored=True для всех (карта не рассыпается)
+- ✅ SpawnLocation с правильным Y (игрок не в стене)
+- ✅ Корректный CFrame YXZ (мостики/wedge'и стоят правильно)
+- ✅ Скайбокс, освещение, экспозиция/контраст через слайдеры
+- ✅ Простые Touched-скрипты (Bouncer, BattleArmor, KillBrick)
+- ✅ Tools.Equipped/Activated handlers (часть оружия)
+
+Что НЕ воспроизводится (принимаем):
+- ❌ Сложные RoundScript / GameClock / Spawner / KillFeed-логика
+- ❌ WaitForChild через while+:wait() паттерны (regex-фильтр пропускает)
+- ❌ Регенерация построек (Regenerate*) — не нужна т.к. Anchored
+- ❌ LeaderboardV3 с DataStore (пропускается)
+- ❌ Сетевые RemoteEvent/RemoteFunction (single-player только)
+
+### Когда снова работать со скриптами
+
+Если попадётся **новая карта (2015+)** — `WaitForChild` встроен в API,
+наш regex-фильтр не сработает. Скрипты пройдут больше и будут работать
+лучше. Старые карты (2007-2010) принципиально ограничены.
+
+### Что НЕ делать
+
+- Не пытаться "ещё раз" решить yield-across-C-boundary через debug.sethook
+  или pcall-трюки. Проверено — не работает с wasmoon.
+- Не переписывать wasmoon — это месяцы работы.
+- Не сужать regex-фильтр в надежде запустить ещё пару скриптов — лучше
+  пусть пропустится лишний, чем висит страница.
+
+### Что делать дальше
+
+- Идти по .rbxl из Desktop/RBLX/ как пользователь.
+- На каждой карте проверять: геометрия загрузилась? игрок ходит? видна?
+- Если виснет — добавлять regex-паттерн в фильтр.
+- Если игрок застрял — улучшать spawn-fallback.
+- Если падают конкретные API — реализовывать в shim (как Mouse.Icon,
+  BodyVelocity-bouncer, leaderstats).
+
+### В JS
+
+✅ Все фиксы spawn + философия общая для студии и плеера.
+
+---
+
 ## 2026-06-08 — Итерация 3: ROBLOX Battle (arch1_ROBLOX_Battle_v2.rbxl, проект 2851)
 
 **Контекст:** PvP-арена 2009 в XML, 1677 примитивов, 66 скриптов, 4 команды