Luau语言服务器和VS Code扩展

rbxdev-ls是一个为Roblox开发提供的Luau语言服务器和VS Code扩展,支持实时游戏工具和AI助手集成。

  • by 0neShot101
  • TypeScript
  • 本地部署
  • 20 星标
  • 更新于
在 GitHub 查看 0neShot101/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 @oneshot101/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服务器 --通过模型上下文协议公开的19个工具(执行代码、浏览游戏树、读/写属性、管理实例、读取控制台输出等)。
  • GitHub Copilot集成 -同样的19个工具在VS Code的语言模型API中注册,因此Copilot可以在没有单独MCP客户端的情况下与游戏交互。
  • 实例操作 --从编辑器或通过AI工具创建、克隆、删除、重新分配和传送到实例。

目录

快速开始

从安装扩展 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服务器,也可以在两者同时运行时通过扩展的网桥作为代理客户端连接。

组件 运输 方向
编辑↔ 语言服务器 JSON-RPC over stdio 双向
扩展↔ 执行器 端口21324上的WebSocket 双向
MCP客户端↔ MCP服务器 stdio(模型上下文协议) 双向
MCP服务器↔ 扩展 WebSocket代理 双向(当扩展正在运行时)
工作室插件↔ 扩展 端口21324上的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["@oneshot101/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代码扩展

从任一市场安装:

市场 链接
VS代码市场 rbxdev.rbxdev-ls
打开VSX rbxdev/rbxdev ls

或者,搜索 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代码。

代码执行

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

模式 快捷方式 行为
执行文件 Ctrl+Shift+E 将整个活动文件发送给执行器
执行选择 Ctrl+Shift+Alt+E 仅发送所选文本
捆绑并执行 Ctrl+Alt+E 决议 require() 调用、捆绑到单个有效载荷中并执行

运行时错误和 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;
})
参数 默认值 用途
host ws://127.0.0.1:21324 网桥连接到的WebSocket URL
reconnectDelay 5 断开连接后重新连接尝试之间的秒数
firstConnectDepth 999 在第一次连接时扫描实例树的深度是多少
updateTreeDepth 2 实例更改时发送的树深度更新
expandedTreeDepth 2 在游戏树面板中展开节点时发送的子树深度

MCP服务器

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

设置

该包发布到公共npm注册表下 @oneshot101 范围。

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

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

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

工具 配置位置
克劳德代码 ~/.claude/mcp_config.json
克劳德桌面 设置→ MCP服务器
光标 .cursor/mcp.json 在您的项目中
风浪 喀斯喀特→ MCP → 添加服务器

代理模式

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

自定义端口

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

{
  "mcpServers": {
    "rbxdev-roblox": {
      "command": "npx",
      "args": ["-y", "@oneshot101/rbxdev-mcp"],
      "env": {
        "RBXDEV_BRIDGE_PORT": "21325"
      }
    }
  }
}
Available MCP Tools
工具 说明
get_bridge_status 检查网桥是否正在运行,执行器是否已连接
execute_code 在游戏中使用Roblox API完全访问运行Luau代码
get_game_tree 浏览游戏层次结构(服务、实例、子级)
get_properties 从任何实例读取属性值
set_property 在实例上设置属性(支持Vector3、Color3、UDim2等)
get_children 列出特定实例的子实例
create_instance 在游戏中创建新实例
clone_instance 克隆现有实例
delete_instance 从游戏中删除实例
reparent_instance 将实例移动到新的父级
teleport_player 将本地玩家传送到实例的位置
get_script_source 解压缩并读取脚本源代码
get_console_output 读取游戏最近的打印/警告/错误输出
refresh_game_tree 请求游戏树的新快照
get_remote_calls 查看捕获的RemoteEvent/RemoteFunction调用
set_remote_spy_enabled 打开或关闭远程间谍
set_remote_spy_block_list 阻止所选遥控器向服务器发射信号
set_script_source 通过Studio连接时更新脚本源
save_instance 将游戏或特定实例保存到文件中

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

资源URI 内容
rbxdev://bridge/status 连接状态为JSON
rbxdev://game/tree 完整的游戏树以文本形式呈现
rbxdev://console/logs 最近的控制台输出

配置

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

设置 默认值 目的
rbxdev-ls.typeCheckMode nonstrict 控制没有类型检查的文件的默认类型检查严格性 --! 顶部的注释。接受 strict, nonstrict,或 nocheck
rbxdev-ls.enableSuncApi false 将Sunc执行器API定义加载到类型环境中,为特定于Sunc的全局提供完成和类型检查
rbxdev-ls.executorBridge.port 21324 WebSocket网桥服务器监听执行器和Studio插件连接的TCP端口
rbxdev-ls.mcp.enabled true 启用内置MCP服务器集成,通过VS Code的Copilot API注册语言模型工具
rbxdev-ls.bundler.path "" 自定义路径 luau-bundle 用于捆绑和执行命令的二进制文件。当为空时,使用内置的打包器
rbxdev-ls.debugLogs false 在扩展输出通道中启用详细日志记录,以排除连接和协议问题

键盘快捷键

快捷方式 命令
Ctrl+Shift+E 在游戏中执行当前文件
Ctrl+Shift+Alt+E 在游戏中执行所选文本
Ctrl+Alt+E 捆绑所有必需的模块并执行
Ctrl+Shift+R 将上次远程间谍调用复制到剪贴板
Ctrl+Shift+Alt+R 在光标处插入最后一个远程间谍调用
Ctrl+Alt+C 快速复制(将最后一个远程间谍调用复制为Luau片段)

项目结构

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        19 language model tools for Copilot integration
│   ├── mcp/                       Standalone MCP server (@oneshot101/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
│   ├── 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)

发展

先决条件

依赖关系 最低版本 安装
Bun ≥1.0.0 curl -fsSL https://bun.sh/install | bash
Node.js ≥18 MCP包构建和运行时需要
Rojo 最新 仅需要 build:studio (可选)

设置

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

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

脚本

脚本 描述
bun run build 构建语言服务器(编译 packages/server Bun以Node.js为目标)
bun run build:mcp 构建独立的MCP服务器
bun run build:all 依次构建语言服务器和MCP服务器
bun run test 运行完整的测试套件(29个文件中的984个测试)
bun run type-check 在仅检查模式下对服务器包运行TypeScript编译器
bun run lint:check 运行ESLint而不进行自动修复
bun run lint 运行ESLint并自动修复
bun run format:check 使用Prettier检查格式
bun run format 使用Prettier自动格式化
bun run fetch-api 下载最新的Roblox API转储并将其写入 packages/server/data/roblox-api.json
bun run build:vsix 将VS代码扩展打包为 .vsix 分发文件
bun run build:beta 打包扩展的beta版本
bun run build:studio 使用Rojo构建Roblox Studio插件

验证

克隆和安装后,确认一切正常:

bun run build && bun run test

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

贡献

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

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

许可证

麻省理工学院 ©2025安德鲁