开发指南

打包与发布

11.1 jar 结构与 manifest 字段

一个模组 jar 的内容就是「编译后的类 + 资源 + manifest」：

text

mymod-0.1.0.jar
├── META-INF/MANIFEST.MF          # 入口与元信息（见下表）
├── com/example/mymod/*.class     # 你的类
└── assets/mymod/                 # 你的资源（命名空间 = 模组 id）
    ├── lang/zh.json
    ├── lang/en.json
    └── textures/note.png

资源一律放在 assets/<模组id>/...，代码里用 ResourceLocation.of("<模组id>", "相对路径") 引用；语言文件放 assets/<模组id>/lang/<locale>.json，键名以模组 id 作前缀。

manifest 字段全表：

键	是否必须	说明
`Seecmd-Mod-Class`	必须	入口类全限定名（实现 `Mod` 或 `GameplayMod`）
`Seecmd-Mod-Id`	建议	模组 id：小写 `[a-z0-9_.-]`，同时是资源命名空间与数据目录 `data/mods/<id>`
`Seecmd-Mod-Name`	建议	显示名称，供模组列表展示
`Seecmd-Mod-Version`	建议	模组自己的版本号（与 mod-api 的版本无关）
`Seecmd-Mod-Authors`	建议	作者
`Seecmd-Mod-Description`	建议	描述
`Seecmd-Api-Version`	建议	期望的 mod-api 版本（如 `3.2`）；详见第 12 节

Mod.info() 返回的 ModInfo.id 必须与 Seecmd-Mod-Id 一致。

11.2 两种构建路线

路线一：build.bat（无需 Maven，推荐上手）

确认 mod-api-*.jar 与脚本同级（模板已附带），并准备好 gson-*.jar（脚本会先找同级，再找本地 Maven 仓库）；
编辑脚本顶部的 MOD_ID / MOD_NAME / MOD_VERSION / MOD_CLASS / API_VERSION；
双击运行，产物在 target\<MOD_ID>-<MOD_VERSION>.jar。

要求：本机已安装 JDK 17+，且 javac、jar 在 PATH 中。

路线二：Maven

先把 API jar 安装进本地仓库（只需一次）： mvn install:install-file -Dfile=mod-api-3.2.jar ^ -DgroupId=com.seecmd -DartifactId=mod-api -Dversion=3.2 -Dpackaging=jar
依赖用 provided（编译期引用、运行期由宿主提供）：com.seecmd:mod-api 与 com.google.code.gson:gson；
用 maven-jar-plugin 的 manifestEntries 写 manifest 字段，然后 mvn package，产物在 target\<artifactId>-<version>.jar。

产物与发布范围：只需要发布那个模组 jar。target\ 下的其余内容（classes\、manifest.mf、编译中间产物、打包脚本的临时文件）都不必发布。安装方式是把 jar 放进游戏的 mods\ 目录，启动游戏后模组列表里能看到它，状态为 ACTIVE。

11.3 发布前自检清单

manifest 的 Seecmd-Api-Version 与目标宿主的主版本一致（宿主 major 不一致会拒绝加载）
模组 id 合法（小写 [a-z0-9_.-]）且在目标环境中唯一
ModInfo.id 与 manifest 的 Seecmd-Mod-Id 一致
Seecmd-Mod-Class 指向的入口类确实在 jar 内，且有可用构造
全部资源都在 assets/<模组id>/... 下，代码里的 ResourceLocation 命名空间与模组 id 一致
语言文件键名带 <模组id>. 前缀，且文件放在 assets/<模组id>/lang/<locale>.json
代码没有任何 com.seecmd.*（除 com.seecmd.mod.api.*）的 import
所有 ctx.registries().xxx().register(...) 只出现在 onPreInit 中
在游戏里实测：模组列表状态为 ACTIVE，功能生效
关闭游戏后确认 data/mods/<模组id>/config.json 行为符合预期（读缺失不生成空文件、set 后确实落盘）