数据 Mod(配置表)Data mods (definitions)

游戏中几乎所有内容——物品、建筑、角色技能、战舰、势力、文本——都来自配置表。数据 Mod 用 def.xml 往这些表里追加新行。 Almost everything in the game — items, buildings, skills, warships, factions, text — comes from definition tables. Data mods append new rows to them through def.xml.

配置表是什么What a definition table is

每张表对应一个 C# 类(如食物表 T_FoodDef),一行就是该类的一个实例,类的公共字段就是表的列。游戏启动时从 .fwr 二进制表文件读入所有原版行,再追加各 Mod 的行,最后统一初始化并按 ID 建立索引。 Each table is a C# class (e.g. the food table T_FoodDef); a row is an instance and the class's public fields are the columns. At startup the game reads all built-in rows from binary .fwr files, appends mod rows, then initialises everything and indexes it by ID.

当前版本共有 200+ 张表,全部列在 API 参考 → 配置表,可按类名、中文分类或字段名搜索。 This build has 200+ tables, all listed under API reference → Tables, searchable by class, category or field name.

def.xml 结构def.xml schema

位置:<version>/Resources/Def/def.xml。Location: <version>/Resources/Def/def.xml.

一行:ModDefRowA row: ModDefRow

部分Part规则Rule
Name配置类的 C# 类名。带命名空间的类要写完整名(参考页每张表都给出可直接复制的写法)。类名写错时该行被跳过并记录 class not found。The C# class name. Namespaced classes need the full name (each table in the reference shows the exact form). A wrong name skips the row and logs class not found.
DependID可选。填原版行的 ID(不带前缀),先深拷贝该行作为模板,再写入下方字段。-1 且表中没有 ID 为 -1 的行时,用表的第一行。找不到时该行被跳过并记录 class or dependID not found。Optional. A built-in row ID (unprefixed) to deep-copy as a template before the fields below are applied. -1, when no row has that ID, means the table's first row. If not found, the row is skipped with class or dependID not found.
不用 DependID 时Without DependID新行从类的默认值开始,所有未填写的字段都是代码里的默认值(参考页“默认值”列),其中 Type 默认为 -1,而原版行的 Type 来自表文件。建议写上 <Item Name="Type"> 为该表的 Type ID(参考页每张表都有),并补齐游戏逻辑需要的字段。更推荐用 DependID 以一行原版数据为模板。The row starts from class defaults — every unset field keeps the code default (the reference's “Default” column); Type defaults to -1, whereas built-in rows get it from the table file. Set <Item Name="Type"> to the table's Type ID (shown per table in the reference) and fill the fields game logic needs. Using DependID with a built-in template is preferred.
Item Name字段名,区分大小写,必须是公共字段。写错的字段名会被静默忽略,不报错,请对照参考页检查。Field name, case-sensitive, must be a public field. Unknown field names are silently ignored — check them against the reference.
Item 文本Item text字段值,按字段类型转换。只支持字符串、数字和布尔(参考页“XML”列为 ✓ 的字段);列表、枚举、对象类型不能从 XML 赋值。转换失败时记录错误,该字段保持模板或默认值,行仍会加入。The value, converted to the field's type. Only strings, numbers and booleans work (fields with ✓ in the reference's “XML” column); lists, enums and objects cannot be set from XML. A failed conversion is logged, the field keeps its template/default value, and the row is still added.
数值转换使用运行环境的区域设置。为避免小数点问题,小数统一写成 12.5 这种形式,并在不同语言的系统上测试。 Numbers are converted using the runtime culture. Write decimals as 12.5 and test on systems with different locales.

ID 前缀:只能新增,不能覆盖ID prefixing: add, never replace

每一行(包括来自 .fwr 文件的行)在加入表时都会经过 ImplDef<T>.addRow,ID 被改写为 <packageId>_<ID>,并记录所属 Mod。 Every row (including rows from .fwr files) goes through ImplDef<T>.addRow, which rewrites its ID to <packageId>_<ID> and records the owning mod.

  • 因此写和原版相同的 ID 也不会覆盖原版行,而是多出一行。So reusing a built-in ID does not replace it; you get an extra row.
  • 在其他行或其他 Mod 中引用你的新行时,要写带前缀的完整 ID。Reference your rows from elsewhere using the full prefixed ID.
  • 要修改原版行,用 Lua 或 DLL 程序 Mod,在“配置表就绪”时机直接改 ImplDef<T>.beans 里的对象,见加载流程。To change built-in rows, use a Lua or DLL program mod and edit objects in ImplDef<T>.beans at the “definitions ready” hook; see Load pipeline.

文本与多语言Text & localisation

界面上显示的名称、描述并不直接存在物品表里。物品表的 Name 存的是“原文”,显示时游戏查找语言表 LanguageDef 中 Key 为 id_ + 原文的那一行,再按当前语言取 CN / EN / CNTW。 Names and descriptions are not stored in item tables directly. An item's Name holds a source string; to display it the game looks up the LanguageDef row whose Key is id_ + that string, then picks CN / EN / CNTW by the current language.

T_FoodDef.Name = "docs_example_space_tomato_name"
            ↓  LanguageDef.getTextByID(Name)
LanguageDef.Key = "id_docs_example_space_tomato_name"  →  CN "太空番茄" / EN "Space Tomato"
  • 语言行的 Key 不会加包 ID 前缀。用自己的前缀命名 Key,避免与原版或其他 Mod 冲突。Language keys are not prefixed. Namespace your keys yourself to avoid clashing with the game or other mods.
  • Key 已存在时,先加载的行生效。原版文本先于所有 Mod 加载,所以 Mod 不能用 XML 修改原版文本。For duplicate keys the first loaded row wins. Built-in text loads before any mod, so a mod cannot change built-in text through XML.
  • 找不到 Key 时,界面直接显示原文(去掉 id_)。看到界面上出现 Key 本身,通常就是 id_ 前缀漏写了。For a missing key the UI shows the raw string (without id_). Seeing your key on screen usually means the id_ prefix is missing.
  • CNTW(繁体)为空时回退显示 CN。An empty CNTW (Traditional Chinese) falls back to CN.

图标Icons

给新增行设置 RawIcon(相对 <version>/Resources/Textures/ 的 PNG 文件名),游戏会在配置表加载后把所有 Mod 图标打包进一张图集(最大 2048×2048)。没有设置 RawIcon 的行沿用模板的原版图标。示例中 64×64 的 PNG 显示正常。 Set RawIcon on new rows (a PNG name relative to <version>/Resources/Textures/). After definitions load, all mod icons are packed into one atlas (up to 2048×2048). Rows without RawIcon keep the template's built-in icon. A 64×64 PNG worked well in the example.

附带整张 .fwr 表Shipping whole .fwr tables

<files> 中每个 <ModDefFwr Name="类名">文件名</ModDefFwr> 会读入 Resources/Def/ 下的 .fwr 文件,其中所有行同样加前缀后追加。.fwr 由官方表格导出工具生成,格式与列顺序必须与当前版本的类一致;工具不随游戏提供,大量新增内容时建议优先用 XML 行。 Each <ModDefFwr Name="ClassName">file</ModDefFwr> in <files> reads a .fwr file from Resources/Def/; its rows are prefixed and appended the same way. .fwr files come from the official table exporter and must match the current class layout; the tool is not shipped with the game, so prefer XML rows.

存档兼容Save compatibility

  • 存档按完整 ID 保存物品等引用。发布后不要改 packageId 或行 ID。Saves store full IDs. Don't change packageId or row IDs after release.
  • 玩家卸载 Mod 后再读含有其内容的存档,这些引用将找不到定义。游戏会在读档前提示缺少的 Mod,但不会自动清理或迁移这些引用。If a player removes your mod and loads a save containing its content, those references won't resolve. The game warns about missing mods before loading but does not clean up or migrate them.

示例:食物表字段Example: food table fields

下面是导出器生成的 T_FoodDef 字段表(与 API 参考相同),“首行示例值”来自原版第一行,可用于判断字段格式。The generated T_FoodDef field list (same as in the reference). “First row value” comes from the first built-in row and shows the expected format.