Metadata-Version: 2.4
Name: mc-netease-sdk-stubs
Version: 3.9.0.79920
Summary: Type stubs for the NetEase Minecraft Python Mod SDK
Author: mc-netease-sdk-types contributors
License: MIT
Project-URL: NetEase Mod SDK documentation, https://mc.163.com/dev/mcmanual/mc-dev/mcdocs
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Stubs Only
Requires-Python: >=2.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typing>=3.7.4; python_version < "3.5"
Requires-Dist: typing-extensions<4,>=3.7.4; python_version < "3.8"
Requires-Dist: typing-extensions>=4.4; python_version >= "3.8"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# mc-netease-sdk-stubs

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

当前版本对应 `mc-netease-sdk 3.9.0.79920`，覆盖官方包中的 294 个模块、
282 个引擎事件以及事件回调参数。该项目不是网易官方项目，API 行为仍以
[网易 Mod SDK 文档](https://mc.163.com/dev/mcmanual/mc-dev/mcdocs/1-ModAPI/%E6%8E%A5%E5%8F%A3/Api%E7%B4%A2%E5%BC%95%E8%A1%A8.html?catalog=1)
和实际游戏版本为准。

## 功能

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

## 版本对应

| 类型库版本 | 网易 SDK 版本 | Python 运行环境 |
| --- | --- | --- |
| `3.9.0.79920` | `3.9.0.79920` | Python 2.7 |

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

## 安装

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

```powershell
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 安装合并。

从源码安装时使用：

```powershell
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
代码引用事件参数类型时，可以定义一个不依赖外部库的类型检查标记：

```python
TYPE_CHECKING = False

if TYPE_CHECKING:
    from mod.common.event_types import AddEntityClientEventArgs
```

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

## 事件补全

```python
# 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` 使用全部引擎事件集合。自定义事件仍可直接传入任意字符串。

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

```text
AddEntityClientEvent 回调参数。

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

## 开发与验证

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

```powershell
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 执行：

```powershell
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](LICENSE) 发布。网易 Mod SDK 的版权、商标和许可信息仍
以其官方发布内容为准。
