ONIModTutorial

Appearance

Mod 打包与发布 ​

本章说明如何把编译结果、标准描述文件、兼容性元数据和资源整理成可测试、可发布的 Mod。

验证环境

本页内容已按 Build 740622 对应的本机 Managed DLL 和项目配置检查；尚未在游戏内完成运行验证。

最终目录结构 ​

一个包含 DLL 和资源的 Mod 通常如下：

text
MyMod/
├── MyMod.dll
├── mod.yaml
├── mod_info.yaml
├── anim/
├── elements/
├── translations/
└── assets/

mod.yaml 保存标准描述信息，mod_info.yaml 保存加载和版本兼容信息。具体资源目录按项目需要添加。

mod.yaml ​

yaml
title: "我的第一个 Mod"
description: "一个示例 Mod。"
staticID: "AuthorName.MyMod"

这三个字段分别用于名称、描述和稳定的 Mod ID。发布后不要修改 staticID，否则其他 Mod 或补丁识别它时可能把它视为另一个 Mod。

不要把 version、requiredDlcId 或未经验证的 dependencies 加到这里。Mod 版本和整个 Mod 的 DLC 准入条件属于 mod_info.yaml。

mod_info.yaml ​

DLL Mod 的现代最小格式是：

yaml
minimumSupportedBuild: 740622
version: 1.0.0
APIVersion: 2

没有 DLC 限制时省略限制字段。需要限制时使用复数列表：

yaml
requiredDlcIds:
  - EXPANSION1_ID

# forbiddenDlcIds:
#   - DLC2_ID

mod_info.yaml 会参与 Mod 是否加载以及归档版本选择，不是 Steam 页面描述文件。根目录和每个 archived_versions 子目录都要放置对应版本的 mod_info.yaml。

supportedContent 是旧游戏格式，U55 起弃用。新的根目录示例不要使用 supportedContent: ALL；只在确实需要兼容旧游戏的归档中保留旧格式。

本地输出目录 ​

开发时通常将整个 Mod 目录输出到：

text
%USERPROFILE%\Documents\Klei\OxygenNotIncluded\mods\Dev\MyMod\

不要只复制 DLL。mod.yaml、mod_info.yaml、动画、翻译和其他资源必须与 DLL 一起输出。

生成后复制 ​

如果使用 Visual Studio 生成后事件，先确保目标目录存在：

batch
if not exist "$(UserProfile)\Documents\Klei\OxygenNotIncluded\mods\Dev\MyMod" mkdir "$(UserProfile)\Documents\Klei\OxygenNotIncluded\mods\Dev\MyMod"
copy /Y "$(TargetPath)" "$(UserProfile)\Documents\Klei\OxygenNotIncluded\mods\Dev\MyMod\"
xcopy /Y /I "$(ProjectDir)mod.yaml" "$(UserProfile)\Documents\Klei\OxygenNotIncluded\mods\Dev\MyMod\"
xcopy /Y /I "$(ProjectDir)mod_info.yaml" "$(UserProfile)\Documents\Klei\OxygenNotIncluded\mods\Dev\MyMod\"
xcopy /E /Y /I "$(ProjectDir)translations" "$(UserProfile)\Documents\Klei\OxygenNotIncluded\mods\Dev\MyMod\translations\"
xcopy /E /Y /I "$(ProjectDir)anim" "$(UserProfile)\Documents\Klei\OxygenNotIncluded\mods\Dev\MyMod\anim\"

项目没有某个资源目录时，应删除对应的复制命令，避免把不存在的路径当作文件复制。

本地测试 ​

  1. 将整个 Mod 目录复制到 mods/Dev/。
  2. 启动游戏并打开 Mod 列表。
  3. 确认 Mod 的名称、版本和加载状态正确。
  4. 查看 Player.log，确认没有 YAML、程序集或资源加载错误。
  5. 进入已有存档测试运行时功能。
  6. 对世界生成、科技树和序列化内容创建新档测试。

日志位置通常是：

text
%USERPROFILE%\AppData\LocalLow\Klei\Oxygen Not Included\Player.log

发布前检查 ​

  • mod.yaml 中的 staticID 已确定且稳定。
  • mod_info.yaml 使用实际测试 Build，并包含 APIVersion: 2。
  • DLC 限制使用复数列表，且只声明真实依赖。
  • DLL、资源和元数据位于同一个发布目录。
  • ZIP 不包含源码、游戏原版 DLL 或 .git 目录。
  • 已在目标游戏版本中启用 Mod 并进行功能测试。

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