开发 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,进入扩展面板:

  1. 按 Ctrl+Shift+X。
  2. 点击扩展面板右上角的 …。
  3. 选择“从 VSIX 安装”。
  4. 选择构建生成的 .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。

file

建议把文件关联写在 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 时:

  1. 尝试使用工作区的 .lpc/config。
  2. 查找根目录或 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 不会为这个扩展启用输入时格式化。

八、验证安装是否成功

安装并配置后,可以依次检查:

  1. 打开 .c 或 .h 文件,确认 VS Code 右下角的语言模式为 LPC。
  2. 按 Shift+Alt+F,确认格式化器能够运行。
  3. 保存文件,确认自动格式化已启用。
  4. 若已配置 lpcc,保存 LPC 源文件并查看“问题”面板。
  5. 运行 Compiler Explorer,检查需要的视图能否显示。

本文构建流程已在 Windows、Node.js 24、npm 12 环境中验证,语言引擎测试、扩展测试及 LSP 协议测试均通过,并成功生成 VSIX。示例 mudlib 的编译器路径和配置文件已核对;真实 mudlib 的保存编译流程尚未完成实机验证。