内容
<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/logo.svg">
<source media="(prefers-color-scheme: light)" srcset="assets/logo.svg">
<img src="assets/logo.svg" width="120" alt="BloxForge logo" />
</picture>
<h1 align="center">BloxForge</h1>
<p align="center">
<strong>Roblox Studio 的开源 AI 代理工具包。</strong><br />
使用 AI 构建、检查、测试和自动化 Roblox 游戏。<br />
<em>Claude Code · Codex · Cursor · Gemini · 任意 MCP 兼容的 AI 客户端</em>
</p>
[](https://github.com/princeofscale/bloxforge/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@princeofscale/bloxforge)
[](https://www.npmjs.com/package/@princeofscale/bloxforge)
[](LICENSE)
[](package.json)
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/banner.svg">
<source media="(prefers-color-scheme: light)" srcset="assets/banner.svg">
<img src="assets/banner.svg" width="100%" alt="BloxForge banner" />
</picture>
</div>
---
将 Claude、Codex、Cursor 或 Gemini 连接到 Roblox Studio，让代理直接构建、编辑、测试和调试您的游戏。BloxForge 是一个本地的开源代理运行时，具有安全的编辑、游戏脚手架、资产工作流和自动播放测试。
> 🏆 **免费 · MIT · 自托管 · 核心功能无需账户**
---
## 快速开始
```bash
# 1. 在游戏设置 → 安全中启用 Allow HTTP Requests
# 2. 连接您的 AI 客户端（一条命令）：
# Claude Code
claude mcp add bloxforge -- npx -y @princeofscale/bloxforge@latest --auto-install-plugin
# Codex CLI
codex mcp add bloxforge -- npx -y @princeofscale/bloxforge@latest --auto-install-plugin
# Cursor — 添加到 .cursor/mcp.json
# Gemini CLI
gemini mcp add bloxforge npx --trust -- -y @princeofscale/bloxforge@latest --auto-install-plugin
```
> 在插件首次安装或更新后，请完全关闭并重新打开 **Roblox Studio**。
**运行诊断以确认：**
```bash
npx -y @princeofscale/bloxforge@latest --doctor
```
仅加载作业所需的工具，使用 `--profile core|builder|tester|full`。`core` 保留 token-lean 默认值；只读包使用检查器工具集。
### 🎮 试试这些提示
| 类别 | 示例提示 |
|---|---|
| **检查** | _"这个游戏的结构是什么？"_ |
| **脚手架** | _"创建一个带有 6 个检查点和计时器 HUD 的 obby 游戏。"_ |
| **调试** | _"查找所有脚本错误并解释它们。"_ |
| **构建 UI** | _"创建一个适用于移动设备的商店 UI，带有关闭按钮。"_ |
| **编辑** | _"将所有名为 'Part' 的部分批量重命名为 'Terrain_Block'。"_ |
| **资产** | _"在市场上搜索一个低多边树，检查是否安全插入，然后添加它。"_ |
| **环境** | _"设置恐怖灯光并添加昼夜循环脚本。"_ |
| **调试实时** | _"启动播放测试，采样玩家位置，运行游戏玩法断言。"_ |
> 完整的文档、[已知限制](docs/known-limitations.md) 和 [故障排除指南](docs/troubleshooting.md) 位于 [docs/](docs/README.md)。
---
## 它是如何工作的
```
您的 AI 客户端（Claude Code / Codex / Cursor / Gemini）
│
▼ MCP（stdio）
BloxForge 服务器（Node/TypeScript）
│
▼ 本地 HTTP 网桥（长轮询，不会离开您的机器）
Roblox Studio 插件
│
▼
您的开放空间：工作区 · ServerScriptService · ReplicatedStorage · StarterGui · Lighting · 地形 …
```
**本地优先，默认私有。** 网桥仅在 `localhost` 上运行 - 没有数据离开您的机器。无需云依赖，核心功能无需账户。
---
## BloxForge 可以做什么
### 🔍 场景检查
`get_scene_summary` · `get_node_batch` · `get_changes_since` · `scene_search` · `get_descendants` · `get_file_tree` · 属性 · 属性 · 标签 · 内存/分析分解
→ Token 高效：首先进行廉价的概述，然后深入研究。无需完整的 DataModel 转储。
### 📝 脚本和 Luau
`get_script_source` · `set_script_source` · `edit_script_lines` · `grep_scripts` · `find_and_replace` · `diagnose_scripts`（错误 → 脚本：行）· `execute_luau` · 异步 Luau 作业
→ 对任何脚本、LocalScript 或 ModuleScript 进行完整的读写/补丁。
`get_roblox_docs` 在代理触摸不确定的 API 前获取官方引擎参考 Markdown（也可以作为 `robloxdocs://...` MCP 资源）。
### ✏️ 批量编辑
`apply_mutation_plan`（事务批量：设置属性、属性、标签 - 一次调用，回滚包含）· `mass_set_property` · `smart_duplicate` · `mass_create_objects` · 每次变异的试运行。
### 🖥️ UI 构建器
`ui_create_screen_gui` · `ui_create_frame` · `ui_create_text_label/button` · `ui_create_image_label/button` · `ui_apply_layout` · `ui_make_mobile_friendly`
→ 完全从代理提示生成 UI。
### 🌍 地形和环境
**地形：** 基板 · 岛屿 · 山脉 · 水 · 绘制材质 · 清除区域（体积限制，门控）。
**环境：** 8 个灯光预设（晴天，夕阳，夜晚，恐怖，赛博朋克，obby，模拟器，现实主义）· 大气 · 天空 · 昼夜循环脚本。
### 🏗 游戏模板
`template_create_obby_game` · `template_create_simulator_game` · `template_create_tycoon_game` · `template_create_round_game`
→ 一个提示 → 大厅 + 竞技场 + 排行榜 + 循环。
### 🏪 市场和资产
**无需密钥：** `marketplace_search` · `marketplace_search_and_insert` · `insert_asset` · `preview_asset` · `asset_preflight_insert`（权威 LoadAssetAsync 检查）。
**使用 Open Cloud 密钥：** `search_assets` · `get_asset_details` · `upload_asset` · `.rbxm` 导入/导出 · 构建库 CRUD。
### 🎮 实时调试
`start_playtest`/`stop_playtest` · `multiplayer_test_start`/`add/leave/end` · `get_runtime_logs` · `capture_screenshot` · `playtest_sample_state` · `run_gameplay_assertions` · `simulate_mouse/keyboard_input` · `character_navigation`.
### 🛡 安全层
- ⚠️ **确认门控** 对破坏性操作（删除受保护的服务，批量突变，地形清除，危险的 Luau 模式）。
- 💾 **自动脚本备份** 在覆盖前 - 使用 `restore_script_backup` 恢复。
- 👁 **试运行** 每次重大突变使用 `dryRun: true`。
- 📋 **操作历史** 通过 `get_operation_history` + 撤销/重做。
- 📏 **硬限制** 对象每操作、脚本大小、地形体积。
### 🔧 更多工具
- **AI 图像生成** （Pollinations 文本到图像）- 在本地生成纹理。
- **音频和动画** - 创建/播放声音，在模型上加载和播放动画。
- **本地同步** - 将脚本拉取到 `.server.lua`/`.client.lua` 文件，在您的 IDE 中编辑，推送回冲突检测。
- **诊断仪表盘** - 运行服务器上的 `/dashboard`，显示 Studio 状态、版本、请求日志。
- `--doctor` CLI - 验证 Node、包、插件、网桥和 Studio 连接性。
---
## CLI 参考
| 标志 | 目的 |
|---|---|
| `--auto-install-plugin` | 启动时安装/刷新捆绑插件。 |
| `--install-plugin` | 安装插件并退出。 |
| `--port <n>` | 覆盖网桥端口（默认 58741）。 |
| `--debug` | 详细日志记录。 |
| `--doctor` | 运行诊断并退出。 |
| `--pollinations-key <k>` | Pollinations API 密钥，用于 AI 图像生成。 |
| `--open-cloud-key <k>` | Roblox Open Cloud 密钥，用于 Creator Store + 资产上传。 |
### 可选密钥
所有核心功能 **无需密钥**。两个可选集成添加更多功能：
| 密钥 | 启用 |
|---|---|
| `POLLINATIONS_API_KEY` | `image_generate`，`image_generate_and_upload`（文本到图像）和 `design_review`（视觉 UI 批评）通过 Pollinations。获取服务器端 `sk_` 密钥，从 [enter.pollinations.ai](https://enter.pollinations.ai) 获取。 |
| `ROBLOX_OPEN_CLOUD_API_KEY` | `search_assets`，`get_asset_details`，`upload_asset` 和外部资产导入 - Creator Store 访问和资产发布。 |
#### 获取 Roblox Open Cloud API 密钥
`upload_asset`（和外部资产导入）需要具有写入范围的 Open Cloud 密钥：
1. 进入 [Creator Dashboard → Credentials → API Keys](https://create.roblox.com/dashboard/credentials?activeTab=ApiKeysTab)。
2. **创建 API 密钥**。添加这些 API 系统/范围:
- **资产** → `asset:read`，`asset:write`
- **资产权限** → `asset-permissions:write`（如果您还管理资产共享）
3. 在 **安全**下，添加您的 IP（或 `0.0.0.0/0` - 不太安全），然后 **保存并生成**。
4. 复制密钥 **一次** 并将其作为环境变量公开 - 永远不要提交它：
```bash
export ROBLOX_OPEN_CLOUD_API_KEY="<your-key>"
export POLLINATIONS_API_KEY="<your-sk_-key>" # 可选，用于图像/设计工具
```
> **将密钥留在仓库和聊天中。** 它们授予对您账户资产的写入访问权限。将已粘贴到任何位置的密钥视为已泄露并 **轮换它**（在仪表盘上删除 + 重新生成）。
---
## 检查版（只读）
[](https://www.npmjs.com/package/@princeofscale/bloxforge-inspector)
相同的插件，仅限只读工具 - 无写入，无脚本编辑，无创建。安全用于浏览、代码审查和零突变风险的调试。
```bash
claude mcp add robloxstudio-inspector -- npx -y @princeofscale/bloxforge-inspector@latest --auto-install-plugin
```
---
## 为什么选择这个而不是 WEPPY？
| | 这个 MCP | WEPPY |
|---|---|---|
| **价格** | **免费，MIT，自托管** | 免费层 + 付费 **专业版** |
| **安全层** | 可配置的试运行/确认/备份/限制 | 部分 |
| **游戏模板** | obby，模拟器，暴君，回合 - 全部免费 | - |
| **市场搜索** | 免费，无需密钥 | - |
| **本地同步** | 免费，双向，冲突感知 | 专业版 gated |
| **操作历史** | 免费，带有恢复 | 专业版 gated |
| `--doctor` 诊断 | ✅ | - |
| **只读版** | ✅ | - |
| **许可证** | MIT - 免费使用，分享，修改 | 专有 |
该项目是一个 **免费，开源的替代品** - 不是克隆，不是绕过。它共享此代码与 WEPPY，并且不尝试规避任何闭源工具。MIT 许可证意味着您可以自由使用，分享，修改和构建它。
---
## 从源代码构建
```bash
npm install && cd studio-plugin && npm install && cd ..
npm run build # Node packages
npm run typecheck && npm test # 419 unit tests
cd studio-plugin && npm run build && cd .. # plugin TS → Luau
node scripts/build-plugin.mjs # → MCPPlugin.rbxmx
```
---
## 路线图
- [ ] **交互式应用 UI** 用于资产审查和批量变更审批（MCP 应用）
- [ ] **混合语义场景搜索** （嵌入 + 词典）适用于大规模需求
- [ ] **更丰富的脚本诊断** ，带有 AI 建议的修复
- [ ] **更安全的对象差异预览** 在突变前
- [ ] **更多游戏模板** （战斗，平台，谜题）
- [ ] **文档网站**
- [ ] **示例游戏** 完全由 AI 代理使用此 MCP 构建
- [ ] **评估基准套件** 带有任务成功指标
- [ ] **开源构建库** 社区贡献的模型
---
## 贡献
我们欢迎来自各个背景的贡献者：
- **Roblox 开发者** - 您最需要哪些工具？
- **MCP / AI 代理用户** - 哪些工作流程感觉很麻烦？
- **Luau 开发者** - 想要提高生成的代码质量吗？
- **插件测试者** - 帮助我们测试不同地点和 Studio 版本？
在 https://github.com/princeofscale/bloxforge/issues 上开启一个问题。
---
## 故障排除
| 症状 | 修复 |
|---|---|
| 插件从未显示“已连接” | 启用 **允许 HTTP 请求**（游戏设置 → 安全）；在首次安装后完全重启 Studio。 |
| `--doctor` 说端口上没有任何内容 | 网桥仅在您的 MCP 客户端启动服务器时运行。启动客户端，然后重新运行。 |
| 插件中的黄色横幅 | 服务器/插件版本不同。重新运行 `--auto-install-plugin` 并重启 Studio。 |
| 工具调用挂起 | 连接了多个 Studio 位置 - 传递 `instance_id`（参见 `get_connected_instances`）。 |
| 插件代码在 IDE 中显示红色 | 安装插件依赖项：`cd studio-plugin && npm install`。它是一个单独的 roblox-ts 包。 |
| macOS 插件路径 | `~/Documents/Roblox/Plugins/` |
| Windows 插件路径 | `%USERPROFILE%\Documents\Roblox\Plugins\` |
---
## 许可证
MIT © princeofscale。 BloxForge 最初是 [Chrrxs/robloxstudio-mcp](https://github.com/Chrrxs/robloxstudio-mcp) 的一个分支，
源自 [boshyxd/robloxstudio-mcp](https://github.com/boshyxd/robloxstudio-mcp)，
现在由扩展的构建、测试、安全性和资产工作流独立维护。Roblox 是 Roblox Corporation 的商标； BloxForge 不受 Roblox Corporation 认可或关联。
在 [LICENSE](LICENSE) 中查看完整文本。
---
*正在寻找适用于 **Claude Code**、**Codex**、**Cursor** 或 **Gemini** 的开源 **Roblox Studio MCP 服务器**？ BloxForge 在本地连接 AI 代理到 Studio，无需订阅、帐户或云依赖。*
