环境准备与第一个脚本

前面的快速入门中，我们都是通过编辑器配置和 JSON 文件来制作模组。从这一节开始，我们进入 Python 脚本开发——它能实现配置和 JSON 无法完成的复杂玩法逻辑。

Python 版本

Mod SDK 使用的是 Python 2.7，不是 Python 3。请确保已安装 Python 2.7（参考 安装工具）。

你将学到

• 配置 Python 2.7 开发环境
• 理解 Mod 的脚本文件结构（modMain.py、ServerSystem、ClientSystem）
• 编写并运行你的第一个 Python 脚本——在聊天栏输出 "Hello World"

前置准备

工具	用途	安装地址
Python 2.7	脚本运行环境	下载
VS Code	代码编辑器	下载
MC Studio	开发工作台	已安装

配置 VS Code

1. 下载并安装 VS Code
2. 安装 Python 扩展：打开 VS Code → 左侧扩展图标（Ctrl+Shift+X）→ 搜索 Python → 安装微软官方的 Python 扩展
3. 配置 Python 2.7 解释器：
   • 按 Ctrl+Shift+P 打开命令面板
   • 输入 Python: Select Interpreter
   • 选择你安装的 Python 2.7 路径（通常是 C:\Python27\python.exe）
4. 打开作品目录：File → Open Folder → 定位到 behavior_pack_xxx/ 文件夹
5. 配置 Mod SDK 补全库（可选但推荐）：
   • 在 MC Studio 中找到补全库路径：MCStudioDownload\game\MinecraftPE_Netease\{版本号}\data\mod_sdk\
   • 在 VS Code 的 settings.json 中添加：

   "python.analysis.extraPaths": [
     "MCStudioDownload路径/game/MinecraftPE_Netease/{版本号}/data/mod_sdk"
   ]

   • 配置后 VS Code 就能识别 mod.server.extraServerApi 等模块并提供补全

补全库的作用

配置补全库后，编辑器可以自动提示 Mod SDK 的所有 API 方法、参数和返回值，大幅减少查文档的频率和拼写错误。

关于 PyCharm

如果你更偏好完整的 IDE 体验，也可以使用 PyCharm Community Edition（免费）替代 VS Code。PyCharm 在项目管理、重构和错误检查方面更强大，适合大型项目开发。

Mod 脚本文件结构

一个包含 Python 脚本的 Mod，在行为包中有如下文件结构：

behavior_pack_xxx/
├── entities/
├── netease_items_beh/
└── Scripts/                      ← 脚本根目录
    ├── modMain.py                ← 入口文件（必须）
    ├── ServerSystem.py           ← 服务端逻辑
    └── ClientSystem.py           ← 客户端逻辑

文件	作用
modMain.py	Mod 入口，注册服务端和客户端的 System 类
ServerSystem.py	服务端逻辑：游戏规则、物品操作、伤害计算、实体管理
ClientSystem.py	客户端逻辑：UI 显示、特效播放、动画控制、输入处理

第一步：创建 modMain.py

在 Scripts/ 目录下创建 modMain.py：

# -*- coding: utf-8 -*-
from mod.common.mod import Mod
import mod.server.extraServerApi as serverApi
import mod.client.extraClientApi as clientApi

@Mod.Binding(name="TomatoIslandMod", version="0.0.1")
class TomatoIslandMod(object):

    def __init__(self):
        pass

    @Mod.InitServer()
    def initServer(self):
        serverApi.RegisterSystem(
            "TomatoIslandMod",
            "TomatoIslandServerSystem",
            "Scripts.ServerSystem.TomatoIslandServerSystem"
        )

    @Mod.InitClient()
    def initClient(self):
        clientApi.RegisterSystem(
            "TomatoIslandMod",
            "TomatoIslandClientSystem",
            "Scripts.ClientSystem.TomatoIslandClientSystem"
        )

关键点

• @Mod.Binding 装饰器声明 Mod 名称和版本
• @Mod.InitServer() 在服务端启动时调用
• @Mod.InitClient() 在客户端启动时调用
• RegisterSystem 的第三个参数是 包名.模块名.类名 格式

第二步：创建 ServerSystem.py

# -*- coding: utf-8 -*-
import mod.server.extraServerApi as serverApi

ServerSystem = serverApi.GetServerSystemCls()

class TomatoIslandServerSystem(ServerSystem):

    def __init__(self, namespace, systemName):
        ServerSystem.__init__(self, namespace, systemName)
        print "====== TomatoIslandMod 服务端启动 ======"

    def Destroy(self):
        print "====== TomatoIslandMod 服务端关闭 ======"

第三步：创建 ClientSystem.py

# -*- coding: utf-8 -*-
import mod.client.extraClientApi as clientApi

ClientSystem = clientApi.GetClientSystemCls()

class TomatoIslandClientSystem(ClientSystem):

    def __init__(self, namespace, systemName):
        ClientSystem.__init__(self, namespace, systemName)
        print "====== TomatoIslandMod 客户端启动 ======"

    def Destroy(self):
        print "====== TomatoIslandMod 客户端关闭 ======"

Python 2 语法

注意 print 是语句，不是函数：写 print "hello" 而不是 print("hello")。

第四步：运行测试

1. 保存所有文件
2. 在 MC Studio 中点击「运行」
3. 打开「脚本测试日志」窗口（开发者菜单 → 脚本日志测试）
4. 如果看到以下输出，说明脚本加载成功：

====== TomatoIslandMod 服务端启动 ======
====== TomatoIslandMod 客户端启动 ======

小结

在这一节中，你搭建了 Python 脚本开发的基础框架：

• 在 Scripts/ 目录下创建了三个核心文件
• modMain.py 作为入口注册了服务端和客户端 System
• 两个 System 类分别输出了启动日志

接下来我们将深入学习 Mod SDK 最核心的概念——Client-Server 架构。