From cc5e6d60e5aac31a998853009b4710c66e27380c Mon Sep 17 00:00:00 2001
From: min <maksimivankov26@yandex.ru>
Date: Mon, 8 Jun 2026 21:11:38 +0300
Subject: [PATCH] =?UTF-8?q?docs(lua):=20=D0=B8=D1=82=D0=B5=D1=80=D0=B0?=
 =?UTF-8?q?=D1=86=D0=B8=D1=8F=204=20=E2=80=94=20spawn=20fix=20+=20=D1=84?=
 =?UTF-8?q?=D0=B8=D0=BB=D0=BE=D1=81=D0=BE=D1=84=D0=B8=D1=8F=20=D0=B8=D0=BC?=
 =?UTF-8?q?=D0=BF=D0=BE=D1=80=D1=82=D0=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Зафиксировано как принцип:
- Цель импорта .rbxl = геометрия + базовые интеракции
- 100% Lua-логики не реализуется (wasmoon yield C-boundary)
- Что должно работать (фиксить если ломается)
- Что НЕ воспроизводится (не тратить время)
- Что делать дальше с новыми картами

Также: SpawnLocation +5 Y + auto-fallback на max_top если
SpawnLocation в карте не был — игрок не застревает в Anchored
геометрии.
---
 RUBLOX_LUA_API_CHANGELOG.md | 76 +++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)

diff --git a/RUBLOX_LUA_API_CHANGELOG.md b/RUBLOX_LUA_API_CHANGELOG.md
index c20ed8b..b6795d9 100644
--- a/RUBLOX_LUA_API_CHANGELOG.md
+++ b/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 команды