mcpywrap

>_ 我的世界中国版 · 命令行开发工具

从代码到世界，
只隔一条命令

用 Python 标准项目与依赖管理方式开发《我的世界》中国版 Mod 和资源包。依赖、构建、打包、进游戏测试都是一条命令，AI Agent 也能自己搭环境、跑游戏、操作和截图验收。

uv tool install mcpywrap

需要 Python 3.9+；装好后运行 mcpy --help。还没有 uv？看uv 安装说明。

快速开始GitHub阅读 Wiki
  • Windows
  • Apple Silicon macOS
  • Android ARM64
  • MIT 开源

01 为什么需要它

补上 MC Studio 缺的那一半

mcpywrap 继续使用 MC Studio 的引擎与编辑器，把它们接进命令行、包管理和自动化测试。

02 AI 自主测试闭环

让 AI 自己进游戏，看完再改

从启动世界到热更代码，每一步都是一条返回 JSON 的命令。AI Agent 可以自己观察画面、操作玩家、截图，再在游戏里执行 Python 读回结果。

  1. 启动本地世界并立即返回会话，后续命令复用同一个 session。

    mcpy run --no-gui --detach --json

  2. HUD 下返回玩家位置、朝向、物品和准星目标；菜单下返回语义 UI 树。

    mcpy runtime input observe --session <sid> --json

  3. 提交 JSON 输入计划：走路、视角、攻击、点 UI。completed 只代表流程完成，效果要再观察。

    mcpy runtime input run --session <sid> --file plan.json --json

  4. 后台截取游戏内容区，不抢前台；窗口被遮挡也能截。

    mcpy screenshot --session <sid> --background-only --output shot.png --json

  5. 在游戏服务端执行 ModSDK Python，读回业务状态做断言。

    mcpy runtime py --session <sid> --side server --file check.py --json

  6. 不重启游戏替换模块；已有对象和回调不会重建，改结构时重新部署并重载世界。

    mcpy runtime reload python --session <sid> --module MyMod.server.logic --side server --json

边界：completed 只代表控制流程完成，效果需要再观察；Python 热更替换模块，不重建已有对象和回调。游戏仍需要图形会话和 GPU。

03 VS Code 游戏测试工作区

在 VS Code 里，完成一轮游戏开发与测试

准备 ModSDK 自动补全，管理项目与测试世界，直接从编辑器启动游戏。 日志实时进入原生输出面板，Python 片段直接在游戏中执行，让修改与验证紧挨着发生。

安装 VS Code 扩展 查看使用指南
干净的 VS Code 工作区：左侧是 Hello Addon 项目结构，中间编写玩家位置查询组件，下方原生输出显示组件加载日志，右侧管理测试世界与游戏会话。状态栏显示已安装的 ModSDK 补全库。
VS Code 实机 · Hello Addon查看原图 ↗
原生日志

游戏日志，就在输出面板里

引擎与脚本系统分流，日志实时更新并按类型染色。搜索、复制、清空与滚动锁定，都是熟悉的 VS Code 操作。

游戏内 Python

写一段代码，直接在游戏里验证

选择会话与客户端或服务端，执行选区或无需保存的独立草稿，在输出面板读取游戏回执。保存项目模块后，也可手动热更。

ModSDK 补全

补全库，装到正在使用的环境里

确认当前文件使用的 Python 环境，安装或切换 ModSDK 补全库。配合 Pylance，在普通 Python 文件中获得 API 提示与代码跳转。

测试工作区

项目、世界与会话，一处管理

自动识别多项目与嵌套项目，在侧栏选择测试世界、查看会话和联调组。从编辑器右上角运行当前项目，继续测试。

支持 Windows / Apple Silicon macOS 本机开发。扩展与 mcpy CLI 配合使用。

插件源码 ↗

04 Android 手机开发

在手机上写模组，看着游戏改代码

mcpy Android 是面向《我的世界》中国版模组开发的手机源码工作台：创建或导入作品，编辑 Python / JSON，构建并启动真实游戏测试。

手机本地开发工作台

在安卓手机上，完成模组开发与测试

创建作品、编辑源码、构建运行、查看日志。游戏显示在小窗里，开发界面继续可用；不用电脑，也能完成一次真实的修改与验证。

下载 Android 预览版
mcpy Android 实机：源码在手机上，游戏在小窗里mcpy Android 实机：搜索日志，对照运行中的游戏mcpy Android 实机：作品、实例和重新测试集中管理mcpy Android 实机：用你习惯的工具，运行同一份作品

直接改源码

源码在手机上，游戏在小窗里

编辑 Python / JSON 文件，保存后直接构建并测试；真实游戏画面留在画中画中，改一行就能看结果。

实时调试

搜索日志，对照运行中的游戏

按客户端、服务端、游戏和引擎切换来源，搜索高亮并过滤匹配内容，代码和现象放在一起看。

作品管理

作品、实例和重新测试集中管理

新建或导入作品，查看当前测试实例，保存退出、查看日志、重新测试都从作品入口完成。

外部工具

用你习惯的工具，运行同一份作品

可搭配 Minis、Termux、编辑器或 AI Agent；外部工具编辑源码，mcpy Android 负责构建、启动和日志。
Android 11+ARM64Nightly 预发布首次使用需在 App 内安装游戏运行环境

05 依赖管理

像普通 Python 项目一样管理 Mod 依赖

在项目中声明需要的前置组件和开发框架，统一管理本地 Addon、Git 依赖和 QuMod。 添加时固定所用的代码提交，队友克隆项目后用 mcpy sync 恢复同一套依赖，打包时自动组装代码与资源。

  1. 这是你的商店玩法项目，负责商品和购买流程。接下来为它加入提供金币功能的经济前置组件。

  2. 运行这条命令，把已有的经济组件加入商店项目。先看这一层关系：商店玩法依赖经济组件。

    mcpy add --git <经济组件仓库URL> --dep-name economy --json

  3. 示例中的经济组件在配置中声明了 QuMod 依赖。mcpywrap 继续准备这一层前置，无需再手动执行一条添加命令。

  4. 将经济组件和 QuMod 所用的代码提交记录到依赖锁文件中，后续同步就能恢复同一套依赖。

  5. 队友拿到商店项目后运行 sync，就能恢复项目里声明的经济组件和 QuMod，不用逐个找仓库、下载和拷贝。

    mcpy sync --json

  6. 把商店玩法、经济组件和 QuMod 的代码与资源按规则组装成一个 ZIP，不用发布前再手动拼包。

    mcpy package --json
示例：一个商店玩法的组件组合
商店玩法组件：商品、购买流程
  ↓ 依赖
经济前置组件：金币余额、扣款
  ↓ 依赖
QuMod：玩法开发框架

游戏前置，要作为组件加入

这里假设经济 Addon 本身基于 QuMod，并在配置中声明了这项依赖；玩法项目只需加入经济组件。mcpy add package-name 安装的普通 Python 包只供开发工具使用，不会自动进入游戏。

依赖与 QuMod 说明 →

06 macOS 原生

Mac 上也能跑中国版 Addon 测试

ARM64 + Metal 原生运行：游戏直接运行在 Apple Silicon 上，使用 Metal 图形后端，无需 CPU 指令转译、Wine 或 Windows 虚拟机。 支持 macOS 13.0+，首次 run 自动准备原生运行包与开发者 APK。后台截图直接读取游戏渲染帧，无需屏幕录制授权。

Apple Silicon Mac 上的游戏实机画面：自然生成的雪山与针叶林中，玩家以第一人称持枪；保留 macOS 窗口标题栏、红绿灯和原生阴影。
Apple Silicon macOS 实机画面
Windows 与 macOS 功能对比
功能WindowsmacOS
依赖管理、构建与打包支持支持
本地 Addon 世界与世界参数支持支持
client / server Python、热更与 JSON UI 重载支持支持
统一输入与后台截图支持支持
连接无认证服务器支持支持
项目界面与日志小窗支持支持
Map 本地运行支持暂不支持
录屏与视频提帧支持暂不支持
原始桌面键鼠支持暂不支持
MCEditor 与 MCS 登录身份支持暂不支持
本地主客机双客户端支持暂不支持

以上对比本机能力，本地主客机联调需手动加入局域网世界。跨平台远程操作见 远程执行。

07 生命周期脚本

构建前，先把资源生成好

在构建、打包、启动前自动运行项目自己的生成器：策划表转 JSON、处理贴图、校验资源。脚本在宿主机运行，失败或超时会中断本次操作。

  1. 只读列出项目定义的脚本与钩子，不执行任务。

    mcpy script list --json

  2. 构建前先跑 before_build：策划表变成 JSON，再进入组装。脚本失败会中断构建。

    mcpy build --json
pyproject.toml
[tool.mcpywrap.scripts.assets]
python = "tools/assets.py"
args = ["--quality", "development"]
timeout = 120

[tool.mcpywrap.hooks]
before_build = ["assets"]
before_package = ["assets"]
before_run = ["assets"]
什么时候执行
操作执行
buildbefore_build 一次，然后组装
packagebefore_package 一次，组装后可接 before_archive
dev首次构建前 before_build 一次
本地 run / restart真正准备新游戏进程时 before_run 一次
runtime reload、connect、远程 run不执行

脚本可读取 MCPY_PROJECT_ROOT、MCPY_EVENT、MCPY_OPERATION。框架依赖还能通过 consumer_prepare 带着自己的工具处理消费项目的素材。脚本对源码的写入不会自动回滚。

08 服务器联调

开发服务端时，让客户端自己连上来

开发 Nukkit 等服务端时，用 mcpy connect 启动开发客户端连上指定服务器，再用同一套会话执行客户端 Python、统一输入和截图来验证服务端逻辑。

  1. 启动两个开发客户端连上你的服务器（例如本机 Nukkit）。

    mcpy connect <服务器> --port 19132 --clients 2 --detach --json

  2. connection_verified=true 才表示确认两名不同玩家在同一世界。

    mcpy status --group <组ID> --json
项目长期固定目标时写进 pyproject.toml，然后直接 mcpy run
[tool.mcpywrap.server]
host = "127.0.0.1"
port = 19132
  • Windows可按次加 --mcs-auth 使用 MC Studio 已登录身份，身份不落盘、日志脱敏
  • macOS无认证连接，已用本机 Nemisys + SynapseAPI + Nukkit 测试栈验证
  • 双客户端--clients 2 建组，组内可统一查状态、看日志、热更，失败客机单独重试

边界：服务器需允许无认证的开发客户端（或配合 MCS 身份）。网络会话不装配、上传或部署本地 Mod，不提供服务端 Python。这是中国版（基岩）客户端，与 Java 版服务端无关。

09 更多能力

日常开发用得上的其他命令

10 快速开始

四条命令进游戏，或者交给 AI

在你的 Addon 目录里
$ uv tool install mcpywrap
$ mcpy init
$ mcpy add --qumod
$ mcpy run

需要 Python 3.9+。Windows 使用 MC Studio 引擎，Apple Silicon Mac 首次运行时自动准备资源。

交给 AI

让 Agent 安装 EaseCation/mcpywrap 仓库的 skills/mcpywrap 目录（或把整个文件夹复制到它的技能目录）。CLI 与 Skill 分开安装。然后直接描述任务：

  • “为这个 Addon 添加 QuMod，并生成分发 ZIP。”
  • “运行前把策划表生成 JSON，检查游戏加载结果。”
  • “保留原世界，用两个客户端验证同步，只重试失败的客机。”
AI 接入说明 →

11 开源

MIT 开源，持续发布到 PyPI

GitHub反馈问题更新记录PyPIWiki