工程参考/配置文件/Public/CommonItem.txt
来自天龙知识库
CommonItem.txt 定义材料、消耗品和任务物品的模板。一行对应一种物品编号，例如 20101001 白英；背包里同种物品可以有多格，每件或每组物品另有自己的 GUID。本页解释怎样修改既有物品，不把复制一行等同于完成新增道具。
文件位置与生效
| 项目 | 说明 |
|---|---|
| 运行文件 | ../Public/Config/CommonItem.txt，相对于 Server 工作目录。源码 resources/Public/Config 是样本；玩家电脑还使用自己的同名资源。
|
| 读取程序 | Server 游戏进程；Game.exe 的同名客户端资源；GM 工具也可读取其选择的资源包 |
| 生效方法 | 正常保存并停服，更新 Server 使用的表，再重启 Server；客户端同步同一模板后重启 Game.exe。当前检索范围未发现可用的本表单独重载入口。部分字段写入物品数据，旧物品不保证自动采用新值；用重新生成的测试物品验证。 |
| 样本格式 | GB18030-compatible，CRLF。保留原编码；源码读取器不会自动把中文转为 UTF-8。
|
本表共 27 列。服务端读取其中 22 列；图标、说明文字、最大持有数量、类型描述和颜色主要由客户端使用。客户端 _DBC_ITEM_MEDIC 结构包含前 26 列，最后一列的服务端消费范围另见字段说明。
两端各改哪里
Server 读取 ../Public/Config/CommonItem.txt。玩家客户端查看 Client/Bin/FairyResources.cfg 的 [General]：FileSystem=*../Data/Config 对应 Client/Data/Config/CommonItem.txt；AxpFileSystem=../Data/Config.axp 则更新包内同名成员。按现有资源更新流程保存，退出并重启 Game.exe。只改服务端不会更新玩家名称、图标或客户端堆叠判断；修改 GM 工具打开的资源包也不等于更新服务器。
文件格式
首行是类型行：INT INT INT INT INT STRING STRING STRING INT INT INT INT INT INT INT INT INT INT INT INT STRING INT INT INT INT INT INT；第二行是列名行，程序跳过其内容；从第三行开始读取数据。各列用真实 Tab 分隔，保留首列、空列及行尾，不用空格代替。数据行行首 # 表示注释，分号不是此表的注释规则。首列为空的行被跳过；不足的尾列补为空值，多余列不参与本页字段读取。空整数和非数字经 atoi 可能成为 0，空字符串仍为空，不把解析成功当作业务合法。第一列须唯一，重复会触发读取器错误。
字段详解
列号从 1 开始，源码列下标从 0 开始。
| 字段与类型 | 含义与修改要点 | 缺项或特殊值 |
|---|---|---|
第 1 列INT：index，物品模板编号 |
服务端按本列二分查询，文件须按本列数值递增且唯一，加载器不会替你排序。允许编号间隔。它与第 2..5 列产生的组合编号是两个读取结果，历史样本存在不同值，不能批量按公式改写本列。 | 非空、正数；重复触发读取器错误。不是行号、背包位置、角色对象 ID 或物品 GUID。改旧编号会影响商店、掉落、脚本及持久库存引用。 |
第 2 列INT：class，大类 |
2 材料；3 普通消耗品；4 任务物品。参与模板编号拆分与创建分支。装备、宝石、藏宝图有各自表，不能只把这一列改成 1、5 或 6 来转换物品。 | 保留与编号一致的大类；0 不表示通用类型。使用入口还有大类检查，材料不会仅因设置脚本就变成普通可用道具。 |
第 3 列INT：quality，分类段 |
组合编号中的两位分类段。名称虽叫 quality，在本表不等同于装备颜色或星数。部分服务端入口另外从第一列拆分类，例如 class=3 时 5 为杂物类，更多用途须核对实际取值位置。 | 十进制组合结构使用 0..99。保留旧行；不要把它当颜色列修改，也不要因发现与第一列分解不同就自动修正。 |
第 4 列INT：type，子类型段 |
客户端保存的子类型及组合编号字段。某些服务端流程从第一列拆分子类型，再结合品质识别鉴定卷轴等。因此表内 type 与第一列拆出的 type 应分别核对。 | 十进制组合结构使用 0..99；完整业务枚举未全部实测。保留旧行的对应关系，新增类别须核对两端入口。 |
第 5 列INT：Medindex，组内末段 |
参与组合编号：((class*100+quality)*100+type)*1000+Medindex。白英样本 2、1、1、1 得到 20101001；但部分历史行与第一列不同，不能一概说它必定是第一列的末三位。客户端有接口取组合编号的末三位。 | 十进制末段通常使用 0..999；保留既有值。不是背包格或所有物品的连续行号。批量改成第一列末三位可能改变相关客户端查询。 |
第 6 列STRING：资源 |
客户端图标资源名，例如白英样本为 Herbal1_1。客户端 GetIconName 使用它；服务端加载器没有读取此列。 | 保留已存在的图标资源名。空值不会自动生成图标；不要把文件磁盘绝对路径或装备模型号写在这里。 |
第 7 列STRING：name$1$，名称 |
两端物品名称。服务端保存最多 49 字节并补结束符，按原编码计算字节数；中文不能按 49 个字理解。名称也用于门派任务物品候选和通知。 | 建议使用短名称，不包含 Tab、换行或百分号格式串。保留原编码，过长名称可能截断半个汉字；脚本引用一般应使用编号而非改名后的文字。 |
第 8 列STRING：说明文字$1$ |
客户端物品说明。改变文字不会改变实际回血、伤害、奖励或使用限制；这些要查关联脚本和技能。服务端加载器未读取此列。 | 空字符串显示内容减少，不代表禁用物品。保留已有可识别的文本格式，不插入真实 Tab 或换行拆列。 |
第 9 列INT：等级 |
创建物品时写入等级字段；常规使用入口检查玩家等级是否达到它，客户端 GetNeedLevel 也读此列。它与第 22 列的材料档次不同。 | 新物品内部等级为 BYTE，整数范围 0..255；超范围会截断。保留已核对的玩法等级，0 不是按角色自动适配。旧物品是否更新需分别验证。 |
第 10 列INT：基本价格 |
材料/普通物品的商店基础单价。金币显示按铜计：100 铜=1 银，10000 铜=1 金；最终购买价还受商店货币、倍率、PK 折扣、独立价格等影响。任务类的部分商店换算分支固定返回 1，不能一概按本列计价。 | 用非负、适度的整数；加载后保存在 UINT，负数会变成很大的无符号值。不是元宝兑换汇率，也不是出售收入。 |
第 11 列INT：出售价格 |
普通卖出分支以本列为单价乘当前格数量，再应用新服售出倍率并受基础价格乘数量的上限限制。材料未有额外售出类型覆盖时走交子结算。客户端基础提示未必反映所有服务端倍率。 | 普通卖出代码对非正单价先按 1 处理，因此填 0 不能可靠禁止出售；是否允许出售需查实际业务和 ItemRule。负值同样不能当作关闭开关。 |
第 12 列INT：适应规则 |
引用 ItemRule.txt 第一列的规则组。该组控制堆叠、交易、绑定、银行等已说明的检查入口；多个物品可共用同一个规则组。 | 必须引用完整、有序的已存在规则；规则号存入 CHAR，不随意使用大数。改模板的规则引用不等于取消物品已有绑定或密码锁。 |
第 13 列INT：叠放数量 |
一格的堆叠上限，不是获得数量，也不是角色持有总上限。需同时满足 ItemRule 的重叠标志；新物品创建时当前数量仍为 1。客户端也读取此值进行堆叠判断。 | 需要堆叠的普通物品保持 1..255，且不超过已验证业务上限。实际保存为 BYTE，256 会成为 0，300 会成为 44；不要填 9999。旧物品的持久字段可能仍保留旧上限。 |
第 14 列INT：脚本编号 |
常规使用入口取本列对应脚本，区分技能式脚本与默认事件。应对应 Server 实际加载的 Script.dat 映射及所需事件函数；不是 Lua 注册函数名，也不是 Lua 文件行号。 | -1 表示没有该脚本入口；0 和空字段不会自动选择默认脚本。鉴定等特殊道具可能走专门流程，不能只改此项就覆盖其全部行为。 |
第 15 列INT：技能编号 |
写入物品技能字段，客户端 GetItemSkillID 读取；须与当前物品使用流程、技能定义和脚本配合。不会单独生成回复量、冷却时间或伤害。 | 保留现有有效技能号或样本的 -1。常规请求先检查脚本入口，仅填此列不能保证点击就施放技能；具体道具需要实测。 |
第 16 列INT：是否消耗 |
服务端仅整数 1 置为真，其他值为假。在 Skill_DepleteItem 这类已核对的技能消耗路径中，为真时扣减一个使用物品。客户端此列为保留字段。 | 推荐 0/1；空值会变成 0。脚本自行删除、兑换或发奖不受这一标志统一控制，0 不能保证所有使用路径都不消耗。 |
第 17 列INT：需求技能 |
配方提示使用的生活技能编号，客户端配合下一列显示要求。服务端还用 11..19 的特定编号建立门派任务物品候选列表，不能全部按普通学习门槛理解。 | 保留与现有配方/脚本一致的编号；-1 是样本中可见的未指定值。当前未发现通用 GetReqSkill 调用对所有道具统一拦截，实际学习限制需核对配方及脚本。 |
第 18 列INT：需求技能等级 |
客户端配方提示的技能等级。服务端创建物品时保存为 BYTE；用于门派物品候选时，12 对应角色等级 60，其余按 5*本列+5 计算候选需求。 | 正等级须在相应玩法范围，存储范围 0..255；样本 -1 存入 BYTE 会成为 255，不能把它当成普通零级要求。仅调整本列不承诺修改所有配方学习条件。 |
第 19 列INT：最大持有数量 |
客户端任务物品（class=4）的手动和自动拾取前，会统计背包同编号数量并检查此列。Server 的当前 CommonItem 加载器未读取本列，不能把它当成全服唯一或防重复发放限制。 | 客户端 -1 跳过上限检查；0 会在数量>=0 时阻止相应任务拾取。其他负数不等同 -1。判断在拾取请求前，不证明各种批量发放都不会超过上限。 |
第 20 列INT：选择对象类型 |
客户端用于选目标，数值对照见下方目标类型表。对象目标传场景对象 ID，自己的出战珍兽另携带珍兽 GUID；这列填枚举值，不填具体角色 ID、GUID 或物品模板号。 | -1 无效，0 无需目标；字段内部为 BYTE，-1 变为 255。只选已核对的物品/技能流程；方向和物品目标的通用客户端路径未支持。 |
第 21 列STRING：类型描述$1$ |
客户端说明中的类型文字，例如“初级药材”。只改变显示，不改变第 2..5 列的分类，也不改变背包分栏或合成归类。服务端加载器未读取。 | 可保留原文字或已验证显示文本；空值没有自动根据类型补全的承诺。 |
第 22 列INT：档次等级 |
材料品级、部分鉴定卷轴和生活技能加工使用的整数档次。服务端 Lua 注册名 GetCommonItemGrade 返回此列，原料和普通物品可查；不是玩家等级或经验倍率。 | 用对应玩法的已存在档次。客户端某些卷轴检查用本列乘 10 得到装备等级界限；调整可能影响合成判断及结果，需按使用入口实测。 |
第 23 列INT：配方id |
客户端用于配方提示和已学配方查询；服务端 class=3 的掉落拾取回调也据其是否大于 0 区分配方类。引用配方编号，须核对对应 ItemCompound 表和脚本。 | 0 表示非配方；不是物品模板 ID 或脚本 ID。填正数不会自动建立配方、学习技能或创建掉落。 |
第 24 列INT：颜色 |
客户端按 SystemColour.txt 的编号查询名称颜色；是资源行 ID，不是 RGB 值、品质或装备星数。当前样本常用 2000。 | 保留已存在颜色编号。未找到颜色行时查询返回空字符串；服务端加载器未读取本列。 |
第 25 列INT：SubClass |
材料进一步分类，已核对的高级合成检查会与配方要求的特殊材料子类比较。它不参与第 1 列的编号组合，也不等于第 4 列 type。 | 服务端把小于 -1 的值归为 -1；-1 表示未指定子类的样本约定。其他编号的业务意义需与配方逐项核对，不能凭数值猜材料用途。 |
第 26 列INT：是否广播 |
服务端大于 0 置为真；掉落通知流程仍要求匹配的通知编号、通知表记录及实际调用。class=4 的广播查询直接返回假。不是任意方式得到物品都会自动全服公告。 | 0/负数关闭所读标志，建议 0/1。客户端结构有对应字段，但当前检索未发现独立消费该客户端值的业务。 |
第 27 列INT：是否元宝交易 |
服务端保存这一字段，但当前 GetItemYuanBaoTrade/GetIsYuanBaoTrade 查询的是 EquipExtraAttr 数据。当前检索未发现交易入口直接使用本表保存的 m_YuanBaoTrade；不能据表头承诺此列可切换元宝交易。 | 先转为 BYTE，再把大于 2 的值改为 1，空值为 0，不会保留构造初值 1。保留当前 0/1/2 原值；最终交易限制需看实际附加属性表和交易入口。 |
常用修改实例
示例为局部教学片段，先备份原运行文件，再修改对应行并保留其余配置。教学值不是程序默认值。 以下代码块保留真实 Tab；本地示例文件保留原样本编码、中文表头与 CRLF。网页文字使用浏览器编码显示，不表示运行文件应改存 UTF-8。
把白英单格堆叠上限从 40 调到 80
修改前：
INT INT INT INT INT STRING STRING STRING INT INT INT INT INT INT INT INT INT INT INT INT STRING INT INT INT INT INT INT index class quality type Medindex 资源 name$1$ 说明文字$1$ 等级 基本价格 出售价格 适应规则 叠放数量 脚本编号 技能编号 是否消耗 需求技能 需求技能等级 最大持有数量 选择对象类型 类型描述$1$ 档次等级 配方id 颜色 SubClass 是否广播 是否元宝交易 20101001 2 1 1 1 Herbal1_1 白英 茄科植物。味苦、辛、微寒，入肝、胆经。有清热，利湿，祛风，解毒，消肿的功效。可用于制药等。 1 375 10 4 40 -1 -1 1 8 1 -1 -1 初级药材 1 0 2000 -1 0 1
修改后：
INT INT INT INT INT STRING STRING STRING INT INT INT INT INT INT INT INT INT INT INT INT STRING INT INT INT INT INT INT index class quality type Medindex 资源 name$1$ 说明文字$1$ 等级 基本价格 出售价格 适应规则 叠放数量 脚本编号 技能编号 是否消耗 需求技能 需求技能等级 最大持有数量 选择对象类型 类型描述$1$ 档次等级 配方id 颜色 SubClass 是否广播 是否元宝交易 20101001 2 1 1 1 Herbal1_1 白英 茄科植物。味苦、辛、微寒，入肝、胆经。有清热，利湿，祛风，解毒，消肿的功效。可用于制药等。 1 375 10 4 80 -1 -1 1 8 1 -1 -1 初级药材 1 0 2000 -1 0 1
在原表第一列找到 20101001（白英），只把第 13 列的 40 改为 80。上面保留原样本中文、图标、价格和其余字段；整个文件的其他行也必须保留。第 12 列为规则 4，先确认 ItemRule 中规则 4 的第 3 列仍为 1。同步客户端的同一行；停服更新后，用新生成的白英分别检查 40+1、79+1 和满 80 后新增一个的正常合并或分格结果。不能把这三行局部示例覆盖整表，也不能通过修改角色库存数据直接把旧格改成 80。
验证与排查
先看 Server 日志 InitCommonItemInfoTable() Ok!，再核对第一列数值排序和示例只改第 13 列。当前样本有 4919 行，其中 366 行的组合编号与第一列不同，例如 30001011 的 3、0、1、5 组合为 30001005；这是保留的历史数据差异，不要求为了本教程批量修正。白英示例两种编号一致。日志成功不代表关联图标、规则、技能和脚本都正确。以新生成的测试物品验证数量、分格、重登后保留和客户端显示，再另测改前已有的物品。失败时正常停服，恢复两端表格备份并重启；恢复表格不会自动拆分已保存的较大物品堆，也不会恢复已消耗物品。
目标类型对照
| 数值 | 定义与限制 |
|---|---|
| -1 | 无效目标类型。 |
| 0 | 无需目标 |
| 1 | 场景位置 |
| 2 | 方向：当前通用客户端 IsValidTarget 返回不支持；专门界面流程另行核对。 |
| 3 | 物品：当前通用客户端 IsValidTarget 返回不支持；专门界面流程另行核对。 |
| 4 | 自己 |
| 5 | 自己的出战珍兽 |
| 6 | 友好角色 |
| 7 | 友好玩家 |
| 8 | 友好怪物 |
| 9 | 友好珍兽：当前客户端友好珍兽分支误比较友好怪物枚举，不能承诺此值正常生效，需要实测。 |
| 10 | 敌对角色 |
| 11 | 敌对玩家 |
| 12 | 敌对怪物 |
| 13 | 敌对珍兽 |
| 14 | 所有角色：当前客户端此分支仅返回通过，未在此分支回填目标对象 ID，具体调用链需要实测。 |
模板编号与背包格
20101001 是白英的模板编号，可以用它查表；背包位置只是当前格的索引；物品 GUID 区分实际生成的物品或物品组；selfId 是场景内角色对象 ID。它们即便都显示成数字也不能混用。以下是只查询配置档次的服务端 Lua 片段，已核对注册名与参数：
local itemTableIndex = 20101001
local grade = GetCommonItemGrade(itemTableIndex)
if grade == -1 then
return
end
参见 GetCommonItemGrade。已存在的原料/普通物品返回第 22 列；其他大类返回 -1。未知编号可能触发断言，不应用不存在的编号测试返回值。它不查询背包，不需要 sceneId 或 selfId。
新物品与旧物品
堆叠上限、等级、使用消耗等部分字段会复制到生成物品，并参与物品数据保存；当前恢复修正函数只刷新普通物品的规则、脚本和技能部分字段。因此改表、重启与重登不能代替对旧物品的单独核对。试改应在隔离环境使用新物品，同时保留旧样本作对照。
关联与依据
Public/ItemRule.txt · Public/SlotCost.txt · Server/ItemSerial.ini
其他配置及整理状态 · 服务端外网设置 · Lua 接口索引
Common/DataBase/TLBB_DBC.cpp：实际加载、解析、字段使用或示例关联依据Common/DataBase/TLBB_DBC.h：实际加载、解析、字段使用或示例关联依据Common/ServerBase/FileDef.h：实际加载、解析、字段使用或示例关联依据Common/GameStruct_Item.h：实际加载、解析、字段使用或示例关联依据Common/GameStruct.cpp：实际加载、解析、字段使用或示例关联依据Common/GameDefine_Item.h：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Item/ItemTable.cpp：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Item/ItemTable.h：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Item/ItemRuler.cpp：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Item/Item.cpp：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Item/Item.inl：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Item/ItemManager.cpp：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Other/ShopManager.cpp：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Packets/CGUseItemHandler.cpp：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Packets/CGShopBuyHandler.cpp：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Packets/CGShopSellHandler.cpp：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Packets/CGStallAddItemHandler.cpp：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Packets/CGPlayerShopOnSaleHandler.cpp：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Obj/Obj_Human_Skill.cpp：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Obj/Obj_ItemBox.cpp：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Ability/AbilityAdvancedCompound.cpp：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Ability/AbilityArtwork.cpp：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Ability/AbilityFoundry.cpp：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Ability/AbilityTailor.cpp：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Skills/ScriptLogic.cpp：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Script/LuaFnTbl_Ability.h：实际加载、解析、字段使用或示例关联依据Server/Server/GameServer/Server/Script/LuaFnRegister.cpp：实际加载、解析、字段使用或示例关联依据Client/Client/Game/DBC/GMDataBase.cpp：实际加载、解析、字段使用或示例关联依据Client/Client/Common/TDDBC_Struct.h：实际加载、解析、字段使用或示例关联依据Client/Client/Game/Object/Item/Obj_Item.cpp：实际加载、解析、字段使用或示例关联依据Client/Client/Game/Object/Item/Obj_Item_Medicine.cpp：实际加载、解析、字段使用或示例关联依据Client/Client/Game/DataPool/GMDataPool.cpp：实际加载、解析、字段使用或示例关联依据Client/Client/Game/Action/GMActionSystem_Item.cpp：实际加载、解析、字段使用或示例关联依据Client/Client/Game/Interface/GMInterface_Script_Tooltip.cpp：实际加载、解析、字段使用或示例关联依据Client/Client/Game/Interface/GMGameInterface_Script_LifeAbility.cpp：实际加载、解析、字段使用或示例关联依据Client/Client/CEGUIFalagardEx/FalMoney.cpp：实际加载、解析、字段使用或示例关联依据Client/Client/Render/ResourceProvider.cpp：实际加载、解析、字段使用或示例关联依据Client/Client/Render/RenderSystem.cpp：实际加载、解析、字段使用或示例关联依据Client/Client/Core/Core/FairySystem.cpp：实际加载、解析、字段使用或示例关联依据Server/Tools/TlbbGmTool/TlbbGmTool/Services/AxpService.cs：实际加载、解析、字段使用或示例关联依据resources/Client/Bin/FairyResources.cfg：实际加载、解析、字段使用或示例关联依据resources/Client/Bin/FairyResources正式服.cfg：实际加载、解析、字段使用或示例关联依据resources/Public/Config/ItemRule.txt：实际加载、解析、字段使用或示例关联依据
原始文本读取器、模板加载、二分查询、物品创建时的窄整数赋值及 Lua 档次查询使用独立夹具核对。中文示例保留样本字节编码与 Tab，逐值回读；未启动游戏、数据库或服务。实际堆叠、旧物品恢复、提示和玩法效果仍需要实测。
