快速开始:第一个数据 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)
AndroidAndroid/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 is docs.example.data_space_tomato.
  • Name/Desc 填的是文本 Key 去掉 id_ 的部分;游戏显示时查 id_ + 该值。详见文本与多语言。Name/Desc hold the text key without its id_ prefix; the game looks up id_ + value. See Text & localisation.

5. 启用并重启5. Enable and restart

  1. 启动游戏,在封面点 模组管理。Launch the game and click Mod Management on the title screen.
  2. 在“未启用”列表点 +,Mod 移到“已启用”。Press + in the Disabled list to move the mod to Enabled.
  3. 点 保存并使用,确认后游戏重启。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 for mod install success: <name> in the log, then follow the troubleshooting page.

下一步Next