Rbxdev Ls

rbxdev-ls

Luau language server and VS Code extension for Roblox development with live-game tooling.

______________________________________________________________________

概述

rbxdev ls是一个monorepo，它提供了一个功能齐全的Luau语言服务器、一个VS Code扩展、一个独立的MCP服务器和一个Roblox Studio桥接插件。工作空间包括 服务器 （解析器、类型检查器、30+LSP处理程序和执行器网桥协议）， VSCode （游戏树浏览器、属性面板、远程间谍和AI工具注册）， 主控程序 （the @0neshot101/rbxdev-mcp 适用于Claude、Cursor、Windsurf和其他MCP兼容助手的软件包），以及 工作室插件 （一个用Rojo构建的Luau插件，将Studio连接到语言服务器）。

大多数Luau编辑器都提供语法高亮显示，也许还有基本的补全功能。rbxdev-ls更进一步，加载官方Robloxneneneba API转储，用于类型感知完成和悬停文档，运行一个真正的类型检查器 --!strict / --!nonstrict / --!nocheck 注释，以及在顶部分层实时游戏工具——您可以在不离开编辑器的情况下浏览实例层次结构、编辑属性、执行代码和监视远程调用。MCP服务器将相同的桥扩展到AI助手，这样他们就可以读取游戏状态并在对话中运行代码。

特性

• 完整Roblox API完成和悬停文档 -从官方API转储加载，包括继承的成员、不推荐使用的标记和文档字符串。
• Luau类型检查 --三种严格模式(--!strict, --!nonstrict, --!nocheck)诊断结果在编辑器中内联显示。
• 30+LSP处理程序 --完成、悬停、签名帮助、转到定义、查找引用、重命名、文档符号、语义标记、代码操作、格式化、嵌入提示、调用层次结构、折叠、选择范围、类型层次结构、代码镜头、文档链接、颜色选择器和链接编辑。
• Rojo和源代码映射支持 --解析交叉文件 require() 呼叫使用 default.project.json 和 sourcemap.json 因此，转到Rojo项目的定义和自动导入工作。
• 游戏树资源管理器 --侧边栏面板，用于呈现连接的Roblox游戏中的实时实例层次结构，具有展开/折叠、属性检查和上下文菜单操作。
• 远程消息监视程序 --实时捕获RemoteEvent和RemoteFunction流量，通过过滤、阻止列表和快速复制来再现调用。
• 在编辑器代码执行中 --直接在游戏中运行当前文件、选择或捆绑的多文件有效负载。
• 用于AI助手的MCP服务器 --通过模型上下文协议公开的16个工具（执行代码、浏览游戏树、读/写属性、管理实例、读取控制台输出等）。
• GitHub Copilot集成 -同样的16个工具在VS Code的语言模型API中注册，因此Copilot可以在没有单独MCP客户端的情况下与游戏交互。
• 实例操作 --从编辑器或通过AI工具创建、克隆、删除、重新分配和传送到实例。

目录

• 快速开始
• 运作原理
• 建筑
• 安装
• 用法
• 执行器桥设置
• MCP服务器
• 配置
• 键盘快捷键
• 项目结构
• 发展
• 贡献
• 许可证

快速开始

从安装扩展 VS代码市场 或 打开VSX，打开一个包含以下内容的文件夹 .lua 或 .luau 文件，并开始编码。语言服务器会自动激活，并提供补全、类型检查和悬停文档，无需额外设置。

--!strict

local Players = game:GetService("Players")
local localPlayer = Players.LocalPlayer
local character = localPlayer.Character or localPlayer.CharacterAdded:Wait()

类型检查、补全和悬停文档会立即出现。有关实时游戏功能（游戏树、远程间谍、代码执行），请参阅 执行器桥设置.

运作原理

当VS Code激活扩展时，它会将语言服务器生成为通过JSON-RPC（标准LSP传输）通信的Node.js子进程。服务器解析每个打开的 .lua 和 .luau 文件转换为AST，针对Robloxneneneba API转储和任何工作空间定义运行类型检查器，并通过30多个注册的LSP处理程序响应编辑器请求。Rojo项目文件和 sourcemap.json 在启动时读取并监视更改，以便跨文件 require() 分辨率保持最新，无需手动重新加载。

实时游戏功能使用单独的WebSocket通道。该扩展在端口21324（可配置）上启动WebSocket服务器，并等待执行器网桥客户端从正在运行的Roblox游戏内部连接。连接后，扩展可以发送命令（执行代码、请求实例树、读取属性）和接收事件（游戏树快照、远程间谍捕获、运行时错误、控制台日志）。MCP服务器可以直接拥有此WebSocket服务器，也可以在两者同时运行时通过扩展的网桥作为代理客户端连接。

建筑

graph TD
    subgraph Editor["VS Code"]
        EXT["Extension Client"]
        GT["Game Tree Panel"]
        PROPS["Properties Panel"]
        RSPY["Remote Spy Panel"]
        COPILOT["Copilot Tools"]
    end

    subgraph Server["Language Server (Node.js)"]
        LSP["LSP Handlers"]
        PARSER["Luau Parser"]
        TC["Type Checker"]
        DEFS["API Definitions"]
        WS["Workspace / Rojo"]
    end

    subgraph Bridge["Executor Bridge (WebSocket :21324)"]
        BRIDGE["Bridge Server"]
    end

    subgraph MCP["MCP Server"]
        MCPS["@0neshot101/rbxdev-mcp"]
    end

    subgraph Game["Roblox Game"]
        EXEC["Executor Client"]
        STUDIO["Studio Plugin"]
    end

    EXT |JSON-RPC| LSP
    LSP --> PARSER
    LSP --> TC
    TC --> DEFS
    LSP --> WS
    EXT  BRIDGE
    GT  BRIDGE
    PROPS  BRIDGE
    RSPY  BRIDGE
    COPILOT  BRIDGE
    BRIDGE |WebSocket| EXEC
    BRIDGE |WebSocket| STUDIO
    MCPS |Proxy or Direct| BRIDGE

安装

最简单的方法是从市场安装预构建的扩展。对于希望从源代码构建的贡献者，请参阅 发展.

VS代码扩展

从任一市场安装：

或者，搜索 rbxdev-ls 在VS Code扩展面板中，直接安装。

MCP服务器（独立）

如果你想让AI助手在没有VS Code的情况下与Roblox游戏进行交互，请全局安装MCP服务器或通过npx运行它。看 MCP服务器 有关完整的设置说明。

用法

语言服务器

语言服务器会自动激活任何包含以下内容的工作区 .lua 或 .luau 文件夹。它提供了完整的编辑器功能，无需任何配置：

• 类型 game:GetService(" 查看所有Roblox服务的完成列表。
• 将鼠标悬停在任何Roblox API成员上，查看其类型签名和文档。
• 使用 Ctrl+Click （或 F12)跳到局部变量、函数或所需模块的定义。
• 使用重命名符号 F2 并且所有引用都会在整个工作区中更新。
• 类型错误显示为“问题”面板中的诊断信息，请遵守 --!strict / --!nonstrict / --!nocheck 每个文件顶部的注释。

现场游戏功能

连接执行器桥后（参见 执行器桥设置)，侧边栏面板变为活动状态：

• 游戏树 --展开服务和实例以浏览层次结构。右键单击可执行传送、克隆、删除或复制Luau路径等操作。
• 属性 --在游戏树中选择一个实例以查看和编辑其属性。支持所有标准Roblox类型（Vector3、CFrame、Color3、UDim2等）。
• 远程消息监视程序 --切换间谍以捕获所有RemoteEvent和RemoteFunction流量。按名称过滤，设置阻止列表，并将调用复制为可运行的Luau代码。

代码执行

通过键盘快捷键或命令面板，有三种执行模式可供选择：

运行时错误和 print/warn/error 输出出现在VS Code输出通道中。

执行器桥设置

executor桥是一个Luau脚本，在Roblox游戏中运行，并打开一个返回语言服务器的WebSocket连接。要启用实时游戏功能，请将此粘贴到执行器的自动执行中：

loadstring(game:HttpGetAsync('https://raw.githubusercontent.com/0neShot101/rbxdev-ls/main/scripts/executor-bridge.lua'))()

这座桥连接到 ws://127.0.0.1:21324 默认情况下。如果需要自定义连接，请传递一个配置表：

loadstring(game:HttpGetAsync('https://raw.githubusercontent.com/0neShot101/rbxdev-ls/main/scripts/executor-bridge.lua'))({
    host = 'ws://127.0.0.1:21324';
    reconnectDelay = 5;
    firstConnectDepth = 999;
    updateTreeDepth = 2;
    expandedTreeDepth = 2;
})

MCP服务器

这 @0neshot101/rbxdev-mcp 该软件包通过模型上下文协议公开了16个工具，让Claude、Cursor、Windsurf和其他兼容MCP的AI助手与实时Roblox游戏进行交互。它需要Node.js 18+和一个正在运行的执行器桥连接。

设置

该包托管在GitHub Packages上。配置npm以使用GitHub注册表 @0neshot101 通过将此添加到您的 ~/.npmrc:

@0neshot101:registry=https://npm.pkg.github.com

然后将此块添加到MCP客户端配置中：

{
  "mcpServers": {
    "rbxdev-roblox": {
      "command": "npx",
      "args": ["-y", "@0neshot101/rbxdev-mcp"]
    }
  }
}

配置文件的位置取决于您的工具：

代理模式

如果rbxdev ls VS Code扩展已经在运行（它拥有端口21324上的WebSocket服务器），MCP服务器会自动通过扩展的网桥作为代理客户端连接。这两个工具共享相同的执行器连接，没有端口冲突。如果扩展未运行，MCP服务器将启动自己的WebSocket服务器并直接连接到执行器。

自定义端口

要使用非默认端口，请设置 RBXDEV_BRIDGE_PORT 环境变量：

{
  "mcpServers": {
    "rbxdev-roblox": {
      "command": "npx",
      "args": ["-y", "@0neshot101/rbxdev-mcp"],
      "env": {
        "RBXDEV_BRIDGE_PORT": "21325"
      }
    }
  }
}

Available MCP Tools

服务器还公开了三个MCP资源用于被动读取：

配置

所有设置都以前缀 rbxdev-ls. 并且可以在VS Code中设置 settings.json 或者通过设置UI。

键盘快捷键

项目结构

rbxdev-ls/
├── packages/
│   ├── server/                    Language server package (rbxdev-server)
│   │   ├── src/
│   │   │   ├── core/              LSP server bootstrap, connection, and capability registration
│   │   │   ├── lsp/
│   │   │   │   └── handlers/      30+ LSP request handlers (completion, hover, rename, etc.)
│   │   │   ├── parser/            Luau lexer, parser, and doc-comment extraction
│   │   │   ├── typings/           Type system, type checker, and subtyping logic
│   │   │   ├── definitions/       Roblox API, stdlib, executor, and third-party type definitions
│   │   │   ├── workspace/         Module resolution, Rojo integration, and sourcemap support
│   │   │   ├── executor/          Bridge protocol, WebSocket server, and proxy handling
│   │   │   └── utils/             Shared utility functions
│   │   ├── tests/                 29 test suites (984 tests)
│   │   └── data/                  Roblox API dump (roblox-api.json)
│   ├── vscode/                    VS Code extension client
│   │   └── src/
│   │       ├── extension.ts       Extension activation and command registration
│   │       ├── gameTreeProvider.ts Game tree sidebar data provider
│   │       ├── propertiesProvider.ts Properties panel data provider
│   │       ├── remoteSpyWebview.ts Remote spy webview panel
│   │       └── mcpTools.ts        16 language model tools for Copilot integration
│   ├── mcp/                       Standalone MCP server (@0neshot101/rbxdev-mcp)
│   │   └── src/
│   │       ├── index.ts           Entry point (stdio transport)
│   │       └── server.ts          Tool and resource registration
│   └── studio-plugin/             Roblox Studio bridge plugin (Luau, built with Rojo)
│       ├── default.project.json   Rojo project file
│       └── src/                   Plugin source
├── scripts/                       Build orchestration and maintenance
│   ├── build-vsix.ts              Packages the VS Code extension as a .vsix
│   ├── build-studio-plugin.ts     Builds the Studio plugin via Rojo
│   ├── publish-mcp.ts             Publishes @0neshot101/rbxdev-mcp to GitHub Packages
│   ├── fetch-roblox-api.ts        Downloads the latest Roblox API dump
│   └── executor-bridge.lua        Bridge script loaded by executors at runtime
└── package.json                   Workspace root (bun workspaces)

发展

先决条件

设置

git clone https://github.com/0neShot101/rbxdev-ls && cd rbxdev-ls
bun install

每个工作区中的所有依赖项都由单个 bun install 在repo根目录下。

脚本

验证

克隆和安装后，确认一切正常：

bun run build && bun run test

所有984个测试都应该通过。如果通过，语言服务器二进制文件位于 packages/server/dist/index.js 并准备好供扩展使用。

贡献

欢迎问题和拉取请求。如果要添加新行为或更改现有行为，请在相关 packages/server/tests/ 一套。Bug报告应包括重现问题和预期与实际行为的Luau代码片段。

要提交pull请求，请分叉存储库，创建分支，然后打开PR mainCI管道在每次推送时运行类型检查、linting、格式化和完整的测试套件。

许可证

麻省理工学院 ©2025安德鲁