MOD 架构、工具与排错

本页合并旧语雀的 API 原理、游戏工作机制、编译、反编译、移植、优化、XML、Emmet、翻译、模组分工和报错教程。旧教程的 .NET Framework、手机编译器和直接替换原版类只作为历史背景。

先理解加载边界

MOD 能做什么取决于加载器提供的入口：数据合并、事件、继承、组件/子系统注册、方法注入或资源替换。SCAPI 与 SuAPI 实现不同，旧联机版服务器插件又是第三套接口。

游戏/服务端宿主
    ├─ 内容加载：XML、表格、纹理、声音、模型
    ├─ 生命周期：初始化、世界加载、更新、保存、卸载
    ├─ 扩展点：事件、注册器、组件、子系统
    └─ 注入层：仅在没有稳定扩展点时使用

工具选择

任务	当前建议	历史教程的处理
C# 构建	目标仓库指定的 .NET SDK、VS/Rider 或 CLI	不再推荐固定 .NET Framework 4.x 教程
查看程序集	ILSpy 等只读分析工具	用于理解公开/有权分析的程序集，不直接复制代码发布
XML/JSON	支持编码和格式校验的编辑器	Emmet 只提高输入效率，不保证结构正确
版本管理	Git、独立测试分支和可重复构建	不在唯一安装目录直接开发
移动端构建	以目标 API 当前 CI/文档为准	旧手机 IDE 和路径大多已经失效

修改既有逻辑的顺序

1. 使用公开事件或注册接口；
2. 继承类型，只覆盖必要行为；
3. 新增组件或子系统组合功能；
4. 用可撤销、范围最小的方法注入；
5. 最后才考虑替换核心类，并锁定原始提交。

直接复制完整原版类会同时继承未知 bug、版权风险和升级冲突。即使能编译，也不代表可以公开再分发。

新方块的依赖链

一个新物品通常同时涉及类型注册、方块数据、本地化、纹理/模型、配方和存档标识。历史“加入新物品”和“添加新工具”教程的核心价值是这条依赖链，而不是旧版类名。

性能

• 每帧更新不做同步磁盘、网络请求或无边界遍历；
• 事件只注册一次，卸载时按 API 要求解除；
• 缓存稳定结果，但要在世界切换和资源重载时失效；
• 避免每帧创建临时集合、字符串和大对象；
• 优化前先测量，不用“感觉更快”代替数据。

移植

移植应分层进行：先让空入口加载，再迁移数据与资源，之后迁移纯逻辑，最后处理注入、平台和存档。SCAPI、SuAPI 与旧服务器插件之间通常需要重写生命周期和 Hook，不是替换 using 即可。

排错顺序

1. 锁定游戏、API、SDK、分支和平台。
2. 只启用当前 MOD，在新世界复现。
3. 读取第一条异常及完整内部异常，不只看最后一句。
4. 区分编译失败、程序集加载失败、内容解析失败和运行时异常。
5. 回退最近一项修改，建立最小复现。
6. 提交日志和复现项目，删除账号、Token 与私服密钥。

协作与分工

复杂模组可以按程序、数据、模型/纹理、关卡、测试和文档分工，但每一项都应通过版本库合并。明确内容 ID、资源命名、分支策略和验收标准，避免用聊天文件覆盖彼此成果。

当前入口：SCAPI 项目搭建 · SuAPI · DLL 开发