九州书剑录 · 代码导航手册

目的：帮「接手源码的人」快速建立全局地图，把零散的文件/函数联系起来。适用对象：想从底层修改（数值/存档/技能/物品/任务/机制）的开发者。

左侧是目录树：点击跳转、滚动阅读时自动高亮你所在的篇/章节；右侧为全部内容，一次贴入即可，无需翻页、不触发加载动画。配套索引工具：../code-tools/index.ps1。

篇1 · 入门与核心机制

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.〔篇一〕中英术语对照表（专治英文注释）

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"

篇2 · 目录总览（全景）

1.〔篇二〕目录总览：哪些是系统、哪些是内容

根目录全部顶层文件夹/文件如下，按”能不能改、改了影响什么”分 5 类。加新内容去”内容层/资源层”建文件；改规则/机制去”系统层/框架层”；运维/文案去 adm/etc/、help/、news/、gift/。

1.1 框架层（⚠️不要直接改，用继承+覆盖扩展）

1.2 系统代码层（改规则/机制来这）

1.3 内容数据层（加新武功/物品/任务/房间来这，建文件即可）

1.4 运行期资源 / 数据（文本与配置，多数不用编译）

1.5 外部接口 / 顶层文件

记法：改”规则/公式/机制”→ feature/、inherit/、adm/daemons/、include/；加”新武功/新物品/新任务”→ 在 kungfu/、clone/、quest/ 里新建文件；运维/文案→ adm/etc/、help/、news/、gift/。

篇3 · 角色与成长体系

9.〔篇三〕角色创建与初始化全流程（必读，改数值的入口）

新手从”连上”到”进游戏”的关键链路：

1. 连接 → 驱动创建 LOGIN_OB（clone/user/login.c），logon() 委托 LOGIN_D->logon()。

2. 鉴权/建号 → adm/daemons/logind.c。新角色在 make_body() 里被赋予初始属性：

代码位置：adm/daemons/logind.c（行 276–281）

   user->set("str", 10);
   user->set("dex", 10);
   user->set("con", 10);
   user->set("int", 10);
   user->set("kar", 10);
   user->set("per", 10);

⚠️ 这就是”初始五维=10″的出生点。想改出生数值，改这里（或后续新手引导/门派入门再追加）。注意还有 kar（福缘）也是初始 10。

3. 角色对象诞生 → USER_OB（clone/user/user.c）被创建，调用 setup()：

代码位置：clone/user/user.c（行 230–246）

   void setup()
   {
       last_age_set = 0;
       update_age();        // 先定年龄（影响 per 等）
       ::setup();           // 调用父类(char.c)的 setup，完成技能/条件/装备等初始化
       set_temp("user_setup", 1);
       restore_autoload();
       ...
   }

4. 父类装配 → inherit/char/char.c（角色基类 CHARACTER）是”所有角色能力的装配中心”。它一次性继承了所有功能片段：

代码位置：inherit/char/char.c（行 17–34）

   inherit F_ACTION;      // 行动/出手
   inherit F_ALIAS;       // 别名
   inherit F_APPRENTICE;  // 师徒
   inherit F_ATTACK;      // 攻击/战斗启动
   inherit F_ATTRIBUTE;   // 五维属性
   inherit F_COMMAND;     // 指令解析
   inherit F_CONDITION;   // 状态(中毒/疾病等)
   inherit F_DAMAGE;      // 受伤结算
   inherit F_DBASE;       // 属性存储
   inherit F_EDIT;        // 在线编辑
   inherit F_FINANCE;     // 钱银
   inherit F_MESSAGE;     // 消息广播
   inherit F_MORE;        // 翻页显示
   inherit F_MOVE;        // 移动
   inherit F_NAME;        // 名字
   inherit F_SKILL;       // 技能数据
   inherit F_TEAM;        // 组队
   inherit F_SUIT;        // 套装

记法：要加一个”所有角色都该有的能力”，就在 char.c 里 inherit 一个新的 F_XXX 片段；改某类角色的差异，再在 boss.c/npc.c/user.c 等子类里覆盖。

修改建议：若想”改初始分配规则”（比如属性随机范围、按门派给不同初始值），优先改 logind.c::make_body() + 门派入门逻辑；若想”改属性成长公式”，改 feature/attribute.c（见第 10 节）。

10.〔篇三〕五维属性公式逐条拆解（feature/attribute.c）

属性 = query("xx") 基值 + 各项加成。基值来自：出生 10（logind.c）+ 天赋点 up_tianfu（见第 11 节）+ 门派/任务/转生等写入。各维加成来源如下：

关键结构：每个 query_xx() 末尾都遍历 12 个肉身部位 头/躯/臂/手/腿/脚/皮/心/肝/脾/肾/肺，累加 query("肉身_<部位>/属性")["str"等] —— 这是”肉身/部位锻造”系统的数值出口，改装备/肉身数值看这里。

改属性时影响面：在 attribute.c 改公式后，凡是调用 query_str() 等的地方（战斗伤害、负重 query_backpack_limit = 300 + query_str()/10、NPC 强度等）都会自动跟着变。改完用 index.ps1 callers query_str 核对调用点即可。

11.〔篇三〕等级 / 经验 / 天赋点（feature/level.c）

• 升级不改变战斗经验（只比较 combat_exp 与阈值），函数 improve_level(me)。
• 升级所需经验 level_max_exp(me) 分段递增（单位已随等级数量级放大）：

• 每升 10 级送 1 点 tianfu_point（天赋点）（level%10==0 时 add("tianfu_point",1)）。
• 天赋点用法 up_tianfu(me, arg)：arg 为 str/int/con/dex 时，add("xx",1)（直接加在基值上，永久），并消耗 1 点。
• 注意：天赋能加的只有 str/int/con/dex 四维，不含 per；per 主要靠年龄/容貌技能/肉身。

17.〔篇三〕修炼 · 境界 · 五行 · 肉身体系（修炼成长的另一条大线，含原第33节）

与 attribute.c 的 query_con() 强相关（内功 force ÷10 计入根骨）。相关文件：

• adm/daemons/meridiand.c meridian2d.c jingmaid.c（经脉/内功修炼、冲穴、运行）
• inherit/skill/force.c（内功基类 FORCE，含 exert 运功效果）
• feature/kungfu.c（exert/perform 公共函数，见第12.2）
• 内功实例在 kungfu/ 下（force 类）

修炼大境界：char.c 的 life_base 映射（寿元表）揭示了本游戏境界体系：苦海(22–37重)→命泉→神桥→彼岸→道宫(38–42)→四极(43–46)→化龙(47–50)→仙台(51–56)→准帝(57–65)→大帝(66)→红尘仙及以上(68+)。每突破一重对应不同”寿元”，境界名存 query("jingjie_1_name")，在 damage.c 里换算成减伤比例（灵启1% … 苍穹傲世51%，见第12.3第1步）。

五行：combatd.c 定义 skill_shuxing = ({"金","木","水","火","土"})，配合 include/combat/wuxing.h 做”五行相生相克”判定（法术/修仙功法伤害加成）。

肉身12部位：全局常量 roshen_buwei = ({"头","躯","臂","手","腿","脚","皮","心","肝","脾","肾","肺"})，是 attribute.c(属性加成) 与 damage.c(减伤) 共同使用的”肉身锻造”维度（见第10节”遍历12肉身部位”）。

改成长/境界/五行/肉身曲线：联动 meridiand.c(冲穴)、attribute.c(con/境界减伤/肉身累加)、char.c(life_base)、kungfu/ 内功文件、include/combat/wuxing.h(五行)。

28.〔篇三〕门派 / 家族系统（familyd）

• 守护进程 familyd.c(FAMILY_D) 管门派关系、技能授予、叛门、贡献等。
• 门派专属 NPC 在 inherit/char/family_npc.c 及 d/<门派>/ 目录下（如 d/shaolin/ 的罗汉/僧侣）。
• 门派与武功绑定：很多武功的 valid_learn 直接查 me->query("family/family_name")，例如 bagua-bu.c 限制只有”雁荡派”能学。改门派收徒规则/可学武功看 familyd.c + 对应 family_npc + 各武功 valid_learn。
• 玩家门派数据存 query("family/family_name")、query("family/skill") 等（dbase 路径式）。

29.〔篇三〕经济 / 货币系统（moneyd + money clone）

• 守护进程 moneyd.c(MONEY_D) 管货币换算/发放。
• 货币是对象：/clone/money/<type>（铜钱/银两/金子等），NPC 用 add_money(type, amount) 造钱（npc.c 见第25节）。
• 玩家钱袋子走 dbase（如 query("money/<type>") 或专门字段），交易/商店逻辑在 feature/finance.c(F_FINANCE) + dealer.c/dealers.c/banker.c（商人/钱庄）。
• 修改经济（掉率/物价/兑换比）：先看 moneyd.c 与各 dealer；调某 NPC 卖什么改其 carry_object/商品列表。

篇4 · 战斗与 PK 体系

12.〔篇四〕战斗系统深度（底层逻辑核心）

战斗相关文件：feature/attack.c(F_ATTACK)、feature/damage.c(F_DAMAGE)、feature/kungfu.c(F_KUNGFU)、adm/daemons/combatd.c(COMBAT_D)、inherit/char/fighter.c、include/combat.h。

12.1 战斗启动（attack.c）

• fight_ob(ob)：把 ob 加入 enemy 数组、开启心跳 set_heart_beat(1)；受房间 no_fight、是否 living 等限制；守卫还会 kill_enemy 呼叫支援。
• kill_ob(ob)：进入”仇杀”状态，写入 killer 名单；有保护人/主人/体验NPC等豁免。
• is_fighting(ob)：判断是否交战；注意队伍联合作战（is_comb_ob/fight_team）——多人合击时 enemy 取自队伍。
• 常量 #define MAX_OPPONENT 4：同一目标最多同时被 4 个敌人锁定。

12.2 命中率（kungfu.c::hit_rate）

• 等级制：rate_level 0–18 共 19 级，S级(95%)→F-级(5%)，对应系数表 rate_coef。
• 身法影响：idata1 = idata1*(owner->query("dex")+150)/180（身法越高越容易命中）。
• 攻方可经 query_enhance("HitRate") 上调最多 3 级；守方可经 query_proof("AntiHitRate") 下调最多 5 级（即 apply/kf_hit_rate、apply/kf_anti_hr 这两个常见属性的底层）。
• hit_rate_sk 是简化版（用于 skill 判定，查 dex_tz 表），降低计算量。
• 判定：random(idata1) > random(idata2)*100/rate_coef[rate_level] 则返回命中(1)。

12.3 伤害结算（damage.c::receive_damage）

入参 type 只能是 "jing"(精) 或 "qi"(气)，who 为攻击者。结算链路（按顺序）：

1. 境界减伤：读 query("jingjie_1_name")（灵启/神游/逍遥/…/苍穹傲世），分别对应减伤 n%（灵启1% … 苍穹傲世51%），damage = damage*(100-n)/100。

2. 肉身部位减伤：遍历 12 部位累加 roushen_jianshang，总和 roushen 封顶 60%，damage*(100-roushen)/100。

3. 气血转内力：30% 概率按 apply/qi_abs_neili 比例把受损气血转成内力。

4. 宠物”掩青”：pet/掩青 在冷却(120s)外自动回血。

5. 装备减伤：apply/jian_damage + zhujis/jian_damage，30% 触发，封顶 90%。

6. 快活林”春去来”：1 小时内 20% 概率回满半血半精。

7. 天赋守护：talent/fa_gong 按 talent/shouhu 减伤。

8. 先天之炁抵消：query("xiantian") 直接抵消伤害（可完全免伤）。

• 常量：PVP_DAMAGE_SCALE=70、PVP_WOUND_SCALE=60（玩家互伤的缩放系数，在 combatd 调用时传入）。
• 受伤过重(>150) 触发 improve_craze（狂暴）。

改伤害/命中：优先改 damage.c 各减伤系数与封顶、kungfu.c 的 rate_coef/rate_level 逻辑；改 PVP 烈度调 PVP_DAMAGE_SCALE/PVP_WOUND_SCALE。注意这些都是数值，改完用测试角色对打验证。

12.4 PK 系统（pkd / pksd / combatd）

• 守护进程 pkd.c(PK_D)、pksd.c(PKS_D) 记录杀戮/仇杀数据。
• combatd.c 头部定义 PK 统计字段（玩家数据在 /combat/ 下）：PKS(杀玩家数)、MKS(打没NPC数)、WPk(主动打没玩家次数)、DPS(打晕玩家次数)、dietimes(死亡次数) 等，并区分正派/邪派(shen)统计。
• 每日 PK 上限：#define DEFAULT_MAX_PK_PERDAY 3、DEFAULT_MAX_PK_PERMAN 1，由 CONFIG_D->query_int("max pk perday/perman") 读取（可在运行配置里调）。
• 正邪 shen 值：角色有 shen(神/正邪值)，正派 shen>500、邪派 shen<-500，影响 PK 统计与门派态度。
• 改 PK 烈度/惩罚：调 combatd 的 PK 常量、pkd/pksd 的惩罚逻辑、globals.h 的 PVP_DAMAGE_SCALE/PVP_WOUND_SCALE（见 12.3）。

12.5 状态 / BUFF（负面状态与增益）

• 框架：feature/condition.c(F_CONDITION) 管理中毒/疾病等负面状态；buffd(/adm/daemons/buffd.c) 管理增益 BUFF。
• 状态对象：具体的状态/BUFF 定义放在 /kungfu/condition/ 下（每个状态一个对象，描述持续效果、到期、解除条件）。
• 与战斗联动：伤害结算（damage.c）会触发/受状态影响；命中（kungfu.c）也可能被状态修正。新增/调整状态：在 /kungfu/condition/ 建对象 + 改 condition.c/buffd。

篇5 · 内容创作（造东西）

18.〔篇五〕物品 / 装备体系细节

• 基类：inherit/item/item.c(ITEM) 为总类；inherit/weapon/(51) 与 inherit/armor/(19) 为武器/防具细分。
• 实例：clone/weapon/(276)、clone/armor/(106)、clone/misc/、clone/box/（宝箱/礼包）。
• 生成随机属性：equipmentd.c/equipmentd1.c（装备）、equifabaod.c（法宝）、itemd.c（普通物品掉落）。
• 穿戴：feature/equip.c(F_EQUIP) 处理穿/脱；装备加成通过 apply（即 attribute.c 里的 query_temp("apply/str") 等）流入五维。
• 物品属性存储：同样用 query("xxx")/set("xxx",...)，随 save_object 入档。典型字段：equipped(是否装备)、apply/str、apply/dex、耐久 max_endure/endure、价值 value。
• 新增物品：在 clone/weapon|armor|misc/ 建 .c 继承对应 WEAPON/ARMOR/ITEM 基类，设 name/unit/weight/value/apply/*。

19.〔篇五〕任务体系细节

• 基类：QUEST_OB = inherit/misc/quest。状态机常量在 include/quest.h：QUEST_CREATE/created、QUEST_READY/ready、QUEST_FINISH/finish。
• 任务对象需实现：name()、can_know_by(who)（谁能接）、change_status(status)（状态流转）、奖励发放等。
• 玩家侧接口：feature/quester.c(F_QUESTER) 提供接/交任务、查询可接任务。
• 任务守护进程：QUEST_D = adm/daemons/questd.c，外加 adm/daemons/task/（25个系统任务脚本）、newbiequest/（新手任务）。
• 任务实例：/quest/（176+，按剧情分目录如 quest/tulong/、quest/quest_jun/、quest/job/）。
• 新增任务：建对象继承 QUEST_OB，实现状态机，放回 /quest/ 下，questd 会自动管理。

24.〔篇五〕房间与世界系统（ROOM + d/ 目录）

世界就是成千上万个 ROOM 对象，每个文件是一个场景。

• 基类：ROOM /inherit/room/room.c，另有 17 个细分（室外/室内/城市/商店/战斗房/迷宫房等）。
• 房间文件结构（以 d/baiyun/xiaolu1.c 为例）：

代码位置：d/baiyun/xiaolu1.c（行 7–19）

  void create()
  {
      set("short","小路");                       // 房间短名(进房显示)
      set("long","这里是小路，...");             // 详细描述
      set("exits", ([                         // 出口：方向->相邻房间路径
          "north" : __DIR__"xiaolu2",
          "south" : __DIR__"chengwai1",
      ]));
      set("fuben2", 1);
      set("objects", ([ ]));                    // 房内刷新的NPC/物品(空)
      setup();
  }

• exits：方向(north/south/east/west/up/down/enter 等) → 目标房间路径，__DIR__ 指当前文件所在目录。
• objects：房内常驻对象（NPC/物品）定义，格式 ([ 路径 : 数量 ])。
• 其它常见字段：no_fight(禁止战斗)、no_clean_up(不回收)、outdoors(室外)、coor/x|y|z(坐标，地图用)。
• 移动机制：feature/move.c(F_MOVE) 处理 move(ob) / 玩家 go 指令，校验 exits 并搬运对象到目标房。
• d/ 世界地图（按门派/城市分目录，改世界、加房间看这里）：
• 门派/武林势力：shaolin(少林)、wudang(武当)、emei(峨眉)、huashan(华山)、songshan(嵩山)、quanzhen(全真)、mingjiao(明教)、gumu(古墓)、lingjiu(灵鹫)、tangmen(唐门)、wudu(五毒)、xingxiu(星宿)、heimuya(黑木崖)、taohua(桃花)、xiaoyao(逍遥)、shenlong(神龙)、kunlun(昆仑)、taishan(泰山)、hengshan(恒山)、henshan(衡山)、qingcheng(青城)、tiezhang(铁掌)、jueqing(绝情)、yihua(移花)、xueshan(雪山)、xuedao(血刀)、baiyun(白云城)、huanggon、lingxiao、wanjiegu、xuantian、yashan、motianya、xuanminggu、wanmei、wanmeishanzhuan 等。
• 城市/地图：beijing(北京,463)、changan(长安)、dali(大理)、hangzhou(杭州)、suzhou(苏州)、xiangyang(襄阳)、fuzhou(福州)、quanzhou(泉州)、guanwai(关外)、hainan(海南)、loulan(楼兰)、yingtian(应天) 等。
• 特殊区域：pk/(PK场)、death/(地府)、dujie/(渡劫)、maze/(迷宫)、migong/(迷宫,1853个房间)、newbie/(新手村)、wizard/(巫师区)、zhutian/(诸天,1.2万房间，最大)、obj/(世界物品)、item/(世界物品)、npc/(世界NPC)、register/(注册相关)、fuben*/(各类副本)。
• 房间也是存档：玩家档在 /d/user/，但房间本身 .c 是代码不是存档（除 /d/login、/d/user 是数据）。**不要手改 /d/user/*.o 二进制档**。

25.〔篇五〕NPC 系统（inherit/char/npc.c）

npc.c 继承 CHARACTER + F_CLEAN_UP，是所有 NPC 的通用基类。关键能力：

• NPC 放置：由房间的 set("objects", ([ 路径:数量 ])) 在房间 setup() 时刷新，或脚本动态 new()+move()。
• NPC 强度来源：同样走 attribute.c 的 query_str() 等（NPC 也继承 CHARACTER），其属性在 NPC 对象 create() 里 set("str",...) 等写入；装备经 apply/* 加成。
• 特化 NPC：inherit/char/ 下 boss.c(BOSS)、guarder.c(守卫)、family_npc.c(门派NPC)、smith.c(铁匠)、waiter.c(店小二)、trainee.c(学徒)、quarry.c(打手)、punisher.c(执法)、snake.c/worm.c/insect.c(动物/虫) 等，按需继承覆写。
• NPC 的”态度/性格”：attitude(heroism/aggressive/peaceful…)、character(心狠手辣/国士无双…)、can_speak(能否对话) 等字段驱动 AI，改 NPC 行为看这些字段 + accept_fight/scan/chat。

26.〔篇五〕单个武功文件结构模板（kungfu/skill/xxx.c）

每个武功是独立对象，继承 SKILL。典型 API（从 abc-unarmed.c、aikido.c、badao.c、bagua-*.c 等归纳）：

• 命名约定：文件名即技能 ID（如 cuff.c=拳脚，badao-daofa.c=霸刀刀法）。skill.c::set_skill 会按 SKILL_D(skill) 找 /kungfu/skill/<skill>.c。
• 战斗联动：武功的 valid_enable("blade") 决定它强化”刀”类攻击；实际伤害/命中在 feature/kungfu.c + attack.c + damage.c 统一结算（见第12节）。
• 新增武功：在 /kungfu/skill/ 建 .c 继承 SKILL，实现 valid_learn 等，驱动自动加载；需要配套的 map_skill/prepare 由玩家在游戏内绑定。

27.〔篇五〕颜色与消息系统（ansi.h + 消息函数）

27.1 颜色码（include/ansi.h）

常用前景色：RED(红) GRN(绿) YEL(黄) BLU(蓝) MAG(紫) CYN(青) WHT(白)；高亮版 HIR HIG HIY HIB HIM HIC HIW。背景色 BRED…BWHT。NOR = 清除所有特效（每段彩色文本结尾务必加 NOR，否则颜色串到后面）。还有 BOLD(加粗)、U(下划线)、BLINK(闪烁)、REV(反显)。256色用 FCC(x)(前景)/BCC(x)；RGB 用 RGB(r,g,b)/BRGB(...)。光标/清屏类：CLR(清屏)、HOME、ECL(清行) 等。

27.2 消息函数（常见于 simul_efun / message 系统）

• message_vision(fmt, ob)：向房间内所有人广播，$N=主语(ob)、$n=宾语、$w=武器等占位符自动替换。例：message_vision("$N对$n出手！\n", me, target)。
• tell_object(ob, msg)：只发给某个对象。
• tell_room(env, msg, exclude)：发给房间（可排除某些人）。
• command("look")：让对象执行指令。
• 文本拼接常量（combatd 里大量使用）：guard_msg(守卫监视)、catch_hunt_msg(仇杀)、winner_msg(胜利台词)、roshen_buwei(12肉身部位) 等。

写界面/提示文本时：颜色常量来自 ansi.h；$N/$n/$w 占位符靠 message_vision/tell_object 解析；多段文本记得每段后 NOR 收尾。

34.〔篇五〕常见”内容文件”骨架（新建时照抄）

新建武功 kungfu/skill/my-skill.c：

inherit SKILL;
int valid_enable(string usage) { return usage=="unarmed"; }
int valid_learn(object me) { return 1; }   // 或加学习条件
int skill_improved(object me) { ... }

新建武器 clone/weapon/my-blade.c：继承 /inherit/weapon/blade，设 name/unit/weight/value/apply/str 等。

新建防具 clone/armor/my-armor.c：继承 /inherit/armor/...，设 apply/con 等。

新建物品 clone/misc/my-item.c：继承 ITEM。

新建任务 quest/my-quest.c：继承 QUEST_OB，实现 name()/can_know_by()/change_status()。

新建NPC d/<area>/my-npc.c：继承 NPC，create() 里 set("name",...)、set("str",...)、carry_object(...)、set("attitude",...)。

新建房间 d/<area>/my-room.c：继承 ROOM，create() 里 set("short",...)、set("exits",([...]))、set("objects",([...]))、setup()。

篇6 · 系统代码层

13.〔篇六〕feature/ 功能片段全清单（F_ 系统代码）

注：文件名带 .1 / - 副本 的是备份/冲突副本，不要改（如 attack.c.1、suit - 副本.c、yaotiand - 副本.c）。改之前确认你打开的是正式文件。

14.〔篇六〕inherit/ 基类全清单（继承体系）

继承规律：user.c（玩家）继承 CHARACTER + F_SAVE；NPC 继承 NPC（再继承 CHARACTER）；具体武器/防具实例继承 WEAPON/ARMOR 细分基类；具体武功继承 SKILL/FORCE；具体任务继承 QUEST_OB；具体房间继承 ROOM 细分。

15.〔篇六〕adm/daemons/ 守护进程大全（系统服务）

守护进程是”全局单例服务”，一般通过 宏_D（如 COMBAT_D）在 globals.h 引用。改动某系统先看这里有没有对应 daemon。

子目录 task/（25个）是系统级任务脚本；quest/（根目录）是任务实例对象（176+）。两者都归 questd 管。

16.〔篇六〕cmds/ 指令体系

指令 = 玩家输入命令的实现。按权限/类别分目录：

指令如何生效：在 globals.h/commandd 注册；玩家输入 → F_COMMAND 解析 → 匹配 cmds/ 下对应 .c 的 main()/create() 里 set("verb","xxx")。新增指令：在对应目录建 .c 继承 CMD（或 COMMAND），set("verb","指令名") 并实现 main(string arg)。

22.〔篇六〕include/ 头文件详解（不止 globals.h）

include/ 下几十个 .h 是全局声明集中地。除已说的 globals.h 外，最常用、你必须认识的：

改代码时若报”函数/宏未声明”，先来 include/ 找对应 .h 并 #include 它。

23.〔篇六〕simul_efun：常用”伪内置函数”从哪来

LPC 里你到处会用到 message_vision()、tell_object()、tell_room()、ansi()、msg()、chinese()、to_chinese() 等”看起来像内置”的函数——它们不是驱动 efun，而是框架在 adm/simul_efun/ 下用 .c 扩展的”模拟外部函数”。该目录现有：

遇到不认识的函数，先用 index.ps1 def <函数名> 查；若定义在 adm/simul_efun/ 或 mudcore/ 下，就是 simul_efun。在 mudcore/system/kernel/simul_efun/ 也可能有底层定义（框架层）。

篇7 · adm 内核与管理区

36.〔篇七〕adm/ 顶层目录全解（管理与核心服务的总根）

adm/（administration，管理区）是整个 MUD 的”系统内核层”：主控对象、守护进程、模拟函数、配置数据、外部对接都在这里。它共 8 个子目录，除第 15 节（daemons）、第 23 节（simul_efun）已详解外，本节把其余全部补齐。

36.0 adm/ 子目录总览

36.1 adm/single/ —— 单例核心（最重要，改这里要极其谨慎）

single/ 存放全局唯一的核心对象，MUD 启动时由驱动 driver.exe 直接加载。共 3 个文件：

master.c 关键回调（改动前必读）：

⚠️ master.c 是全服唯一、驱动强依赖的对象。改错会导致整服无法启动。改前务必备份，改后先在测试库 startlib.bat 验证能正常起服。

36.2 adm/etc/ —— 配置与静态数据

纯数据/文本文件（多数无扩展名），由 CONFIG_D、master.c、各 daemon 读取。改这些不用编译，但多数要重启或让对应 daemon 重读才生效。

顶层配置/文本文件：

数据子目录：

改运营参数（人数上限、公告、封禁、SMTP、PK 上限）优先来 etc/；改数值逻辑仍回 feature//daemons/。config 里 max users、ask_recreate（存档损坏是否要求重建）等是常调项。

36.3 adm/go-cqhttp/ —— QQ 群 ↔ 游戏消息互通

基于 go-cqhttp（QQ 机器人框架）的对接，让游戏内消息与 QQ 群互发。用 FluffOS 的 socket_* efun 走 TCP。

• 消息流向：游戏频道消息 →（client.c）→ go-cqhttp →QQ 群；QQ 群消息 → go-cqhttp →（server.c）→ 游戏频道（配合 channeld）。
• 两者都在 etc/preload 里（开机常驻），见第 36.2。
• 改群号/服务器地址：改 client.c 的 ADDR/QQ/IP 宏；改转发格式看 read_callback 与 channeld 联动。

注意：这里硬编码了外部服务器 IP 与 QQ 号，属于部署相关配置，迁服/换机器人时必须同步修改。

36.4 adm/item/ —— 装备/物品生成模板

不是物品实例（实例在 clone/），而是装备生成器用的基类模板与字段定义头，被 equipmentd/equifabaod（第15节）等引用来批量生成随机装备。

clone/ 子目录：

shenqi/ 子目录：神器（顶级装备）专属模板/数据。

装备的随机属性池、品级、词条多来自这些 .h。想调”爆装属性范围/品质概率”，先看 equipmentd.c（逻辑）+ 这里的 .h（数据表）。

36.5 adm/npc/ —— 系统级功能 NPC

区别于 d/<门派>/ 下的场景 NPC，这里是跨区域、承担系统功能的特殊 NPC（继承 NPC），被各系统按需 new() 或放到功能房间。

顶层功能 NPC（挑重点）：

子目录：

想调”赞助档位/返利”改 wizard.c；”打造规则”改 ganjiang/luban；”婚姻”改 hongniang.c；”签文内容”改 qian/*.txt；”拍卖/彩票/捐献”改 obj/ 对应文件。注意所有 - 副本 文件是备份，勿动。

36.6 adm/socket/ —— 套接字（预留）

当前为空目录，用于放置 socket 通信相关脚本（与 go-cqhttp 的 TCP 对接、外部接口等配套）。若将来新增自定义网络服务（如 Web 接口、跨服通信），惯例放这里。

36.7 adm/ 速查：改 X 动哪（补充第 20 节）

至此 adm/ 八个子目录全部展开。搭配第 15 节（daemons）、第 23 节（simul_efun）即为 adm/ 完整地图。

篇8 · 附录速查

5.〔篇八〕子系统导航索引（改什么 / 去哪篇看）

本节只做”指路”；每个系统的原理与改法在对应篇的专节。所有”改 X 动哪”的终极速查见 第20节。

20.〔篇八〕「我想改 X，该动哪」速查表

32.〔篇八〕对象生命周期（create → setup → heart_beat → reset/clean_up）

理解对象何时被创建/初始化/回收，是改代码不出 bug 的关键：

改 create() 加字段时，旧存档可能没有该字段（缺省 0/undefined），要做好默认值兜底；改 heart_beat 注意性能（高频 tick 别写重逻辑）。

21.〔篇八〕调试与排错（接手期必备）

1. 编译报错：.c 由 lpcc.exe 编译。改完加载时若报语法错，看 MUD 内回显的行号定位。常见：中文全角符号、缺分号、inherit 路径错、函数未声明（加 .h 或 prototype）。

2. 热更新：改完系统代码后，MUD 内（巫师）用 update <对象路径> 重新加载；改守护进程（*d.c）或 globals.h 一般要重启 driver.exe（运行 startlib.bat）。

3. 在线执行：call <对象> <函数>(参数) 可在线上直接调函数验证；eval 求值表达式。

4. 查调用/定义：用配套 code-tools/index.ps1：

• def <函数> 找定义位置
• callers <函数> 找所有调用点（防漏改）
• grep "<正则> 任意搜
• inherit F_XXX / macro XXX 查继承与宏

5. 存档损坏排查：玩家档在 /d/user/X/角色名.o。若某字段读不到，多半是改了 dbase 字段名/结构导致旧档不兼容——用 backupd 的备份恢复，或写迁移把旧字段映射到新字段。

6. 不要碰：mudcore/（框架）、*.1/ - 副本/.zip 文件（备份/冲突副本）、/d/（世界房间+玩家存档，勿手改二进制）。

7. #pragma 指令：文件头常见 #pragma save_binary（存档用二进制）、#pragma optimize（优化编译）、#pragma strict_types（严格类型，易报类型错）。遇到奇怪编译问题先检查文件头 pragma。

维护提示：本手册随你对代码的理解逐步补全。每深入一个系统，就把”主改文件 + 关键函数 + 调用点”补进对应小节；配合 code-tools/index.ps1 的 def/callers 双查，可保证改动不漏、不改错。

31.〔篇八〕备份系统（backupd）

• 守护进程 backupd.c(BACKUP_D) 定期把玩家存档 /d/user/X/角色名.o 复制备份。
• 存档损坏/误删时，从备份恢复（具体备份目录在 backupd 内定义，通常有 /d/backup/ 或类似）。
• 改存档结构（加字段安全、改名/删字段需迁移）时，先确认 backupd 有近期备份再动手，出问题可回滚。

35.〔篇八〕游戏概念速查（读代码常遇到的字段/词）

维护提示（续）：本手册已覆盖”系统代码 + 内容模板 + 游戏概念”三层。后续每接手一个具体玩法（副本/活动/排行/聊天等），把对应 daemon 与 d//kungfu//quest/ 实例补成专节即可。所有”改 X 动哪”的索引仍以第20节速查表 + code-tools/index.ps1 的 def/callers 为准。