快速开始:第一个数据 ModGetting started: your first data mod
做一个只用 XML 的 Mod:新增一种食物“太空番茄”,带中英文名称和自定义图标。不需要编程,PC 和手机都能用。 Build an XML-only mod that adds a food item, “Space Tomato”, with Chinese/English text and a custom icon. No programming; works on PC and mobile.
完整示例在本站目录
examples/ExampleDataMod/,已在游戏中实测加载(结果见界面图解)。可以直接复制后改名。
The finished example lives in examples/ExampleDataMod/ next to this site and was verified in game (see the walkthrough). Copy and rename it to start.
1. 找到 mods 目录1. Find the mods folder
| 平台Platform | 位置Location |
|---|---|
| Windows | 游戏安装目录下的 mods/(与游戏 exe 同级;不存在时游戏启动会自动创建)mods/ in the install folder, next to the game exe (created on first launch) |
| Android | Android/data/<package>/files/mods/ |
| iOS | 应用沙盒 Documents/mods/App sandbox Documents/mods/ |
| Steam | 订阅的创意工坊物品会自动扫描,且与本地 Mod 同 packageId 时工坊优先。Subscribed Workshop items are scanned automatically and win over a local mod with the same packageId. |
来源:ModStatics.RootDirectory。
Source: ModStatics.RootDirectory.
2. 建立目录结构2. Create the folder layout
mods/
└─ ExampleDataMod/ ← 文件夹名随意← any folder name
├─ Manifest/
│ ├─ manifest.xml ← 必需← required
│ ├─ icon.png ← Mod 列表图标(可选)← list icon (optional)
│ └─ preview.jpg ← 详情预览图(可选)← preview image (optional)
└─ v_common/ ← 版本目录,见“清单与版本”← version folder, see “Manifest & versions”
└─ Resources/
├─ Def/def.xml ← 配置表数据← definition rows
└─ Textures/space_tomato.png
3. 写 manifest.xml3. Write manifest.xml
Manifest/manifest.xml
<?xml version="1.0" encoding="utf-8"?>
<ModXmlManifest>
<packageId>docs.example.data</packageId>
<name>Example Data Mod</name>
<author>FreeWorld Docs</author>
<icon>icon.png</icon>
<previewImage>preview.jpg</previewImage>
<desc>Adds one food item and its bilingual text with XML only.</desc>
<versions>
<ModMetaVersion>
<version>v_common</version>
</ModMetaVersion>
</versions>
</ModXmlManifest>
packageId 必须全局唯一,建议用反向域名风格。它会成为你新增数据的 ID 前缀,发布后不要再改,否则存档里引用的旧 ID 会失效。
packageId must be globally unique; a reverse-domain style is recommended. It becomes the ID prefix of every row you add, so never change it after release — saves reference the prefixed IDs.
4. 写 def.xml4. Write def.xml
v_common/Resources/Def/def.xml
<?xml version="1.0" encoding="utf-8"?>
<ModXmlDef>
<files />
<rows>
<ModDefRow Name="LanguageDef">
<Item Name="Key">id_docs_example_space_tomato_name</Item>
<Item Name="CN">太空番茄</Item>
<Item Name="EN">Space Tomato</Item>
</ModDefRow>
<ModDefRow Name="LanguageDef">
<Item Name="Key">id_docs_example_space_tomato_desc</Item>
<Item Name="CN">在低重力温室中培育的番茄,可直接食用。</Item>
<Item Name="EN">A tomato grown in a low-gravity greenhouse. Edible raw.</Item>
</ModDefRow>
<ModDefRow Name="T_FoodDef" DependID="3">
<Item Name="ID">space_tomato</Item>
<Item Name="Name">docs_example_space_tomato_name</Item>
<Item Name="Desc">docs_example_space_tomato_desc</Item>
<Item Name="RawIcon">space_tomato.png</Item>
<Item Name="Price">12.5</Item>
</ModDefRow>
</rows>
</ModXmlDef>
Name="T_FoodDef"是 C# 类名,不是表文件名。所有可用的类名见 配置表参考。Name="T_FoodDef"is the C# class name, not the table file name. All class names are in the table reference.DependID="3":先深拷贝原版 ID 为 3 的食物,再用下面的字段覆盖。没写的字段(味道、腐烂速度、营养等)都沿用模板。DependID="3"deep-copies the built-in food with ID 3, then overwrites the listed fields. Everything else (taste, spoilage, nutrition…) comes from the template.- 最终 ID 是
docs.example.data_space_tomato。The final ID isdocs.example.data_space_tomato. Name/Desc填的是文本 Key 去掉id_的部分;游戏显示时查id_+ 该值。详见文本与多语言。Name/Deschold the text key without itsid_prefix; the game looks upid_+ value. See Text & localisation.
5. 启用并重启5. Enable and restart
- 启动游戏,在封面点 模组管理。Launch the game and click Mod Management on the title screen.
- 在“未启用”列表点 +,Mod 移到“已启用”。Press + in the Disabled list to move the mod to Enabled.
- 点 保存并使用,确认后游戏重启。Click Save and Use; confirm and the game restarts.
界面各部分的说明见界面图解 → Mod 管理。Each part of the screen is explained in Walkthrough → Mod manager.
6. 确认生效6. Check that it worked
- 新行加入了食物表(
T_FoodDef),按 ID 查询、在地图上放置与选中都能正常显示,见实测截图。它是否会出现在商人货单、配方等列表,取决于那些表是否引用它的 ID——原版表不会自动引用新物品。The row joins the food table (T_FoodDef): lookups by ID, placing it on the map and selecting it all work — see the verified screenshot. Whether it appears in trader stock, recipes and similar lists depends on those tables referencing its ID; built-in tables never reference new items by themselves. - 没有出现时,先看日志里的
mod install success: <name>,再按排错页逐项检查。If it doesn't, look formod install success: <name>in the log, then follow the troubleshooting page.