ONIModTutorial

Appearance

Mod 目录结构 ​

本页说明 DLL Mod 的最小发布结构，以及 mod.yaml 和 mod_info.yaml 的职责。

验证环境

本页的文件格式按 Mod API 2 和本机游戏 DLL（Build 740622）重新核对。

最小目录结构 ​

通常一个 Mod 目录包含以下文件：

text
MyFirstMod/
├── MyFirstMod.dll
├── mod.yaml
├── mod_info.yaml
└── preview.png

mod.yaml 提供 Mod 的标准描述信息；mod_info.yaml 提供加载、版本和兼容性信息。资源目录（例如 anim/、assets/、translations/）按 Mod 功能添加。

mod.yaml 是推荐的标准描述文件，不应简单表述为所有场景下的硬性必需文件；对 DLL Mod 来说，mod_info.yaml 才决定加载和兼容性判断。

两个 YAML 文件的职责 ​

文件用途
mod.yaml游戏内名称、描述和稳定的 staticID。
mod_info.yaml最低游戏 Build、Mod 版本、DLL API 版本、DLC 限制以及归档版本选择。

mod_info.yaml ​

DLL Mod 的现代最小格式如下：

yaml
minimumSupportedBuild: 740622
version: 1.0.0
APIVersion: 2

minimumSupportedBuild 应填写 Mod 实际验证过的游戏 Build。本教程示例使用本机验证的 740622；Klei 官方文档中的 652372 只是示例值，不是固定推荐值。

如果 Mod 没有 DLC 限制，就省略 DLC 字段。只有确实需要或禁止某个 DLC 时才添加列表：

yaml
requiredDlcIds:
  - EXPANSION1_ID

# forbiddenDlcIds:
#   - EXPANSION1_ID

示例中的 EXPANSION1_ID 只是演示写法。DLC ID 会随游戏版本增加，应以当前 DLL 的 DlcManager.RELEASED_VERSIONS 和限制辅助 API 为准；VANILLA_ID 与 ALL 不是新 DLC 列表格式中的值。

supportedContent 是旧版本格式。它仍可能出现在面向旧游戏分支的归档版本中，但新的根目录示例不应继续使用 supportedContent: ALL。

mod.yaml ​

yaml
title: "MyFirstMod"
description: "这是一个示例 Mod。"
staticID: "AuthorName.MyMod"

staticID 用于稳定识别 Mod，也会影响 Harmony ID。发布后不要随意修改它。

mod.yaml 不用于声明 version、requiredDlcId 或未经游戏加载器验证的 dependencies 字段。Mod 使用的外部库应按照该库自己的安装和加载要求配置。

常见资源目录 ​

  • translations/：.po 翻译文件。
  • anim/assets/：自定义动画资源。
  • assets/：其他图片或资源。
  • elements/：自定义元素配置。
  • worldgen/：世界生成配置。

更多发布和多版本归档规则见多版本兼容性与发布管理。