开发 FluffOS MUD 时,可以使用 LPC (FluffOS) 扩展为 VS Code 添加 LPC 语言支持,包括语法高亮、结构检查、代码格式化、补全、定义跳转和引用查找。配合 FluffOS 的 lpcc 编译器,还可以在保存文件时查看真实的编译错误。
本文介绍从源码构建扩展、安装 VSIX,以及配置 mudlib 工作区的方法。示例使用 Windows 和 PowerShell。
一、准备环境
需要准备:
- VS Code 1.75 或更新版本。
- Node.js 18 或更新版本。
- Git。
- 一个 FluffOS mudlib 项目。
检查 Node.js 和 Git:
node --version
npm --version
git --version
项目地址:fluffos/fluffos-vscode。
二、获取源码和子模块
首次下载项目时,可以连同子模块一起获取:
git clone --recurse-submodules https://github.com/fluffos/fluffos-vscode.git
cd fluffos-vscode
如果已经下载了项目,但没有初始化子模块,在项目根目录执行:
git submodule update --init --depth 1
这里的 fluffos/ 子模块提供扩展所需的语言引擎,包括分词器、格式化器、检查器和语法文件。
从源码构建扩展必须有这些文件,但不需要编译整个 FluffOS 驱动。 子模块会检出项目固定的版本,不必手动切换到最新分支。
三、测试并构建 VSIX
在扩展项目根目录执行:
node fluffos/tools/lpc-syntax/test.mjs
node scripts/test.mjs
node scripts/build.mjs
前两条命令分别运行语言引擎测试和扩展测试,最后一条命令生成安装包。
输出位置为:
out/fluffos-lpc-<版本号>.vsix
例如:
out/fluffos-lpc-0.1.0.vsix
构建会从子模块同步语言引擎,并安装打包所需的运行依赖。首次打包通常需要联网。
extension/lib/、extension/syntaxes/ 和 out/ 都是生成目录,不需要手动修改。
Windows 下出现 spawnSync npm ENOENT 怎么办?
部分 Windows 环境中,直接运行脚本会出现:
Error: spawnSync npm ENOENT
即使 PowerShell 中能执行 npm --version,也可能遇到这个问题:脚本使用 Node.js 直接启动 npm,而 Windows 通常通过 npm.cmd 启动它。
在本文验证环境中,可以使用以下临时启动适配完成测试和打包,无需修改项目源码:
node -e 'const cp=require("node:child_process");const orig=cp.execFileSync;cp.execFileSync=function(file,args,opts){return orig(file,args,(file==="npm"||file==="npx")?{...opts,shell:true}:opts)};require("node:module").syncBuiltinESMExports();import("./scripts/test.mjs");'
测试通过后,再运行:
node -e 'const cp=require("node:child_process");const orig=cp.execFileSync;cp.execFileSync=function(file,args,opts){return orig(file,args,(file==="npm"||file==="npx")?{...opts,shell:true}:opts)};require("node:module").syncBuiltinESMExports();import("./scripts/build.mjs");'
这两条命令只调整当前 Node.js 进程启动 npm、npx 的方式。仅在遇到上述错误时使用。
四、安装扩展
打开 VS Code,进入扩展面板:
- 按
Ctrl+Shift+X。 - 点击扩展面板右上角的
…。 - 选择“从 VSIX 安装”。
- 选择构建生成的
.vsix文件。
也可以使用命令行安装:
code --install-extension .\out\fluffos-lpc-0.1.0.vsix
文件名需要替换为实际生成的版本。
五、打开 mudlib 并配置工作区
安装扩展后,用 VS Code 打开你的 mudlib 根目录。
例如:
C:/MUD/my-mud/
├─ .vscode/
│ └─ settings.json
├─ adm/
├─ include/
├─ config.cfg
└─ fluffos/
└─ build/
└─ bin/
└─ lpcc.exe
扩展自动识别 .lpc 文件。许多 mudlib 使用 .c 和 .h,需要在工作区中将它们关联为 LPC。
在 mudlib 的 .vscode/settings.json 中加入:
{
"files.autoGuessEncoding": true,
"files.insertFinalNewline": true,
"files.trimFinalNewlines": true,
"files.trimTrailingWhitespace": true,
"files.eol": "\n",
"files.associations": {
"*.c": "lpc",
"*.h": "lpc"
},
"lpc.format.printWidth": 100,
"lpc.format.indentSize": 4,
"[lpc]": {
"editor.renderWhitespace": "all",
"editor.defaultFormatter": "fluffos.fluffos-lpc",
"editor.tabSize": 4,
"editor.insertSpaces": true,
"editor.formatOnSave": true
}
}
如果文件已有其他设置,将这些配置合并进去即可。
| 设置 | 作用 |
|---|---|
files.associations |
将 .c、.h 识别为 LPC 文件 |
lpc.format.printWidth |
格式化器的首选行宽,示例为 100 |
lpc.format.indentSize |
格式化后的缩进空格数 |
editor.defaultFormatter |
指定使用 LPC (FluffOS) 扩展格式化 |
editor.tabSize |
编辑器中的 Tab 显示宽度和缩进宽度 |
editor.insertSpaces |
缩进时使用空格 |
editor.formatOnSave |
保存时自动格式化 |
editor.renderWhitespace |
显示空格、Tab 等空白字符 |
"[lpc]" 中的设置只针对 LPC 文件生效。缩进应与项目规范保持一致;如果项目使用两空格缩进,将对应的两个 4 都改成 2。

建议把文件关联写在 mudlib 的工作区设置里,避免影响其他 C/C++ 项目。
六、配置真实编译检查
基础高亮、结构检查和格式化可以直接使用。真实编译检查需要 lpcc 编译器和 FluffOS 驱动配置文件。
如果已有原生 lpcc,在工作区设置中增加:
"lpc.lpcc.path": "fluffos/build/bin/lpcc.exe",
"lpc.lpcc.configFile": "config.cfg"
上述示例要求:
- VS Code 打开的是 mudlib 根目录。
fluffos/build/bin/lpcc.exe确实存在。- 根目录中的
config.cfg是该 mudlib 使用的驱动配置。 - 驱动配置中的 mudlib 路径与实际目录一致。
当前实现运行编译器时会设置工作目录,因此在这种目录布局下可以使用上述相对路径。如果 lpcc 放在其他位置,也可以填写绝对路径:
"lpc.lpcc.path": "C:/FluffOS/build/bin/lpcc.exe",
"lpc.lpcc.configFile": "C:/MUD/my-mud/config.cfg",
"lpc.mudlibRoot": "C:/MUD/my-mud"
Windows 路径推荐使用 /,避免在 JSON 中重复转义反斜杠。
配置完成后,保存 LPC 文件,编译错误和警告会显示在编辑器及“问题”面板中。
是否必须手动指定配置文件?
扩展可以在未填写 lpc.lpcc.configFile 时:
- 尝试使用工作区的
.lpc/config。 - 查找根目录或
etc/中的config.*驱动配置。
如果没有现成配置,可以通过命令面板运行:
LPC: Initialize compiler config (.lpc/ scaffold)
该命令优先提供发现的驱动配置,否则生成最小配置。已有 MUD 项目通常应使用自己的真实驱动配置,以匹配 include 路径、master 和其他运行环境。
安装包是否自带编译器?
只有构建时提供了 WebAssembly 版 lpcc.js 和 lpcc.wasm,安装包才会包含编译器。
普通源码打包不会自动下载或编译 WebAssembly lpcc。 构建输出如果提示:
no wasm lpcc found ... packaging without a bundled compiler
说明本包需要配置外部 lpcc,语言编辑功能仍可使用。
七、日常使用
| 操作 | 快捷键或入口 |
|---|---|
| 手动格式化文档 | Shift+Alt+F |
| 跳转定义 | F12 |
| 查找引用 | Shift+F12 |
| 搜索工作区符号 | Ctrl+T |
| 打开“问题”面板 | Ctrl+Shift+M |
| 打开命令面板 | Ctrl+Shift+P |
还可以在 LPC 编辑器中运行:
LPC: Open Compiler Explorer
Compiler Explorer 可以查看源码和 Token。配置可用的 lpcc 后,还能查看 AST、字节码和预处理结果。
保存时格式化由 editor.formatOnSave 控制;editor.formatOnType 不会为这个扩展启用输入时格式化。
八、验证安装是否成功
安装并配置后,可以依次检查:
- 打开
.c或.h文件,确认 VS Code 右下角的语言模式为 LPC。 - 按
Shift+Alt+F,确认格式化器能够运行。 - 保存文件,确认自动格式化已启用。
- 若已配置 lpcc,保存 LPC 源文件并查看“问题”面板。
- 运行 Compiler Explorer,检查需要的视图能否显示。
本文构建流程已在 Windows、Node.js 24、npm 12 环境中验证,语言引擎测试、扩展测试及 LSP 协议测试均通过,并成功生成 VSIX。示例 mudlib 的编译器路径和配置文件已核对;真实 mudlib 的保存编译流程尚未完成实机验证。