⚡ Universal Roblox AI Studio — Автономная многомодовая MCP-платформа

Universal Roblox AI Studio — это среда выполнения нового поколения на базе Model Context Protocol (MCP), которая превращает Roblox Studio в AI-нативную, автономную и двунаправленную платформу разработки для внешних ИИ-ассистентов кодирования (Claude Desktop, Cursor, Antigravity, VS Code и др.).

📖 Содержание

• 🌟 Ключевые возможности

• 🏛️ Архитектура и 11 специализированных провайдеров

• 🧱 Иерархия и приоритетное построение компонентов (парадигма «+»)

• 🛡️ Ограниченное и официальное дерево маршрутизации MCP (Restricted Taxonomy)

• 🧠 Самовосстанавливающийся диагностический движок (Self-Healing Diagnostics)

• 🛠️ Полный список MCP-инструментов (63+ Tools)

• 🚀 Быстрая установка и начало работы

• 🤖 Конфигурации ИИ-клиентов (Claude Desktop / Cursor)

• 📊 Живая телеметрия и интерфейс Studio

• 🧪 Тестирование и проверка

🌟 Ключевые возможности

1. 63+ первоклассных универсальных MCP-инструмента: иерархия DataModel, жизненный цикл Instance, управление Luau-скриптами, PBR-материалы, Voxel Terrain, симуляция Playtest, 3D Generative AI и ввод виртуального оборудования.

2. Локальная интеграция с официальным Roblox Studio MCP (StudioMCP.exe): официальный MCP-клиент Roblox (%LOCALAPPDATA%\Roblox\Versions\...\StudioMCP.exe и mcp.bat) автоматически обнаруживается, а ограниченные команды 3D/Asset/Playtest направляются напрямую в официальный движок.

3. Приоритетное построение компонентов и иерархии (VisualConstructionEngine): вместо генерации всего с помощью массивных скриптов создаёт физические объекты, ограничения (Constraints), источники света, частицы и звуки слой за слоем по логике + (Insert Object) в Studio Explorer.

4. Продвинутая анимация и калибровка оборудования (AnimationAuthoringEngine): позирование R15/R6-ригов (Motor6D), безопасность суставов, создание KeyframeSequence и калибровка Tool.Grip для правильного удержания инструментов в руках персонажа.

5. Самовосстанавливающаяся диагностика ошибок (DiagnosticsEngine): мгновенно анализирует ошибки Luau-движка (C0 is read only, attempt to index nil, HttpDisabled и др.) и предоставляет ИИ-ассистенту готовый код исправления (suggestedFix) и рекомендации.

6. 4-уровневое динамическое разрешение возможностей (UniversalCapabilityEngine): команда выполняется напрямую через инструмент, шаблон рабочего процесса, скомпилированные примитивы или автономный планировщик.

7. Двунаправленный безопасный HTTP/HTTPS-мост: мгновенное прослушивание событий между плагином Studio и Node.js-сервером (LogService, ошибки, изменения выделения) и безопасность Undo/Redo (Ctrl+Z) через ChangeHistoryService.

🏛️ Архитектура и 11 специализированных провайдеров

Universal Roblox MCP работает не через единый статический список инструментов, а через 11 специализированных провайдеров (IProvider) и Центральный маршрутизатор возможностей (CapabilityRouter):

                      ┌────────────────────────────────────────────────────────┐
                      │             AI Client (Claude / Cursor)                │
                      └──────────────────────────┬─────────────────────────────┘
                                                 │ MCP (JSON-RPC)
                                                 ▼
                      ┌────────────────────────────────────────────────────────┐
                      │         Universal Roblox Studio MCP Router             │
                      │           (UniversalCapabilityEngine)                  │
                      └───────┬──────────────────┬───────────────────┬─────────┘
                              │                  │                   │
         ┌────────────────────┴───┐     ┌────────┴────────┐   ┌──────┴────────────────┐
         │ 1. Embedded Plugin     │     │ 2. Official MCP │   │ 3-11. Specialized     │
         │    (HTTP/HTTPS Bridge) │     │ (StudioMCP.exe) │   │       Domain Engines  │
         └────────────┬───────────┘     └────────┬────────┘   └──────┬────────────────┘
                      │                          │                   │
                      │ Polling RPC              │ Stdio / WS        │ Logic & Templates
                      ▼                          ▼                   ▼
    ┌──────────────────────────────────────────────────────────────────────────────────┐
    │                               Roblox Studio Session                              │
    │  • DataModel Tree    • Luau ScriptEditor    • Viewport Framebuffer  • Simulation │
    └──────────────────────────────────────────────────────────────────────────────────┘

Уровень 11 провайдеров:

1. EmbeddedPluginProvider: управляет 36 базовыми примитивами, взаимодействуя с локальным плагином внутри Roblox Studio.

2. OfficialRobloxMCPProvider: подключается к официальному бинарному файлу Roblox StudioMCP.exe и выполняет ограниченные команды 3D, Asset и Playtest.

3. ModelingProvider: координирует 3D-меши, PBR-материалы и процедурную сборку деталей.

4. AnimationProvider: управляет анимационными частями, контроллерами воспроизведения и позами ригов.

5. LuauProvider: обеспечивает статический анализ Luau, проверку синтаксиса и безопасное выполнение кода.

6. WorkflowProvider: применяет составные игровые системы (День/Ночь, Leaderstats, Генератор островов и т.д.) в виде шаблонов.

7. AssetProvider: извлекает/добавляет модели, звуки и визуальные ассеты из Creator Store и облачного инвентаря.

8. TestingProvider: управляет автоматическими сценарными тестами, виртуальным вводом с клавиатуры/мыши и процессами проверки.

9. DiagnosticsProvider: отслеживает вывод Studio, выполняет анализ первопричин и предлагает безопасные исправления.

10. ObservationProvider: управляет захватом экрана Viewport и визуальным осмотром.

11. DesignProvider: проверяет пространственную эстетику, цветовую гармонию и правила дизайна.

🧱 Иерархия и приоритетное построение компонентов (парадигма «+»)

Опытный разработчик в Roblox Studio не создаёт всё процедурно одним массивным Luau-скриптом. Вместо этого он использует компонентно-ориентированную (Component-Driven) разработку. Наша система создаёт объекты в 5 этапов по отраслевым стандартам:

[Katman 1: Mekansal İskelet]  ───▶ Model / Folder / Frame / Parts / Meshes / PrimaryPart
            ↓
[Katman 2: Görsel & Duyusal]  ───▶ PBR Materials / PointLight / Particles / Sounds / SurfaceGui
            ↓
[Katman 3: Etkileşim & Fizik] ───▶ ProximityPrompt / HingeConstraint / WeldConstraint / Attachments
            ↓
[Katman 4: Animasyon & Donanım]──▶ KeyframeSequence / Motor6D Poses / Tool Grip Calibration
            ↓
[Katman 5: Ayrık Mantık]      ───▶ Sadece sinyalleri dinleyen hafif ve modüler Luau Controller

Готовые шаблоны компонентов (component_compose):

• interactive_door: деревянная рама (Frame), петля (HingePart), дверная панель (DoorPanel), ProximityPrompt, звук открытия (Sound), контроллер TweenService и пользовательские Attributes (IsOpen, OpenAngle).

• collectible_coin: вращающаяся цилиндрическая монета, металлический материал, золотой PointLight, Sparkles, звук сбора и тег CollectionService.

• equippable_weapon: откалиброванный Tool.Grip, RightGripAttachment, Handle, звук взмаха, след удара (Trail) и скрипт активации.

• interactive_chest: неподвижный корпус сундука, открывающаяся крышка (ChestLid), HingeConstraint, ProximityPrompt, золотое сияние и атрибуты LootTable.

• streetlamp_fixture: металлический столб, стеклянный плафон, PointLight, SpotLight, неоновый материал и автоматический датчик света День/Ночь.

• teleporter_pad: платформа телепортации, луч частиц (ParticleEmitter и Beam), звук телепортации и целевые координаты.

• dialogue_npc: позированный персонаж R15/R6, именная метка BillboardGui, ProximityPrompt диалога и дерево разговора.

🛡️ Ограниченное и официальное дерево маршрутизации MCP (Restricted Taxonomy)

Движок Roblox по соображениям безопасности ограничивает некоторые API для сторонних плагинов (RobloxSecurity, RobloxScriptSecurity, SensitiveInput, Capture). Наша система автоматически распознаёт эти ограничения через RestrictedCapabilityRegistry и направляет их напрямую в официальный прокси StudioMCP.exe:

RESTRICTED / OFFICIAL-ONLY (12 Kategori)
├── 1. RobloxSecurity                   ──▶ official-roblox-mcp (execute_luau / search_game_tree)
├── 2. RobloxScriptSecurity             ──▶ official-roblox-mcp (script_grep / execute_luau)
├── 3. Internal Studio APIs             ──▶ official-roblox-mcp (get_studio_state, list_roblox_studios)
├── 4. Internal Engine APIs             ──▶ official-roblox-mcp (generate_mesh / get_console_output)
├── 5. Internal Plugin APIs             ──▶ official-roblox-mcp (internal plugin manager)
├── 6. Protected Debug APIs             ──▶ official-roblox-mcp (get_console_output)
├── 7. Protected Studio Control APIs    ──▶ official-roblox-mcp (start_stop_play [Play/Run/Stop])
├── 8. Missing Sandbox Capabilities     ──▶ official-roblox-mcp (screen_capture, keyboard/mouse input)
├── 9. Restricted Asset APIs            ──▶ official-roblox-mcp (generate_mesh, generate_material, search_asset)
├── 10. Restricted HTTP APIs            ──▶ official-roblox-mcp (Cloud Auth HTTP)
├── 11. Internal Network APIs           ──▶ official-roblox-mcp (Replication diagnostics)
└── 12. Provider-Specific Capabilities  ──▶ official-roblox-mcp (subagent, execute_luau)

🧠 Самовосстанавливающийся диагностический движок (Self-Healing Diagnostics)

ИИ-модели могут застревать на распространённых ошибках Roblox API при выполнении кода. DiagnosticsEngine перехватывает эти ошибки и генерирует для ИИ готовое работающее решение:

🛠️ Полный список MCP-инструментов (63+ Tools)

1. Инструменты визуального построения и анимации

• component_compose: строит полные компоненты (дверь, сундук, монета, NPC и т.д.) по готовым шаблонам.

• component_template_list: перечисляет все доступные шаблоны компонентов и деревья иерархии.

• hierarchy_scaffold: разделяет проект Studio на папки по профессиональным отраслевым стандартам.

• tool_grip_calibrate: автоматически калибрует углы удержания оружия и предметов в руке персонажа (Tool.Grip).

• rig_pose_and_animate: безопасно позирует суставы персонажей R15/R6 (Motor6D).

2. Официальные инструменты Roblox MCP (интеграция StudioMCP.exe)

• generate_mesh: генерирует 3D-меш через Roblox Cloud AI по текстовому запросу.

• generate_material: генерирует PBR-материал и текстуру по текстовому запросу.

• generate_procedural_model: создаёт процедурную сборку деталей.

• search_asset и insert_asset: ищет и размещает ассеты из Creator Store и облачной библиотеки.

• screen_capture: делает снимок экрана высокого разрешения из 3D Viewport Studio.

• start_stop_play: физически запускает игру (Play/Run) или возвращает в режим редактирования (Stop).

• get_studio_state: запрашивает сеанс Studio, открытый документ и активный режим симуляции.

• list_roblox_studios и set_active_studio: перечисляет запущенные окна Studio и выбирает активное.

• character_navigation: перемещает персонажа в 3D-координаты мира во время симуляции.

• user_keyboard_input и user_mouse_input: внедряет ввод клавиш и кликов мыши на уровне оборудования в симуляцию.

• script_read, multi_edit, script_search, script_grep: локальное многопользовательское редактирование и поиск файлов через Script Editor Studio.

• subagent и execute_luau: запускает локальный субагент Roblox и движок выполнения кода Luau.

3. Базовые инструменты DataModel и примитивов

• studio_info, studio_get_tree, studio_search, studio_inspect: сканирование иерархии DataModel и глубокий осмотр свойств.

• instance_create, instance_delete, instance_clone, instance_reparent, instance_rename, instance_move: жизненный цикл объектов и 3D-позиционирование.

• property_get, property_set, property_get_all: чтение/запись свойств с автоматическим преобразованием типов Luau.

• attribute_get, attribute_set, attribute_delete, attribute_get_all: управление атрибутами (Attribute).

• script_get_source, script_set_source, script_patch_source, script_search_code: чтение исходного кода скриптов, построчное исправление и поиск кода.

• selection_get, selection_set, selection_add, selection_clear: управление выделением в Studio Explorer.

• output_get, output_get_errors, output_clear: журнал вывода и перехват ошибок.

• terrain_fill_block, terrain_fill_ball, terrain_clear: создание и очистка Voxel Terrain.

• batch_execute: атомарное выполнение множества команд за одну операцию (с поддержкой точек Undo/Redo waypoint).

🚀 Быстрая установка и начало работы

1. Требования

• Node.js: версия v18.0.0 или выше (рекомендуется v20+ / v24).

• Roblox Studio: установлен на Windows или macOS.

2. Клонирование репозитория и сборка

git clone <repo-url>
cd "Roblox Studio MCP"
npm install
npm run build

3. Установка плагина Roblox Studio

Вы можете установить плагин одним из двух способов:

Метод A: Копирование готового файла плагина (рекомендуется)

Выполните команды npm run bundle:plugin и node scripts/build-rbxmx.js (или скопируйте скомпилированные файлы):

• Windows: скопируйте файл plugin-build\RobloxUniversalMCP.rbxmx в каталог %LOCALAPPDATA%\Roblox\Plugins\.

• macOS: скопируйте файл plugin-build/RobloxUniversalMCP.rbxmx в каталог ~/Library/Application Support/Roblox/Plugins/.

Метод B: Ручная установка в Studio

1. Откройте любое место (Place) в Roblox Studio.

2. Вставьте содержимое файла plugin-build/RobloxUniversalMCP.luau в Script.

3. Щёлкните правой кнопкой мыши по Script и выберите «Save as Local Plugin...».

4. В разделе Home > Game Settings > Security включите опцию «Allow HTTP Requests».

🤖 Конфигурации AI-клиентов (универсальная установка для всех компьютеров)

Для стабильной и переносимой работы на любом компьютере предлагаются 3 различных универсальных метода:

🌟 Метод 1: Глобальная регистрация CLI (рекомендуется — одна строка на всех компьютерах!)

Выполните npm link один раз в папке проекта, чтобы зарегистрировать систему как глобальную команду:

npm run build
npm link

Теперь вам не нужно указывать пути к файлам в Claude Desktop, Cursor или любом другом MCP-клиенте:

Claude Desktop (claude_desktop_config.json)

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "roblox-universal-studio": {
      "command": "roblox-studio-mcp"
    }
  }
}

🚀 Метод 2: Универсальное рабочее пространство Cursor / VS Code (${workspaceFolder})

Когда вы открываете проект в Cursor или VS Code, добавьте его в файл .cursor/mcp.json или .vscode/mcp.json. На каком бы компьютере он ни был открыт, ${workspaceFolder} определяется автоматически:

{
  "mcpServers": {
    "roblox-universal-studio": {
      "command": "node",
      "args": [
        "${workspaceFolder}/dist/index.js"
      ]
    }
  }
}

📁 Метод 3: Запуск с указанием прямого пути к файлу

Если вы хотите вызвать скомпилированный файл dist/index.js напрямую вместо глобального CLI:

{
  "mcpServers": {
    "roblox-universal-studio": {
      "command": "node",
      "args": [
        "<PROJE_KLASORUNUZ_TAM_YOLU>/dist/index.js"
      ]
    }
  }
}

(Пример для Windows: C:\\Projects\\Roblox-Studio-MCP\\dist\\index.js | macOS: /Users/username/Projects/Roblox-Studio-MCP/dist/index.js)

📊 Живая телеметрия и интерфейс Studio

При загрузке плагина в Roblox Studio открывается специальный DockWidget (DiagnosticsView):

• Plugin Runtime: ONLINE / STANDALONE

• MCP Bridge: CONNECTED (зелёный) / DISCONNECTED (красный)

• Capabilities Discovered: 80+ Live Capabilities (все провайдеры и подсистемы)

• Low-Level Tools: 57 Primitive Tools

• High-Level Workflows: 19 Composite Workflows

• Total Universal Tools: 76 Universal Tools

• Active Mode: CHAT | OBSERVE | BUILD | PLAYTEST | AUTONOMOUS

🧪 Тестирование и проверка

Чтобы запустить весь набор тестов:

npm test

Вывод теста:

✔ Tool Registry contains all universal tools
✔ HTTP Bridge Status returns disconnected when no session is active
✔ HTTP Bridge Handshake registers studio session
✔ Executing a command dispatches over polling RPC and resolves with response
✔ 11 Providers are registered and operational in ProviderRegistry
✔ Universal Capability Engine resolves across 4-tier hierarchy
✔ MultiModeEngine handles operating mode transitions and permissions
✔ Live Dashboard endpoint returns comprehensive real-time telemetry
✔ Visual Construction Engine lists rich archetypes and templates
✔ Animation Authoring Engine calibrates tool grips and keyframe sequences

📄 Лицензия

Этот проект лицензирован под лицензией MIT. Наслаждайтесь AI-native разработкой игр с Roblox Studio! 🎮⚡