🚀 快速入门我的世界 Mod 开发

⚠️ 接下来需要 Python2 基础知识

如果你不熟悉 Python 的这些概念（变量、函数、类等），或是还没有安装 Python2 环境，可以先学习 Python 官方教程

1. 创建你的 Addons

什么是 Addons？

Addons 是基岩版的玩法与内容扩展的载体，分为行为包（Behavior Pack）和资源包（Resource Pack）两部分。

在中国版的行为包中，我们可以使用 Python2 编写 Mod 脚本，实现自定义的复杂游戏逻辑。

我们一般推荐使用 MCStudio 来创建你的 Addons（Mod）

• 左侧切换到 作品库 > 基岩版组件 标签页
• 顶部切换到 附加包 标签页
• 点击右上角 新建 按钮，选择 空白附加包 或 入门预设脚本模板
• 输入 作品名称、命名空间 等信息，点击 启动编辑 启动 MCStudio 编辑器（但是暂时没什么用），也可以点击 仅新建 来创建。

2. 创建基础 Mod 框架

Addons（Mod）创建完毕后，你可以在 MC Studio 中，找到你刚刚创建的 Addons，点击 更多 > 打开目录，即可在资源管理器中找到和打开 Addons 文件夹。

接着，你可以使用任何代码编辑器打开这个 Addons 文件夹。

可以使用 VS Code，也可以使用 PyCharm 等用于 Python 的 IDE（集成开发环境 的缩写）。

Addons目录结构

Addons                     # Addons 根目录
├── resource_pack/         # 基岩版材质包（MCStudio创建时，会自动生成后缀，这是没问题的）
│   ├── manifest.json      # 材质包描述文件
│   └── textures/          # 材质文件目录（目前用不到）
│       ├── blocks/
│       └── items/
├── behavior_pack/         # 基岩版行为包（MCStudio创建时，会自动生成后缀，这是没问题的）
│   ├── manifest.json      # 行为包描述文件
│   ├── myScript/          # Mod脚本目录（这个目录名字随便起！）
│   │   ├── modMain.py
│   │   ├── MyServerSystem.py  # ServerSystem，你也可以随意放在任何子目录，但是需要在modMain.py中正确注册
│   │   └── MyClientSystem.py  # ClientSystem，你也可以随意放在任何子目录，但是需要在modMain.py中正确注册

Mod（Python）逻辑位于 行为包 (Behavior Pack，简称BP) 中的 脚本目录，这里我们取名为 myScript，当然你想你可以随便取名。

BP/myScript/modMain.py

from mod.common.mod import Mod
import mod.server.extraServerApi as serverApi
import mod.client.extraClientApi as clientApi

# 通过Mod.Binding注明这个class是Mod的主入口。
@Mod.Binding(name="MyFirstMod", version="1.0")  # Mod名称(name)可以随便取，但是需要唯一且用于下方注册系统和后续注册事件监听。
class MyFirstMod:  # 这个类名可以随便取
    @Mod.InitServer()
    def serverInit(self):  # 这个方法名可以随便取，因为已经通过@Mod.InitServer()注明是服务端的初始化方法
        serverApi.RegisterSystem("MyFirstMod", "MyServerSystem", "myScript.MyServerSystem.MyServerSystem")
        print("MyFirstMod 服务端已加载！")  # print打印的内容将输出在MCStudio的 日志与调试工具 中

    @Mod.InitClient()
    def clientInit(self):  # 这个方法名可以随便取，因为已经通过@Mod.InitClient()注明是客户端的初始化方法
        clientApi.RegisterSystem("MyFirstMod", "MyClientSystem", "myScript.MyClientSystem.MyClientSystem")
        print("MyFirstMod 客户端已加载！")  # print打印的内容将输出在MCStudio的 日志与调试工具 中

BP/myScript/MyServerSystem.py

from server.extraServerApi import serverApi

ServerSystem = serverApi.GetServerSystemCls()

# 继承 ServerSystem 类，表示这是一个 服务端System
class MyServerSystem(ServerSystem):

    def __init__(self):
        super(MyServerSystem, self).__init__()
        print("MyServerSystem Hello World!")  # print打印的内容将输出在MCStudio的 日志与调试工具 中

BP/myScript/MyClientSystem.py

# 本教程中，我们还暂时用不到 ClientSystem，但是我们可以先创建好
from client.extraClientApi import clientApi

ClientSystem = clientApi.GetClientSystemCls()

# 继承 ClientSystem 类，表示这是一个 客户端System
class MyClientSystem(ClientSystem):

    def __init__(self):
        super(MyClientSystem, self).__init__()
        print("MyClientSystem Hello World!")

BOOM！就这么简单！

💡 为什么需要这些System？

🧩 为什么需要两个系统（System）？用餐厅来理解！

想象一下游戏就像一家餐厅：

• 服务器系统 = 厨房（决定食物实际内容）
• 客户端系统 = 餐厅前厅（呈现给顾客看到的体验）

👨‍🍳 服务器系统：游戏的"厨房"

• 职责: 决定游戏中真正发生了什么
• 简单理解:
  • 计算伤害（怪物真的死了吗？）
  • 决定方块是否被破坏
  • 控制物品掉落
  • 存储真实的游戏数据

👨‍💼 客户端系统：游戏的"前厅"

• 职责: 让玩家看到并互动
• 简单理解:
  • 显示画面和声音
  • 处理你的鼠标点击和按键
  • 播放爆炸、火焰等特效
  • 展示菜单和界面

📮 系统间如何交流：像传纸条一样

当你在游戏中点击方块，发生了什么？

⚠️ 为什么不能混在一起？

就像餐厅里顾客不能随便进厨房一样：

• ❌ 客户端不能直接修改游戏数据（否则会作弊）
• ❌ 服务器不负责播放声音和动画（它只关心真实数据）

🌟 简单例子：击打树木得钻石

简化理解版

1. 你点击树木（客户端检测到）
2. 客户端发消息："嘿，服务器，玩家点击了这棵树"
3. 服务器决定："好，我给他一颗钻石"
4. 服务器通知客户端："请在玩家背包里显示一颗新钻石"
5. 客户端更新画面：你看到钻石出现在背包里

🔑 记住这个简单规则

想象游戏是一部电影：

• 服务器是导演（决定故事情节）
• 客户端是摄像机和屏幕（展示给观众看）

记住：服务器决定发生什么，客户端决定如何展示！

💡 初学者提示

如果遇到问题，先问自己：

• "这个功能应该由谁负责？是真实游戏规则还是显示效果？"
• "我需要发送什么消息让另一边知道？"

学会这种思考方式，你的Mod就能正确运行啦！

🎀 那么总结一下吧！

核心架构：客户端-服务器分离

双系统模型的必要性

服务器系统 (ServerSystem)

• 职责: 维护游戏的"真实状态"
• 具体功能:
  • 处理游戏核心逻辑（如战斗计算、物品掉落）
  • 管理AI行为与路径寻找
  • 执行世界生成与物理规则
  • 拥有数据的最终决定权

客户端系统 (ClientSystem)

• 职责: 处理玩家的直接体验
• 具体功能:
  • 渲染游戏画面与UI界面
  • 处理玩家输入
  • 播放音效与粒子效果
  • 进行预测性渲染（平滑过渡）

系统间通信的关键：事件机制

事件驱动设计的优势

• 松耦合: 系统间无需直接相互调用
• 可扩展: 多个系统可响应同一事件
• 清晰职责: 服务端决定结果，客户端呈现效果

实例：击打方块流程

1. 客户端: 检测到玩家点击方块，发送BlockUseEvent
2. 服务端:
   • 接收到事件，判断方块是否可被破坏
   • 更新方块状态，计算掉落物
3. 客户端:
   • 播放方块破坏动画和音效
   • 显示掉落物

常见问题与最佳实践

避免的错误模式

• ❌ 在客户端直接修改游戏状态
• ❌ 在服务端处理UI渲染逻辑
• ❌ 遗漏事件监听导致功能不同步

最佳实践

• ✅ 服务端验证所有游戏逻辑（防作弊）
• ✅ 合理使用自定义事件进行系统间通信
• ✅ 保持客户端代码专注于视觉体验优化
• ✅ 在事件参数中携带足够的上下文信息

跨系统通信示例

# 服务端发送自定义事件到客户端
def spawn_special_effect(self, position):
    comp = serverApi.GetEngineCompFactory().CreateGame(serverApi.GetLevelId())
    comp.NotifyToClient(player_id, "ShowSpecialEffect", {"position": position})

# 客户端监听并处理
def listen_events(self):
    self.ListenForEvent("MyMod", "MyServerSystem", "ShowSpecialEffect", 
                        self, self.on_special_effect)

def on_special_effect(self, event_data):
    pos = event_data["position"]
    # 在客户端显示特效...

通过掌握客户端-服务端分离的设计模式，你将能够创建更稳定、可扩展且性能优秀的Mod。记住：服务端决定发生什么，客户端决定如何展示。

3. 运行你的Mod

• 保存你的代码
• 在 MCStudio 中找到此 Addons，鼠标划上去后点击 开发测试 按钮
• 选择一个合适的游戏版本（一般为最新）
• 填写相关测试名称和测试地图的配置，点击 开始 按钮
• 等待游戏启动，你会在 脚本与测试工具 看到 MyFirstMod 服务端已加载！ 和 MyFirstMod 客户端已加载！ 的输出

🤔 常见问题

• 如果你没有看到期望的输出，可以在 脚本与测试工具 中查看日志，看看有没有报错
• 如果没有任何报错，你需要检查你的 脚本目录 及以下的各级目录中，是否有__init__.py文件，如果没有，可以手动创建一个空文件
• 再次检查后，可以尝试重启游戏（右侧 测试存档记录）

4. 实现简单功能

🧪 小功能：右键方块，获得钻石

BP/myScript/MyServerSystem.py

from server.extraServerApi import serverApi

ServerSystem = serverApi.GetServerSystemCls()

# 继承 ServerSystem 类，表示这是一个 服务端System
class MyServerSystem(ServerSystem):
    def __init__(self):
        super(MyServerSystem, self).__init__()
        # 监听玩家使用方块事件 
        self.ListenForEvent(serverApi.GetEngineNamespace(), serverApi.GetEngineSystemName(), "ServerBlockUseEvent", self, self.onBlockUse)

    def onBlockUse(self, args):
        # 从事件的参数中，获得玩家ID
        playerId = args["playerId"]
        # 生成（获取）一个引擎的ItemComponent
        itemComp = serverApi.GetEngineCompFactory().CreateItem(playerId)
        # 向玩家背包中放入一个钻石
        itemComp.SpawnItemToPlayerInv({
            "itemName": "minecraft:diamond",
            "count": 1
        })

🔌 使用到的相关API

• 接口：ListenForEvent
• 事件：ServerBlockUseEvent
• 接口：SpawnItemToPlayerInv

太棒了！赶快进入游戏，右键点击任意方块，你将获得一个钻石！