⚡ Universal Roblox AI Studio — Plataforma MCP de Capacidad Multimodo Autónoma

Universal Roblox AI Studio es un runtime de Model Context Protocol (MCP) de nueva generación que transforma Roblox Studio en una plataforma de desarrollo AI-Native, autónoma y bidireccional para asistentes de codificación de IA externos (Claude Desktop, Cursor, Antigravity, VS Code, etc.).

📖 Índice

• 🌟 Características Principales

• 🏛️ Arquitectura y 11 Proveedores Especializados

• 🧱 Construcción Prioritaria de Jerarquía y Componentes (Paradigma del "Signo +")

• 🛡️ Árbol de Enrutamiento MCP Restringido y Oficial (Taxonomía Restringida)

• 🧠 Motor de Diagnóstico Autocorregible (Self-Healing Diagnostics)

• 🛠️ Lista Exhaustiva de Herramientas MCP (63+ Tools)

• 🚀 Instalación Rápida e Inicio

• 🤖 Configuraciones de Clientes de IA (Claude Desktop / Cursor)

• 📊 Telemetría en Vivo e Interfaz de Studio

• 🧪 Pruebas y Validación

🌟 Características Principales

1. 63+ Herramientas MCP Universales de Primera Clase: Jerarquía de DataModel, ciclo de vida de Instance, gestión de scripts Luau, material PBR, Voxel Terrain, simulación de Playtest, IA Generativa 3D y entrada de hardware virtual.

2. Integración Local con el MCP Oficial de Roblox Studio (StudioMCP.exe): El cliente MCP oficial de Roblox (%LOCALAPPDATA%\Roblox\Versions\...\StudioMCP.exe y mcp.bat) se descubre automáticamente y los comandos restringidos de 3D/Asset/Playtest se enrutan directamente al motor oficial.

3. Construcción Prioritaria de Componentes y Jerarquía (VisualConstructionEngine): En lugar de generar todo con scripts masivos, crea objetos físicos, restricciones (Constraints), luces, partículas y sonidos capa por capa siguiendo la lógica de + (Insert Object) del Explorador de Studio.

4. Calibración Avanzada de Animación y Hardware (AnimationAuthoringEngine): Posado de rigs R15/R6 (Motor6D), seguridad de articulaciones, creación de KeyframeSequence y calibración de Tool.Grip para que las herramientas queden correctamente en las manos del personaje.

5. Diagnóstico de Errores Autocorregible (DiagnosticsEngine): Analiza al instante errores del motor Luau (C0 is read only, attempt to index nil, HttpDisabled, etc.) y ofrece al asistente de IA código de corrección listo (suggestedFix) y recomendaciones.

6. Resolución Dinámica de Capacidades en 4 Niveles (UniversalCapabilityEngine): Un comando se resuelve directamente con una herramienta, con una plantilla de flujo de trabajo, con primitivas compiladas o con un planificador autónomo.

7. Puente HTTP/HTTPS Bidireccional Seguro: Escucha de eventos en tiempo real entre el plugin de Studio y el servidor Node.js (LogService, errores, cambios de selección) y seguridad de Undo/Redo (Ctrl+Z) mediante ChangeHistoryService.

🏛️ Arquitectura y 11 Proveedores Especializados

Universal Roblox MCP no funciona con una lista estática de herramientas, sino a través de 11 proveedores especializados (IProvider) y un Enrutador Central de Capacidades (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 │
    └──────────────────────────────────────────────────────────────────────────────────┘

Capa de los 11 Proveedores:

1. EmbeddedPluginProvider: Gestiona 36 primitivas básicas comunicándose con el plugin local dentro de Roblox Studio.

2. OfficialRobloxMCPProvider: Se conecta al binario oficial StudioMCP.exe de Roblox para ejecutar comandos restringidos de 3D, Asset y Playtest.

3. ModelingProvider: Coordina mallas 3D, materiales PBR y ensamblajes de piezas procedimentales.

4. AnimationProvider: Gestiona clips de animación, controles de reproducción y poses de rigs.

5. LuauProvider: Proporciona análisis estático de Luau, validación de sintaxis y ejecución segura de código.

6. WorkflowProvider: Aplica sistemas de juego compuestos (Día/Noche, Leaderstats, Generador de Islas, etc.) mediante plantillas.

7. AssetProvider: Obtiene/inserta modelos, sonidos y activos visuales desde Creator Store y el inventario en la nube.

8. TestingProvider: Gestiona pruebas de escenarios automáticas, entradas virtuales de teclado/ratón y procesos de validación.

9. DiagnosticsProvider: Supervisa las salidas de Studio, realiza análisis de causa raíz y sugiere reparaciones seguras.

10. ObservationProvider: Gestiona la captura de pantalla del Viewport y la inspección visual.

11. DesignProvider: Supervisa la estética espacial, la armonía de colores y las reglas de diseño.

🧱 Construcción Prioritaria de Jerarquía y Componentes (Paradigma del "Signo +")

Un desarrollador experimentado de Roblox Studio no genera todo de forma procedimental con un único script Luau masivo. En su lugar, utiliza un desarrollo basado en componentes y jerarquía (Component-Driven). Nuestro sistema crea los objetos en 5 capas siguiendo el estándar de la industria:

[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

Plantillas de Componentes Listas (component_compose):

• interactive_door: Marco de madera (Frame), bisagra (HingePart), panel de puerta (DoorPanel), ProximityPrompt, sonido de apertura (Sound), controlador TweenService y Attributes personalizados (IsOpen, OpenAngle).

• collectible_coin: Moneda cilíndrica giratoria, material metálico, PointLight dorado, Sparkles, sonido de recogida y etiqueta de CollectionService.

• equippable_weapon: Tool.Grip calibrado, RightGripAttachment, Handle, sonido de balanceo, estela de impacto (Trail) y script de activación.

• interactive_chest: Cuerpo de cofre fijo, tapa abatible (ChestLid), HingeConstraint, ProximityPrompt, brillo dorado y atributos de LootTable.

• streetlamp_fixture: Poste metálico, cabezal de lámpara de cristal, PointLight, SpotLight, material Neon y sensor de luz automático Día/Noche.

• teleporter_pad: Plataforma de teletransporte, haz de partículas (ParticleEmitter y Beam), sonido de teletransporte y coordenadas de destino.

• dialogue_npc: Personaje R15/R6 posado, etiqueta de nombre BillboardGui, ProximityPrompt de diálogo y árbol de conversación.

🛡️ Árbol de Enrutamiento MCP Restringido y Oficial (Taxonomía Restringida)

Por razones de seguridad, el motor de Roblox restringe ciertas API (RobloxSecurity, RobloxScriptSecurity, SensitiveInput, Capture) para plugins de terceros. Nuestro sistema reconoce automáticamente estas restricciones mediante el RestrictedCapabilityRegistry y las enruta directamente al proxy oficial 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)

🧠 Motor de Diagnóstico Autocorregible (Self-Healing Diagnostics)

Los modelos de IA pueden quedarse atascados en errores comunes de la API de Roblox al ejecutar código. DiagnosticsEngine captura estos errores y genera una solución directamente funcional para la IA:

🛠️ Lista Exhaustiva de Herramientas MCP (63+ Tools)

1. Herramientas de Construcción Visual y Animación

• component_compose: Construye componentes completos (puerta, cofre, moneda, NPC, etc.) con plantillas listas.

• component_template_list: Lista todas las plantillas de componentes disponibles y sus árboles de jerarquía.

• hierarchy_scaffold: Organiza el proyecto de Studio en carpetas siguiendo estándares profesionales de la industria.

• tool_grip_calibrate: Calibra automáticamente los ángulos de agarre (Tool.Grip) de armas y objetos en las manos del personaje.

• rig_pose_and_animate: Posiciona de forma segura las articulaciones de personajes R15/R6 (Motor6D).

2. Herramientas MCP Oficiales de Roblox (Integración StudioMCP.exe)

• generate_mesh: Genera mallas 3D con Roblox Cloud AI a partir de una solicitud en lenguaje natural.

• generate_material: Genera materiales y texturas PBR a partir de una solicitud en lenguaje natural.

• generate_procedural_model: Crea ensamblajes de piezas procedimentales.

• search_asset e insert_asset: Busca e inserta activos desde Creator Store y la biblioteca en la nube.

• screen_capture: Captura imágenes de alta resolución desde el Viewport 3D de Studio.

• start_stop_play: Inicia físicamente el juego (Play/Run) o vuelve al modo de edición (Stop).

• get_studio_state: Consulta la sesión de Studio, el documento abierto y el modo de simulación activo.

• list_roblox_studios y set_active_studio: Lista las ventanas de Studio en ejecución y selecciona la activa.

• character_navigation: Mueve el personaje a coordenadas 3D del mundo durante la simulación.

• user_keyboard_input y user_mouse_input: Inyecta pulsaciones de teclas y clics de ratón a nivel de hardware en la simulación.

• script_read, multi_edit, script_search, script_grep: Edición y búsqueda local de múltiples archivos a través del Editor de Scripts de Studio.

• subagent y execute_luau: Ejecuta el subagente local de Roblox y su motor de ejecución de código Luau.

3. Herramientas Básicas de DataModel y Primitivas

• studio_info, studio_get_tree, studio_search, studio_inspect: Exploración de la jerarquía de DataModel e inspección profunda de propiedades.

• instance_create, instance_delete, instance_clone, instance_reparent, instance_rename, instance_move: Ciclo de vida de objetos y posicionamiento 3D.

• property_get, property_set, property_get_all: Lectura/escritura de propiedades con conversión automática de tipos Luau.

• attribute_get, attribute_set, attribute_delete, attribute_get_all: Gestión de atributos (Attribute).

• script_get_source, script_set_source, script_patch_source, script_search_code: Lectura del código fuente de scripts, parcheo por líneas y búsqueda de código.

• selection_get, selection_set, selection_add, selection_clear: Control de la selección en el Explorador de Studio.

• output_get, output_get_errors, output_clear: Registro de salida y captura de errores.

• terrain_fill_block, terrain_fill_ball, terrain_clear: Creación y limpieza de Voxel Terrain.

• batch_execute: Ejecución atómica de múltiples comandos en una sola operación (con soporte de waypoints de Undo/Redo).

🚀 Instalación Rápida e Inicio

1. Requisitos

• Node.js: v18.0.0 o superior (se recomienda v20+ / v24).

• Roblox Studio: Instalado en Windows o macOS.

2. Clonar el Repositorio y Compilar

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

3. Instalar el Plugin de Roblox Studio

Puede instalar el complemento mediante uno de estos dos métodos:

Método A: Copiar el archivo de complemento listo (Recomendado)

Ejecute los comandos npm run bundle:plugin y node scripts/build-rbxmx.js (o copie los archivos compilados):

• Windows: Copie el archivo plugin-build\RobloxUniversalMCP.rbxmx en el directorio %LOCALAPPDATA%\Roblox\Plugins\.

• macOS: Copie el archivo plugin-build/RobloxUniversalMCP.rbxmx en el directorio ~/Library/Application Support/Roblox/Plugins/.

Método B: Instalación manual en Studio

1. Abra cualquier Place en Roblox Studio.

2. Pegue el contenido del archivo plugin-build/RobloxUniversalMCP.luau en un Script.

3. Haga clic derecho en el Script y seleccione la opción "Save as Local Plugin...".

4. Active la opción "Allow HTTP Requests" en la sección Home > Game Settings > Security.

🤖 Configuraciones de clientes de IA (Instalación universal para todos los ordenadores)

Se ofrecen 3 métodos universales diferentes para ejecutarlo de forma estable y portátil en cualquier ordenador:

🌟 Método 1: Registro global de CLI (Recomendado: ¡una sola línea en todos los ordenadores!)

Ejecute npm link una vez en la carpeta del proyecto para registrar el sistema como comando global:

npm run build
npm link

Ahora no necesitará escribir ninguna ruta de archivo en Claude Desktop, Cursor ni en ningún otro cliente 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"
    }
  }
}

🚀 Método 2: Área de trabajo universal de Cursor / VS Code (${workspaceFolder})

Cuando abra el proyecto en Cursor o VS Code, añádalo al archivo .cursor/mcp.json o .vscode/mcp.json. Independientemente del ordenador en el que se abra, ${workspaceFolder} se detecta automáticamente:

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

📁 Método 3: Ejecución especificando la ruta de archivo directamente

Si prefiere llamar directamente al archivo compilado dist/index.js en lugar de la CLI global:

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

(Ejemplo Windows: C:\\Projects\\Roblox-Studio-MCP\\dist\\index.js | macOS: /Users/username/Projects/Roblox-Studio-MCP/dist/index.js)

📊 Telemetría en vivo e interfaz de Studio

Cuando se carga el complemento, se abre un DockWidget (DiagnosticsView) especial dentro de Roblox Studio:

• Plugin Runtime: ONLINE / STANDALONE

• MCP Bridge: CONNECTED (Verde) / DISCONNECTED (Rojo)

• Capabilities Discovered: 80+ Live Capabilities (Todos los proveedores y subsistemas)

• 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

🧪 Pruebas y verificación

Para ejecutar todo el paquete de pruebas:

npm test

Salida de las pruebas:

✔ 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

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT. ¡Disfrute de la experiencia de desarrollo de juegos AI-native con Roblox Studio! 🎮⚡