RUBLOX_LUA_API_CHANGELOG.md

@@ -67,6 +67,49 @@ ContextActionResult, UserInputState, BorderMode, FormFactor.
   не должны запускаться при старте. `parseRobloxLuaMeta()` парсит JSON
   из второй строки packed-кода, при `enabled=false` скрипт идёт в `rbxlSkipped`.
 
+### Tool/Backpack/Mouse flow (Шаг 1)
+
+Контекст: Roblox-Tool это объект который попадает в Backpack игрока,
+при экипировке (клавиша 1-9) фейерит Tool.Equipped с настоящим Mouse,
+скрипты внутри Tool слушают MouseButton1Down/KeyDown.
+
+**В `RobloxShim.js`:**
+- `localPlayer.Backpack` — инвентарь.
+- `localPlayer:GetMouse()` → playerMouse с Button1Down/KeyDown/Hit.Position.
+- Внутренний `allTools[]` registry + `equippedTool` слот.
+- `Instance.new('Tool')` теперь:
+  - создаёт виртуальный `Handle` (Part внутри Tool);
+  - регистрирует в `allTools[]`;
+  - шлёт `toolRegistered {index, name}` в GameRuntime.
+- `fireGlobalEvent` обрабатывает: `equipTool`, `unequipTool`,
+  `toolActivated`, `toolDeactivated`, `mouseButton1Down`/`Up`, `keyDown`/`Up`.
+- `__rbxl_get_tool_by_name(name)` — для script.Parent резолва.
+
+**В `LuaSharedSandbox.js`:**
+- `addScript(id, code, target, name, {toolName})` — расширенная сигнатура.
+- В `_startSingleScript` если есть `toolName` — `script.Parent` = виртуальный Tool.
+
+**В `GameRuntime.js`:**
+- Эвристика: скрипты с `target=null` и содержащие
+  `(script.Parent|Tool).(Equipped|Unequipped|Activated|Deactivated)` →
+  получают `toolName='Tool'`, группируются в один общий Tool.
+- `_registerRbxlTool(payload)` — кладёт item в InventoryUI.hotbar,
+  слушает `slot` event → шлёт `equipTool`/`unequipTool`.
+- `canvas.mousedown` → `mouseButton1Down` + `toolActivated` с raycast Hit.
+- `_raycastFromCamera()` — простой ray из камеры на 50 unit вперёд.
+
+**Надо ли в JS?** ✅ Да — Tool/Backpack/Mouse это базовый Roblox-game-loop.
+
+### Импорт изменений в converter.py (не задеплоено)
+
+Файл изменён локально, но importer на VM 130 — не обновлён. Когда придёт
+время деплоя, ключевые правки:
+- `_collect_tool(inst)` — собирает `scene['tools'][]` из Tool/HopperBin;
+- `_find_ancestor_tool(inst)` — определяет в каком Tool лежит Script;
+- В `_convert_script` добавлено поле `tool_id` в метадату.
+
+Это уберёт необходимость эвристики на стороне studio.
+
 ### Надо ли портировать в JS-движок?
 
 ✅ **Да, всё** — это базовый Roblox-совместимый API, который должен работать