模组SDK调试与热更新¶

这一页只讨论中国版模组SDK开发中的调试流程：脚本日志、内容日志、热更新和开发构建调试工具。这里的接口与工具链基于MC Studio和Python模组SDK，不适用于国际版脚本API。

先看日志，再改逻辑¶

中国版模组SDK开发里，最常见的第一步不是改代码，而是先确认日志里到底报了什么。

在MC Studio启动测试后，打开“脚本测试日志”窗口。
复现问题，记录报错时间点和报错关键词。
再回到代码中定位对应事件、组件或路径。

如果一开始就盲改，通常会把“资源路径错误”“事件没监听到”“热更新未生效”等问题混在一起，排查成本会迅速上升。

用`print`和`mod_log`打印关键上下文¶

print适合快速确认流程是否进入某个函数；mod_log适合输出结构化信息并长期保留在调试习惯里。

from mod_log import logger

def OnServerBlockUseEvent(self, args):
    print "OnServerBlockUseEvent", args.get("playerId")
    logger.info("block=%s player=%s", args.get("blockName"), args.get("playerId"))

建议优先打印这些字段：

事件名与回调是否执行。
玩家ID、实体ID、方块赋命名空间标识符。
组件调用前后的关键参数。

正确使用热更新¶

中国版Python脚本支持热更新，但只对“函数体内部逻辑变更”最稳定。以下改动经常需要重进存档或重启测试：

新增文件或新增类。
变更全局变量初始化结构。
改动导入关系或模块入口。

热更新未生效时的处理顺序

先保存全部脚本文件，再观察脚本测试日志是否出现重载信息；若没有，再退出到菜单并重新进入测试存档。不要在不确认加载状态的前提下继续叠加修改。

开发构建调试工具¶

在中国版开发构建中，还可以使用一组额外调试能力：

开发控制台：可在游戏内快速执行命令。
调试屏幕：查看运行时状态和调试信息。
内容日志界面：快速查看资源与内容加载错误。

内容日志可在设置中开启，也可用快捷键Ctrl+H快速打开。它是定位JSON字段错误、路径错误、资源引用错误的核心入口之一。

手机开发版自测¶

手机开发版自测更适合验证设备适配与表现一致性，例如界面显示、帧率波动和触控交互。建议在以下阶段进行：

电脑端功能跑通后。
资源与脚本日志主要错误清理后。
正式提审前。

这样可以把“逻辑错误排查”和“设备适配排查”分层处理，减少反复回归成本。

最小排错清单¶

事件是否已注册，回调是否收到参数字典。
组件创建目标是否正确（levelId、playerId、实体ID）。
赋命名空间标识符、文件路径、目录名称是否一致。
热更新是否真正触发。
内容日志是否仍有高优先级错误。

若以上都通过，再进入玩法逻辑本身的行为验证，会更高效。