MOD 案例教程

收录边界

SCAPI 与 SuAPI 案例必须分开标注。本页的 SCAPI 路线以 API 1.9 模板为起点；SuAPI 案例请转到SuAPI 开发路线。

案例选择表

想学习什么	最小练习	先读
MOD 结构与打包	修改模板名称、版本和一条本地化文本，生成 scmod	项目搭建
数据扩展	增加一条配方或衣物数据，不写 C#	数据与素材
方块与资源	为测试方块绑定独立纹理和配方	DLL 插件
生命周期	在加载、存档和卸载阶段记录可识别日志	API 开发说明
行为 Hook	监听一个玩家操作，并保证异常不阻止原逻辑	从零开发 MOD
方法注入	用 HarmonyX 做单点、可撤销的前置或后置修改	API 1.9 发行说明
模型与动画	从简单 glTF 模型开始，再增加骨骼与动画	AdvancedGltfFoxModForSC

每个案例都要完成的闭环

1. 写明游戏版本、API 名称、分支或提交以及目标平台。
2. 从干净模板构建，记录使用的 dotnet 命令和 SDK。
3. 只安装当前案例，在新测试世界复现功能。
4. 保存并重启，检查数据和内容 ID 是否稳定。
5. 移除 MOD 后再次启动，说明世界是否仍可安全加载。
6. 打包源码、许可证、依赖、安装、升级和卸载说明。

可以先参考

• API 1.9 示例模板
• AdvancedGltfFoxModForSC
• SC-SPM 组织项目
• 语雀资料迁移对照

常见失败点

• 用 SCAPI 程序集编译，却放进 SuAPI 客户端，或反过来；
• 模板、游戏端和引用 DLL 来自不同分支；
• 数据文件中的标识与 C# 注册值不一致；
• 发布包嵌套了多余目录，加载器找不到 modinfo 或程序集；
• 只测试新世界，没有验证旧存档、卸载和升级；
• 复制游戏本体或第三方资源，却没有明确授权。