旧版中国版模组SDK制作规范¶

这篇说明适合在维护旧版中国版模组SDK项目时阅读。这里整理了旧版MC Studio时代常见的制作规范，并补上今天仍需要注意的兼容边界；新项目仍应优先按照当前开发工作台和当前平台要求实施。

不要外推为国际版规则

本页涉及pack_manifest.json、中国版编辑器命名空间配置、旧版中国版九切片实现等内容。这些内容用于中国版旧项目维护或兼容排查，不表示国际版资源包、行为包或脚本API项目也具有相同要求。

命名与冲突规避¶

旧版资料首先强调的是冲突规避。模组、行为包、资源包和脚本目录应当具有足够独特的名称，避免在多个模组同时启用时与其他开发者的内容冲突。

较稳妥的做法是把团队名、项目名和用途都写进名称中：

对象	旧版资料建议
模组名称	`[团队名称][模组名称]Mod`
行为包目录	`[团队名称][模组名称]BehaviorPack`
资源包目录	`[团队名称][模组名称]ResourcePack`
行为包脚本目录	`[团队名称][模组名称]Scripts`

这些格式不是引擎强制要求，而是工程规范。维护旧项目时，如果原目录名已经被清单文件、脚本导入路径、发布配置或工具链引用，不应只为了统一格式而直接重命名；应先全局搜索引用，再同步修改。

命名空间¶

命名空间用于让自定义方块、自定义物品、脚本系统名和其他内容与其他模组区分。旧版资料建议使用团队名_模组名形式，例如sdkteam_test。

旧版MC Studio操作路径是进入关卡编辑器后选择“组件→命名空间”。较新的中国版官方资料已改为在编辑器顶部菜单通过“作品→命名空间”配置。两者反映的是工具界面历史差异，核心目的相同：让编辑器生成的自定义内容与项目命名空间保持一致。

命名空间不是显示名

命名空间会进入方块、物品、事件或脚本引用中。它应当稳定、简短并避免中文、空格和容易混淆的标点；对玩家展示的名称应交给本地化文件或界面文本处理。

清单文件与版本号¶

旧版中国版资料说明，旧版MC Studio创建的附加包可能把清单文件称为pack_manifest.json。较新的中国版资料仍说明pack_manifest.json和manifest.json在中国版附加包中承担相同职责，但其他环境不一定接受pack_manifest.json这一名称。

清单文件中的UUID用于标识包本身或包内模块。复制官方示例、旧模板或其他项目时，必须重新生成UUID，否则不同包可能被游戏视为同一内容或相互覆盖。版本号则用于区分内容更新；旧版资料特别指出，联机时不同玩家之间会检查模组版本，新版本发布时应提升清单中的相关版本号。

维护旧项目时应按以下顺序处理：

先备份项目。
确认目标环境是否接受pack_manifest.json，不接受时迁移为manifest.json。
确认行为包和资源包的UUID互不重复，并与其他项目不同。
发布实质更新前提升清单版本号。
如果工具提供“配置”或“版本升级”入口，优先使用工具写入，减少手动漏改。

必要目录的兼容要求¶

旧版资料要求中国版行为包中存在entities目录，资源包中存在textures目录。通过MC Studio创建的附加包通常会自动带有这些目录；手动构造目录或从示例复制项目时需要自行检查。

这条要求应视为中国版旧版项目兼容要求，而不是基岩版附加包的通用最小结构。国际版或其他工具链中，清单文件才是识别包的核心入口；是否需要某个资源目录取决于包实际包含的内容和目标平台。

图片资源¶

旧版资料把图片资源分为界面、模型贴图和特效贴图，并给出以下约束和建议：

不使用灰度模式贴图，应使用彩色模式导出。
皮肤贴图需要包含透明度通道；普通模组贴图没有同等限制。
图片长宽建议使用2的幂次方，例如16、32、64、128、256或512。
模型和特效贴图建议优先控制在128×128以内，超过该尺寸的贴图应严格限制数量。
旧版资料给出的图片资源加载后总内存目标上限为100M；这是旧版中国版性能约束，应以当前平台审核、设备性能和实际测试结果作为最终判断。

贴图内存可以按“宽×高×位深÷8”粗略估算。例如1024×1024的32位PNG在完全展开后约占4M级别内存，而不是只按文件压缩后的大小计算。因此，一个看似很小的PNG文件，如果分辨率过大或被大量同时加载，仍可能造成显著内存压力。

较新的中国版官方美术资料还补充了贴图预加载的思路：首次显示时需要异步加载的贴图可能出现闪烁，可以在合适位置预先加载。预加载能改善体验，但也会更早占用内存，所以应只用于确实需要快速显示的界面与资源。

九切片¶

旧版资料把九切片称为“九宫格”或“九宫切图”。它的核心思想是把一张图片按左、上、右、下四条边距切成九个区域：四角不拉伸，四边只沿一个方向拉伸，中间区域横纵方向都可拉伸。按钮、面板、对话框背景等需要在不同尺寸下保持边角形状的图片通常适合使用九切片。

制作九切片资源时，应避免把不能变形的图案放在会被拉伸的边或中心区域。例如对话框尖角、徽章边缘、复杂纹样等应落在四角或不拉伸区域；纯色或简单渐变区域则适合作为拉伸区域。

旧版资料曾建议优先使用微软原版九切片，而不是旧版中国版自研九切片工具。原因是旧版自研实现发生在界面整体缩放之后，可能导致1像素边线过细，也可能因计算精度出现四角异常。较新的中国版界面教程则说明编辑器中存在“原版九宫”和“新版九宫”两类规则，二者适配的分辨率语境不同。维护旧界面时，应先确认该界面原本使用哪一种规则，再决定是否迁移；不要只因为看到“九宫”字样就直接替换实现。

是否应迁移¶

下列情况适合按本页检查旧规范：

项目来自旧版MC Studio或早期中国版教程。
项目中存在pack_manifest.json。
自定义内容的命名空间由编辑器早期版本生成。
资源包或行为包在中国版可运行，但换到其他环境后无法识别。
界面九切片在不同分辨率或缩放比例下出现边缘异常。

如果项目正在从零开始开发，则应只把本页作为历史背景。新项目应优先使用当前中国版开发工作台和当前文档中的入口、字段与限制，并在目标设备上进行实际测试。