@weppy/roblox-mcp 2.5.0 → 2.6.0

package/docs/en/installation/roblox-plugin.md

@@ -1,96 +0,0 @@
-# Roblox Plugin Installation
-
-How to install the plugin to connect AI agents with Roblox Studio.
-
-## Automatic Installation (Recommended)
-
-If the MCP server setup is complete, the plugin is **installed automatically**. No manual download or file copy is needed.
-
-### How it works
-
-1. When the MCP server runs for the first time, it places the plugin file (`WeppyRobloxMCP.rbxm`) into the Roblox Studio Plugins folder automatically.
-2. When you start Roblox Studio, the **WEPPY** button appears in the Plugins tab.
-
-### Connecting
-
-1. Open any project in **Roblox Studio**
-2. Go to **Plugins** tab → **WEPPY**
-
-![WEPPY Button](../../assets/screenshots/plugin/installation/toolbar-button.png)
-
-3. Click the **Connect** button in the plugin window
-4. Once **"Connected"** status is displayed, you're ready
-
-![Plugin Main Screen](../../assets/screenshots/plugin/installation/main-screen.png)
-
-> If automatic installation did not work, follow the manual installation below.
-
----
-
-## Manual Installation
-
-Use this if automatic installation didn't work or you need to install a specific version.
-
-### 1. Download 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 file — you will find `roblox-plugin/WeppyRobloxMCP.rbxm`
-
-### 2. Install Plugin
-
-1. Open **Roblox Studio**
-2. Click the **Plugins** tab in the top menu
-3. Click the **Plugins Folder** button
-
-![Open Plugins Folder](../../assets/screenshots/plugin/installation/plugins-menu.png)
-
-4. **Copy** the `WeppyRobloxMCP.rbxm` file from the extracted folder into the opened Plugins folder
-5. **Restart Roblox Studio**
-
-### 3. Verify Installation
-
-After restarting, the **WEPPY** button will appear in the Plugins tab.
-
-![WEPPY Button](../../assets/screenshots/plugin/installation/toolbar-button.png)
-
-### 4. Connect
-
-Follow the same "Connecting" steps above — click Connect in the plugin.
-
----
-
-## Settings (Optional)
-
-Click the settings button in the top right of the plugin to change options.
-
-![Settings Screen](../../assets/screenshots/plugin/installation/settings-screen.png)
-
-- **Auto Connect**: Automatically connect to MCP server when Studio starts
-- **Auto Reconnect**: Automatically attempt to reconnect when connection is lost
-- **Auto Camera Focus**: Automatically move camera to created objects
-- **Language**: Change the plugin UI language
-
-## Tier Information
-
-- Basic users install the same plugin package and use Basic policy (Studio → Local one-way sync).
-- Pro subscribers unlock bidirectional sync and broader advanced tools after license activation.
-
-## Troubleshooting
-
-### Plugin not visible
-
-- Completely close and restart Roblox Studio
-- Check if the file was properly copied to the Plugins Folder
-- Verify the `.rbxm` file is not corrupted
-
-### Cannot connect
-
-- Verify the MCP server is running in your AI app
-- Click the **Connect** button again in the plugin
-- Check if port 3002 is being used by another program
-
-### Connection frequently drops
-
-- Enable the **Auto Reconnect** option in settings
-- Try restarting your AI app

package/docs/en/pro-upgrade.md

@@ -1,96 +0,0 @@
-# Pro Upgrade Guide
-
-## Why Pro?
-
-### Bidirectional Sync built for real development workflows
-
-Pro Sync goes beyond one-way export. Edit scripts locally and push them to Studio. Make changes in Studio and pull them back to disk. Pro keeps both sides in sync.
-
-- **Bidirectional Sync** — Changes flow in both directions between Studio and local files.
-- **Per-type Direction** — Set direction independently for Scripts, Values, Containers, Data, and Services.
-- **Per-type Apply Mode** — Choose Auto or Manual per type to balance speed and control.
-- **Full Sync / Resync** — Rebuild clean project state on demand after large changes or reconnects.
-- **Change History** — Track what changed, when, and in which direction before applying.
-- **Multi-place Sync** — Sync up to 3 Roblox Places simultaneously, each with isolated storage and its own change history.
-
-### Save AI tokens with high-leverage workflows
-
-Bulk and advanced actions reduce repetitive round trips — do more per prompt.
-
-### Let AI run and verify playtests directly
-
-AI can control Roblox Studio playtests directly. It can start and stop Play (F5) or Run (F8), inject test scripts, collect logs, and generate local reports automatically.
-
-- "Start a Run-mode playtest and check whether the NPC reaches the target."
-- "Write a test that verifies the SpawnLocation is above the ground and run it."
-- "Validate that the script I just changed runs without errors in playtest."
-
-### More Pro-only features
-
-Pro unlocks additional features beyond the core workflow.
-
-- **Bulk operations** — Create, modify, or delete multiple instances in a single request
-- **Terrain generation** — Fill with block, ball, cylinder, wedge, and replace materials
-- **Asset search/insert** — Search the Roblox marketplace and insert assets directly
-- **Spatial analysis** — Raycast, find ground, flat area search, collision checks
-- **Environment control** — Lighting, atmosphere, sky, and time-of-day settings
-- **Audio/Animation** — Sound playback and animation load/play
-
-## Buy and Activate
-
-### Step 1: Buy a Pro subscription license on Gumroad
-
-1. Go to [Gumroad - Weppy Roblox Plugin](https://gumroad.com/l/faccjs?utm_source=github&utm_medium=repo&utm_campaign=pro_upgrade_md)
-2. Complete your Pro subscription license purchase
-3. Copy the license key you receive after purchase
-
-You only need to activate the license once, either in the plugin or in the dashboard. Both surfaces share the same MCP local license state, so once you activate in one place, the same status appears in the other.
-
-### Activate in the plugin
-
-1. Open **WEPPY** in Roblox Studio and connect to the MCP server.
-2. Open **Settings > License** in the plugin.
-3. Paste your purchased key into the `License key` field.
-4. Click **Activate** to activate the license.
-5. If the status does not update immediately, click **Refresh**.
-6. When activation succeeds, the status changes from Basic to Pro and Pro features become available.
-
-![WEPPY Plugin license activation screen](../assets/screenshots/plugin/license/plugin-license-screen.png)
-
-### Activate in the dashboard
-
-1. Start the MCP server, then open **Settings > License** in the dashboard.
-2. Confirm that the provider is set to `gumroad`.
-3. Paste your purchased key into the `License Key` field.
-4. Click **Activate License** to activate the license.
-5. If needed, use **Refresh License** to fetch the latest status.
-
-![WEPPY Dashboard license activation screen](../assets/screenshots/plugin/license/dashboard-license-screen.png)
-
-### After activation
-
-- If the license status is shown as `active` or `grace`, Pro features are available.
-- The plugin and dashboard share the same license state, so activating in one place is reflected in the other.
-- Use **Refresh** or **Refresh License** whenever you want to check the latest status again.
-
-## Feature Comparison
-
-| Feature | Basic | Pro |
-|---------|:-----:|:---:|
-| Script create/edit | ✅ | ✅ |
-| Instance create/delete/move | ✅ | ✅ + bulk operations |
-| Property read/write | ✅ | ✅ + bulk changes |
-| Selection, tags, search | ✅ | ✅ |
-| Camera control | ✅ | ✅ |
-| Log monitoring | ✅ | ✅ |
-| Luau code execution | ✅ | ✅ |
-| Project sync | Studio → Local one-way | Bidirectional + per-type direction/mode |
-| Multi-place sync | — | Up to 3 Places simultaneously |
-| Change history | — | Track changes before applying |
-| Playtest control | — | Play / stop / pause / resume + automated tests |
-| Terrain generation/editing | — | Block, ball, cylinder, wedge, material replace |
-| Asset search/insert | — | Search Roblox marketplace and insert directly |
-| Spatial analysis | — | Raycast, find ground, collision checks |
-| Environment control | — | Lighting, atmosphere, sky, time of day |
-| Audio / Animation | — | Sound playback, animation load/play |
-| AI token efficiency | Per-action calls | Fewer calls with bulk actions |

package/docs/en/sync/luau-lsp.md

@@ -1,41 +0,0 @@
-# Use `luau-lsp` with WEPPY Sync
-
-WEPPY Sync can generate the sourcemap files that `luau-lsp` needs, so you can enable Roblox-aware editor features without setting up a separate Rojo project.
-
-## What WEPPY writes
-
-After Full Sync finishes, WEPPY writes:
-
-- Place sourcemap: `weppy-project-sync/place_<id>/sourcemap.json`
-- Root representative file: `weppy-project-sync/sourcemap.json`
-
-For most users, the recommended path is `weppy-project-sync/sourcemap.json`.
-
-## Why this helps
-
-Pointing `luau-lsp` at the WEPPY sourcemap improves:
-
-- `game.*` autocomplete
-- Navigation across synced scripts
-- `require` resolution between synced scripts
-
-## Recommended setup
-
-1. Run Full Sync once so WEPPY creates `weppy-project-sync/sourcemap.json`.
-2. Point your editor's `luau-lsp` sourcemap setting to `weppy-project-sync/sourcemap.json`.
-3. If your client can disable automatic Rojo generation, set `luau-lsp.sourcemap.autogenerate` to `false`.
-
-Example VSCode settings:
-
-```json
-{
-  "luau-lsp.sourcemap.enabled": true,
-  "luau-lsp.sourcemap.autogenerate": false,
-  "luau-lsp.sourcemap.sourcemapFile": "weppy-project-sync/sourcemap.json"
-}
-```
-
-## Multi-place note
-
-`weppy-project-sync/sourcemap.json` follows the current representative place for the project.
-If you need a fixed place instead, point `luau-lsp` directly to that place's `weppy-project-sync/place_<id>/sourcemap.json`.

package/docs/en/sync/overview.md

@@ -1,153 +0,0 @@
-# Roblox MCP Sync Deep Dive
-
-Sync connects Roblox Studio state and local files so AI can read and modify the full project context reliably.
-
-## Why Sync matters
-
-Without Sync, AI only sees snippets pasted into chat. With Sync enabled, AI works from the whole project.
-
-- Apply refactors consistently across multiple scripts
-- Review risky changes quickly using history
-- Keep source-of-truth clear between Studio and local files
-
-## How it works
-
-![Sync workflow — Studio tree mirrored to local files](../../assets/screenshots/plugin/sync/sync-overview.png)
-
-1. Full Sync: initial mirror from Studio tree/instances to local files
-2. Incremental Sync: continuous update of new changes
-3. History/Status tracking: inspect what changed, when, and in which direction
-
-Sync data is stored under `{projectRoot}/weppy-project-sync/place_{placeId}/explorer`.
-WEPPY also writes a place sourcemap to `{projectRoot}/weppy-project-sync/place_{placeId}/sourcemap.json` and keeps the recommended root representative file at `{projectRoot}/weppy-project-sync/sourcemap.json`.
-Use the root path for editor integrations such as `luau-lsp`. Setup steps are covered in [Use `luau-lsp` with WEPPY Sync](./luau-lsp.md).
-
-### Browse sync data in VSCode
-
-Install the [WEPPY Roblox Explorer](../installation/roblox-explorer.md) extension to browse the synced instance tree in VSCode, just like in Roblox Studio.
-Explorer reads the sync files generated here, and it can show additional live sync state or direction details when the local MCP server is running.
-
-![WEPPY Roblox Explorer — browse synced instance tree in VSCode](../../assets/screenshots/roblox-explorer/roblox-explorer-screen.png)
-
-- Service/instance tree with Roblox class icons
-- Click a script to open it for editing
-- Sync status badges show modified/conflict state
-
-## Basic vs Pro
-
-| Item | 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 APIs | Not supported | Supported (`status_current_place`, `history`, `progress`) |
-| `manage_sync` tool | Not supported | Supported |
-| Multi-place sync | Not supported | Supported (up to 3 places) |
-
-## Sync targets and default exclusions
-
-Default syncable 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`: user confirms before applying to Studio
-- `auto`: detected changes are auto-applied
-
-In Pro, Direction and Apply Mode can be controlled per type.
-
-## `manage_sync` action guide (Pro)
-
-| Action | Description | Key params |
-|------|------|-----------|
-| `status_current_place` | Check current sync state 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 a synced file | `placeId`, `instancePath`, `content` |
-| `progress` | Get realtime sync progress/throughput | `placeId` |
-
-## Recommended workflow
-
-### 1) Start safely
-
-- Complete Full Sync first to establish a stable baseline
-- Start with `manual` apply mode to reduce risk
-
-### 2) Work with AI
-
-- "Check sync status, then summarize only risky changes from recent history"
-- "Refactor scripts in `ServerScriptService` first and include history output"
-
-### 3) Resolve conflicts
-
-When changes are detected on both Studio and local sides during bidirectional sync, a conflict resolution dialog appears.
-
-![Local Changes Detected — conflict resolution options (Studio Priority / Local Priority / Per-File)](../../assets/screenshots/plugin/sync/sync-conflict.png)
-
-- **Studio Priority**: overwrite with Studio state as the source of truth
-- **Local Priority**: apply local files to Studio
-- **Per-File**: choose which side takes priority for each file individually
-
-### 4) Recover when needed
-
-- Track recent entries with `history`
-- Inspect target file with `read_file`
-- Restore content with `write_file`, then verify Studio state
-
-## File format (v2 nested directory)
-
-Each Roblox instance is stored as its own directory containing meta files:
-
-```
-explorer/
-├── Workspace/
-│   ├── _tree.json
-│   ├── Part/
-│   │   └── Part.props.json
-│   ├── MyScript/
-│   │   └── MyScript.server.luau
-│   └── Coins/
-│       └── Coins.value.json
-```
-
-Naming conventions:
-- Props: `{Name}/{Name}.props.json`
-- Scripts: `{Name}/{Name}.server.luau` / `.client.luau` / `.module.luau`
-- Values: `{Name}/{Name}.value.json`
-
-Duplicate instance names use `~N` suffix on the directory (e.g. `Part~2/Part.props.json`).
-Names containing `~` are escaped to `~~` (e.g. `Part~2` becomes `Part~~2/`). The Odd-Count Tilde Rule applies: a trailing `~+N` is a collision suffix only when the tilde count is odd.
-
-## Related docs
-
-- [Use `luau-lsp` with WEPPY Sync](./luau-lsp.md)
-- [Tools Overview](../tools/overview.md)
-- [Pro Upgrade Guide](https://weppyai.com/en/plans)

package/docs/en/tools/assets-and-effects.md

@@ -1,104 +0,0 @@
-# Assets & Effects
-
-> Insert assets and control tweening, audio, particles, animation, and collision groups.
-
-## Included Tools
-
-| Tool | Tier | Description |
-|------|:----:|-------------|
-| `manage_assets` | Pro | Search Creator Store, insert models and packages, inspect asset info |
-| `manage_tween` | Pro | Create, play, pause, and cancel tweens |
-| `manage_animation` | Pro | Load, play, stop, and inspect animation tracks |
-| `manage_audio` | Pro | Play, stop, pause, and resume sounds; set the audio listener |
-| `manage_effects` | Pro | Emit particles, clear effects, and toggle effect state |
-| `manage_physics` | Pro | Register collision groups and configure collisions |
-
-## Key Workflows
-
-### Build a scene with assets
-
-```
-"Search Creator Store for a tree model and place three of them in Workspace."
-```
-
-Use `manage_assets.search_insert` to search and insert in a single step.
-
-### Create interactive set pieces
-
-```
-"Make the door open with a 3-second tween when clicked."
-```
-
-Use `manage_tween.create` to define the motion, then `manage_tween.play` to trigger it. Pair it with `manage_audio.play` for a matching sound effect.
-
-### Combine particles and audio
-
-```
-"Play an explosion sound and emit burst particles when the boss appears."
-```
-
-Use `manage_effects.emit` for the particles and `manage_audio.play` for the sound in the same workflow.
-
-## Action Reference
-
-### Manage Assets (Pro)
-
-| Action | Description | Tier |
-|--------|-------------|------|
-| `insert` | Insert a model by asset ID | Pro |
-| `info` | Get asset metadata | Pro |
-| `search` | Search Creator Store | Pro |
-| `search_insert` | Search and insert the first match | Pro |
-| `insert_free` | Insert a free model | Pro |
-| `insert_package` | Insert a package | Pro |
-| `export` | Export the current selection | Pro |
-
-### Manage Tween (Pro)
-
-| Action | Description | Tier |
-|--------|-------------|------|
-| `create` | Create a tween with target properties | Pro |
-| `play` | Play a created tween | Pro |
-| `pause` | Pause a running tween | Pro |
-| `cancel` | Cancel a tween | Pro |
-
-### Manage Animation (Pro)
-
-| Action | Description | Tier |
-|--------|-------------|------|
-| `load` | Load animation on a Humanoid or AnimationController | Pro |
-| `play` | Play a loaded animation track | Pro |
-| `stop` | Stop a playing animation | Pro |
-| `get_tracks` | List all loaded animation tracks | Pro |
-
-### Manage Audio (Pro)
-
-| Action | Description | Tier |
-|--------|-------------|------|
-| `play` | Play a sound and create `Sound` if needed | Pro |
-| `stop` | Stop a playing sound | Pro |
-| `pause` | Pause a playing sound | Pro |
-| `resume` | Resume a paused sound | Pro |
-| `set_listener` | Set the audio listener type or target | Pro |
-
-### Manage Effects (Pro)
-
-| Action | Description | Tier |
-|--------|-------------|------|
-| `emit` | Emit particles from a `ParticleEmitter` | Pro |
-| `clear` | Clear all particles | Pro |
-| `toggle` | Enable or disable an effect | Pro |
-
-### Manage Physics (Pro)
-
-| Action | Description | Tier |
-|--------|-------------|------|
-| `register_group` | Register a collision group | Pro |
-| `set_collidable` | Set whether two groups can collide | Pro |
-| `get_groups` | List all registered collision groups | Pro |
-
-## Related Docs
-
-- [Instances & Properties](instances-and-properties.md) - create and place objects
-- [World & Environment](world-and-environment.md) - lighting, terrain, and camera
-- [Tools Reference](overview.md)

package/docs/en/tools/instances-and-properties.md

@@ -1,104 +0,0 @@
-# Instances & Properties
-
-> Search, create, and edit Roblox Studio instances while managing properties, attributes, and tags.
-
-## Included Tools
-
-| Tool | Tier | Description |
-|------|:----:|-------------|
-| `query_instances` | Mixed | Search instances, traverse hierarchy, inspect class info |
-| `mutate_instances` | Mixed | Create, delete, clone, move, and rename instances |
-| `manage_properties` | Mixed | Read and write properties, attributes, and tags |
-
-## Key Workflows
-
-### Understand scene structure
-
-```
-"Find every Part under Workspace and tell me its position and size."
-```
-
-Use `query_instances.search_class` to find the parts, then `manage_properties.mass_get` to read `Position` and `Size` in bulk.
-
-### Place objects in bulk
-
-```
-"Place 4 SpawnLocations in a square at the center of the map and give each one a different TeamColor."
-```
-
-Use `mutate_instances.mass_create` to create them in one request, then `manage_properties.mass_set` to assign their properties together.
-
-### Manage tagged objects
-
-```
-"Find every object tagged Collectible and set Anchored to true."
-```
-
-Use `manage_properties.get_tagged` to collect the tagged instances, then `manage_properties.mass_set` to update them.
-
-## Action Reference
-
-### Query Instances (Mixed)
-
-| Action | Description | Tier |
-|--------|-------------|------|
-| `get` | Get instance properties by path | Basic |
-| `children` | Get immediate children or all descendants | Basic |
-| `find_child` | Find first child by name and optional class filter | Basic |
-| `find_descendant` | Find first descendant by name | Basic |
-| `wait_for_child` | Wait for child to appear (with timeout) | Basic |
-| `class_info` | Get class information and valid properties | Basic |
-| `search_name` | Search instances by name pattern (supports wildcards) | Basic |
-| `search_class` | Search instances by class name | Basic |
-| `file_tree` | Get file tree structure from root | Pro |
-| `project_structure` | Get complete project structure | Pro |
-| `descendants` | Get all descendants of an instance | Pro |
-| `ancestors` | Get all ancestors of an instance | Pro |
-| `search_property` | Search instances by property value | Pro |
-| `search_tag` | Search instances by tag | Pro |
-
-### Mutate Instances (Mixed)
-
-| Action | Description | Tier |
-|--------|-------------|------|
-| `create` | Create a new instance | Basic |
-| `create_with_props` | Create instance with initial properties | Basic |
-| `delete` | Delete an instance | Basic |
-| `clone` | Clone an instance | Basic |
-| `move` | Move instance to a new parent | Basic |
-| `rename` | Rename an instance | Basic |
-| `pivot` | Set pivot position or CFrame | Basic |
-| `create_tree` | Create a hierarchical instance tree | Pro |
-| `mass_create` | Create multiple instances at once | Pro |
-| `mass_delete` | Delete multiple instances | Pro |
-| `mass_duplicate` | Duplicate multiple instances | Pro |
-| `smart_duplicate` | Duplicate with spacing and count | Pro |
-
-### Manage Properties (Mixed)
-
-| Action | Description | Tier |
-|--------|-------------|------|
-| `get` | Get a single property value | Basic |
-| `set` | Set a single property value | Basic |
-| `get_all` | Get all properties of an instance | Basic |
-| `set_multiple` | Set multiple properties at once | Basic |
-| `get_attr` | Get attribute value | Basic |
-| `set_attr` | Set attribute value | Basic |
-| `get_all_attrs` | Get all attributes | Basic |
-| `delete_attr` | Delete an attribute | Basic |
-| `add_tag` | Add a tag to an instance | Basic |
-| `remove_tag` | Remove a tag from an instance | Basic |
-| `check_tag` | Check whether an instance has a tag | Basic |
-| `get_tags` | Get all tags on an instance | Basic |
-| `get_tagged` | Get all instances with a specific tag | Basic |
-| `set_calculated` | Set a property using a mathematical expression | Pro |
-| `set_relative` | Set a property relative to its current value | Pro |
-| `mass_set` | Set a property on multiple instances | Pro |
-| `mass_get` | Get a property from multiple instances | Pro |
-| `modify_children` | Modify all children of a parent | Pro |
-
-## Related Docs
-
-- [Scripting & Code Execution](scripting.md) - add or update scripts on instances
-- [Assets & Effects](assets-and-effects.md) - insert models, tween objects, add effects
-- [Tools Reference](overview.md)