篇一 · 入门与核心机制
0.〔篇一〕这是什么项目
- 类型：LPMUD（文字 MUD 游戏），武侠题材，源自「侠客行 / 东方故事2（ES2）」体系。
- 驱动：FluffOS（根目录
driver.exe= 驱动，lpcc.exe= LPC 编译器，startlib.bat= 启动脚本，config.ini= 运行配置）。 - 框架：泥芯 MudCore v1.5（
mudcore/目录）。这是底层框架，不要直接改，要用「继承 + 覆盖」扩展。 - 语言：LPC（类 C 的 MUD 脚本语言），源码都是
.c/.h。
一句话：游戏逻辑写在无数个 .c 对象里，驱动负责编译运行；mudcore/ 提供框架，/feature /inherit /adm/daemons /cmds /include 是你的”系统代码”，其余大目录是”内容数据”。
2.〔篇一〕全局地图：include/globals.h 关键宏速查
globals.h 用宏把每个系统的路径都定义好了。改任何东西前先在这里定位入口：
- 对象：
USER_OB /clone/user/user、LOGIN_OB /clone/user/login、CHARACTER /inherit/char/char、NPC /inherit/char/npc、ITEM /inherit/item/item、ROOM /inherit/room/room、QUEST_OB /inherit/misc/quest、SKILL /inherit/skill/skill、FORCE /inherit/skill/force。 - 守护进程：
COMBAT_D /adm/daemons/combatd、SKILLS_D /adm/daemons/skillsd、QUEST_D /adm/daemons/questd、ITEM_D /adm/daemons/itemd、WEAPON_D /adm/daemons/weapond、EQUIPMENT_D /adm/daemons/equipmentd、MERIDIAN_D /adm/daemons/meridiand、BUFF_D /adm/daemons/buffd、LOGIN_D /adm/daemons/logind、CHAR_D /adm/daemons/chard。 - 功能片段：
F_ATTRIBUTE /feature/attribute.c、F_SKILL /feature/skill.c、F_KUNGFU /feature/kungfu.c、F_SAVE /feature/save.c、F_DBSAVE、F_DBASE（=feature/dbase.c）、F_ATTACK /feature/attack.c、F_DAMAGE /feature/damage.c、F_CONDITION /feature/condition.c、F_EQUIP /feature/equip.c、F_QUESTER /feature/quester.c。 - 路径构造：
SKILL_D(x) "/kungfu/skill/"+x、CLASS_D(x)、CONDITION_D(x)、BINGQI_D(x) "/clone/weapon/"+x、ARMOR_D(x)、DATA_DIR "/d/"、SAVE_EXTENSION ".o"。
3.〔篇一〕启动与热更新
- 启动：运行根目录
startlib.bat（它会拉起driver.exe读config.ini）。 - 编译：
.c由lpcc.exe在加载时编译；改完代码一般不用重启。 - 热更新（MUD 内指令，需 wizard 权限）：
update <对象路径>重新加载对象；call在线上执行函数；改globals.h/mudcore// 守护进程才需要重启驱动。 - 配置：
config.ini（驱动配置）、include/globals.h（游戏内路径/宏）、include/config.h/runtime_config.h（运行参数）。
4.〔篇一〕核心运行机制（必须懂，否则处处联系不上）
4.1 对象 + 继承
LPC 一切皆对象。玩家、房间、武器、NPC、技能都是对象。inherit X; 表示继承（复用）某基础类。例：user.c 里 inherit CHARACTER; inherit F_SAVE;，即玩家同时是”角色”且”可存档”。
4.2 dbase：属性怎么存
feature/dbase.c（F_DBASE）提供 query(prop) / set(prop, val) / add(prop, val) / delete(prop)，把数据存进对象内部的 dbase 映射。所有数值（如 query("str")、query("combat_exp")）都走它。路径属性用 / 分层：query("zjvip/times")。
临时数据用 query_temp/set_temp（不存档，重启即丢）。这是区分”持久属性”和”临时状态”的关键。
4.3 存档：save_object
feature/save.c 调 FluffOS 内置 save_object(file) 把对象序列化到磁盘；restore_object(file) 读回。存档路径由对象的 query_save_file() 决定：
- 玩家：
/d/user/X/角色名（二进制.o，见user.c）。 - 登录对象：
/d/login/X/账号（见login.c）。 - 用
nosave/protected关键字控制变量是否入档（globals.h里#define nosave static、#define protected static）。
⚠️ 兼容性：存档是二进制 .o。新增 dbase 字段对旧档安全（旧档缺省 0/undefined）；改名/删除已有字段会让旧存档读不到数据，必要时写迁移。
4.4 驱动内置函数（efun）与模拟函数（simul_efun）
efun：驱动提供，如this_object()、environment()、all_inventory()、save_object()、call_out()、time()。simul_efun：框架/游戏在adm/simul_efun/、mudcore/system/kernel/simul_efun/里扩展的”伪内置函数”，如ansi()、msg()、config()。遇到不认识的函数先怀疑是不是 simul_efun。
6.〔篇一〕读码方法论（怎么下手，见配套说明）
1. 先读 globals.h + 本手册，建立”哪个系统在哪”的地图。
2. 改某系统时：先用 index.ps1 def <函数名> 找定义，用 index.ps1 callers <函数名> 找所有调用点，避免漏改。
3. 遇到英文注释/不懂的函数：先查 index.ps1 grep + 本手册术语表；仍不懂再让我翻译具体文件。
4. 改完用测试角色验证，优先改 attribute.c 这类”改了立刻看得见”的地方入手。
5. 绝不改 mudcore/；要扩功能就继承后覆盖（参考 mudcore/README.md）。
7.〔篇一〕中英术语对照表（专治英文注释）
| 英文 | 中文 | 备注 |
|---|---|---|
| inherit | 继承 | inherit X; |
| clone / clonep() | 复制 / 是否复制体 | 玩家是 user 的 clone |
| dbase | 对象属性库 | query/set/add |
| efun | 驱动内置函数 | 驱动直接提供 |
| simul_efun | 模拟外部函数 | 框架/游戏扩展的”伪内置函数” |
| daemon | 守护进程 | 系统服务单例 |
| query / set | 读取 / 设置属性 | 走 dbase |
| apply | 装备附加属性 | 如 apply/str |
| temp (query_temp) | 临时属性 | 不存档 |
| heart_beat | 心跳 | 对象定时循环 |
| call_out | 延时调用 | 几秒后执行某函数 |
| room | 房间 | 场景对象 |
| living | 生物 | 有心跳的对象 |
| npc | 非玩家角色 | |
| player / user | 玩家 / 角色 | |
| skill_map | 技能映射 | 把招式绑定到某武功 |
| combat_exp | 实战经验 | 杀怪获得 |
| potential | 潜能 | 用于练功 |
| neili / jingli | 内力 / 精力 | 内功消耗 |
| force | 内功 | 一类技能 |
| condition | 状态 | 多为负面（中毒/疾病） |
| buff | 增益 | 正面状态 |
| meridian | 经脉 | 修炼体系 |
| nosave / protected | 不存档 / 受保护 | 控制是否入档 |
| varargs | 可变参数 | 函数参数可选 |
| nomask | 禁止覆盖 | 防止被继承覆盖 |
| efUN / mapping / array | 映射 / 数组 | LPC 数据类型 |
8.〔篇一〕配套工具用法（../code-tools/index.ps1）
cd ../code-tools
# 首次构建索引（扫描 九州书剑录 全部 .c/.h，较慢，只跑一次）
powershell -ExecutionPolicy Bypass -File index.ps1 build "C:\Users\aym35\Desktop\新建文件夹\九州书剑录"
# 查某个函数定义在哪些文件
powershell -ExecutionPolicy Bypass -File index.ps1 def query_str
# 查某个函数被哪些文件调用（含定义文件，自行区分）
powershell -ExecutionPolicy Bypass -File index.ps1 callers query_str
# 查某个宏 / 继承关系
powershell -ExecutionPolicy Bypass -File index.ps1 macro SAVE_EXTENSION
powershell -ExecutionPolicy Bypass -File index.ps1 inherit F_SAVE
# 任意正则搜索（类似 grep）
powershell -ExecutionPolicy Bypass -File index.ps1 grep "save_object"