Add comprehensive README with installation guide, 20-weapon reference, and AI agent instructions
- Full architecture diagram and data flow explanation - Step-by-step installation (5 minutes) - Complete MCP tool reference with parameter examples - Python injection fallback documentation - 20-weapon FPS game reference table - Troubleshooting guide - AI agent / bot integration instructions - File structure overview Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Admin
585
README.md
585
README.md
@@ -1,349 +1,318 @@
|
|||||||
# ClaudeCode-Roblox-Studio-MCP
|
# ClaudeCode Roblox Studio MCP Server
|
||||||
|
|
||||||
A Model Context Protocol (MCP) server that enables **Claude Code** (by Anthropic) to directly control **Roblox Studio** - create games, manipulate objects, write scripts, and build experiences through natural language commands.
|
> **Control Roblox Studio from Claude Code via MCP (Model Context Protocol)**
|
||||||
|
|
||||||
## Overview
|
This project allows any Claude Code agent/bot to directly control Roblox Studio - creating parts, writing scripts, building maps, spawning enemies, and running Lua code - all through natural language commands.
|
||||||
|
|
||||||
This project creates a bidirectional bridge between Claude Code and Roblox Studio using:
|
---
|
||||||
- **MCP Protocol** (stdio) for Claude Code communication
|
|
||||||
- **HTTP Polling** for Roblox Studio plugin communication
|
|
||||||
- **Express.js** server for command queuing and result handling
|
|
||||||
|
|
||||||
## Architecture Diagram
|
## Architecture
|
||||||
|
|
||||||
```
|
```
|
||||||
┌─────────────────┐ MCP (stdio) ┌──────────────────┐ HTTP Polling ┌─────────────────┐
|
Claude Code <---> MCP Server (stdio) <---> HTTP/WS Bridge <---> Roblox Studio Plugin
|
||||||
│ Claude Code │ ◄─────────────────► │ Node.js MCP │ ◄──────────────────► │ Roblox Studio │
|
| | |
|
||||||
│ (AI Agent) │ │ Server │ (port 37423) │ Plugin │
|
| tool calls | HTTP polling (port 37423) | executes Lua
|
||||||
└─────────────────┘ └──────────────────┘ └─────────────────┘
|
| (create_part, | WebSocket (port 37424) | creates objects
|
||||||
│
|
| create_script, | | runs game logic
|
||||||
▼
|
| execute_code) | |
|
||||||
Express HTTP
|
|
||||||
(Health: 37423)
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### How It Works
|
**How it works:**
|
||||||
|
1. Claude Code communicates with the MCP server via stdin/stdout (MCP protocol)
|
||||||
|
2. The MCP server runs an HTTP + WebSocket bridge on localhost
|
||||||
|
3. The Roblox Studio plugin polls the MCP server and executes commands
|
||||||
|
4. Results flow back: Plugin -> HTTP -> MCP Server -> Claude Code
|
||||||
|
|
||||||
1. **Claude Code** connects to the MCP server via stdio
|
---
|
||||||
2. **MCP Server** exposes tools that Claude can call (create_part, create_script, etc.)
|
|
||||||
3. **Commands** are queued in the MCP server's memory
|
|
||||||
4. **Roblox Plugin** polls the HTTP endpoint for new commands
|
|
||||||
5. **Plugin executes** commands in Roblox Studio and sends results back
|
|
||||||
6. **Results** are returned to Claude Code via the MCP protocol
|
|
||||||
|
|
||||||
## Features
|
## Quick Start (5 minutes)
|
||||||
|
|
||||||
- Create 3D parts, models, folders, and entire scenes
|
### Step 1: Install Dependencies
|
||||||
- Write and inject Lua scripts (Script, LocalScript, ModuleScript)
|
|
||||||
- Build GUI elements (ScreenGui, Frame, TextButton, etc.)
|
|
||||||
- Manipulate workspace hierarchy
|
|
||||||
- Execute arbitrary Lua code
|
|
||||||
- Playtest and save places automatically
|
|
||||||
- Python injection scripts for direct command bar automation
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
### Prerequisites
|
|
||||||
|
|
||||||
- **Node.js** 18+ (for MCP server)
|
|
||||||
- **Claude Code** (by Anthropic)
|
|
||||||
- **Roblox Studio** (installed)
|
|
||||||
- Windows 11 or macOS
|
|
||||||
|
|
||||||
### Step 1: Clone and Install
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd ~
|
|
||||||
git clone https://github.rommark.dev/admin/ClaudeCode-Roblox-Studio-MCP.git
|
|
||||||
cd ClaudeCode-Roblox-Studio-MCP
|
cd ClaudeCode-Roblox-Studio-MCP
|
||||||
npm install
|
npm install
|
||||||
```
|
```
|
||||||
|
|
||||||
### Step 2: Configure Claude Code
|
### Step 2: Install the Studio Plugin
|
||||||
|
|
||||||
Add to your Claude Code config (`~/.claude/config.json` or `.clauderc`):
|
Copy the plugin to your Roblox plugins folder:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Windows
|
||||||
|
copy roblox-plugin\RobloxMCPPlugin.lua "%LOCALAPPDATA%\Roblox\Plugins\"
|
||||||
|
|
||||||
|
# Mac
|
||||||
|
cp roblox-plugin/RobloxMCPPlugin.lua ~/Library/Application\ Support/Roblox/Plugins/
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3: Start the MCP Server
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node src/index.js
|
||||||
|
```
|
||||||
|
|
||||||
|
You should see:
|
||||||
|
```
|
||||||
|
HTTP server listening on port 37423
|
||||||
|
WebSocket server listening on port 37424
|
||||||
|
Roblox Studio MCP server running on stdio
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4: Configure Claude Code
|
||||||
|
|
||||||
|
Add to your `.claude.json` (project settings):
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"mcpServers": {
|
"mcpServers": {
|
||||||
"roblox-studio": {
|
"roblox-studio": {
|
||||||
"command": "node",
|
"command": "node",
|
||||||
"args": ["~/ClaudeCode-Roblox-Studio-MCP/src/index.js"],
|
"args": ["C:\\path\\to\\ClaudeCode-Roblox-Studio-MCP\\src\\index.js"]
|
||||||
"cwd": "~/ClaudeCode-Roblox-Studio-MCP"
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Step 3: Install Roblox Studio Plugin
|
Or use the auto-setup:
|
||||||
|
|
||||||
**Windows:**
|
|
||||||
```powershell
|
|
||||||
Copy-Item roblox-plugin\RobloxMCPPlugin.lua $env:LOCALAPPDATA\Roblox\Plugins\
|
|
||||||
```
|
|
||||||
|
|
||||||
**Mac:**
|
|
||||||
```bash
|
```bash
|
||||||
cp roblox-plugin/RobloxMCPPlugin.lua ~/Library/Application\ Support/Roblox/Plugins/
|
AutoConnect\START-HERE.bat
|
||||||
```
|
```
|
||||||
|
|
||||||
### Step 4: Enable HTTP Requests (Critical!)
|
### Step 5: Open Roblox Studio
|
||||||
|
|
||||||
In Roblox Studio:
|
1. Open Roblox Studio
|
||||||
1. **File** → **Game Settings**
|
2. Create or open a place
|
||||||
2. **Security** tab
|
3. Go to **Game Settings > Security > Allow HTTP Requests** and enable it
|
||||||
3. Enable **"Enable Studio Access to API Services"**
|
4. The plugin auto-connects (check Output window for `[RobloxMCP] Connected!`)
|
||||||
4. Enable **"Allow HTTP Requests"**
|
|
||||||
|
|
||||||
### Step 5: Start Using
|
### Step 6: Use in Claude Code
|
||||||
|
|
||||||
1. Start the MCP server: `npm start`
|
Restart your Claude Code session, then ask it to build:
|
||||||
2. Open Roblox Studio
|
|
||||||
3. The plugin will auto-connect (look for "RobloxMCP" toolbar)
|
|
||||||
4. Start chatting with Claude Code to build your game!
|
|
||||||
|
|
||||||
## Available MCP Tools
|
|
||||||
|
|
||||||
| Tool | Description | Example |
|
|
||||||
|------|-------------|---------|
|
|
||||||
| `roblox_create_script` | Create Script/LocalScript/ModuleScript | "Create a Script in Workspace that prints hello" |
|
|
||||||
| `roblox_create_part` | Create 3D parts (Block, Ball, Cylinder, Wedge, CornerWedge) | "Create a red block at position 5, 10, 0" |
|
|
||||||
| `roblox_create_model` | Create model containers | "Create a model named Weapons in Workspace" |
|
|
||||||
| `roblox_create_folder` | Create folders for organization | "Create a folder named Scripts in Workspace" |
|
|
||||||
| `roblox_create_gui` | Create GUI elements | "Create a ScreenGui with a start button" |
|
|
||||||
| `roblox_set_property` | Set properties on objects | "Set the color of Workspace.Part1 to blue" |
|
|
||||||
| `roblox_get_hierarchy` | Explore object tree | "Show me the Workspace hierarchy" |
|
|
||||||
| `roblox_delete_object` | Delete objects by path | "Delete Workspace.OldPart" |
|
|
||||||
| `roblox_execute_code` | Run arbitrary Lua code | "Execute: print('Hello from Claude')" |
|
|
||||||
| `roblox_play` | Start playtest | "Start playtest in Client mode" |
|
|
||||||
| `roblox_stop` | Stop playtest | "Stop the playtest" |
|
|
||||||
| `roblox_save_place` | Save current place | "Save the place" |
|
|
||||||
|
|
||||||
## Usage Examples
|
|
||||||
|
|
||||||
### Creating a Simple Game
|
|
||||||
|
|
||||||
Ask Claude:
|
|
||||||
```
|
|
||||||
Create an obstacle course game with:
|
|
||||||
- A green starting platform at 0, 1, 0
|
|
||||||
- 5 red checkpoint platforms going upward
|
|
||||||
- A spinning part at the end
|
|
||||||
- A kill brick floor called Lava
|
|
||||||
```
|
|
||||||
|
|
||||||
### Building a GUI
|
|
||||||
|
|
||||||
```
|
```
|
||||||
Create a ScreenGui with:
|
"Build me a military base with guard towers"
|
||||||
- A dark semi-transparent frame
|
"Create a zombie survival game"
|
||||||
- A title saying "MY GAME"
|
"Add 20 weapons to my FPS game"
|
||||||
- A green start button
|
|
||||||
- Make the button print "Started!" when clicked
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Scripting
|
|
||||||
|
|
||||||
```
|
|
||||||
Create a Script in Workspace.Part that makes it spin continuously
|
|
||||||
```
|
|
||||||
|
|
||||||
## Python Injection Scripts
|
|
||||||
|
|
||||||
The `examples/` folder includes Python scripts for direct injection into Roblox Studio:
|
|
||||||
|
|
||||||
### studio-inject.py
|
|
||||||
Inject a single Lua script into the Roblox Studio command bar using Win32 API.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python examples/studio-inject.py
|
|
||||||
```
|
|
||||||
|
|
||||||
### inject-all-parts.py
|
|
||||||
Inject all 5 parts of the FPS game sequentially into Roblox Studio.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python examples/inject-all-parts.py
|
|
||||||
```
|
|
||||||
|
|
||||||
**Requirements:**
|
|
||||||
- Windows 11
|
|
||||||
- Roblox Studio must be open
|
|
||||||
- Python 3.x
|
|
||||||
|
|
||||||
## Examples Folder
|
|
||||||
|
|
||||||
The `examples/` folder contains:
|
|
||||||
- `fps-game/` - Complete 5-part FPS game setup (CoD style)
|
|
||||||
- `demo_game.lua` - Simple obby game example
|
|
||||||
- `spinning_part.lua` - Rotating part script
|
|
||||||
- `start_button.lua` - Start button GUI
|
|
||||||
|
|
||||||
### FPS Game Parts
|
|
||||||
|
|
||||||
1. **Part 1**: Map + Infrastructure (buildings, cover, lighting)
|
|
||||||
2. **Part 2**: Weapon System (weapon data module, client weapon controller)
|
|
||||||
3. **Part 3**: Enemy AI + Server Handler (AI bots, game server script)
|
|
||||||
4. **Part 4**: HUD + Player Scripts (crosshair, minimap, damage effects)
|
|
||||||
5. **Part 5**: Weapon Client Script (final weapon controller)
|
|
||||||
|
|
||||||
## Project Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
ClaudeCode-Roblox-Studio-MCP/
|
|
||||||
├── src/
|
|
||||||
│ └── index.js # Main MCP server + Express/HTTP
|
|
||||||
├── roblox-plugin/
|
|
||||||
│ └── RobloxMCPPlugin.lua # HTTP polling plugin for Studio
|
|
||||||
├── examples/
|
|
||||||
│ ├── fps-game/
|
|
||||||
│ │ ├── part1_map.lua # Map infrastructure
|
|
||||||
│ │ ├── part2_weapons.lua # Weapon system
|
|
||||||
│ │ ├── part3_ai.lua # Enemy AI + server
|
|
||||||
│ │ ├── part4_hud.lua # HUD + player scripts
|
|
||||||
│ │ └── part5_client.lua # Weapon client script
|
|
||||||
│ ├── studio-inject.py # Single script injection
|
|
||||||
│ └── inject-all-parts.py # Multi-part injection
|
|
||||||
├── package.json
|
|
||||||
└── README.md # This file
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
### MCP Server Ports
|
|
||||||
|
|
||||||
Edit `src/index.js`:
|
|
||||||
|
|
||||||
```javascript
|
|
||||||
const HTTP_PORT = 37423; // HTTP polling endpoint
|
|
||||||
const WS_PORT = 37424; // WebSocket (optional, for future use)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Roblox Plugin Configuration
|
|
||||||
|
|
||||||
Edit `roblox-plugin/RobloxMCPPlugin.lua`:
|
|
||||||
|
|
||||||
```lua
|
|
||||||
local CONFIG = {
|
|
||||||
HOST = "localhost",
|
|
||||||
PORT = 37423,
|
|
||||||
POLL_INTERVAL = 0.5, -- seconds between polls
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
|
|
||||||
### "MCP server not reachable"
|
|
||||||
|
|
||||||
**Solution:**
|
|
||||||
- Make sure the MCP server is running: `npm start`
|
|
||||||
- Check port 37423 is not in use
|
|
||||||
- Verify Claude Code config is correct
|
|
||||||
|
|
||||||
### "HTTP Requests Blocked"
|
|
||||||
|
|
||||||
**Solution:**
|
|
||||||
- Game Settings → Security
|
|
||||||
- Enable both HTTP-related options
|
|
||||||
- Restart Roblox Studio after changing
|
|
||||||
|
|
||||||
### Plugin Not Connecting
|
|
||||||
|
|
||||||
**Solution:**
|
|
||||||
- Check Output window in Roblox Studio
|
|
||||||
- Verify plugin is in correct Plugins folder
|
|
||||||
- Make sure HttpService is enabled
|
|
||||||
- Try clicking the toolbar button manually
|
|
||||||
|
|
||||||
### Commands Not Executing
|
|
||||||
|
|
||||||
**Solution:**
|
|
||||||
- Check for Lua errors in Output window
|
|
||||||
- Verify parent paths exist
|
|
||||||
- Make sure object names don't contain special characters
|
|
||||||
|
|
||||||
## Security Considerations
|
|
||||||
|
|
||||||
⚠️ **Important Security Notes:**
|
|
||||||
|
|
||||||
- This plugin allows executing arbitrary Lua code
|
|
||||||
- Only use in trusted development environments
|
|
||||||
- HTTP requests must be enabled (security trade-off)
|
|
||||||
- Consider using a reverse proxy for production
|
|
||||||
- Review all code before execution in production games
|
|
||||||
|
|
||||||
## Development
|
|
||||||
|
|
||||||
### Adding New Tools
|
|
||||||
|
|
||||||
1. Add tool definition in `src/index.js` (in `ListToolsRequestSchema` handler)
|
|
||||||
2. Add handler in `CallToolRequestSchema` handler
|
|
||||||
3. Implement in `roblox-plugin/RobloxMCPPlugin.lua` (add to `handleCommand` function)
|
|
||||||
|
|
||||||
Example:
|
|
||||||
```javascript
|
|
||||||
// src/index.js
|
|
||||||
{
|
|
||||||
name: 'roblox_my_tool',
|
|
||||||
description: 'Does something cool',
|
|
||||||
inputSchema: {
|
|
||||||
type: 'object',
|
|
||||||
properties: {
|
|
||||||
param1: { type: 'string', description: 'Description' },
|
|
||||||
},
|
|
||||||
required: ['param1'],
|
|
||||||
},
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
```lua
|
|
||||||
-- roblox-plugin/RobloxMCPPlugin.lua
|
|
||||||
elseif command == "myTool" then
|
|
||||||
-- Your implementation
|
|
||||||
return { success = true, result = "something" }
|
|
||||||
```
|
|
||||||
|
|
||||||
## Contributing
|
|
||||||
|
|
||||||
Contributions welcome! Please:
|
|
||||||
1. Fork the repository
|
|
||||||
2. Create a feature branch
|
|
||||||
3. Make your changes
|
|
||||||
4. Test thoroughly
|
|
||||||
5. Submit a pull request
|
|
||||||
|
|
||||||
## License
|
|
||||||
|
|
||||||
MIT License - feel free to use in your projects!
|
|
||||||
|
|
||||||
## Credits
|
|
||||||
|
|
||||||
- Built with [Model Context Protocol](https://github.com/modelcontextprotocol) by Anthropic
|
|
||||||
- Powered by [Claude Code](https://claude.ai/code)
|
|
||||||
- For Roblox Studio game development
|
|
||||||
|
|
||||||
## Support
|
|
||||||
|
|
||||||
For issues, questions, or suggestions:
|
|
||||||
- Open an issue on GitHub
|
|
||||||
- Check the Troubleshooting section
|
|
||||||
- Review the examples in `examples/`
|
|
||||||
|
|
||||||
## Changelog
|
|
||||||
|
|
||||||
### v2.0.0 (2025-03-31)
|
|
||||||
- Updated to HTTP polling architecture
|
|
||||||
- Added Python injection scripts
|
|
||||||
- Added complete FPS game example
|
|
||||||
- Improved plugin with toolbar UI
|
|
||||||
- Added comprehensive examples folder
|
|
||||||
|
|
||||||
### v1.0.0 (2025-01-29)
|
|
||||||
- Initial release
|
|
||||||
- 12 MCP tools implemented
|
|
||||||
- WebSocket communication (deprecated)
|
|
||||||
- Full CRUD operations for Roblox objects
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Made with ❤️ for Roblox developers using AI**
|
## Available MCP Tools
|
||||||
|
|
||||||
|
| Tool | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `roblox_create_script` | Create Lua scripts (Script, LocalScript, ModuleScript) |
|
||||||
|
| `roblox_create_part` | Create 3D parts (Block, Ball, Cylinder, Wedge, CornerWedge) |
|
||||||
|
| `roblox_create_model` | Create model containers for grouping objects |
|
||||||
|
| `roblox_create_folder` | Create organizational folders |
|
||||||
|
| `roblox_create_gui` | Create UI elements (ScreenGui, Frame, TextLabel, TextButton, etc.) |
|
||||||
|
| `roblox_set_property` | Set properties on existing objects (Position, Size, Color, etc.) |
|
||||||
|
| `roblox_get_hierarchy` | Inspect the object tree of any path |
|
||||||
|
| `roblox_delete_object` | Delete objects by path |
|
||||||
|
| `roblox_execute_code` | Run arbitrary Lua code in the command bar |
|
||||||
|
| `roblox_play` | Start playtesting |
|
||||||
|
| `roblox_stop` | Stop playtesting |
|
||||||
|
| `roblox_save_place` | Save the current place |
|
||||||
|
| `roblox_import_glb` | Import a GLB 3D model into the workspace |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tool Parameters
|
||||||
|
|
||||||
|
### roblox_create_part
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"parentPath": "Workspace",
|
||||||
|
"partName": "Wall1",
|
||||||
|
"partType": "Block",
|
||||||
|
"position": {"x": 10, "y": 5, "z": 20},
|
||||||
|
"size": {"x": 10, "y": 10, "z": 1},
|
||||||
|
"anchored": true,
|
||||||
|
"color": "Bright red"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### roblox_create_script
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"path": "Workspace.Model",
|
||||||
|
"scriptName": "EnemyAI",
|
||||||
|
"scriptType": "Script",
|
||||||
|
"source": "-- Lua code here\nprint('Hello from Claude!')"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### roblox_execute_code
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": "for i=1,10 do local p = Instance.new('Part', workspace) p.Position = Vector3.new(i*5, 1, 0) p.Anchored = true end"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Python Injection (Alternative Method)
|
||||||
|
|
||||||
|
If the MCP plugin isn't connecting, you can inject Lua code directly into Studio's command bar using the Python scripts:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Single script injection
|
||||||
|
python examples/studio-inject.py
|
||||||
|
|
||||||
|
# Multi-part sequential injection (for large games)
|
||||||
|
python examples/inject-all-parts.py
|
||||||
|
```
|
||||||
|
|
||||||
|
This uses Win32 API to:
|
||||||
|
1. Find the Roblox Studio window
|
||||||
|
2. Focus the command bar
|
||||||
|
3. Copy Lua code to clipboard
|
||||||
|
4. Paste and execute via simulated keyboard input
|
||||||
|
|
||||||
|
**Requirements**: Python 3.x on Windows, Roblox Studio open with a place loaded
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Included Example: CoD-Style FPS Game
|
||||||
|
|
||||||
|
A full Call of Duty-inspired FPS game built entirely from code:
|
||||||
|
|
||||||
|
**Map**: Urban military combat zone with buildings, cover positions, watchtowers, crates, barrels, and boundary walls.
|
||||||
|
|
||||||
|
**20 Weapons** (key to switch):
|
||||||
|
| Key | Weapon | Category | Key | Weapon | Category |
|
||||||
|
|-----|--------|----------|-----|--------|----------|
|
||||||
|
| 1 | M4A1 Carbine | Assault Rifle | 0 | UMP-45 | SMG |
|
||||||
|
| 2 | AK-47 | Assault Rifle | Q | AWP Sniper | Sniper |
|
||||||
|
| 3 | FN SCAR-H | Assault Rifle | E | Barrett M82 | Sniper |
|
||||||
|
| 4 | M16A4 | Assault Rifle | T | SVD Dragunov | Sniper |
|
||||||
|
| 5 | FAMAS F1 | Assault Rifle | Z | SPAS-12 | Shotgun |
|
||||||
|
| 6 | HK G36C | Assault Rifle | X | Remington 870 | Shotgun |
|
||||||
|
| 7 | MP5A4 | SMG | C | M249 SAW | LMG |
|
||||||
|
| 8 | FN P90 | SMG | V | M134 Minigun | LMG |
|
||||||
|
| 9 | HK MP7A2 | SMG | B | Desert Eagle | Pistol |
|
||||||
|
| | | | N | Glock 18C | Pistol |
|
||||||
|
| | | | G | RPG-7 | Launcher |
|
||||||
|
|
||||||
|
**Controls**: WASD=Move, LMB=Shoot, RMB=ADS, Shift=Sprint, Ctrl=Crouch, R=Reload
|
||||||
|
|
||||||
|
**Features**:
|
||||||
|
- First-person camera with ADS zoom + FOV transition
|
||||||
|
- Bullet trails, muzzle flash, impact sparks, explosion effects
|
||||||
|
- Recoil system with crosshair spread dynamics
|
||||||
|
- 10 enemy soldiers with AI (patrol, detect, chase, shoot)
|
||||||
|
- Health regen, damage vignette, hit markers, headshot indicators
|
||||||
|
- Kill feed, killstreak banners ("TRIPLE KILL!", "UNSTOPPABLE!")
|
||||||
|
- Minimap with enemy position dots
|
||||||
|
- Full HUD: health bar, ammo counter, weapon name, score, reload bar
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Auto-Connect Setup
|
||||||
|
|
||||||
|
For hands-free setup on a fresh machine:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
AutoConnect\START-HERE.bat
|
||||||
|
```
|
||||||
|
|
||||||
|
This will:
|
||||||
|
1. Install Node.js dependencies
|
||||||
|
2. Start the MCP server
|
||||||
|
3. Copy the plugin to Roblox's plugins folder
|
||||||
|
4. Register the MCP server with Claude Code
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Plugin doesn't connect
|
||||||
|
- **Enable HttpService**: Game Settings > Security > Allow HTTP Requests = ON
|
||||||
|
- **Check MCP server is running**: Visit `http://localhost:37423/health` in browser
|
||||||
|
- **Check Output window**: Look for `[RobloxMCP]` messages in Studio's Output
|
||||||
|
|
||||||
|
### MCP server won't start
|
||||||
|
- Ensure Node.js 18+ is installed
|
||||||
|
- Run `npm install` in the project directory
|
||||||
|
- Check ports 37423 and 37424 are not in use
|
||||||
|
|
||||||
|
### Commands time out
|
||||||
|
- The plugin polls every 0.5 seconds - slight delay is normal
|
||||||
|
- Make sure you're not in Play mode (commands work in Edit mode)
|
||||||
|
- Check Studio isn't frozen or busy
|
||||||
|
|
||||||
|
### Injection script fails
|
||||||
|
- Make sure Roblox Studio is open with a place loaded
|
||||||
|
- Run as Administrator if the window can't be focused
|
||||||
|
- Try manually: View > Command Bar, paste Lua code, press Enter
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## File Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
ClaudeCode-Roblox-Studio-MCP/
|
||||||
|
src/
|
||||||
|
index.js # MCP server (Node.js)
|
||||||
|
roblox-plugin/
|
||||||
|
RobloxMCPPlugin.lua # Studio plugin v2 (HTTP polling, auto-enable)
|
||||||
|
RobloxMCPServer_HTTP.lua # Alternative HTTP-only server
|
||||||
|
TestConnection.lua # Connection test script
|
||||||
|
examples/
|
||||||
|
fps-game/
|
||||||
|
part1_map.lua # Map building (buildings, cover, towers)
|
||||||
|
part2_weapons.lua # Weapon data module
|
||||||
|
part3_ai.lua # Server handler + enemy AI system
|
||||||
|
part4_hud.lua # HUD elements + player setup
|
||||||
|
part5_client.lua # Client weapon controller
|
||||||
|
studio-inject.py # Direct command bar injection via Win32
|
||||||
|
inject-all-parts.py # Multi-part sequential injection
|
||||||
|
AutoConnect/
|
||||||
|
START-HERE.bat # Main entry point
|
||||||
|
Setup-MCP.bat # MCP setup batch
|
||||||
|
Setup-MCP.ps1 # PowerShell setup script
|
||||||
|
AutoSetup.vbs # Silent launcher
|
||||||
|
package.json
|
||||||
|
README.md
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## For AI Agents / Bots
|
||||||
|
|
||||||
|
If you are an AI agent reading this README, here is how to use this tool:
|
||||||
|
|
||||||
|
1. **Check if the MCP server is configured**: Look in `.claude.json` for `roblox-studio` in `mcpServers`
|
||||||
|
2. **Start the server if needed**: Run `node src/index.js` in the background
|
||||||
|
3. **Ensure Roblox Studio is open** with a place loaded and HttpService enabled
|
||||||
|
4. **Use the MCP tools**: Call `roblox_create_part`, `roblox_create_script`, `roblox_execute_code`, etc.
|
||||||
|
5. **For complex builds**: Use `roblox_execute_code` with large Lua scripts to build entire games at once
|
||||||
|
6. **Fallback injection**: If MCP is not working, use the Python injection scripts (`examples/studio-inject.py`) to paste Lua directly into Studio's command bar via Win32 API
|
||||||
|
|
||||||
|
### Quick build example (via MCP tool)
|
||||||
|
```
|
||||||
|
Tool: roblox_create_part
|
||||||
|
Params: { "partName": "Ground", "parentPath": "Workspace", "partType": "Block",
|
||||||
|
"size": {"x":100,"y":2,"z":100}, "position": {"x":0,"y":-1,"z":0},
|
||||||
|
"anchored": true, "color": "Dark green" }
|
||||||
|
```
|
||||||
|
|
||||||
|
### Quick script example (via MCP tool)
|
||||||
|
```
|
||||||
|
Tool: roblox_create_script
|
||||||
|
Params: { "path": "ServerScriptService", "scriptName": "GameController",
|
||||||
|
"scriptType": "Script", "source": "-- Game logic here" }
|
||||||
|
```
|
||||||
|
|
||||||
|
### Large build example (via execute_code + Python injection)
|
||||||
|
```python
|
||||||
|
# Read the Lua file, inject into Studio command bar
|
||||||
|
python examples/inject-all-parts.py
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT
|
||||||
|
|||||||
Reference in New Issue
Block a user