Mod 开发指引

附加包

什么是附加包（Add-ons）？

附加包（Add-ons）能够自定义修改我的世界基岩版中的游戏内容，属于我们通常说的模组（Mod）的一种。在我的世界中国版中，把Mod、皮肤等资源都统一称为组件。

在Add-ons中，会存放行为包（behavior_packs）和资源包（resource_packs）。behavior_packs中存放的是我们想要改变的游戏行为，包括各种游戏元素的属性配置文件（一般为Json格式），也包括我的世界中国版支持的Python脚本。resource_packs中包含游戏资源，包括模型（model）/光照阴影（shader）/界面（ui）/贴图（textures)等等。

需要注意的是，我的世界中国版支持所有的原生Add-ons功能，用Python脚本控制游戏逻辑是中国版额外提供的功能。后面我们也会把带有Python脚本的Add-ons称为Mod， 这篇文档中，主要就是介绍这种Mod的制作方式。

如果原生的Add-ons方式不能满足你的雄心壮志，你可以学习Python，使用我们提供的各种Python接口去创造世界。

参考资料：

• behavior_packs可参考 教程/制作行为包
• resource_packs可参考 教程/制作资源
• Python可参考 Python入门教程

Add-ons目录结构

以我们提供的AwesomeMod为例来讲解Add-ons目录结构。

​x
AwesomeMod.zip解压后如下：

​
|AwesomeMod
    | awesome_behavior_packs
        | entities
        | uniqueNameScripts
            | __init__.py
            | modMain.py
            | ...
        | ...
        | manifest.json
    | awesome_resource_packs
        | model
        | shader
        | textures
        | sounds
        | ui
            | _ui_def.json
        | ...
        | manifest.json
​

• 注1 AwesomeMod目录下有 awesome_behavior_packs 和 awesome_resource_packs两个目录，但不是必须得有2个，可以只有其中1个。
• 注2 awesome_behavior_packs 目录下必须有entities目录
• 注3 awesome_behavior_packs 目录下的 uniqueNameScripts 是存放脚本的目录
• 注4 manifest.json 资源包的配置

这里要特别说明下manifest.json文件，其内容如下。

xxxxxxxxxx




    

        

        

        
{
    
    
    "format_version": 1,
    
    "header": {
    
        "description": "By @SDKTeam",
    
        "name": "DeveloperDemoMod",
    
        "uuid": "ab7b26c2-9de3-41e0-854f-be8843dd5c47",
    
        "version": [0, 0, 1]
    
    },
    
    "modules": [
    
        {
    
            "description": "By @SDKTeam",
    
            "type": "data",
    
            "uuid": "bafa90df-cca4-4b95-a3ac-312b29990e48",
    
            "version": [0, 0, 1]
    
        }
    
    ]
    
}

这里介绍开发者需要关注的变量：

在地图存档中可以放置多个Add-ons，进入这样的地图存档时，里面放置的Add-ons会在地图中生效。以AwesomeModMap为例。

xxxxxxxxxx




    

        

        

        
解压AwesomeModMap.zip，文件结构如下：
    
    
​
    
| AwesomeModMap
    
    | behavior_packs
    
        | awesome_behavior_packs
    
        | ...
    
    | resource_packs
    
        | awesome_resource_packs
    
        | ...
    
    | level.dat
    
    | ...
    
    | world_behavior_packs.json
    
    | world_resource_packs.json

world_behavior_packs.json和world_resource_packs.json这两个文件主要是记载地图加载的资源包的信息，其中"pack_id" 和 "version" 对应到manifest.json中header / uuid 和 header / version

xxxxxxxxxx




    

        

        

        
[
    
    
    {
    
        "folder": "awesome_packs",
    
        "version": [0, 0, 1],
    
        "pack_id": "ab7b26c2-9de3-41e0-854f-be8843dd5c47"
    
    }
    
]

Python Mod指南

Python Mod是在原生Add-ons的基础上，添加Python脚本控制游戏逻辑。脚本根目录放在behavior_packs中，示例目录如下。

xxxxxxxxxx




    

        

        

        
| awesomeScripts
    
    
    | modClient
    
        | sfx
    
        | ui
    
        | ...
    
        | __init__.py
    
    | modCommon
    
        | entity
    
        | gameSetting
    
        | network
    
        | ...
    
        | __init__.py
    
    | modServer
    
        | ai
    
        | attr
    
        | buff
    
        | entity
    
        | ...
    
        | __init__.py
    
    | __init__.py
    
    | modMain.py

示例目录中的modClient存放客户端代码，modCommon存放公共代码，modServer存放服务端代码。脚本文件结构不需要完全按照示例目录来，开发者可以根据自己习惯安排。但是modMain.py文件一定要有，而且要放在脚本目录的根目录下，这是用来标识Mod并初始化Mod的脚本。

modMain.py是什么？

modMain是Python逻辑的入口文件，必须包含初始化函数。这些初始化函数中，InitClient和InitServer分别初始化客户端和服务端的RegisterSystem和RegisterComponent，也可以做一些自定义的初始化操作。DestroyServer和DestroyClient一般用来做一些离开Mod后的析构操作，恢复一些设置或销毁一些内容。具体可以参见Mod SDK中关于RegisterSystem，RegisterComponent的说明。

xxxxxxxxxx




    

        

        

        
# Mod属于SDK的内部类用于绑定
    
    
from common.mod import Mod
    
​
    
# 将引擎的方法绑定到我们自己的类HugoMod上用于识别
    
@Mod.Binding(name = "HugoMod", version = "0.0.1")
    
class HugoMod(object):
    
​
    
    def __init__(self):
    
        pass
    
    
    
    # 服务端脚本初始化的入口函数
    
    @Mod.InitServer()
    
    def testServerInit(self):
    
        pass
    
    
    
    # 服务端脚本在退出时执行的析构函数
    
    @Mod.DestroyServer()
    
    def testServerDestroy(self):
    
        pass
    
    
    
    # 客户端脚本初始化的入口函数
    
    @Mod.InitClient()
    
    def testClientInit(self):
    
        pass
    
    
    
    # 客户端脚本在退出时执行的析构函数
    
    @Mod.DestroyClient():
    
    def testClientDestroy(self):
    
        pass

• 注 具体Mod开发参照给到的Mod SDK文档

如何搭建开发环境呢？

Mod PC开发包是我们提供给开发者的PC基岩版的包，无需启动器登陆（非开发包需使用游戏账号登录），开发者可以在上面开发和测试自己的MOD。注册成为开发者后（通过MC Studio内的发布界面或者网页https://mcdev.webapp.163.com/#/login注册），可以在开发者平台下载到Mod PC开发包。

在开发的时候Mod的加载（install）、卸载（uninstall）、使用（use）、不使用（unuse）可以由一个addon.json配置文件来控制，通过修改配置文件来决定MC每次启动时的Mod行为，而不用每次都去改地图存档中的文件。该配置文件需存放在和Minecraft.Windows.exe同一目录里。这种Mod加载方式是只为开发者准备的，方便开发者在windows上查看资源和文件。在实际运行环境中会对Mod中的Python脚本进行加密。

addon.json是什么？

xxxxxxxxxx




    

        

        

        
{
    
    
    "install" : [
    
        "F:/ModDev/awesomeMod"
    
    ],
    
​
    
    "uninstall" : [
    
    ],
    
​
    
    "use" : {
    
        "levelID" : ["awesomeMod"]
    
    },
    
​
    
    "unuse" : {
    
    }
    
}

文件目录

在PC端，我们可以很方便地查看各种文件和资源路径在哪。Mod PC开发包会把资源和地图资源加载到C盘的指定位置，我们需要打开隐藏目录才能看到相关内容。在查看前，需先设置可查看隐藏项目（点击文件夹中的菜单“查看”，勾选“隐藏的项目”）。 这些目录让我们清晰地知道，我们的地图在哪里，我们的Mod资源被加载到哪里。在Mod资源不生效时，可以查看这些地方，确定哪个步骤出了问题，也可以对Mod资源和地图加载的内容进行手动清除。

游戏的路径：RootPath = C:\Users\xxxx\AppData\Roaming\MinecraftPE_Netease

Add-ons路径：Add-onsPath = RootPath + \games\com.netease\

Add_ons目录：保存了我们安装好的mod.lst，里面包含我们每一个MOD的所有文件资源的列表。

behavior_packs目录：保存了我们安装好MOD的behavior资源

resource_packs目录：保存了我们安装好MOD的resource资源

Level路径：LevelPath = RootPath + \minecraftWorlds\

在Level路径下，每个文件夹代表了一个地图存档，文件夹名字即是上文中的levelID

开发环境和测试

Mod代码目前不支持断点调试，因此只能通过在不同的地方打Log来调试代码。打Log可以使用 print 也可以使用 logging模块（可以参考AwesomeMod的使用方式）。Log会显示在Mod PC开发包的命令窗口中。由于命令窗口还会显示游戏自身的Log，脚本的Log最好加上特殊的前缀方便查找。当鼠标选中了命令窗口中的文本时，游戏逻辑会暂停，此时在命令窗口中按下空格键，游戏逻辑就会继续。也可以使用开发者测试工具查看脚本Log，该工具可以屏蔽掉游戏自身的log，用起来更加方便。可在MOD测试工具中下载该工具。

开发工具

Python Mod的开发工具推荐使用PyCharm或VSCode。 JSON和一些其他简单的配置文件推荐使用Sublime。 markdown文档推荐使用Typora。

建议

• 在每次启动时，Mod PC开发包会自动将addon.json的“install”路径下的内容同步到C盘真正加载的地方。所以可以把开发中的Mod放在常用的开发路径下，然后配置“install”为这个Mod路径。

• 如何清理开发环境：

  • 手动清理：删除Add-ons路径下的add_ons / behavior_packs / resource_packs 三个文件夹，并清除该地图存档下的 used_add_on_list.txt / world_behavior_packs.json / world_resource_packs.json 三个文件，重启游戏。
  • 工具清理：使用Mod开发辅助工具中清理缓存的功能。

• Mod里资源包和行为包的取名需使用英文字母和下划线组合(英文或拼音)，尽量使用个性化的名字不与其他人冲突。

• 遇到自身没法解决的问题时，及时和官方沟通反馈（可通过MC Studio内嵌开发者论坛或网页http://mc.netease.com/forum-111-1.html）。

图片资源内存规范

图片资源主要有UI，模型贴图，特效贴图。图片资源加载后占用总内存不能超过100M。图片资源占用内存的计算方法，以分辨率(1024 x 1024)的32位png图片为例：1024 x 1024 x 32 / 8 = 4194304Bytes = 4M

可参考：图片在内存中的占用的空间大小

开始行动吧

跟着文档《从零开始创造MOD.docx》来开始你的Mod之旅吧。

建议一边做一遍学，有什么不懂的再回头参考《Mod入门简介.md》和Mod SDK其他文档。

如果你不满足于从零开始，那可以参考我们提供的射击MOD《AwesomeMod》来学习更多的MOD开发技巧。