mc-netease-sdk-stubs

为网易《我的世界》Python Mod SDK 提供 .pyi 类型声明，支持 PyCharm、 Pylance、Pyright 和 mypy 的代码补全、参数提示、快速文档与静态检查。

当前版本对应 mc-netease-sdk 3.9.0.79920，覆盖官方包中的 294 个模块、 282 个引擎事件以及事件回调参数。该项目不是网易官方项目，API 行为仍以 网易 Mod SDK 文档 和实际游戏版本为准。

功能

• 覆盖 mod、Meta、Preset、apolloCommon、lobby、master 等官方顶层包。
• 保留 API 类、方法、参数、默认值、返回值和官方中文说明。
• ListenForEvent 与 UnListenForEvent 按客户端、服务端提供 Literal 事件名补全。
• 为每个引擎事件提供独立 TypedDict，精确标注回调参数名和类型。
• 在事件类型快速文档中集中展示全部参数的类型与官方说明。
• 保留自定义事件的 str 入口，不限制 Mod 自己定义的事件名。
• 仅安装类型文件，不替换或执行官方 SDK 的 Python 代码。

版本对应

类型库版本与目标 SDK 版本保持一致。使用其他 SDK 版本时，部分接口、事件或参数 可能不同。

安装

在 PyCharm 使用的本地 Python 2.7 开发解释器中安装官方 SDK 和类型库：

python -m pip install mc-netease-sdk==3.9.0.79920
python -m pip install mc-netease-sdk-stubs==3.9.0.79920

这些安装命令只用于本地开发环境。类型库会在开发解释器中安装兼容 Python 2.7 的 typing 和 typing-extensions，供 IDE 解析 Literal、TypedDict 等类型； 它们不需要打包进 Mod，也不会被网易游戏内置解释器加载。Mod 运行代码不应导入 typing、typing_extensions 或仅存在于 .pyi 中的模块。

不要使用 editable 安装。官方运行时包和类型库都会提供 mod 包，普通安装会把 .pyi 放到官方 .py 文件旁边，使 IDE 能同时解析运行时代码和类型声明；两个 独立源码目录中的同名普通包无法可靠地通过 editable 安装合并。

从源码安装时使用：

python -m pip install -r requirements.txt
python -m pip install .

PyCharm 配置

1. 将项目解释器设为实际运行 Mod 的 Python 2.7 环境。
2. 确认 mc-netease-sdk 和 mc-netease-sdk-stubs 安装在同一个解释器中。
3. 安装或更新后，让 PyCharm 重新加载解释器包索引。

所有生成的 stub 都声明为 Plain docstring 格式，查看快速文档不需要为项目额外 配置 Python 3 SDK。

mod.common.event_types 只有类型声明，没有对应的运行时 .py 模块。Python 2.7 代码引用事件参数类型时，可以定义一个不依赖外部库的类型检查标记：

TYPE_CHECKING = False

if TYPE_CHECKING:
    from mod.common.event_types import AddEntityClientEventArgs

TYPE_CHECKING 为 False 时游戏不会执行该导入；PyCharm、mypy 和 Pyright 仍会解析分支中的类型声明。不要为了这个类型导入而在 Mod 运行环境中依赖 typing。

事件补全

# coding=utf-8

import mod.client.extraClientApi as clientApi

TYPE_CHECKING = False

if TYPE_CHECKING:
    from mod.common.event_types import AddEntityClientEventArgs

ClientSystem = clientApi.GetClientSystemCls()


class ExampleClientSystem(ClientSystem):
    def __init__(self, namespace, system_name):
        super(ExampleClientSystem, self).__init__(namespace, system_name)
        self.ListenForEvent(
            clientApi.GetEngineNamespace(),
            clientApi.GetEngineSystemName(),
            "AddEntityClientEvent",
            self,
            self.on_add_entity,
        )

    def on_add_entity(self, args):
        # type: (AddEntityClientEventArgs) -> None
        print(args["id"])

继承客户端系统后，eventName 会补全客户端事件；继承服务端系统后会补全服务端 事件；通用 BaseSystem 使用全部引擎事件集合。自定义事件仍可直接传入任意字符串。

事件参数类型的快速文档会显示类似内容：

AddEntityClientEvent 回调参数。

参数：
id (str)：实体id
posX (float)：位置x
posY (float)：位置y
posZ (float)：位置z
dimensionId (int)：实体维度
...

开发与验证

生成工具需要 Python 3.9 或更高版本；生成出的 .pyi 仍以网易 Mod 的 Python 2.7 环境为目标。

python -m pip install -r requirements-dev.txt
python -m unittest discover -s tests -v
python -m mypy --config-file mypy.ini src
python -m mypy --config-file mypy.ini tests\typecheck\valid_usage.py
npx --yes pyright
python -m build
python -m twine check dist\*

更新到新版 SDK 时，先在目标 Python 2.7 环境中更新官方包，再使用 Python 3 执行：

C:\Path\To\Python3\python.exe -m tools.update_events
C:\Path\To\Python3\python.exe -m tools.generate_stubs --sdk-root .venv\Lib\site-packages

第一条命令从官网事件分类页更新 data/events.json；第二条命令从真实 SDK 源码生成 src 下的 .pyi，并让 VERSION 与官方 SDK 版本保持一致。遇到未知事件类型、 冲突定义或无法对应的函数参数时，生成器会失败并输出具体位置。

第三方声明

生成的声明描述网易 Mod SDK API，事件名、参数说明和 API 文档来自网易开发者文档。 Minecraft 和网易产品名称归各自权利人所有。本项目与网易没有关联，也未获得网易 官方认可。详细信息见源码包中的 THIRD_PARTY_NOTICES.md。

许可证

本项目采用 MIT License 发布。网易 Mod SDK 的版权、商标和许可信息仍 以其官方发布内容为准。