数据 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 inImplDef<T>.beansat 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 (withoutid_). Seeing your key on screen usually means theid_prefix is missing. CNTW(繁体)为空时回退显示CN。An emptyCNTW(Traditional Chinese) falls back toCN.
图标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 changepackageIdor 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.