打包与发布

动手前先把这三个值定下来，代码、构建脚本、manifest 都要用同一个值：

ModInfo 的 id、name、version、authors、description 宿主都要求非空，任一为空会被拒绝注册。

打开模组根目录的 build.bat，只改顶部这 5 行：

set "MOD_ID=hello_mod"
set "MOD_NAME=Hello Mod"
set "MOD_VERSION=0.1.0"
set "MOD_CLASS=com.example.hellomod.HelloMod"
set "API_VERSION=3.2"

• MOD_CLASS 从代码里复制 package 行再拼类名，避免手打出错。
• API_VERSION 写宿主当前的 3.2。模板里默认的 3.0 也能加载（主版本相同），新工程建议对齐 3.2。
• 脚本自动查找同级的 mod-api-*.jar，找不到直接报错退出；gson-*.jar 先找同级，再找 %USERPROFILE%\.m2。

在模组根目录执行（不是游戏根）：

build.bat

脚本固定做四件事：

1. javac --release 17 -encoding UTF-8 -cp "mod-api-*.jar;gson-*.jar" 把 src\main\java 编译到 target\classes；
2. 把 src\main\resources 整个复制进 target\classes，所以资源在 jar 里的路径就是 assets\...；
3. 写 target\manifest.mf，内容来自上一步那 5 个变量；
4. jar cfm "target\<MOD_ID>-<MOD_VERSION>.jar" "target\manifest.mf" -C "target\classes" .

成功时发布物只有一个：

target\hello_mod-0.1.0.jar

target\classes\、target\manifest.mf、target\srcfiles.txt 都是中间产物，不要发出去。

pom.xml 与 build.bat 二选一。先把 API jar 安装进本地仓库（只需一次），在模组根执行：

mvn install:install-file -Dfile=mod-api-3.2.jar -DgroupId=com.seecmd -DartifactId=mod-api -Dversion=3.2 -Dpackaging=jar

然后：

mvn package

产物是 target\<artifactId>-<version>.jar。pom.xml 里与发布相关的三处：

• <artifactId> 与 <version>：决定产物文件名；
• <maven.compiler.release>17</maven.compiler.release>：与 javac --release 17 等价；
• maven-jar-plugin 的 <manifestEntries>：写 Seecmd-Mod-Class、Seecmd-Api-Version 等字段，改类名或模组 id 时要同步改这里。

两个依赖都必须是 provided：

<dependency>
    <groupId>com.seecmd</groupId>
    <artifactId>mod-api</artifactId>
    <version>3.2</version>
    <scope>provided</scope>
</dependency>

provided 的含义是「编译期可见、运行期由宿主提供」，也就是「不拷进 jar」的开关。gson 同理。

列出条目：

jar tf target\hello_mod-0.1.0.jar

期望看到三类，且都在 jar 根：

META-INF/MANIFEST.MF
com/example/hellomod/HelloMod.class
assets/hello_mod/lang/zh.json
assets/hello_mod/textures/note.png

不应该看到：

com/seecmd/mod/api/...
com/google/gson/...

出现后者说明 API 或 gson 被打进了 jar。

再直接看 manifest：

jar xf target\hello_mod-0.1.0.jar META-INF/MANIFEST.MF
type META-INF\MANIFEST.MF

期望内容：

Manifest-Version: 1.0
Seecmd-Mod-Class: com.example.hellomod.HelloMod
Seecmd-Mod-Id: hello_mod
Seecmd-Mod-Name: Hello Mod
Seecmd-Mod-Version: 0.1.0
Seecmd-Mod-Authors: YourName
Seecmd-Mod-Description: Theseus mod hello_mod .1.0
Seecmd-Api-Version: 3.2

宿主真正读取的属性只有两个：

• Seecmd-Mod-Class：入口类全限定名，缺失就找不到模组；
• Seecmd-Api-Version：参与 API 版本协商。

Seecmd-Mod-Id 只在加载失败时作为失败记录的键（API 版本不兼容、入口类找不到、实例化失败），缺失时退化为 jar 文件名。Seecmd-Mod-Name / -Version / -Authors / -Description 当前宿主不读取；模组列表显示的是 ModInfo 里的值。保留这些字段是为了 jar 自描述，改不改都不影响加载。

ModInfo 的 version 是模组自己的版本，建议按语义递增：

• 主版本：有不兼容改动才加，玩家可能需要删旧配置；
• 次版本：兼容地新增功能；
• 修订：只修 bug。

模组之间的依赖写在 info() 里，不在 manifest：

@Override
public ModInfo info() {
    return new ModInfo(
            "hello_mod",              // id
            "Hello Mod",              // 显示名称
            "0.1.0",                  // 模组版本
            List.of("YourName"),      // 作者
            "依赖 core_lib 的示例",     // 描述
            List.of("core_lib"));     // 第 6 个分量：硬依赖的模组 id
}

ModInfo.of(...) 是 5 参工厂，等价于 dependsOn = List.of()。dependsOn 的字段含义：

• 写的是被依赖模组的 id，不是 jar 文件名，也不带版本号；
• 被依赖模组必须已注册且已启用，否则本模组 LOAD_FAILED，原因为 Missing dependencies: [core_lib]；
• 循环依赖同样失败，原因为 Circular dependency: a -> b -> a；
• 只影响本模组，其它模组照常加载。

只想要顺序、不强制目标存在时，用软依赖：

@Override
public ModLoadOrder loadOrder() {
    return new ModLoadOrder(LoadStage.INIT, List.of("core_lib"), List.of());
}

目标不存在时这条约束自动失效，不会报错。需要「目标一定在，而且先跑完」时，dependsOn 与 loadAfter 一起写。

把 jar 复制到游戏根目录的 mods\：

<游戏根>\
├── mods\
│   └── hello_mod-0.1.0.jar
└── 游戏本体...

加载器只扫描 mods\ 的直接子文件，不递归子目录。新放入的 jar 默认未启用：第一次启动看到 REGISTERED 是正常的，在模组菜单里启用后重启，状态才变 ACTIVE。

发布说明至少写清四件事：适用 API 主版本、依赖哪些模组 id、jar 放在 mods\ 根目录、启用后要重启。