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 学习者,可以按下面的顺序使用这些工具:
-
用
lpcshell学习基础。
练习表达式、数组、mapping、循环和 efun,立即观察结果。 -
把练习整理成对象文件,用
lpcc检查。
学习函数声明、静态类型、继承和头文件组织。 -
用
driver验证完整运行行为。
测试对象生命周期、玩家命令、定时器和异步操作。 -
用
generate_keywords查询当前 efun 签名。
将 API 资料与实际练习结合。 -
进阶时使用
lpcc的阶段输出和symbol。
理解源码如何经过预处理、词法分析、语法分析并生成字节码。 -
涉及持久化数据时使用
o2json/json2o。
学习保存格式,并完成离线数据检查或迁移。
日常选择可以直接参考:
| 当前任务 | 优先使用 |
|---|---|
| 快速试验一段 LPC | lpcshell |
| 检查一个完整对象能否编译 | lpcc |
| 启动 MUD 或测试定时、交互行为 | driver |
| 查询当前可用 efun 的参数类型 | generate_keywords |
| 排查宏展开或语法结构 | lpcc -E / --tokens / --ast |
| 分析编译符号事件 | symbol |
| 查看、修改和迁移对象存档 | o2json + json2o |
对大多数学习和 mudlib 开发工作,先熟练掌握 lpcshell、lpcc 和 driver,就能覆盖从小段实验到完整运行验证的主要需求。