FluffOS 的工具覆盖了从学习 LPC、检查源码、运行 MUD,到分析符号和维护存档的完整流程。对普通用户、mudlib 开发者和学习者,最值得掌握的是以下七个程序:

程序 主要功能 适用人群
driver.exe 运行完整 mudlib 和 MUD 服务 服务器管理者、mudlib 开发者
lpcshell.exe 交互执行 LPC 表达式、语句和脚本 LPC 学习者、开发者
lpcc.exe 编译检查 LPC,输出预处理、语法树或字节码信息 mudlib 开发者、编译器学习者
generate_keywords.exe 导出当前构建的 efun 签名资料 学习者、编辑器和文档工具开发者
symbol.exe 导出编译过程中的符号事件 编辑器工具开发者、进阶学习者
o2json.exe 将 LPC 对象存档转换为 JSON 数据维护人员、mudlib 开发者
json2o.exe 将规定格式的 JSON 转换为 LPC 对象存档 数据维护人员、mudlib 开发者

本文依据当前项目源码整理。命令以 Windows PowerShell 为例;本地已有 EXE 如果来自旧版本,可能尚不支持文中部分新增参数。

1. 使用前的准备

driver、lpcshell、lpcc 和 symbol 都需要有效的 FluffOS 配置文件,以及对应的 mudlib 环境。配置文件负责指定 mudlib 根目录、master、simul_efun、头文件路径和运行限制等。

generate_keywords、o2json 和 json2o 不需要 mudlib 配置文件。

下面假设:

  • EXE 所在目录已作为当前目录。
  • config.cfg 是能够加载你的 mudlib 的配置文件。
  • /study/demo.lpc 是 mudlib 中的示例对象。
  • player.o、player.json 是磁盘上的数据文件。

PowerShell 中执行当前目录里的程序,需要使用 .\:

.\driver.exe config.cfg

程序不在当前目录时,可以使用绝对路径:

& "C:\Users\oiuv\home\mud\fluffos\build\bin\driver.exe" "C:\mud\config.cfg"

要区分两种路径:

  • 宿主机文件路径:例如 C:\mud\config.cfg。
  • mudlib 内部路径:例如 /study/demo.lpc,由驱动根据 mudlib 根目录解析。

对于字符串、JSON 和脚本文件,建议统一使用 UTF-8。

2. driver.exe:运行完整 LPC 环境与 MUD 服务

driver.exe 是 FluffOS 的核心运行程序。它初始化 VM,加载 master 和 simul_efun,执行 mudlib 启动逻辑,建立网络监听,并持续运行事件循环。

日常游戏命令、对象交互、call_out、heartbeat 和异步回调等行为,都需要在这样的完整运行环境中验证。

启动服务器:

.\driver.exe config.cfg

监听协议与端口由配置文件控制,例如:

external_port_1 : telnet 4000
external_port_2 : websocket 8080

实际配置应与 mudlib 和客户端需求一致。驱动完成初始化后,使用对应客户端连接所配置的端口。端口配置说明见 config.md:202。

它最适合以下场景:

  • 启动并运营 MUD。
  • 调试登录、玩家命令、战斗和对象交互。
  • 验证对象初始化、销毁和定时逻辑。
  • 检查网络通信和异步功能。
  • 运行项目的 LPC 测试套件。

当前源码还提供几个实用参数。

生成起始配置模板:

.\driver.exe --generate-config |
    Set-Content -Encoding utf8 config.example.cfg

它输出配置模板后直接退出。模板仍需根据自己的 mudlib 修改;生成配置不等于生成一个可运行的游戏项目。

启用默认调试日志:

.\driver.exe config.cfg -d

记录运行跟踪信息:

.\driver.exe config.cfg --tracing trace.json

跟踪输出可用于分析启动和运行过程中的耗时。

向 master 传递启动标记:

.\driver.exe config.cfg -f自定义标记

-f 后面的文本会传给 mudlib 的 master::flag(),具体意义由 mudlib 决定。例如 FluffOS 自带 testsuite 使用:

# 从 FluffOS 的 testsuite 目录运行
..\build\src\driver.exe etc/config.test -ftest

-ftest 是测试 mudlib 实现的约定,其他 mudlib 需要自行实现对应行为。

源码依据:mainlib.cc:286、mainlib.cc:392。

3. lpcshell.exe:学习 LPC 与执行短脚本

lpcshell 提供交互式 LPC 控制台。它启动 mudlib 环境,然后读取输入,编译并执行表达式或语句。

启动:

.\lpcshell.exe config.cfg

可以逐条练习:

1 + 2
strlen("hello")
sizeof(({ 10, 20, 30 }))

也可以声明变量并继续操作:

mapping info = ([ "name" : "张三", "level" : 10 ]);
info["name"]
info["level"] += 1;
info

表达式通常自动显示结果;执行语句时,可以使用 write() 或 printf() 明确输出:

foreach (int n in ({ 1, 2, 3 })) {
    printf("数值:%d\n", n);
}

它很适合:

  • 学习运算符、字符串、数组、mapping。
  • 观察 efun 的参数和返回值。
  • 验证循环、条件分支和数据处理逻辑。
  • 重现小段运行时错误。
  • 调用 mudlib 中已有的对象函数。

例如:

object ob = load_object("/study/demo");
ob->query_status()

这里操作的是 lpcshell 自己进程中的 mudlib 对象,不会连接到另一个正在运行的 MUD 服务。

除了交互模式,它还能执行脚本文件:

.\lpcshell.exe config.cfg check.lpc

脚本示例:

string *names = ({ "张三", "李四", "王五" });
foreach (string name in names) {
    printf("你好,%s\n", name);
}

这类脚本适合数据检查、文本转换、小型回归检查或调用维护函数。复杂业务可以放在普通 LPC 对象中,再由脚本调用:

"/study/checker"->run_checks();

也能通过管道输入:

'sprintf("%O", ({ 1, 2, 3 }))' |
    .\lpcshell.exe config.cfg

脚本和管道模式不会显示 REPL 提示符。存在失败语句时,最终返回非零状态:

.\lpcshell.exe config.cfg check.lpc

if ($LASTEXITCODE -ne 0) {
    throw "LPC 检查失败"
}

使用时需要了解几个边界:

  • 每段输入会包装成临时对象进行编译。
  • 跨输入保存的变量在后续输入中重新声明为 mixed,因此不能完全体现正式文件的静态类型约束。
  • 当前实现只识别单变量声明;学习时尽量分别声明变量。
  • 跨输入状态保存依赖序列化,更适合数字、字符串、数组和 mapping 等数据。
  • 主循环没有像 driver 一样持续推进后台事件,不适合验证依赖定时器、heartbeat 或异步回调的完整流程。
  • 脚本失败不会自动回滚已经执行的操作。

mudlib 可使用 __LPCSHELL__ 宏识别 shell 环境,并跳过服务器专用的启动行为。

源码依据:main_lpcshell.cc:10、main_lpcshell.cc:483。

4. lpcc.exe:检查完整 LPC 文件并观察编译过程

lpcc 适合检查正式 LPC 文件,以及学习编译器如何处理源码。

基本命令:

.\lpcc.exe config.cfg /study/demo.lpc

它启动配置对应的 VM 环境,加载目标对象,成功后默认输出字节码反汇编信息。

它不会把 .lpc 编译成独立的 Windows EXE,也不会生成供玩家启动的程序。

最常见的用途是:

  • 检查函数声明、继承和类型错误。
  • 验证头文件、simul_efun 和对象依赖是否正确。
  • 分析宏、词法、语法树和字节码。
  • 批量检查 mudlib 文件。

当前源码支持的主要参数如下:

参数 输出内容 适合解决的问题
默认 字节码反汇编 代码能否编译,生成了哪些 VM 指令
-E 预处理后的源码 宏展开、头文件和条件编译问题
--tokens Token、位置和拼写 字符串、数字及运算符的词法识别问题
--ast 代码生成前的语法树 表达式优先级和语法结构问题
-O0 关闭树优化后的字节码 比较优化前后的指令
--json 机器可读的阶段数据 编辑器、分析脚本和可视化工具
--batch 多文件编译检查结果 大规模 mudlib 回归检查

示例:

.\lpcc.exe -E config.cfg study/demo.lpc
.\lpcc.exe --tokens config.cfg study/demo.lpc
.\lpcc.exe --ast config.cfg /study/demo.lpc
.\lpcc.exe -O0 config.cfg /study/demo.lpc
.\lpcc.exe --ast --json config.cfg /study/demo.lpc

-E 和 --tokens 直接打开文件,示例中的相对路径需要对应程序初始化后所在目录;普通编译模式使用 mudlib 对象路径。

批量检查:

.\lpcc.exe --batch config.cfg /study/a.lpc /study/b.lpc

也可以从文本文件读取每行一个路径:

Get-Content .\files.txt |
    .\lpcc.exe --batch config.cfg

批量模式只启动一次 VM,逐个打印 PASS 或 FAIL;任意文件失败,最终返回 1。--batch 不能与其他阶段输出参数组合。

另有两点需要注意:

  • --json 的有效载荷可能混在启动日志中,通过 fluffos_lpcc 字段识别,不能直接把整个 stdout 当成单个 JSON 文档。
  • 普通编译使用对象加载路径,启动和对象初始化可能执行 LPC。它适合检查代码,但并非完全没有执行行为的文本检查工具。

源码依据:main_lpcc.cc:31、main_lpcc.cc:114。

5. generate_keywords.exe:导出 efun API 资料

直接运行:

.\generate_keywords.exe

程序在当前目录生成:

keywords.json

文件包含当前构建中 efun 的以下信息:

字段 意义
name efun 名称
type 条目类型,当前为 efun
returns 返回类型
min_args 最少参数数量
max_args 最多参数数量;-1 表示可变参数
args_types 各参数位置允许的类型集合

它适合:

  • 查询当前构建提供的 efun。
  • 为学习资料生成函数列表。
  • 制作编辑器补全和参数提示。
  • 对比不同 package 配置下的 API 差异。
  • 为自动化文档提供结构化输入。

例如在 PowerShell 中查看 sizeof 的签名:

$efuns = Get-Content -Raw .\keywords.json | ConvertFrom-Json
$efuns | Where-Object { $_.name -eq "sizeof" } | Format-List

列出所有 efun 名称:

$efuns | Select-Object -ExpandProperty name

虽然名称叫 generate_keywords,当前实现主要导出 efun 签名;它不包含完整语言保留字表、mudlib 的 simul_efun 或普通对象函数。

输出反映的是该 EXE 编译时的能力,最好与所用 driver 来自同一构建。它不在标准 EXE 安装列表中,本地可从 build-msys2/src 找到。

源码依据:main_generate_keywords.cc:23。

6. symbol.exe:观察编译器的符号处理

用法:

.\symbol.exe config.cfg /study/demo.lpc

程序启用符号记录,启动 VM 并加载目标对象,在:

log/symbol/

写出符号事件文件。

记录形式为:

操作编号 文件名 行号 详细内容

事件包括 include、define、变量、函数,以及编译符号作用域相关的创建、弹出和释放。输出文件名会将源码路径中的 / 替换为 #。

它适合:

  • 研究函数和变量在编译时如何登记。
  • 为自制源码索引工具提供输入。
  • 调查符号作用域相关问题。
  • 配合 lpcc --tokens、lpcc --ast 学习编译器。

它输出的是需要进一步解析的事件记录,并不是可以直接使用的完整语言服务器或调用图。

符号记录在 VM 启动前开启,因此 master、simul_efun 等启动过程中编译的文件也可能产生输出。

源码依据:main_symbol.cc:14、symbol.cc:17。

7. o2json.exe 与 json2o.exe:离线维护对象存档

这两个程序负责 LPC 对象存档与 JSON 的转换。

这里的 .o 是对象保存的数据文件,不是 C/C++ 目标文件,也不是 LPC 编译字节码。

存档转 JSON:

.\o2json.exe -pretty player.o player.json

完整格式:

o2json [-pretty] [-ascii] <o_file> [json_file]
  • -pretty:格式化输出,使用两空格缩进。
  • -ascii:将非 ASCII 字符转为 JSON 转义形式。
  • 输入 -:读取 stdin。
  • 省略输出文件或指定 -:写到 stdout。

JSON 转存档:

.\json2o.exe player.json player.new.o

完整格式:

json2o <json_file> [o_file]

输入 - 表示 stdin;省略输出或指定 - 表示 stdout。

典型维护流程:

.\o2json.exe -pretty player.o player.json

# 检查或修改 player.json

.\json2o.exe player.json player.new.o

它们适合:

  • 查看玩家、物品或其他对象保存的数据。
  • 使用外部脚本统计和迁移存档。
  • 修复变量数据。
  • 生成测试存档。
  • 对比变更前后的保存内容。

JSON 使用保留 LPC 类型的专用结构:

{
  "program_name": "/obj/player",
  "variables": [
    {
      "name": "level",
      "value": {
        "type": "number",
        "value": 10
      }
    }
  ]
}

因此,普通业务 JSON 不能直接交给 json2o。

类型表示也有特点:

  • 数组元素递归携带类型。
  • mapping 使用键值条目数组,支持非字符串键。
  • buffer 使用 Base64 表示。
  • 运行时对象引用不会作为完整对象保存。

转换工具负责数据格式,不负责验证等级、装备、账户等业务规则。维护正式存档时,先生成新文件,再由项目流程验证和替换。

源码依据:main_o2json.cc:19、main_json2o.cc:19、ofile.cc:276。

8. 学习和开发时如何组合使用

对于 LPC 学习者,可以按下面的顺序使用这些工具:

  1. 用 lpcshell 学习基础。
    练习表达式、数组、mapping、循环和 efun,立即观察结果。

  2. 把练习整理成对象文件,用 lpcc 检查。
    学习函数声明、静态类型、继承和头文件组织。

  3. 用 driver 验证完整运行行为。
    测试对象生命周期、玩家命令、定时器和异步操作。

  4. 用 generate_keywords 查询当前 efun 签名。
    将 API 资料与实际练习结合。

  5. 进阶时使用 lpcc 的阶段输出和 symbol。
    理解源码如何经过预处理、词法分析、语法分析并生成字节码。

  6. 涉及持久化数据时使用 o2json/json2o。
    学习保存格式,并完成离线数据检查或迁移。

日常选择可以直接参考:

当前任务 优先使用
快速试验一段 LPC lpcshell
检查一个完整对象能否编译 lpcc
启动 MUD 或测试定时、交互行为 driver
查询当前可用 efun 的参数类型 generate_keywords
排查宏展开或语法结构 lpcc -E / --tokens / --ast
分析编译符号事件 symbol
查看、修改和迁移对象存档 o2json + json2o

对大多数学习和 mudlib 开发工作,先熟练掌握 lpcshell、lpcc 和 driver,就能覆盖从小段实验到完整运行验证的主要需求。