# WEPPY Docs (full text) ## Antigravity CLI Setup https://weppyai.com/en/docs/agents/antigravity-cli/ How to use the WEPPY MCP Server from WEPPY Roblox AI Toolkit with [Antigravity CLI](https://antigravity.google/product/antigravity-cli). Antigravity CLI and Antigravity IDE share the canonical global MCP config at `~/.gemini/config/mcp_config.json`. ## Prerequisites 1. **Antigravity CLI** installed 2. **Node.js** (v18.0.0 or higher, with `npx` available) 3. **WEPPY Roblox Studio Plugin** installation complete ## Install WEPPY AI Agent Plugin Use the one-line installer from the [WEPPY install page](/en/install/). Antigravity CLI and its `agy plugin` command are required to install **WEPPY AI Agent Plugin**. The installer stages the latest public release locally, runs `agy plugin install` with that local payload, and verifies the result with `agy plugin list`. Do not pass a GitHub URL directly to `agy plugin install`. If the **WEPPY AI Agent Plugin** installation cannot be verified, the installer preserves the shared direct **WEPPY MCP Server** fallback. ## Manual MCP Fallback ### Global Config File Add/merge the following into the global MCP config file for Antigravity CLI. | OS | Path | | --- | --- | | macOS / Linux | `~/.gemini/config/mcp_config.json` | | Windows | `%USERPROFILE%\.gemini\config\mcp_config.json` | ```json { "mcpServers": { "weppy-roblox-mcp": { "command": "npx", "args": ["-y", "@weppy/roblox-mcp@latest"] } } } ``` ### Workspace Config If you only want the MCP server in one project, you can put the same JSON in `.agents/mcp_config.json` at the project root. The public one-line installer and browser installer use `~/.gemini/config/mcp_config.json` as the global fallback. The older `~/.gemini/antigravity-cli/mcp_config.json` path is legacy input for migration, not a new registration target. ## Connection Test 1. Launch **Roblox Studio** → Plugins tab → **WEPPY** → **Connect** 2. Enter the following in **Antigravity CLI**: ``` Tell me what is currently selected in Roblox Studio ``` 3. Use `/mcp` in the CLI to check MCP server status ## Troubleshooting ### Server Won't Start Run the MCP server directly to see the error: ```bash npx -y @weppy/roblox-mcp@latest ``` ### Connection Fails - Confirm the WEPPY Roblox Studio Plugin shows **Connected** status - Check that port **3002** is not blocked by a firewall - Use `/mcp` in Antigravity CLI to check server status - Make sure you did not edit Gemini CLI's `~/.gemini/settings.json` or the Antigravity IDE config by mistake --- ## Antigravity / Antigravity IDE Setup https://weppyai.com/en/docs/agents/antigravity/ How to use the WEPPY MCP Server from WEPPY Roblox AI Toolkit with [Google Antigravity](https://developers.googleblog.com/build-with-google-antigravity-our-new-agentic-development-platform/) and Antigravity IDE. > **Antigravity** is Google's agent-based development platform where AI agents autonomously perform complex tasks spanning code editing, the terminal, and the browser. ## Recommended Setup Use the one-line installer from the [WEPPY install page](/en/install/) first. Installing **WEPPY AI Agent Plugin** requires Antigravity CLI and its `agy plugin` command. If the CLI is unavailable, the installer keeps Antigravity connected through the shared direct **WEPPY MCP Server** configuration and links to the [official CLI installation guide](https://antigravity.google/docs/cli-install). The browser installer configures the **WEPPY MCP Server** connection. It cannot run `agy plugin` or confirm that **WEPPY AI Agent Plugin** was installed. ## Prerequisites 1. **Antigravity / Antigravity IDE** installed (see the official docs for supported OS and requirements) 2. **Node.js** (v18.0.0 or higher, with `npx` available) 3. **WEPPY Roblox Studio Plugin** installation complete ## Manual MCP Fallback In Antigravity, MCP servers are managed from the **Agent pane**. The canonical global fallback is `~/.gemini/config/mcp_config.json`; a workspace-only fallback uses `.agents/mcp_config.json`. ### Manual Registration via Raw Config 1. In the Agent pane, click **⋯** → **MCP Servers** → **Manage MCP Servers** → **View raw config** ![Opening the MCP Servers menu](/docs/assets/screenshots/antigravity/antigravity_mcp_services_menu.png) 2. Add/merge the following into the displayed JSON config: ```json { "mcpServers": { "weppy-roblox-mcp": { "command": "npx", "args": ["-y", "@weppy/roblox-mcp@latest"] } } } ``` ![Editing raw config](/docs/assets/screenshots/antigravity/antigravity_mcp_raw.png) 3. Save and **Refresh** (or restart/reload as indicated by the UI) > The actual path and filename of the config file may vary by OS and Antigravity version — always modify the location shown in **View raw config**. ### Optional: Adjust Port/Log via Environment Variables Keeping the default (`HTTP 127.0.0.1:3002`) is recommended. If needed, you can set environment variables like this: ```json { "mcpServers": { "weppy-roblox-mcp": { "command": "npx", "args": ["-y", "@weppy/roblox-mcp@latest"], "env": { "HTTP_HOST": "127.0.0.1", "HTTP_PORT": "3002", "LOG_LEVEL": "INFO" } } } } ``` ## Connection Test 1. Launch **Roblox Studio** → Plugins tab → **WEPPY** → **Connect** 2. Enter the following in **Antigravity**: ``` Tell me what is currently selected in Roblox Studio ``` ## Troubleshooting ### Server Won't Start Run the MCP server directly to see the error: ```bash npx -y @weppy/roblox-mcp@latest ``` ### Connection Fails - Confirm the WEPPY Roblox Studio Plugin shows **Connected** status - Check that port **3002** is not blocked by a firewall - Check server status via **⋯** → **MCP Servers** in the Agent pane - (Advanced) If you changed `HTTP_PORT`, make sure the WEPPY Roblox Studio Plugin and bridge settings also use the same port. --- ## Claude Code Setup https://weppyai.com/en/docs/agents/claude-code/ How to use the WEPPY MCP Server from WEPPY Roblox AI Toolkit with [Claude Code](https://claude.ai/code) (terminal-based AI coding tool). ## Prerequisites - **Claude Code** installed - **WEPPY Roblox Studio Plugin** installation complete ## Installation ```bash npm install -g @anthropic-ai/claude-code ``` ## Registering the MCP Server ### Method 1: Install the WEPPY AI Agent Plugin (Recommended) Run from your terminal. The WEPPY AI Agent Plugin adds the MCP server config plus WEPPY skills for Studio actions, UI Studio and playtest workflows, and Studio-local sync. ```bash # Add marketplace claude plugin marketplace add hope1026/weppy-roblox-mcp --scope user # Install plugin claude plugin install weppy-roblox-ai-toolkit@hope1026-roblox-mcp --scope user ``` Verify installation: ```bash claude plugin list ``` ### Method 2: Edit Config File Directly Use this if you only want the MCP server config without the WEPPY AI Agent Plugin. Create a `.mcp.json` file: ```json { "mcpServers": { "weppy-roblox-mcp": { "command": "npx", "args": ["-y", "@weppy/roblox-mcp@latest"] } } } ``` **Config file location:** | Scope | Path | |------|------| | Project | `/.mcp.json` | | Global | `~/.claude/mcp.json` | ## Automatic Server Management Claude Code manages the MCP server automatically: - Starts automatically when needed - Stops automatically when the session ends - No additional configuration required ## Connection Test 1. Launch **Roblox Studio** → Plugins tab → **WEPPY** → **Connect** 2. Test from **Claude Code**: ``` Create a blue Part in Roblox Studio ``` ## Troubleshooting ### Plugin Installation Fails ```bash claude plugin marketplace add hope1026/weppy-roblox-mcp --scope user claude plugin install weppy-roblox-ai-toolkit@hope1026-roblox-mcp --scope user ``` ### Server Won't Start 1. Check the Node.js version (18.0 or higher required): ```bash node --version ``` 2. Test starting the server manually: ```bash npx -y @weppy/roblox-mcp@latest ``` ### MCP Tools Not Visible Check in Claude Code: ``` Show me the list of available MCP tools ``` --- ## Claude Desktop App Setup https://weppyai.com/en/docs/agents/claude-desktop/ How to use the WEPPY MCP Server from WEPPY Roblox AI Toolkit with the [Claude Desktop App](https://claude.ai/download). ## Prerequisites - **Claude Desktop App** installed - **Node.js** (v18.0.0 or higher) - **WEPPY Roblox Studio Plugin** installation complete ## Registering the MCP Server ### Method 1: Desktop Extensions (Recommended) > Available from 2026 — one-click install like a browser extension 1. Claude Desktop → **Settings** → **Extensions** 2. Search for `weppy-roblox-mcp` 3. Click **Install** ### Method 2: Edit Config File Directly 1. Claude Desktop → **Settings** → **Developers** → **Edit Config** 2. Add the following to `claude_desktop_config.json`: ```json { "mcpServers": { "weppy-roblox-mcp": { "command": "npx", "args": ["-y", "@weppy/roblox-mcp@latest"] } } } ``` 3. **Fully quit** Claude Desktop and restart it **Config file location:** | OS | Path | |----|------| | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | | Windows | `%APPDATA%\Claude\claude_desktop_config.json` | ## Connection Test 1. Launch **Roblox Studio** → Plugins tab → **WEPPY** → **Connect** 2. Start a new conversation in **Claude Desktop** and test: ``` Create a blue Part in Roblox Studio ``` ## Troubleshooting ### MCP Server Not Loading 1. **Check JSON syntax**: Validate the config file with an online JSON validator 2. **Fully restart Claude Desktop**: After changing config, always quit the app completely and restart it 3. **Check the path**: Confirm the command and args are correct ### Server Won't Start Run the MCP server directly to see the error: ```bash npx -y @weppy/roblox-mcp@latest ``` ### Connection Fails - Confirm the WEPPY Roblox Studio Plugin shows **Connected** status - Check that port 3002 is not blocked by a firewall --- ## Codex App Setup https://weppyai.com/en/docs/agents/codex-app/ How to use the WEPPY AI Agent Plugin and the WEPPY MCP Server from WEPPY Roblox AI Toolkit with [OpenAI Codex App](https://openai.com/codex/) (macOS). In Codex App, install plugins from the **Plugins** menu and find installed skills from the **Skills** menu or by invoking them in a prompt. The WEPPY AI Agent Plugin includes the MCP server config and Roblox Studio workflow skills, so installing the plugin first is recommended over manual MCP setup. ## Prerequisites - **Codex App** installed (macOS) - The **`codex` command** available in your terminal (for adding the marketplace) - **WEPPY Roblox Studio Plugin** installation complete If the `codex` command is not available, install Codex CLI: ```bash npm install -g @openai/codex ``` ## Method 1: Install the WEPPY AI Agent Plugin (Recommended) Add the WEPPY AI Agent Plugin marketplace from your terminal: ```bash codex plugin marketplace add hope1026/weppy-roblox-mcp ``` Then reopen Codex App, select the added WEPPY marketplace from the **Plugins** menu, and install **WEPPY AI Agent Plugin**. In the app, use the plus button or `Add to Codex` to install it. After installation, start a new conversation. The plugin adds the `npx -y @weppy/roblox-mcp@latest` MCP server config together with WEPPY skills. ## Check and Use Skills After installation, you can find WEPPY skills in the Codex App **Skills** menu. - **WEPPY MCP Server Guide**: direct Studio control, UI Studio, playtest, and log checks - **WEPPY Roblox Sync Guide**: Studio-local sync, sync direction, conflict handling, and Roblox Explorer context Use `@` in a prompt to target a plugin or bundled skill, or use `$` to call a specific skill. Even if you do not target one manually, Codex can use a skill automatically when your task matches its description. ## Method 2: Register the WEPPY MCP Server Manually Use this only if you want the MCP server without WEPPY skills. In the app, open **Settings** (`Cmd` + `,`) → **Integrations & MCP**, then add a custom MCP server. If you installed the plugin with Method 1, you can skip this step. ```text Server name: weppy-roblox-mcp Command: npx -y @weppy/roblox-mcp@latest ``` Codex App, Codex CLI, and IDE extensions use the same `~/.codex/config.toml` MCP settings. ## Connection Test 1. Launch **Roblox Studio** → Plugins tab → **WEPPY** → **Connect** 2. Start a new conversation in **Codex App** and test: ``` Tell me what is currently selected in Roblox Studio ``` ## Troubleshooting ### Server Won't Start Run the MCP server directly to see the error: ```bash npx -y @weppy/roblox-mcp@latest ``` ### WEPPY AI Agent Plugin Does Not Appear in the Plugins Menu Refresh the marketplace, then restart Codex App: ```bash codex plugin marketplace upgrade hope1026-roblox-mcp ``` ### Connection Fails - Confirm the WEPPY Roblox Studio Plugin shows **Connected** status - Check that port 3002 is not blocked by a firewall --- ## Codex CLI Setup https://weppyai.com/en/docs/agents/codex-cli/ How to use the WEPPY AI Agent Plugin and the WEPPY MCP Server from WEPPY Roblox AI Toolkit with [OpenAI Codex CLI](https://github.com/openai/codex) (terminal-based AI coding tool). Codex plugins can bundle skills, app integrations, and MCP server settings. WEPPY ships as a Codex plugin with the MCP server config and Roblox Studio workflow skills, so installing the plugin first is recommended over manual MCP setup. ## Prerequisites - **Node.js** (v18.0.0 or higher) - **Codex CLI** installed - **WEPPY Roblox Studio Plugin** installation complete ## Install Codex CLI ```bash npm install -g @openai/codex ``` If it is already installed, update it to the latest version: ```bash codex update ``` ## Method 1: Install the WEPPY AI Agent Plugin (Recommended) Add the WEPPY AI Agent Plugin marketplace from your terminal: ```bash codex plugin marketplace add hope1026/weppy-roblox-mcp ``` Then reopen Codex CLI and open the plugin list: ```text codex /plugins ``` Select **WEPPY AI Agent Plugin** from the added WEPPY marketplace and run `Install plugin`. After installation, start a new conversation. The plugin adds the `npx -y @weppy/roblox-mcp@latest` MCP server config together with WEPPY skills. If needed, use `@` in a prompt to target a plugin or bundled skill, or use `/skills` or `$` to find and invoke installed skills. ## Method 2: Register the WEPPY MCP Server Manually Use this only if you want the MCP server without WEPPY skills. If you installed the plugin with Method 1, you can skip this step. ### CLI Command ```bash codex mcp add weppy-roblox-mcp -- npx -y @weppy/roblox-mcp@latest ``` ### Edit Config File Directly Add the following to your `~/.codex/config.toml` file: ```toml [mcp_servers.weppy-roblox-mcp] command = "npx" args = ["-y", "@weppy/roblox-mcp@latest"] ``` **Config file location:** | OS | Path | |----|------| | macOS/Linux | `~/.codex/config.toml` | | Windows | `%USERPROFILE%\.codex\config.toml` | ## Connection Test 1. Launch **Roblox Studio** → Plugins tab → **WEPPY** → **Connect** 2. Run **Codex CLI** and enter: ``` Tell me what is currently selected in Roblox Studio ``` ## Troubleshooting ### Server Won't Start Run the MCP server directly to see the error: ```bash npx -y @weppy/roblox-mcp@latest ``` ### WEPPY AI Agent Plugin Does Not Appear in the List Refresh the marketplace, then restart Codex: ```bash codex plugin marketplace upgrade hope1026-roblox-mcp ``` ### Connection Fails - Confirm the WEPPY Roblox Studio Plugin shows **Connected** status - Check that port 3002 is not blocked by a firewall --- ## Cursor Setup https://weppyai.com/en/docs/agents/cursor/ How to use the WEPPY MCP Server from WEPPY Roblox AI Toolkit with [Cursor](https://cursor.com/). ## Prerequisites - **Cursor** installed - **Node.js** (v18.0.0 or higher) - **WEPPY Roblox Studio Plugin** installation complete ## Registering the MCP Server ### Method 1: Project Settings Add the following to your project's `.cursor/mcp.json` file: ```json { "mcpServers": { "weppy-roblox-mcp": { "command": "npx", "args": ["-y", "@weppy/roblox-mcp@latest"] } } } ``` ### Method 2: Global Settings Add the same content to the global Cursor MCP config file. **Config file location:** | Scope | Path | |------|------| | Project | `/.cursor/mcp.json` | | Global (macOS/Linux) | `~/.cursor/mcp.json` | | Global (Windows) | `%USERPROFILE%\\.cursor\\mcp.json` | > If the file already exists, merge only the `weppy-roblox-mcp` entry into the existing `mcpServers` object. ### Applying Changes After modifying the config, reload the Cursor window or restart the app. ## Connection Test 1. Launch **Roblox Studio** → Plugins tab → **WEPPY** → **Connect** 2. Enter the following in **Cursor**: ``` Tell me what is currently selected in Roblox Studio ``` ## Troubleshooting ### MCP Server Not Visible - Check that the config file path is correct - Confirm the JSON syntax is valid - Confirm you reloaded Cursor after changing the config ### Server Won't Start Run the MCP server directly to see the error: ```bash npx -y @weppy/roblox-mcp@latest ``` ### Connection Fails - Confirm the WEPPY Roblox Studio Plugin shows **Connected** status - Check that port 3002 is not blocked by a firewall --- ## Gemini CLI Setup https://weppyai.com/en/docs/agents/gemini-cli/ How to use the WEPPY MCP Server from WEPPY Roblox AI Toolkit with [Google Gemini CLI](https://github.com/google-gemini/gemini-cli). ## Prerequisites 1. **Node.js** (v18.0.0 or higher) ```bash node --version ``` 2. **Gemini CLI** installed ```bash npm install -g @google/gemini-cli ``` 3. **WEPPY Roblox Studio Plugin** installation complete ## Registering the MCP Server ### Method 1: CLI Command (Recommended) Register in one line from the terminal: ```bash gemini mcp add weppy-roblox-mcp npx --trust -- -y @weppy/roblox-mcp@latest ``` > The `--trust` flag skips the confirmation prompt on each tool call. To register as a global setting, add `-s user`: ```bash gemini mcp add weppy-roblox-mcp npx -s user --trust -- -y @weppy/roblox-mcp@latest ``` ### Method 2: Edit Config File Add the following to your `.gemini/settings.json` file: ```json { "mcpServers": { "weppy-roblox-mcp": { "command": "npx", "args": ["-y", "@weppy/roblox-mcp@latest"] } } } ``` **Config file location:** | Scope | Path | |------|------| | Project | `/.gemini/settings.json` | | Global | `~/.gemini/settings.json` | ### Method 3: Using Environment Variables When specific environment variables are needed: **CLI:** ```bash gemini mcp add weppy-roblox-mcp npx --trust -e HTTP_PORT=3002 -- -y @weppy/roblox-mcp@latest ``` **Config file:** ```json { "mcpServers": { "weppy-roblox-mcp": { "command": "npx", "args": ["-y", "@weppy/roblox-mcp@latest"], "env": { "HTTP_PORT": "3002" } } } } ``` ## Connection Test 1. Launch **Roblox Studio** → Plugins tab → **WEPPY** → **Connect** 2. Run **Gemini CLI** and enter: ``` Tell me what is currently selected in Roblox Studio ``` ## Checking MCP Server Status Use the `/mcp` command inside Gemini CLI to check the status of connected servers: ``` /mcp ``` ## Troubleshooting ### Server Won't Start Run the MCP server directly to see the error: ```bash npx -y @weppy/roblox-mcp@latest ``` ### Connection Fails - Confirm the WEPPY Roblox Studio Plugin shows **Connected** status - Check that port 3002 is not blocked by a firewall - Check server status with the `/mcp` command ### Tool Name Conflicts If multiple MCP servers have tools with the same name, the tool names are prefixed in `serverAlias__toolName` format. --- ## Check Connections https://weppyai.com/en/docs/check-connections/ After installation, the first thing to do is verify that the connection is live. Of the two methods below, **check the plugin first**. The plugin's Connect button is the most direct indicator, and you'll notice immediately when a connection is lost.
1. Check via Plugin (Recommended) 2. Check via Dashboard When Connection Fails
## 1. Check via Plugin (Recommended) Open Roblox Studio and check the plugin's Connect status — that's all you need. Once the MCP installation is complete, the plugin is automatically placed in the Roblox Studio Plugins folder the first time the MCP server runs. ### Step 1 — Find the WEPPY Button in the Plugins Tab When you open Roblox Studio, the **WEPPY** button appears in the top Plugins tab. ![WEPPY button in the Roblox Studio Plugins tab](/docs/assets/screenshots/plugin/installation/toolbar-button.png) ### Step 2 — Open the WEPPY Panel and Click Connect Click the WEPPY button to open the panel. Click **Connect** to connect to the MCP server. Once connected, the status indicator at the top changes to **Connected**. ![WEPPY plugin main screen — Connect button and connection status](/docs/assets/screenshots/plugin/installation/main-screen.png) ### What to Verify - The top status indicator shows **Connected** - If there is an active session, the session label is visible ### Plugin Settings The plugin settings screen lets you adjust the following options. - **Auto Connect** — Automatically connect to the MCP server when Studio starts - **Auto Reconnect** — Automatically retry when the connection is lost - **Language** — Change the plugin UI language ![Plugin settings screen — Auto Connect, Auto Reconnect, and Language options](/docs/assets/screenshots/plugin/installation/settings-screen.png) ## 2. Check via Dashboard Even when the plugin is connected, use the dashboard when you need to see the full connection map: which AI agents are attached, which Roblox Studio windows are available as Studio Targets, and how connection events are flowing. The dashboard opens automatically at `http://localhost:3002` when the MCP server starts. ![Connection page — topology map showing AI agents, MCP server, and Studio targets](/docs/assets/screenshots/dashboard/dashboard_connection.png) ### Connection Topology The first card shows the runtime shape at a glance: AI agents connect to one MCP server, and one or more Roblox Studio windows connect as Studio Targets. The MCP Server node also shows the current routing mode for agent requests that do not name a specific Studio target. ### AI Agents The AI Agents column and diagnostic table show the clients currently attached to the MCP server. Use this when you need to confirm that Claude Code, Codex, Gemini, or another agent is connected from the expected project folder. ### Studio Targets Studio Targets are the connected Roblox Studio windows that can receive MCP requests. Each target has a read-only **Studio ID** such as `studio-1`, plus place information, last-used timing, connection state, and a **Priority** or **Pinned** badge when it is the default target for requests without a named Studio. When several Studio windows are connected, copy the Studio ID and include it in your prompt, for example: `use Studio ID studio-1`. To change the default target for requests that do not name a Studio, open **Controls → Studio Routing** from the Connection page. ### Server Status and Connection Log Server Status shows core MCP process information such as version, uptime, session, and executable path. Connection Log shows agent and Studio Target connect/disconnect events in real time through SSE.
Dashboard Guide →
## 3. When Connection Fails If neither method above shows a connection, check in the following order. ### Plugin Not Visible - Fully quit Roblox Studio and relaunch it - Check that the WEPPY plugin file is present in the auto-installed Plugins folder - If auto-install didn't work, see the [Plugin Installation Guide](/en/docs/guides/mcp-plugin/) for manual installation steps ### Connect Fails in the Plugin Panel - Verify that your AI app is actually running the MCP server. You can also run it directly: ```bash npx -y @weppy/roblox-mcp@latest ``` - Check that port `3002` is available — quit any process occupying it - Make sure no firewall, antivirus, or VPN is blocking `localhost:3002` - Check that the **Auto Reconnect** option is enabled in the plugin settings - If none of the above works, restart both Roblox Studio and the MCP server ### Dashboard Doesn't Open - Check the AI app console logs to verify the MCP server started successfully - Open `http://localhost:3002` directly in your browser - The server only binds to `127.0.0.1`. It cannot be accessed from any other host. ### Agent Not Registering - Review the [per-agent setup guide](/en/docs/agents/claude-code/) for your AI app to re-check the MCP registration steps - Fully quit your AI app and relaunch it (Codex CLI, Cursor, and Claude Desktop all require a restart when registration changes)
Troubleshooting Guide → Review Installation
--- ## First Workflows https://weppyai.com/en/docs/first-workflows/ Once WEPPY is installed and connected, you can use an AI agent to control Roblox Studio directly. This page walks you through the basic flow for starting your first task and safely verifying the results. ## Core Workflow ### Step 1 — Verify the Connection Before starting a task, confirm the connection status. ``` Check the connection status ``` Or follow the steps on the [Check Connections](/en/docs/check-connections/) page. Check the plugin's Connect status first, and use the dashboard's Connection tab if you need more details. ### Step 2 — Submit Your First Task Start with something simple. Give instructions to the AI agent in natural language. ``` Create a red Part in Workspace. Set the size to 5x1x5. ``` ``` Create a 'GameManager' ModuleScript in ServerScriptService. ``` ``` Set the Lighting time to 6:00 PM. ``` ### Step 3 — Review the Results When the AI performs a task, it's reflected in Studio immediately. You can review changes Before & After in the dashboard's Changelog. See the [Change History](/en/docs/review-changes/) page for details. ### Step 4 — Move to More Complex Tasks Once you've verified the basics, move on to tasks that involve multiple changes at once. ``` Add a particle effect and sound when the player jumps, and include a cooldown. ``` ``` Build a boss arena in the center of the map and place spawn points without collisions. ``` ``` Change this module's interface and update all scripts that reference it. ``` ## Core Tool Examples ### Creating Instances ``` Create a 'Platform' Part in Workspace and set its Position to (0, 5, 0). ``` Internally, the `mutate_instances` tool's `create` action and the `manage_properties` tool's `set` action are used. ### Writing Scripts ``` Create a 'PlayerController' Script in ServerScriptService that prints a message when a player spawns. ``` Internally, the `manage_scripts` tool's `create` and `set_source` actions are used. ### Inserting Assets ``` Search for a 'Tree' model in the Creator Store and insert it into Workspace. ``` Internally, the `manage_assets` tool's `search_insert` action is used. ### Batch Execution When processing multiple tasks at once, using `batch_execute` saves AI tokens. ## Large-Scale Changes with Sync To work from the full project structure, activate Sync first. With Sync enabled, the AI uses locally synced files as its reference to understand the entire structure and apply consistent changes across multiple files. ``` Check the Sync status and summarize only the risky changes based on recent history. ``` ``` Refactor the scripts in ServerScriptService first and keep a change history. ``` See [Bidirectional Sync](/en/docs/sync/) for details. ## Next Steps
Change History → Playtest Bidirectional Sync
--- ## Getting Started https://weppyai.com/en/docs/getting-started/ import DocsAgentGrid from '../../../components/docs/DocsAgentGrid.astro'; Using Roblox MCP requires two components. ``` AI app (Claude, Codex, Gemini, etc.) │ MCP Server ← Translates AI commands into a form Roblox understands │ Roblox Studio Plugin ← Executes commands inside Studio ``` When your AI app says "create a blue Part," the MCP server translates the request and the Roblox Studio plugin actually creates the Part. ## One-Line Install (Recommended) Open the [web install page](/en/install/) first and use the one-line install guidance for your platform. The single command below installs both the MCP server and the plugin at once. **macOS / Linux** ```bash curl -fsSL https://raw.githubusercontent.com/hope1026/weppy-roblox-mcp/main/install.sh | bash ``` **Windows (PowerShell)** ```powershell irm https://raw.githubusercontent.com/hope1026/weppy-roblox-mcp/main/install.ps1 | iex ``` After installation, reopen your AI app and restart Roblox Studio. If an error occurs during installation, the path to a temporary log file is printed. In interactive mode, the console stays open before exiting so you can see the cause. Automatic MCP registration is supported for **Claude Code, Claude Desktop, Cursor, Codex CLI / App, Gemini CLI, and Antigravity / Antigravity IDE / Antigravity CLI**. If terminal or PowerShell is uncomfortable, use the terminal-free web installer on the same [web install page](/en/install/). If PowerShell execution is blocked on Windows, proceed with manual installation below. When using the ZIP package, you can run `setup-plugin.bat` and `setup-mcp.bat`. ## Manual Installation An alternative procedure if the one-line install and web installer do not work or automatic installation is not available in your environment. ### Step 1 — Install the Roblox Studio Plugin Download the plugin file from GitHub and place it in the Roblox Studio Plugins folder.
Plugin Installation Guide →
### Step 2 — Register the MCP Server in Your AI App Choose your AI app and follow its setup guide. WEPPY works with any AI app that supports MCP. > Even if your AI app isn't listed above, you can use it as long as it supports MCP. The MCP server command is `npx -y @weppy/roblox-mcp@latest`. ## Optional — WEPPY Roblox Explorer (VSCode Extension) Browse the synced instance tree with Roblox class icons right inside VSCode. This extension requires the Roblox MCP installation above to be completed first, since Explorer reads the `weppy-project-sync` sync data under your project root.
Roblox Explorer Guide → VS Code Marketplace Open VSX (Antigravity, etc.)
## After Installation 1. Open **Roblox Studio** and click **WEPPY → Connect** in the Plugins tab. 2. Test it from your AI app: ``` Create a blue Part in Roblox Studio ``` 3. If the Part is created successfully, the installation is complete.
Check Connections → Troubleshooting
--- ## Assets & Object Presentation Guide https://weppyai.com/en/docs/guides/assets/ > Save generated images, RBXM files, and Creator Store assets in Asset Library, then carry them through Roblox upload and Place application. ![Assets page — local Asset Library items and Roblox upload status](/docs/assets/screenshots/dashboard/dashboard_assets.png) ## From Generated Image to Place When you need an icon, Decal, or UI image, the manual process usually means saving a file, uploading it in Creator Dashboard, copying the asset ID, then pasting it into a Studio property. WEPPY Assets keeps that work in one request. ``` "Create a gem icon for the shop button, upload it to Roblox, then apply it to the ShopButton image in the Lobby Place" ``` The usual path is: 1. The AI creates or prepares the needed image or file. 2. The file is saved to the current Place Asset Library or the shared Asset Library. 3. WEPPY runs the Roblox Open Cloud upload. 4. The uploaded asset URI is applied to Studio properties such as ImageLabel, Decal, or Texture. Saved assets can be reused in the same Place, or stored as shared assets for another Place. ## Asset Library The Dashboard **Assets** page shows the local Asset Library. - Separate current Place assets from shared assets. - Review Images, Decals, and RBXM files. - Edit asset names and descriptions, then check upload status. - After Roblox upload, copy the asset ID and Studio-ready URI. When you want to keep a Studio selection as an RBXM file, use **Save Selection to Library** from the WEPPY Plugin **Assets** tab. It saves the selected Studio object into the local Asset Library so it can be inserted again later, including in another Place. ## Reuse Assets Across Places When several Places are open at once, separate Place-specific assets from shared assets. Keep a Lobby-only button image as a current Place asset, but save icons or RBXM files that should also be used in Game or Shop as shared assets. ```text Create a gem icon for the shop as a shared asset and upload it to Roblox. Apply that asset URI to ShopButton in studio-1 Lobby and RewardPanel in studio-2 Game. ``` Naming the Studio ID tells the AI exactly where to apply the uploaded asset after Open Cloud returns the URI. See the [Multi-Place Work guide](/en/docs/guides/multi-place/) for the multi-Studio setup. ## Assets & Object Presentation ### Included Tools | Tool | Description | | ------ | ------ | | `manage_assets` | Creator Store search/insert, RBXM export/import, thumbnail generation | | `manage_open_cloud_assets` | Roblox Open Cloud upload, update, and status checks | | `manage_tween` | Create, play, pause, and cancel tweens | | `manage_animation` | Load, play, stop animations, and query tracks | | `manage_audio` | Play/stop/pause sounds, set audio listener | | `manage_effects` | Emit, clear, and toggle particle effects | | `manage_physics` | Register collision groups, set collidability | ### Key Workflows **Building a Scene with Assets** ``` "Search for a 'tree' model in the Creator Store and place 3 of them in Workspace" ``` Use `manage_assets`'s `search_insert` to search and insert in one step. **Generated Image Upload and Application** ``` "Create a red cracked texture for the boss health bar, upload it to Roblox, then apply it to the BossHud ImageLabel" ``` Save the image file in Asset Library, then upload it through `manage_open_cloud_assets` or the Dashboard upload action. After upload, apply the returned `rbxassetid://...` URI to the Studio UI or Decal property. **Save a Studio Selection as an RBXM Asset** ``` "Save the currently selected treasure chest model to Asset Library and generate a thumbnail" ``` Use the Plugin Assets tab or `manage_assets` RBXM export actions to save the current selection as a local asset. The saved RBXM can be inserted into another Place later. **Interactive Presentation** ``` "Create a tween that opens a door over 3 seconds when clicked" ``` Use `manage_tween`'s `create` to define the tween and `play` to run it. Simultaneously add a door-opening sound effect with `manage_audio`'s `play`. **Particles + Sound Combination** ``` "Play an explosion particle effect along with a sound effect when the boss appears" ``` Use `manage_effects`'s `emit` to emit particles and `manage_audio`'s `play` to play the sound simultaneously. ### Action Reference **Manage Assets** | Action | Description | | ------ | ------ | | `insert` | Insert a model by asset ID | | `info` | Get asset metadata | | `search` | Search the Creator Store | | `search_insert` | Search and insert the first match | | `insert_free` | Insert a free model | | `insert_package` | Insert a package | | `export_selection_rbxm` | Save the current selection as an RBXM asset | | `export_path_rbxm` | Save a Studio path as an RBXM asset | | `import_rbxm` | Insert an RBXM from Asset Library into Studio | | `generate_thumbnail` | Generate a thumbnail for a selection or asset | **Manage Open Cloud Assets** | Action | Description | | ------ | ------ | | `credential_status` | Check Open Cloud API key and Creator setup status | | `capabilities` | Check upload capability by category | | `upload` | Upload a local asset file to Roblox | | `update` | Update a supported Roblox asset category | | `info` | Read Roblox asset information | | `operation_status` | Check Open Cloud operation status | **Manage Tween** | Action | Description | | ------ | ------ | | `create` | Create a tween with target properties | | `play` | Play a created tween | | `pause` | Pause a running tween | | `cancel` | Cancel a tween | **Manage Animation** | Action | Description | | ------ | ------ | | `load` | Load an animation onto a Humanoid/AnimationController | | `play` | Play a loaded animation track | | `stop` | Stop a playing animation | | `get_tracks` | List all loaded animation tracks | **Manage Audio** | Action | Description | | ------ | ------ | | `play` | Play a sound (creates a Sound if needed) | | `stop` | Stop a playing sound | | `pause` | Pause a playing sound | | `resume` | Resume a paused sound | | `set_listener` | Set audio listener type and target | **Manage Effects** | Action | Description | | ------ | ------ | | `emit` | Emit particles from a ParticleEmitter | | `clear` | Clear all particles | | `toggle` | Enable or disable an effect | **Manage Physics** | Action | Description | | ------ | ------ | | `register_group` | Register a collision group | | `set_collidable` | Set whether two groups can collide | | `get_groups` | List all registered collision groups | ## World Environment ### Included Tools | Tool | Description | | ------ | ------ | | `manage_lighting` | Configure Lighting, Atmosphere, Sky, and time of day | | `manage_terrain` | Generate/edit terrain and manage voxel data | | `spatial_query` | Raycasting, ground detection, placement validation, heightmaps | | `manage_camera` | Query camera info, move focus, suggest views, capture Edit-mode viewport screenshot | ### Key Workflows **Setting World Atmosphere** ``` "Change the mood to dusk: orange sky, increase fog density, set time to 18:00" ``` Use `manage_lighting`'s `time` to set the time of day, `atmosphere` to adjust fog, and `sky` to change sky color. **Building Terrain** ``` "Create a grassy hill with radius 200 in the center of the map and fill the surrounding area with water" ``` Use `manage_terrain`'s `fill_ball` to create the hill and `fill_block` to fill the surrounding water area. **Placement Validation** ``` "Find a flat area where I can place this building" ``` Use `spatial_query`'s `find_flat` to locate a suitable area, `check_placement` to confirm no collisions, then `manage_camera`'s `focus_position` to visually verify the result. ### Action Reference **Manage Lighting** | Action | Description | | ------ | ------ | | `lighting` | Set Lighting service properties | | `atmosphere` | Set Atmosphere properties | | `sky` | Set Sky properties | | `terrain_props` | Set Terrain water/visual properties | | `time` | Set time of day | **Manage Terrain** | Action | Description | | ------ | ------ | | `fill_block` | Fill terrain in a block shape | | `fill_ball` | Fill terrain in a sphere shape | | `fill_cylinder` | Fill terrain in a cylinder shape | | `fill_wedge` | Fill terrain in a wedge shape | | `clear_region` | Clear terrain in a region | | `clear_bounds` | Clear terrain within bounds | | `replace_material` | Replace material in a region | | `colors_get` | Get material colors | | `colors_set` | Set material colors | | `read_voxel` | Read a single voxel | | `read_voxels` | Read voxels in bulk | | `write_voxels` | Write voxels in bulk | | `generate` | Generate procedural terrain | | `smooth` | Smooth terrain | **Spatial Query** | Action | Description | | ------ | ------ | | `raycast` | Single raycast | | `find_ground` | Find ground position below a point | | `check_placement` | Check if placement is collision-free | | `multi_raycast` | Batch multiple raycasts | | `scan_area` | Generate a heightmap of an area | | `find_flat` | Find a flat area for construction | | `find_spawn` | Find a suitable spawn position | | `analyze_walkable` | Analyze walkable area grid | | `spatial_map` | Get positions of all BaseParts | | `find_space` | Find empty space for an object | | `bounds` | Get the bounding box of an instance | | `snap_grid` | Snap a position to a grid | | `collision` | Check AABB collision | **Manage Camera** | Action | Description | | ------ | ------ | | `info` | Get camera position, rotation, FOV, and viewport size | | `focus_path` | Focus camera on an instance by path | | `focus_position` | Focus camera on a position | | `suggest` | Get a suggested camera view for a target | | `screenshot` | Capture the current Studio Edit-mode viewport as a PNG image (Edit mode only) | --- ## MCP Dashboard Guide https://weppyai.com/en/docs/guides/dashboard/ > Monitor and manage server status, connections, sync, tool execution history, and game change history in real time from a web browser. ![Dashboard Overview — server status, recent changes, and session summary at a glance](/docs/assets/screenshots/dashboard/dashboard_overview.png) ## Overview The dashboard is the web-based monitoring interface provided by the MCP server. It opens automatically in your browser when the MCP server starts, and lets you track everything the AI agent does in Roblox Studio in real time. - Understand system state visually without digging through terminal logs - Track what the AI changed in Studio via the change history - View sync status, connection status, and tool execution statistics in one place ### How to Access The dashboard opens automatically in your browser when the MCP server starts. To open it manually: ``` http://localhost:3002 ``` > Set `DASHBOARD_AUTO_OPEN=false` to disable automatic opening. ### Available Features by Connection State | State | Condition | Available Pages | |------|------|-------------------| | **Server disconnected** | Server not running | Reconnection waiting screen only | | **Server connected** | Server connected, plugin not connected | Connection, Tools, Settings | | **Studio connected** | Both server and plugin connected | All pages | ### Status Cards The Overview page is the dashboard's home screen and shows the overall system state at a glance. | Card | Information Shown | |------|----------| | **Server** | Server connection state (Online/Offline) | | **Plugin** | Plugin connection state and Place info | | **Agent** | Currently connected AI agent name | | **Sync** | Sync state (Idle/Syncing/Error) | ### Recent Game Changes Displays the most recent changes the AI made in Studio in real time (up to 20). Each entry is shown with a change category icon, and clicking it takes you to the Changelog detail view. Category icons: - Script — scripts created/modified - Instance — instances created/deleted/moved - Property — property changes - Lighting — lighting/environment changes - Terrain — terrain changes - Asset — assets inserted The dashboard uses SSE (Server-Sent Events) to update data in real time. It automatically reconnects 3 seconds after an SSE connection is lost. ## Connection > Inspect the MCP server, attached AI agents, connected Studio Targets, and connection log in one place. ![Connection page — topology map showing AI agents, MCP server, and Studio targets](/docs/assets/screenshots/dashboard/dashboard_connection.png) The Connection page is the fastest way to understand how the local MCP runtime is wired at the moment. It is available whenever the dashboard is in **Server connected** or **Studio connected** state. ### Connection Topology The topology map shows three conceptual columns: **AI Agents → MCP Server → Studio Targets**. It is display-first: connector lines show what is attached to the MCP server, but they do not change routing by themselves. The MCP Server node shows server status plus the current routing summary for requests that do not name a Studio target. ### Studio Targets Studio Targets are the connected Roblox Studio windows that can receive MCP requests. Each target displays: | Field | Meaning | |------|------| | Studio ID | Short selector such as `studio-1` that you can copy into an agent prompt | | Place / Place ID | The Roblox place currently associated with that Studio window | | Connection ID | The full connection identifier for diagnostics | | Last Used / Last Seen | When WEPPY routed work to the target and when it last heard from it | | Routing | Whether the target is currently **Priority** or **Pinned** | | In Flight | Whether a request is currently running on that target | To aim an agent at a specific Studio window, copy the Studio ID and say something like `use Studio ID studio-1`. ### Studio Routing Studio routing only affects requests that do not name a Studio target. - **Automatic: Recent priority** chooses the highest-priority active Studio target. Recent routed work takes priority over simple heartbeat activity. - **Manual: Pinned Studio** sends selector-less requests to the pinned connected target. - Explicit Studio ID, Connection ID, or Place ID in an agent request always wins over the dashboard routing mode. Connection shows the current mode and a **Manage routing** link. Change the mode or pinned target from **Controls → Studio Routing**. ### Multi-agent and Multi-Studio Workflows Use this page when more than one agent or Studio window is active. You can keep Claude Code, Codex, Gemini, or another agent connected at the same time, and keep Lobby, Game, Shop, or Tutorial Places visible as separate Studio Targets. Good prompts are explicit about the target: - `Use Studio ID studio-1 for this change.` - `Run this in the Lobby place, not the World place.` - `Check studio-2 before changing shared scripts.` - `In studio-1, add the event portal to Lobby. In studio-2, add the arrival point and guide UI to Game.` This is useful when one request needs to split work by Place, or when separate agent sessions each name their target Studio ID. One agent does not directly send work to another agent. Check which Studio ID belongs to which Place in Dashboard before prompting, so each agent modifies the intended Place. For prompt patterns and a wrong-Place checklist, continue with the [Multi-Place Work guide](/en/docs/guides/multi-place/). ### Diagnostics The lower diagnostic tables keep the detailed Server Status, AI Agents, Studio Targets, and Connection Log data available for copying identifiers, checking working directories, and reviewing connect/disconnect events. ## Controls > Set whether the AI can use Studio, and whether Script edits are automatically checked for syntax errors. ### Luau Syntax Validation — Automatic Script Syntax Checking When you let the AI edit Scripts, this setting automatically checks for Luau syntax errors right after the edit is saved. The check runs without starting Playtest, so it can immediately catch a missing `end`, a mismatched bracket, or two lines merging into broken syntax during an edit. Available on both Basic and Pro. The default is **Off**. Turn it on or off from **Controls → Luau Syntax Validation** in Dashboard. | Setting | After the AI edits a Script | |------|------| | **Off** | No automatic syntax check runs. Script edits complete at the usual speed | | **On** | Checks the full code that was actually saved to Studio or the Sync file. If there's a syntax error, the same response reports where and why | This setting takes priority over the AI's request. With **On**, the check still runs even if the AI tries to skip it — turning it off requires switching Dashboard to **Off**. Conversely, with **Off**, even if the AI asks for a syntax check along with a Script edit, the automatic check does not run, and the response tells the AI to switch Dashboard to **On**. Finding a syntax error never undoes a change that was already saved. Instead, the AI can see which Script and which line to fix in the same response, so it can correct it before Playtest starts. With **On**, the full saved Script is checked again, so larger Scripts can make the response a little slower. When the syntax is valid, the response stays as simple as usual; details are added only when there's an error or the check couldn't run. The syntax check runs on your computer and never sends Script code to an external checking service. The file needed for the first check is downloaded from WEPPY's GitHub Release, and later checks reuse the file already stored on your computer. If a network issue prevents the check file from being prepared, the Script edit still completes as normal, and the response reports that the syntax check could not run. This setting only controls the **automatic check** that runs after the AI edits a Script. Even with **Off**, you can still ask the AI directly, "Check the Luau syntax of this Script." ## Sync > Monitor the current sync state, direction settings, and logs for Studio ↔ local file sync. The Sync page visually shows the current state and configuration of Studio ↔ local file sync. It is only accessible when the dashboard is in **Studio connected** state. ### Sync Status | Status | Meaning | |------|------| | **Idle** | Sync is idle | | **Initializing** | Initial sync in progress | | **Syncing** | Incremental sync in progress | | **Error** | Sync error occurred | The status card also shows the sync path, number of synced instances, and the current Apply Mode (Auto/Manual). ### Sync Directions Shows per-type sync directions in a table: | Column | Description | |----|------| | Type | Sync target type (Scripts, Values, Instances, Data, Services) | | Direction | Sync direction (Local → Studio, Studio → Local) | | Apply Mode | Apply mode (Auto/Manual) | The Sync Log shows sync events in chronological order. Each log entry includes a change type tag (create, update, delete, etc.) and the target path. ## Changelog > Records all changes the AI makes in Roblox Studio by session and provides a change summary, timeline, and Before & After comparison. ![Changelog — list of session change cards](/docs/assets/screenshots/dashboard/dashboard_changelog1.png) The Changelog tracks the game change history that AI agents perform in Studio. Changes are grouped by session so you can see at a glance what type of changes happened and how many in each session. ### Session Card List Each session card shows a status: | Status | Meaning | |------|------| | **Active** | Currently ongoing session (updates in real time) | | **Completed** | Finished session | | **Bootstrap** | Initial sync session | Each card shows a per-category count of changes for that session (Script, Instance, Property, Lighting, Terrain, Asset). Use the top tabs to filter sessions: **All**, **Active**, **Completed**. ### Session Detail View Click a session card to enter the detail view. **Change Summary**: Visualizes the session's changes as 6 category cards (Scripts, Instances, Properties, Lighting, Terrain, Assets). **Change Timeline**: Lists all changes in the session in chronological order. Use the Category dropdown to filter by a specific category; click an entry to expand the Before & After comparison view. ### Before & After | Confidence | Meaning | Example | |--------|------|------| | **exact** | Before and after values are precisely recorded | Property change, script edit | | **partial** | Only partial information recorded | Compound change | | **after-only** | Only the after value exists | New instance creation | | **intent-only** | Only the intent is recorded | Deletion, etc. | ## Playtest > Check the status and results of playtests run by the AI. ![Playtest — playtest status and test history](/docs/assets/screenshots/dashboard/dashboard_playtest.png) The Playtest page shows the status and results of playtests the AI has run. It is only accessible when the dashboard is in **Studio connected** state. ### Playtest Status | Status | Meaning | |------|------| | **NotRunning** | Playtest is not running | | **Running** | Playtest is running | | **Paused** | Playtest is paused (Run mode only) | ### Test History Lists test results from AI `run_test` action calls in chronological order: | Field | Description | |------|------| | Timestamp | Test execution time | | Test Report | Link to the test report | | Mode | Execution mode (play/run) | | Duration | Time the test took | | Status | Result (Passed/Failed) | Click a test report to view the detailed markdown report and logs. ## Tools > View the execution history and statistics for MCP tools run by the AI. ![Tools — tool execution history and statistics](/docs/assets/screenshots/dashboard/dashboard_tools.png) The Tools page shows the execution history and statistics for MCP tools the AI has run. It consists of two sub-tabs: **History** and **Statistics**. It is always accessible when the dashboard is in **server connected** or **Studio connected** state. ### History Tab Shows tool execution history in a chronological table: | Column | Description | |----|------| | Time | Execution time | | Tool.Action | Tool and action executed (e.g., `query_instances.get_instance`) | | Duration | Time taken to execute | | Status | Result status (OK/Error) | | Tier | Tier used (Basic/Pro) | Features: Filter by specific tool using the Tool dropdown, browse large histories with pagination, new execution records are added in real time. ### Statistics Tab Visually analyzes tool usage statistics: - **Tier distribution** — Basic/Pro tool usage ratio - **Per-tool statistics** — call count and average response time per tool - **Per-action analysis** — detailed per-action statistics within a tool Basic tier users also see a Tier Usage Progress bar and a Basic vs Pro comparison modal. ## Settings > View and manage license information, server settings, and language. The Settings page lets you view and modify license information and server settings. It is always accessible when the dashboard is in **server connected** or **Studio connected** state. ### License (Read-Only) | Field | Description | |------|------| | Status | Status badge (Active/Inactive) | | Tier | Current tier (Basic/Pro) | | License Key | Masked license key | | Provider | License provider info | ### General | Setting | Description | |------|------| | Log Level | Log output level | | History Recording | Whether to save tool execution history | | Stats Collection | Whether to collect tool usage statistics | | Request Timeout | Request timeout (seconds) | ### Server Environment (Read-Only) | Environment Variable | Description | Default | |----------|------|--------| | `HTTP_PORT` | HTTP port | 3002 | | `HTTP_HOST` | HTTP host | 127.0.0.1 | | `DASHBOARD_AUTO_OPEN` | Auto-open dashboard | true | ### Language Change the dashboard UI language. Supports 6 languages + Auto (auto-detect from browser). | Option | Language | |------|------| | Auto | Auto-detect from browser | | English | English | | 한국어 | Korean | | 日本語 | Japanese | | Español | Spanish | | Português | Portuguese | | Bahasa Indonesia | Indonesian | --- ## Roblox Explorer Guide https://weppyai.com/en/docs/guides/explorer/ **WEPPY Roblox Explorer** is a companion extension that shows the Roblox Studio Explorer tree in the same form inside editors like VSCode and Antigravity. You can navigate the synced instance hierarchy, open scripts, and edit properties without switching back and forth between Studio and your editor. > **Optional** — Explorer is not required. All core features work with just the MCP server and Roblox Studio plugin. Install it when you want to navigate the project structure or quickly view and edit properties without leaving your editor. ![WEPPY Roblox Explorer — Studio instance tree displayed in the VSCode sidebar](/docs/assets/screenshots/roblox-explorer/roblox-explorer-screen.png) ## Why Use Explorer The sync files alone are enough for the AI to understand the full project context, but when humans navigate manually, file paths alone don't reveal the structure clearly. Explorer re-presents the same sync data in **the same hierarchy as Roblox Studio**, which makes the following easier. - See at a glance which service/instance a script lives under - Quickly find instances across services by name or path - Check sync status (modified / studio / conflict) per file - Edit property values without switching to Studio ## Requirements - VSCode 1.85+ or Antigravity - [Roblox MCP](/en/docs/getting-started/) installed with Sync active - `weppy-project-sync/place_*/.sync-meta.json` present under the project root (created by Sync) Explorer works by reading sync files from disk, and additionally reflects real-time sync status and direction info when the local MCP server is running. ## Installation Search for **WEPPY Roblox Explorer** in the Extensions sidebar (`Ctrl+Shift+X` / `Cmd+Shift+X`) in VSCode or Antigravity, and click **Install**. Marketplace direct links: - [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=weppy.weppy-roblox-explorer) - [Open VSX](https://open-vsx.org/extension/weppy/weppy-roblox-explorer) Antigravity is VSCode-based and uses the same extension. ## Navigating the Instance Tree After installation, a **WEPPY Explorer** view is created in the VSCode Activity Bar, and it automatically discovers the sync directory from the project root. - **Service roots**: Synced services like `Workspace`, `ReplicatedStorage`, and `ServerScriptService` appear at the top level. - **Roblox class icons**: 200+ Studio icons automatically switch between dark/light themes. - **Multi-place**: When multiple Places are synced, each Place has a separate tree root. - **Auto-refresh**: The tree is refreshed automatically with a 500ms debounce when sync files change. - **Sync status badges**: `modified`, `studio`, and `conflict` states are shown next to icons so you can spot changes and conflicts instantly. Clicking an item in the tree opens the file backing that instance (`.server.luau`, `.client.luau`, `.module.luau`, `.props.json`, etc.) directly. The right-click menu lets you copy the instance path in `game.Workspace.Part` format, or reveal the file's location in the default VSCode Explorer. ## Property Panel Select an instance in the Explorer tree and run the **Open Properties** command to open a panel that looks like Studio's Properties window. You can view and edit properties by group without directly editing the `.props.json` file. ![Property Panel — Studio-style property editing inside VSCode](/docs/assets/screenshots/roblox-explorer/roblox-explorer-property-window.png) - **Group display**: Properties are organized in the same categories as Studio — Appearance, Behavior, Data, Part, Transform, etc. - **Type-aware editors**: Input widgets are provided for each property type: number, string, Boolean, Color, Vector3, Enum, etc. - **File-based editing**: Changes are saved to the instance's `*.props.json` file and reflected in Studio via Sync's reverse path when bidirectional mode is active. - **Custom editor registration**: Opening a `.props.json` file directly automatically launches the Property Panel instead of the default editor. To have the Property Panel open automatically, set `robloxExplorer.propertyPanel.autoOpen` to `true` in settings. ## Instance Search Use the `WEPPY Explorer: Search Instances` command (the icon at the top of the view, or the Command Palette) for a QuickPick-based search across all services. - Quickly find instances by partial name match - Focus jumps to the matching item in the tree when a result is selected - Searches across per-place namespaces when multiple Places are synced ## Settings | Setting | Default | Description | |------|--------|------| | `robloxExplorer.mcpBaseUrl` | `""` | Local MCP HTTP base URL. If empty, tries `http://127.0.0.1:3002` then `http://127.0.0.1:3003`. | | `robloxExplorer.syncRoot` | `""` | Absolute path to the `weppy-project-sync` root. If empty, auto-discovers from workspace folders. | | `robloxExplorer.hidePropsFiles` | `false` | Hides sync files (`.props.json`, `_tree.json`, `.value.json`) in the default VSCode Explorer. | | `robloxExplorer.autoRefresh` | `true` | Auto-refreshes the tree when sync files change. | | `robloxExplorer.showSyncStatus` | `true` | Shows sync status badges on tree items. | | `robloxExplorer.followFocusCue` | `false` | Auto-expands the tree and opens related files based on an external focus cue file. | | `robloxExplorer.propertyPanel.autoOpen` | `false` | Automatically opens the Property Panel when an instance is selected in the tree. | ## Commands | Command | Description | |--------|------| | `WEPPY Explorer: Refresh` | Manually refresh the instance tree | | `WEPPY Explorer: Search Instances` | Search for instances across all services | | `WEPPY Explorer: Open Backing File` | Open the backing file for the selected instance | | `WEPPY Explorer: Open Properties` | Open the Property Panel for the selected instance | | `WEPPY Explorer: Copy Instance Path` | Copy the full instance path (e.g., `game.Workspace.Part`) | | `WEPPY Explorer: Reveal in Explorer` | Show the file location in the default VSCode Explorer | | `WEPPY Explorer: Collapse All` | Collapse all tree nodes | | `WEPPY Explorer: Open Settings` | Open the Explorer settings page | ## Troubleshooting - **Tree is empty**: Check that the `weppy-project-sync/place_*` directory exists and that Sync has completed at least one Full Sync. If needed, set `robloxExplorer.syncRoot` manually. - **Sync status not showing**: Confirm the local MCP server is running, and try explicitly setting `robloxExplorer.mcpBaseUrl`. - **Property Panel won't open**: If a `.props.json` file opens in the default editor, right-click the file and select **Reopen Editor With... → WEPPY Property Panel**. - **Icons broken**: Re-select your VSCode theme or restart the window to refresh the icon cache. --- ## Roblox Studio Plugin Installation Guide https://weppyai.com/en/docs/guides/mcp-plugin/ How to install the plugin that connects Roblox Studio to the AI agent. ## Automatic Installation (Recommended) If the MCP server installation is complete, the plugin is **installed automatically**. No separate download or file copying is needed. ### How It Works 1. The first time the MCP server runs, it automatically places the plugin file (`WeppyRobloxMCP.rbxm`) in Roblox Studio's Plugins folder. 2. When Roblox Studio starts, the **WEPPY** button appears in the Plugins tab. ### Connecting 1. Open any project in **Roblox Studio** 2. Click the top **Plugins** tab → **WEPPY** ![WEPPY button](/docs/assets/screenshots/plugin/installation/toolbar-button.png) 3. Click the **Connect** button in the plugin window 4. When **"Connected"** status is shown, the connection is complete ![Plugin main screen](/docs/assets/screenshots/plugin/installation/main-screen.png) > If automatic installation doesn't work, proceed with the manual installation below. ## Manual Installation Use this when automatic installation doesn't work, or when you need to install a specific version directly. ### 1. Download the Plugin 1. Open [GitHub Releases](https://github.com/hope1026/weppy-roblox-mcp/releases/latest) 2. Download `weppy-roblox-mcp-v{version}.zip` 3. Extract the ZIP — it includes the `roblox-plugin/WeppyRobloxMCP.rbxm` file ### 2. Install the Plugin 1. Launch **Roblox Studio** 2. Click the **Plugins** tab in the top menu 3. Click the **Plugins Folder** button 4. **Copy** `WeppyRobloxMCP.rbxm` from the extracted folder into the opened Plugins folder 5. **Restart Roblox Studio** ### 3. Verify Installation After restarting, the **WEPPY** button appears in the Plugins tab. ![WEPPY button](/docs/assets/screenshots/plugin/installation/toolbar-button.png) ### 4. Connect Click the Connect button following the same steps in the "Connecting" section above. ## Settings (Optional) Click the settings button in the top-right of the plugin to change various options. ![Settings screen](/docs/assets/screenshots/plugin/installation/settings-screen.png) - **Auto Connect**: Automatically connect to the MCP server when Studio starts - **Auto Reconnect**: Automatically retry when the connection is lost - **Auto Camera Focus**: Automatically move the camera to newly created objects - **Language**: Change the plugin UI language ## Troubleshooting ### Plugin Not Visible - Fully quit Roblox Studio and restart it - Check that the file was properly copied to the Plugins folder - Confirm the `.rbxm` file is not corrupted ### Connection Fails - Confirm the MCP server is running in your AI app - Click the **Connect** button in the plugin again - Check whether port 3002 is in use by another program ### Connection Drops Frequently - Enable the **Auto Reconnect** option in settings - Restart your AI app --- ## Multi-Place Work Guide https://weppyai.com/en/docs/guides/multi-place/ > Keep Lobby, Game, Shop, and Tutorial Places open in separate Roblox Studio windows, then split one request across them by Studio ID. ![Connection page — multiple AI agents and Studio Targets connected](/docs/assets/screenshots/dashboard/dashboard_connection.png) ## When to Use It Many Roblox experiences are made of several Places. You may need a portal in Lobby, an arrival point in Game, a Shop UI, and Tutorial guidance that all match the same event or feature. Multi-Place Work connects multiple Roblox Studio windows to one MCP server. The Dashboard labels each Studio window with a Studio ID such as `studio-1` or `studio-2`, and the AI agent uses that ID to send work to the right Place. The benefit is less repeated context and less manual copying. You can say “do this in Lobby and that in Game” in one request. If you use several agents in separate sessions, each agent can name its own Studio ID, and the Dashboard still shows which agent and Studio target are active. ## Setup 1. Open each Place in its own Roblox Studio window. 2. Connect the WEPPY Plugin in each Studio window. 3. Open the Dashboard **Connection** page. 4. Check the Place name, Place ID, and Studio ID under **Studio Targets**. 5. Put the Studio ID and Place role in your prompt. If Dashboard shows Lobby as `studio-1` and Game as `studio-2`, prompt like this: ```text studio-1 is Lobby, and studio-2 is Game. In Lobby, add the event portal and reward guide UI. In Game, add the portal arrival point and guide message. ``` ## Prompt Patterns ### Split One Request by Place ```text In studio-1 Lobby, create the shop entrance button. In studio-2 Game, add a button that returns the player to Lobby after the round ends. Use the same text and color rules in both Places. ``` ### Use Separate Agent Sessions One agent cannot directly assign work to another agent. If you use Claude and Codex at the same time, prompt each app or session separately. Claude session: ```text Update the event UI in studio-1 Lobby. Before changing shared ModuleScripts, explain the plan first. ``` Codex session: ```text Inspect the portal arrival script in studio-2 Game. If a shared ModuleScript needs to change, explain the required change first. ``` This works when several agents are connected to the same MCP server. Check the agent and Studio Target in Dashboard, then name the target Studio ID in each session's prompt. ### Use Assets Across Places ```text Create a gem icon for the shop button, save it as a shared asset, then apply the same asset URI to ShopButton in studio-1 Lobby and RewardPanel in studio-2 Game. ``` ### Validate Each Place with PlayTest ```text In studio-1, check that the portal button is visible. In studio-2, run a Run-mode test to confirm the arrival script starts without errors. ``` ## Routing Rules WEPPY follows the most explicit target in the request. | Priority | Targeting method | How it works | |------|------|------| | 1 | Studio ID / Connection ID / Place ID | An explicit target in the prompt always wins. | | 2 | Pinned Studio | If no target is named, Dashboard can pin a Studio target. | | 3 | Recent priority | If nothing is named or pinned, WEPPY picks the active Studio that recently received real work. | For Multi-Place work, name the Studio ID whenever possible. A Place name alone can be ambiguous in large projects. ## Avoid Editing the Wrong Place - Check the Studio ID and Place name on the Dashboard Connection page first. - Start the prompt with a mapping such as `studio-1 is Lobby, studio-2 is Game`. - Before destructive or bulk changes, ask the AI to print the target Place and plan. - After the request, review Dashboard Changelog for the changed Place and change type. - Run PlayTest separately in each Place when the change touches gameplay. ## Next Steps - Use the [MCP Dashboard Guide](/en/docs/guides/dashboard/) to inspect Studio Targets and routing state. - Use the [Assets Guide](/en/docs/guides/assets/) to share generated assets across Places. - Use [Playtest](/en/docs/playtest/) to validate each Place after changes. --- ## Scripts & Code Execution Guide https://weppyai.com/en/docs/guides/scripts/ > Manage script source code and execute arbitrary Luau code in Studio. ## Included Tools | Tool | Description | |------|------| | `manage_scripts` | Create, read, edit, search, and analyze script dependencies | | `execute_luau` | Execute arbitrary Luau code in the Roblox Studio sandbox | ## Key Workflows ### Editing a Script ``` "In the GameManager script in ServerScriptService, change maxPlayers from 12 to 24" ``` Use `manage_scripts`'s `search` to find the line, then `edit_replace` to modify it. ### Validate Syntax Without Playtest ``` "Validate the Luau syntax in ServerScriptService.GameManager and show every error" ``` `manage_scripts.validate` checks either raw source or one existing Script path. It does not start Playtest and checks only whether the Luau source parses. Turn on **Controls → Luau Syntax Validation** in Dashboard to check the source that was actually saved after successful `set_source`, `edit_replace`, `edit_insert`, and `edit_delete` calls. A syntax error or unavailable check does not undo the applied change, so the AI can fix it in the same Script immediately. ### Bulk Refactoring ``` "Replace 'OldModule' with 'NewModule' across all scripts" ``` Use `manage_scripts`'s `replace` to update multiple scripts in one operation. ### Querying Runtime Data ``` "Calculate the average Health of all Humanoids currently in Workspace" ``` Use `execute_luau` to run arbitrary Luau code and retrieve runtime data. ## Action Reference ### Manage Scripts | Action | Description | |------|------| | `get_source` | Get script source code | | `set_source` | Set script source code | | `create` | Create a new script | | `delete` | Delete a script | | `edit_replace` | Replace specific lines in a script | | `edit_insert` | Insert lines at a specific position | | `edit_delete` | Delete specific lines | | `search` | Search for text in scripts | | `get_dependencies` | Get script dependencies | | `validate` | Check Luau syntax in raw source or an existing Script | | `replace` | Bulk replace across multiple scripts | ### Execute Luau Executes arbitrary Luau code in the Roblox Studio sandbox. - **Blocked services**: HttpService, DataStoreService, MessagingService - **No access**: CoreGui, CorePackages --- ## UI Studio Guide https://weppyai.com/en/docs/guides/ui-studio/ The workflow where AI agents build Roblox in-game UI to match your game's style, or analyze existing UI and suggest improvements you can review from the dashboard. ![UI Studio — UI Studio page in the dashboard](/docs/assets/screenshots/dashboard/dashboard_ui_studio_analysis.png) ## Overview When you ask the AI to "build me a UI", the following flow runs automatically. 1. **Gather requirements** — At the start of a new UI task, the AI uses guided questions to clarify the purpose, the screen, and the target devices. 2. **Compose the UI** — Based on the captured requirements, the AI creates, updates, and removes in-game menus, HUDs, buttons, labels, image panels, and related UI. 3. **Confirm the result** — The current screen can be captured so you can verify the output directly. 4. **Surface improvement suggestions** — Items like touch target size, text contrast, and safe zones are inspected, and improvement suggestions are surfaced to the AI. The dashboard's **UI Studio** page is where you review the outcomes of this flow (request history, captured screens, suggested improvements) in one place. ![Roblox Studio — UI generated in the live place](/docs/assets/screenshots/dashboard/dashboard_ui_roblox_studio.png) ## How to use ### 1. Ask in natural language as usual Ask the AI agent the way you normally do — no special commands required. ``` Build me a main menu UI for mobile landscape with a centered start button ``` If anything is missing, the AI follows up with guided questions before building the screen UI. ### 2. Review results and inspections in the dashboard The dashboard's **UI Studio** page is split into two tabs. #### History tab A chronological list of UI requests handled by the AI, with the captured screen and the applied changes for each entry. ![History tab — list of UI requests](/docs/assets/screenshots/dashboard/dashboard_ui_studio_history.png) Open an entry to compare the before/after captures and review the recorded change details for the same UI target. ![History detail — before and after comparison](/docs/assets/screenshots/dashboard/dashboard_ui_studio_history_before_after.png) #### Analysis tab A summary of inspection results and improvement suggestions surfaced to the AI (touch targets, contrast, safe zones, etc.), grouped per item. ![Analysis tab — inspection summary](/docs/assets/screenshots/dashboard/dashboard_ui_studio_analysis.png) Click any card to open the detail view; suggested improvements appear per item alongside the captured screens. ![Suggestion detail — per-item improvement notes](/docs/assets/screenshots/dashboard/dashboard_ui_studio_suggestion.png) Use **Re-check Suggestions** to recompute improvement suggestions for the same target. It refreshes the current analysis without saving a new screenshot. ## Common use cases ### Track a UI change ``` Show me the result of the main menu I just added ``` Open the most recent entry in the History tab and review the captured result alongside the applied changes. ### Iterate on improvement suggestions ``` Apply the touch target suggestion you just surfaced and rebuild it ``` Forward the item you saw in the Analysis tab back as a natural-language request and the AI will apply it. ## Notes - UI Studio data is stored on disk per project. Manage retention from the dashboard at **Settings → Data & History → UI Studio**. - The dashboard lets you revisit captured results and refresh Design Check suggestions. - Captures run in Edit mode. Captures during an active playtest are not supported because of a Roblox platform limitation. --- ## WEPPY Docs Home https://weppyai.com/en/docs/ WEPPY is an MCP server that connects AI coding agents directly to Roblox Studio. AI coding agents like Claude, Codex, and Gemini are powerful, but they can't directly see or modify the DataModel, scripts, terrain, or lighting inside Roblox Studio. WEPPY bridges that gap. When the AI creates or modifies instances, scripts, properties, and terrain inside Studio, changes are reflected immediately in both Studio and the dashboard so you can see exactly what changed at a glance. No copy-pasting required. The AI does the work; you verify the results.
Get Started → Understanding Sync
## Recommended Starting Path If this is your first time, follow the steps below in order. Each step finishes with the minimum verification needed before moving to the next. 1. **[Getting Started](/en/docs/getting-started/)** — Install the MCP server and Studio plugin, make your first connection 2. **[Check Connections](/en/docs/check-connections/)** — Verify server, plugin, and agent status from the dashboard 3. **[Multi-Place Work](/en/docs/guides/multi-place/)** — Use Studio IDs to target the right Place in multiple Studio windows 4. **[First Workflows](/en/docs/first-workflows/)** — A safe path to validate your first task 5. **[Sync](/en/docs/sync/)** — How bidirectional sync works and how to handle conflicts 6. **[Change History](/en/docs/review-changes/)** / **[Playtest](/en/docs/playtest/)** — Workflows for validating AI results ## Key Features ### 1. MCP Tools — Control Studio with Natural Language Scripts, instances, properties, terrain, lighting, assets, audio, animations — the AI handles all of it directly inside Studio. - "Add a particle effect, sound, and cooldown when the player jumps." - "Build a boss arena in the center of the map and place spawn points without collisions." - "Change this module's interface and update all scripts that reference it." ### 2. Multi-Place — Work across several Places in one request Open Lobby, Game, Shop, or Tutorial Places in separate Roblox Studio windows, then route work by Studio ID. - "In studio-1, add the event portal to Lobby. In studio-2, add the arrival point and guide UI to Game." - See which Studio window belongs to which Place from the Dashboard, even when multiple agents are connected - Reduce repeated context, manual copying, and accidental edits to the wrong Place For targeting rules and a wrong-Place checklist, see the [Multi-Place Work guide](/en/docs/guides/multi-place/). ![Connection page — multiple AI agents and Studio Targets connected](/docs/assets/screenshots/dashboard/dashboard_connection.png) ### 3. Assets — From generated image to applied Place asset Save generated images or prepared RBXM files to the Asset Library, upload them to Roblox, then apply them to the current Place. - "Create a gem icon for the shop button, upload it to Roblox, then apply it to the ShopButton image in the Lobby Place." - Manage place-specific assets and shared assets separately - Apply the asset URI returned by Open Cloud upload to Studio properties ![Assets page — local Asset Library items and Roblox upload status](/docs/assets/screenshots/dashboard/dashboard_assets.png) ### 4. Sync — Keep the Entire Project Context Stable The AI uses a locally synced project as its reference to understand the full structure and apply consistent changes across multiple files. ![Sync workflow — Studio and local files syncing in real time](/docs/assets/screenshots/plugin/sync/sync-overview.png) ### 5. Playtest — AI Runs and Validates Tests Automatically The AI controls Studio playtesting directly. It can start/stop F5 (Play) / F8 (Run) modes, inject test scripts, collect logs, and generate reports automatically. - "Start a playtest in Run mode and verify that the NPC reaches its target." - "Write and auto-run a test script to check whether SpawnLocation is above the ground." - "Run a playtest to verify the script I just modified works without errors." ![WEPPY Playtest dashboard — test history and detailed reports](/docs/assets/screenshots/dashboard/dashboard_playtest.png) ### 6. WEPPY Dashboard — Real-Time Workflow Monitoring The web dashboard served by the MCP server lets you check connection status, tool execution history, sync state, and game change history in real time. - See server / plugin / agent connection status at a glance - Compare every AI-made change Before & After in the Changelog - Analyze workflow patterns with tool execution history and statistics ![Dashboard Overview — server status, recent changes, session summary](/docs/assets/screenshots/dashboard/dashboard_overview.png) ### 7. WEPPY Roblox Explorer — Browse the Studio Tree in VSCode View the complete Roblox Studio instance tree directly inside VSCode. Explore services, open synced scripts and property files, and track sync status. - Intuitive navigation with the same class icons as Studio - Click to open synced scripts and property files - Multi-place support with sync status indicators ![WEPPY Roblox Explorer — Studio instance tree displayed in the VSCode sidebar](/docs/assets/screenshots/roblox-explorer/roblox-explorer-screen.png) ## Use Cases - **Rapid Prototyping** — Describe game mechanics in natural language and the AI implements them directly in Studio - **Multi-Place Production** — Keep Lobby and Game open in separate Studio windows and split one request across them - **Bulk Refactoring** — Change a module interface and update all dependent scripts at once - **Terrain & Environment** — Procedural terrain generation, lighting and atmosphere setup, asset placement — all in a single prompt - **Multi-File Consistency** — The AI reads the full project via Sync and modifies related scripts together - **Asset Integration** — Generate images, upload them to Roblox, apply them to a Place, and insert Creator Store assets without leaving the editor ## Compatibility | Claude Code | Claude Desktop | Cursor | Codex CLI | Codex Desktop | Gemini CLI | Antigravity / Antigravity IDE / Antigravity CLI | |:-----------:|:--------------:|:------:|:---------:|:-------------:|:----------:|:-----------:| | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | Requirements: Node.js 18+, Roblox Studio, Windows 10+ or macOS 12+ ## FAQ ### How do I connect Claude Code to Roblox Studio? Install the Roblox Studio plugin, then register the MCP server (`npx -y @weppy/roblox-mcp@latest`) in Claude Code. Claude can then read and write scripts directly inside Studio. See the [Claude Code setup](/en/docs/agents/claude-code/) guide for the full procedure. ### Is it safe? Can AI break my game? The server only runs on localhost (127.0.0.1:3002). Forbidden paths (CoreGui, CorePackages) are blocked, and a 30-second per-tool timeout prevents runaway operations. All changes are tracked in the sync history. ### How is Weppy different from other Roblox MCP servers? Instead of separating tools by feature, WEPPY uses action-based dispatching to reduce AI token consumption. It also combines Studio ID based multi-place work, Asset Library with Roblox upload, bidirectional project sync, and Playtest control. --- ## Playtest https://weppyai.com/en/docs/playtest/ Check the status and results of AI-driven playtests, and let the AI control Studio playtesting directly. ![Playtest — playtest status and test history](/docs/assets/screenshots/dashboard/dashboard_playtest.png) ## Overview The Playtest page shows the status and results of playtests the AI has run. It is only accessible when the dashboard is in **Studio connected** state. The `system_info` tool's play/stop/pause/resume/play_status/run_test actions let the AI control playtesting directly. ## Playtest Status Shows the current playtest state: | Status | Meaning | |------|------| | **NotRunning** | Playtest is not running | | **Running** | Playtest is running | | **Paused** | Playtest is paused (Run mode only) | ## Test History Lists test results from AI `run_test` action calls in chronological order: | Field | Description | |------|------| | Timestamp | Test execution time | | Test Report | Link to the test report | | Mode | Execution mode (play/run) | | Duration | Time the test took | | Status | Result (Passed/Failed) | Click a test report to view the detailed markdown report and logs. ## Key Workflows ### Manual Playtest Control ``` "Start the game in Play mode (F5)" "Stop the current playtest" ``` `play` → confirm state with `play_status` → end with `stop`. ### Automated Testing (run_test) ``` "Write and run a test to check whether SpawnLocation is in the correct position" ``` `run_test` injects a test script and automatically starts, collects, and cleans up the playtest. ### CI-Style Validation ``` "Test in Run mode (F8) whether the NPC AI reaches its target, and show the logs if it fails" ``` Run `run_test` with `mode: "run"` to perform a server-side test. ### Validate Multi-Place Changes When one request changes several Places, validate each target by Studio ID. ``` "In studio-1 Lobby, check that the portal button is visible. In studio-2 Game, run a Run-mode test to confirm the arrival script starts without errors." ``` Check the Studio ID and Place name on the Dashboard Connection page before prompting, so the AI runs the test in the intended Place. ## Playtest State Machine ``` Edit ──play──→ Running ──stop──→ Edit │ ↑ pause stop │ │ ↓ │ Paused ──resume──→ Running ``` | State | Available Actions | |------|------------| | `edit` | play | | `running` | stop, pause (Run mode only) | | `paused` | resume, stop | - **Play mode (F5)**: Client + server simulation. pause/resume not available. - **Run mode (F8)**: Server-only simulation. pause/resume available. ## run_test Pipeline `run_test` automatically orchestrates the following steps: ### 1. Preparation - Fetch Place info (`place_info`) - Clear the existing log buffer ### 2. Script Injection - Create the wrapped test script in `ServerScriptService.__MCP_TestRunner` - The wrapper automatically handles START/FINISHED signals and error tracebacks ### 3. Execution and Monitoring - Start the playtest (Play or Run mode) - Poll logs every 500ms - Mark complete when the `[WEPPY_TEST]:FINISHED` signal is received - Auto-terminate on timeout (default 60s, max 300s) ### 4. Cleanup - Automatically stop the playtest - Delete the injected test script - Collect final logs ### 5. Report Generation Reports and logs are saved locally under `{projectRoot}/weppy-project-sync/place_XXXXX/tests/YYYYMMDD-HHmmss/`. ``` {projectRoot}/weppy-project-sync/place_XXXXX/tests/YYYYMMDD-HHmmss/ ├── test-report.md # Result summary (status, time, signals) └── test-log.txt # Full logs (timestamp, sequence, level) ``` **test-report.md example:** ```markdown # Test Report - Status: passed - Test Name: spawn_location_test - Mode: run - Place ID: 123456 - Duration (ms): 1523 - Total Logs: 12 - Signal Count: 2 ## Signals - START: 2026-03-12T10:30:00.000Z - FINISHED: 2026-03-12T10:30:01.523Z ``` ## Action Reference | Action | Description | Parameters | | ------ | ------ | --------- | | `play` | Start playtest in Play (F5) or Run (F8) mode | `mode`: "play" \| "run" | | `stop` | Stop the current playtest | — | | `pause` | Pause the playtest in Run mode | — | | `resume` | Resume a paused Run mode playtest | — | | `play_status` | Get playtest state and available actions | — | | `run_test` | Inject test script → run → collect logs → generate report | `script` (required), `test_name`, `mode`, `timeout` | ### run_test Parameters | Parameter | Type | Required | Description | |---------|------|:----:|------| | `script` | string | ✅ | Luau test code to execute | | `test_name` | string | — | Test name shown in the report | | `mode` | "play" \| "run" | — | Playtest mode (default: "play") | | `timeout` | number | — | Timeout in seconds (default: 60, max: 300) | ## Use Cases ### Analyzing Test Failures ``` "I want to find out why the automated test I just ran failed" ``` Find the Failed test in Test History and click the Test Report to view the detailed logs and failure cause. ### Reviewing Test History ``` "I want to see the pass/fail status of all tests I ran today" ``` Check the timestamps and Status in Test History to track test result trends. --- ## Change History https://weppyai.com/en/docs/review-changes/ Every change the AI agent makes in Roblox Studio is recorded per session, with a change summary, timeline, and Before & After comparison. ![Changelog — list of session change cards](/docs/assets/screenshots/dashboard/dashboard_changelog1.png) ## Overview The Changelog tracks the game change history that AI agents perform in Studio. Changes are grouped by session so you can see at a glance what type of changes happened and how many in each session. ## Session Card List The Changelog's main screen shows a list of session cards. ### Session Status Each session card displays a status: | Status | Meaning | |------|------| | **Active** | Currently ongoing session (updates in real time) | | **Completed** | Finished session | | **Bootstrap** | Initial sync session | ### Session Summary Each card shows a per-category count of changes in that session: - Script — scripts created/modified - Instance — instances created/deleted/moved - Property — property changes - Lighting — lighting/environment changes - Terrain — terrain changes - Asset — assets inserted ### Filter Tabs Use the top tabs to filter sessions: - **All** — all sessions - **Active** — ongoing sessions only - **Completed** — finished sessions only ## Session Detail View Click a session card to enter the detail view. ![Changelog detail view — change summary, timeline, Before & After](/docs/assets/screenshots/dashboard/dashboard_changelog2.png) ### Change Summary Visualizes the session's changes as 6 category cards: | Category | Icon | Description | |---------|--------|------| | Scripts | Script | Scripts created/modified | | Instances | Instance | Instances created/deleted/moved | | Properties | Property | Property changes | | Lighting | Lighting | Lighting/environment changes | | Terrain | Terrain | Terrain changes | | Assets | Asset | Assets inserted | ### Change Timeline Lists all changes in the session in chronological order. - Each entry shows a timestamp, change category tag, and target path - Use the **Category** dropdown to filter by a specific category - Click an entry to expand the Before & After comparison view ### Before & After Compares data before and after the change. The level of information provided varies by change type: | Confidence | Meaning | Example | |--------|------|------| | **exact** | Before and after values are precisely recorded | Property change, script edit | | **partial** | Only partial information recorded | Compound change | | **after-only** | Only the after value exists | New instance creation | | **intent-only** | Only the intent is recorded | Deletion, etc. | ## Use Cases ### Verifying Work ``` "I want to check which scripts the AI just modified" ``` Filter the Script category in the Active session's Changelog to see the list of modified scripts and compare the before/after code. ### Tracking Changes ``` "I want to review how Lighting was set up in yesterday's session" ``` Find the session in the Completed tab and filter by the Lighting category to review the change history and configured values. ### Debugging Issues ``` "I need to find out at what point a specific instance was deleted" ``` Filter the Instance category in the timeline and trace delete-type changes in chronological order. ## Next Steps After reviewing changes: - Run automated validation with [Playtest](/en/docs/playtest/) to confirm nothing is broken. - You can also review the AI's tool execution history in [Tools & Stats](/en/docs/tools-and-stats/). --- ## Bidirectional Sync https://weppyai.com/en/docs/sync/ Sync connects Roblox Studio state with local files so the AI can reliably read and modify the full project context. ## Why Sync Matters Without Sync, the AI only sees fragments of code pasted into the conversation. With Sync enabled, the AI works from the entire project, which makes the following much easier. - Apply consistent refactoring across multiple scripts - Quickly review only risky changes based on change history - Keep a clear direction for which side — Studio or local — is the source of truth ## How It Works ![Sync workflow — Studio tree synced to local files](/docs/assets/screenshots/plugin/sync/sync-overview.png) 1. **Full Sync**: Initial sync of the Studio tree and instances to a local mirror 2. **Incremental Sync**: Subsequent changes are applied as diffs via change monitoring 3. **History/Status Tracking**: See what changed, when, and in which direction Sync data is created under `{projectRoot}/weppy-project-sync/place_{placeId}/explorer`. WEPPY also writes a per-place sourcemap to `{projectRoot}/weppy-project-sync/place_{placeId}/sourcemap.json` and keeps a canonical root-level file at `{projectRoot}/weppy-project-sync/sourcemap.json`. ## Project Directory Structure and Multi-Place WEPPY Sync creates a `weppy-project-sync/` directory under the project root and maintains a separate mirrored tree for each Place. ``` weppy-project-sync/ ├── sourcemap.json # Root-level canonical sourcemap (recommended path for luau-lsp) ├── .sync-config.json # Global configuration (shared by all Places) ├── place_123456/ # Per-Place directory │ ├── explorer/ # Mirrored workspace (v2 nested format) │ │ ├── Workspace/ │ │ │ ├── _tree.json │ │ │ ├── Part/ │ │ │ │ └── Part.props.json │ │ │ └── MyScript/ │ │ │ └── MyScript.server.luau │ │ └── ServerScriptService/ │ │ └── _tree.json │ ├── sourcemap.json # Per-Place sourcemap │ ├── .sync-meta.json # Place metadata │ └── .sync-index.json # Hash index (version: 2) └── place_789012/ # Another Place └── ... ``` Each Place has its own `place_XXXXX/` directory. With **Pro tier**, up to 5 Places can be synced simultaneously; the LRU policy evicts infrequently-used Places from memory (disk data is preserved). This structure ensures that sync state stays isolated when working across multiple games from the same project root. ### Browsing Sync Data in VSCode Installing the WEPPY Roblox Explorer extension lets you navigate the synced instance tree in the same form as Roblox Studio, right inside VSCode. Explorer reads the sync files generated here and additionally reflects real-time sync status and direction info when the local MCP server is running. ![WEPPY Roblox Explorer — browsing the synced instance tree in VSCode](/docs/assets/screenshots/roblox-explorer/roblox-explorer-screen.png) - Shows service / instance tree with Roblox class icons - Click script files to open and edit them directly - Sync status badges show changes and conflicts
Explorer Guide →
## Basic vs Pro | Feature | Basic | Pro | |------|------|-----| | Sync direction | Studio → Local | Bidirectional | | Per-type Direction | Not supported | Supported (Scripts / Values / Containers / Data / Services) | | Per-type Apply Mode | Not supported | Supported (Auto / Manual) | | Status/History query API | Not supported | Supported (`status_current_place`, `history`, `progress`) | | `manage_sync` tool | Not supported | Supported | | Multi-place Sync | Not supported | Supported (up to 5 Places) | ## Sync Targets and Default Exclusion Rules Default synced services: - `Workspace` - `Lighting` - `ReplicatedStorage` - `ServerStorage` - `ServerScriptService` - `StarterGui` - `StarterPlayer` - `StarterPack` - `ReplicatedFirst` - `SoundService` - `Chat` - `LocalizationService` Default exclusions: - Classes: `Terrain`, `Camera` - Security-restricted paths: `CoreGui`, `CorePackages`, `RobloxScript`, `RobloxScriptSecurity` ## Direction and Apply Mode ### Direction (Per-Type Sync Direction) - `forward`: Studio → Local - `reverse`: Local → Studio - `bidirectional`: Both directions Types are managed separately: `scripts`, `values`, `containers`, `data`, `services`. ### Apply Mode (How Reverse Changes Are Applied) - `manual`: The user reviews and approves changes before they are applied to Studio - `auto`: Detected changes are applied automatically With Pro, you can configure different Direction/Apply Mode settings per type for fine-grained workflow control. ## `manage_sync` Action Reference (Pro) | Action | Description | Key Parameters | |------|------|-----------| | `status_current_place` | Check sync status for the currently connected Place | — | | `history` | Query change history | `placeId`, `query.limit`, `query.offset` | | `directions` | Get per-type Direction settings | `placeId` | | `read_file` | Read a synced file | `placeId`, `instancePath` | | `write_file` | Write to a synced file | `placeId`, `instancePath`, `content` | | `progress` | Check real-time progress and throughput | `placeId` | ## Recommended Workflows ### 1) Starting Safely - Complete a Full Sync first to establish the current state as your baseline. - Use `manual` apply mode initially to reduce the risk of unexpected changes. ### 2) Making Changes with AI - "Check the Sync status and summarize only the risky changes based on recent history." - "Refactor the scripts in `ServerScriptService` first and keep a change history." ### 3) Resolving Conflicts During bidirectional sync, if changes are detected on both Studio and local sides, a conflict resolution screen appears. ![Local Changes Detected — conflict resolution options (Studio Priority / Local Priority / Per-File)](/docs/assets/screenshots/plugin/sync/sync-conflict.png) - **Studio Priority**: Overwrite using Studio as the source of truth - **Local Priority**: Apply local files to Studio - **Per-File**: Choose which side takes priority for each file individually ### 4) Recovery When Something Goes Wrong - Use `history` to trace recent changes - Use `read_file` to inspect the file you need - Apply the recovered content with `write_file` and re-verify the Studio state ## File Format (v2 Nested Directory) Each Roblox instance is stored in its own directory with meta files inside it: ``` explorer/ ├── Workspace/ │ ├── _tree.json │ ├── Part/ │ │ └── Part.props.json │ ├── MyScript/ │ │ └── MyScript.server.luau │ └── Coins/ │ └── Coins.value.json ``` Naming conventions: - Properties: `{Name}/{Name}.props.json` - Scripts: `{Name}/{Name}.server.luau` / `.client.luau` / `.module.luau` - Values: `{Name}/{Name}.value.json` Instances with the same name get a `~N` suffix on their directory to distinguish them (e.g., `Part~2/Part.props.json`). If a name contains `~`, it is escaped as `~~` (e.g., `Part~2` → `Part~~2/`). Odd-Count Tilde Rule: a trailing `~+N` is interpreted as a collision suffix only when the number of tildes is odd. ## luau-lsp Integration WEPPY Sync can automatically generate the sourcemap file required by `luau-lsp`, so you get Roblox-aware editor features without setting up a separate Rojo project. After a Full Sync completes, WEPPY generates the following files: - Place sourcemap: `weppy-project-sync/place_/sourcemap.json` - Root canonical file: `weppy-project-sync/sourcemap.json` With `luau-lsp` reading the WEPPY sourcemap, you get improvements to: - `game.*` autocompletion - Navigation based on synced scripts - `require` resolution across synced scripts ### Recommended Setup 1. Run a Full Sync once so WEPPY creates `weppy-project-sync/sourcemap.json`. 2. Point the `luau-lsp` sourcemap setting in your editor to `weppy-project-sync/sourcemap.json`. 3. If your client allows disabling automatic Rojo generation, set `luau-lsp.sourcemap.autogenerate` to `false`. VSCode settings example: ```json { "luau-lsp.sourcemap.enabled": true, "luau-lsp.sourcemap.autogenerate": false, "luau-lsp.sourcemap.sourcemapFile": "weppy-project-sync/sourcemap.json" } ``` `weppy-project-sync/sourcemap.json` follows the current representative place in the project. To pin it to a specific place, configure `luau-lsp` to point directly to that place's `weppy-project-sync/place_/sourcemap.json`. --- ## Tools & Stats https://weppyai.com/en/docs/tools-and-stats/ Review the execution history and statistics for MCP tools the AI has run, and get a high-level picture of the tool categories WEPPY provides. ![Tools — tool execution history and statistics](/docs/assets/screenshots/dashboard/dashboard_tools.png) ## Overview The dashboard's Tools page shows the execution history and statistics for MCP tools the AI has run. It has two sub-tabs — **History** and **Statistics** — and is always accessible when the dashboard is in **server connected** or **Studio connected** state. ## History Tab Shows tool execution history in a chronological table. | Column | Description | |---|---| | Time | Execution time | | Tool | Name of the tool executed | | Action | The specific action performed within the tool | | Duration | Time taken to execute | | Status | Result status (OK / Error) | | Tier | Tier used (Basic / Pro) | Features - Filter by specific tool using the tool filter dropdown - Browse large histories with pagination - New executions are added in real time ## Statistics Tab Visually analyzes tool usage statistics. - **Tier distribution** — Basic / Pro tool usage ratio - **Per-tool statistics** — call count and average response time per tool - **Category analysis** — usage patterns by category ## Notice for Basic Tier Users Basic tier users see the following additional UI elements. - Usage progress bar - Pro feature info modal ## WEPPY Tool Categories A high-level view of what you can ask the AI to do. See the [feature guides](/en/docs/guides/dashboard/) for detailed usage. | Category | What You Can Do | | --- | --- | | Instance Management | Search, create, delete, clone, and move instances; traverse trees and hierarchies | | Properties & Tags | Read/write instance properties and attributes; manage tags | | Script Operations | Read, write, edit, and partially replace scripts | | Selection Management | Read, set, and clear Studio selection | | Camera | Query camera info and move focus | | Logs & System Info | View logs, check connection and tier status | | One-Way Sync | Studio → Local automatic mirror | | Tool History & Stats | Query call history and statistics | | Bidirectional Sync | Local ↔ Studio bidirectional sync, Direction / Apply Mode, history, multi-place | | Bulk Operations | Create, modify, query, and replace multiple instances at once | | Environment & Presentation | Lighting, atmosphere, terrain, tweens, animations, audio, particles and effects, physics groups | | Spatial Queries | Raycasting, ground detection, spawn position analysis, collision checks | | Assets | Search, insert, and export assets; Creator Store integration | | Playtest Automation | Start/stop/pause Run / Play mode, inject test scripts, auto-generate reports | | Camera Capture | Viewport screenshot in Studio Edit mode | | AI UI Design (UI Studio) | AI builds and edits game-style UI, captures screens, and surfaces improvement suggestions | | Batch Execution & Arbitrary Code | Process multiple commands at once, execute arbitrary Luau code | ## Use Cases ### Analyzing Tool Performance ``` Show me which tools take the longest to run ``` Check the per-tool average response time in the Statistics tab. ### Tracking Errors ``` I want to know why the tool I just ran failed ``` Find entries with an Error status in the History tab and review the details.
Dashboard Guide → Troubleshooting
--- ## Troubleshooting https://weppyai.com/en/docs/troubleshooting/ A step-by-step guide for narrowing down connection, permission, Sync, and validation issues. ## Plugin Not Connecting **Symptom:** "Connection failed" or the plugin shows as disconnected in Roblox Studio. 1. Confirm the MCP server is running: `npx -y @weppy/roblox-mcp@latest` 2. Roblox Studio: Plugins tab → WEPPY → click **Connect** 3. Make sure no firewall, antivirus, or VPN is blocking `localhost:3002` 4. Restart both Roblox Studio and the MCP server ## AI Client Not Recognizing the MCP Server 1. Check that the correct command is used in AI client settings: `npx -y @weppy/roblox-mcp@latest` 2. Confirm Node.js 18 or higher is installed: `node --version` 3. On Windows, if you get a permissions error, try running the terminal as Administrator 4. Check the [installation guide](https://weppyai.com/en/install/) for your AI app ## "Pro feature required" Notice When a Pro-only action is requested on Basic, WEPPY tries to find a workaround where possible. However, the workaround flow consumes additional tokens and doesn't always produce identical results. Some Pro-only tools also have no feasible workaround and cannot be executed on Basic at all. If this notice appears repeatedly, check whether the requested action is available on your current plan. ## Sync Not Working 1. Check Sync status: ask the AI to run `manage_sync status` 2. Confirm the plugin is connected before starting Sync 3. If reverse sync (file → Studio) isn't working, verify that Pro tier is active 4. Confirm the local sync folder exists and has write permissions See [Bidirectional Sync](/en/docs/sync/) for detailed Sync configuration. ## Multi-Place Work Applies to the Wrong Place 1. Recheck Studio ID and Place name on the Dashboard **Connection** page. 2. Start the prompt with a target map such as `studio-1 is Lobby, studio-2 is Game`. 3. Requests with no explicit target may use the pinned Studio or recent-priority routing, so name the Studio ID for important work. 4. Before bulk deletion or broad script edits, ask the AI to print the target Place and plan first. See the [Multi-Place Work guide](/en/docs/guides/multi-place/) for prompt patterns. ## Assets Upload or Application Fails 1. Ask the AI to run `manage_open_cloud_assets credential_status` to check Open Cloud setup. 2. Confirm the API key permissions, Creator, and group/owner settings match the asset category you are uploading. 3. After upload, wait for the Roblox operation to finish before applying the asset URI. 4. Confirm that the property expects an asset URI such as `rbxassetid://...`, for example ImageLabel, Decal, or Texture. See the [Assets guide](/en/docs/guides/assets/) for generated image, upload, and Place application workflows. ## Compatible AI Clients | Client | | ----------- | | Claude Code | | Claude Desktop | | Cursor | | Codex CLI | | Codex Desktop | | Gemini CLI | | Any MCP-compatible app | Server command: `npx -y @weppy/roblox-mcp@latest` ## System Requirements | Item | Minimum | |------|--------| | Node.js | 18.0.0 or higher | | Roblox Studio | Latest version (keep auto-update enabled) | | Operating System | Windows 10+ or macOS 12+ | | Network | localhost:3002 must be accessible | ## Common Error Messages | Error | Cause | Fix | |------|------|----------| | `ECONNREFUSED localhost:3002` | MCP server not running | Run `npx -y @weppy/roblox-mcp@latest` | | `Timeout waiting for plugin` | Studio plugin not connected | Click Connect in the plugin panel | | `Forbidden path` | Attempted access to CoreGui/CorePackages | Use only valid instance paths | | `Place ID mismatch` | Wrong Place connected | Reconnect from the correct Studio session | ## Need Help? If the issue still isn't resolved, open a [GitHub Issue](https://github.com/hope1026/weppy-roblox-mcp/issues/new/choose) with the following information: - Operating system and Node.js version - AI client and version - Error message or logs - Steps you have already tried Do not include raw license keys, receipts, email addresses, billing details, or private project data in a public issue. Email `support@weppyai.com` instead if the question includes purchase, license, email, billing, or private project information. --- ## UI Tasks https://weppyai.com/en/docs/ui-design/ The flow for asking AI agents to build and modify game-style menus, HUDs, buttons, labels, image panels, and other in-game UI, then reviewing captured results and inspection findings in the dashboard. ![UI Studio — UI Studio page in the dashboard](/docs/assets/screenshots/dashboard/dashboard_ui_studio_analysis.png) ## Flow at a glance 1. **Ask in natural language** — Just say something like "build me a main menu UI" the way you normally would. 2. **Requirements gathering** — The AI fills in the necessary details (purpose, screen, target devices) through guided questions. 3. **UI composition** — Based on the gathered requirements, the AI creates and updates the UI needed for the game screen. 4. **Review results and suggestions** — Open the dashboard's **UI Studio** page to see the captured screens and the improvement suggestions surfaced (touch targets, contrast, safe zones, etc.). 5. **Iterate** — Forward the suggested improvements to the AI as natural-language requests. In the dashboard, you can revisit captured results and refresh Design Check suggestions for the same UI. ## Common patterns ### Building a new UI ``` Build me a main menu UI for mobile landscape with a centered start button ``` If the AI needs more information, simply answer and the work continues. ### Confirming the result ``` Show me the result of the UI you just built ``` The AI captures and replies; the same result is also viewable in the **History** tab of the dashboard's UI Studio page. ### Applying improvement suggestions ``` Apply the touch-target suggestion you just surfaced and rebuild it ``` Pass the item you saw in the **Analysis** tab back as natural language and it will be applied. ## Learn more For details on tab structure, retention policies, and examples, see the [UI Studio guide](/en/docs/guides/ui-studio/). ---