图形界面 · mcpy ui

mcpy ui 是 Windows 和 macOS 共用的图形化项目管理器。它把依赖、测试世界、游戏会话和运行时调试放在同一个窗口中，适合希望通过按钮与表单完成日常开发的用户。它与 CLI、VS Code 扩展共用同一套项目和会话能力。

打开项目管理器

在已初始化的项目目录中运行：

mcpy ui

也可以明确指定项目目录：

mcpy --local --project /path/to/addon ui

尚未初始化的项目，先按第一个项目准备 pyproject.toml。管理器顶部显示当前项目与路径，操作前先确认没有打开错误的项目。

mcpy ui：先认识三个主要区域放大查看 ↗

1. 1

   左侧管理依赖：选择 Python 包、本地 Addon 或 Git 来源，并同步项目声明。

2. 2

   右侧管理测试世界：选中实例后启动，也可接管已经运行的会话。

3. 3

   下方切换“操作”“Debug 日志”“Python / 热更”，查看准备结果或调试游戏。

截图来自本机 macOS 的 Hello Addon 示例。Windows 使用相同的主要布局，MCEditor 和部分运行能力由平台决定；按钮名称和布局以当前安装的版本为准。

添加与同步依赖

左侧“添加新依赖”提供三类入口：

类型	如何填写	用途
Python 包（工具环境）	包名或版本约束	准备宿主开发工具依赖；不会自动进入游戏
本地 Addon 目录	浏览或填写 Addon 根目录，核对路径预览	同机协作开发公共组件；可选择保存为相对或绝对路径
Git 依赖（项目与代码库）	仓库、引用及可选布局字段	读取远端项目或代码库，添加后锁定提交

用表单添加 Git 依赖放大查看 ↗

1. 1

   先切到“Git 依赖”；接入 QuMod 可使用快捷按钮及其下拉菜单。

2. 2

   填写仓库与引用；子目录、安装位置和导出类型用于指定仓库布局。

3. 3

   “添加 Git 依赖”写入新声明；“同步项目依赖”恢复已有声明锁定的代码。

接入 QuMod：切到 Git 类型，点击“一键添加 QuMod”。按钮右侧下拉菜单还可切换来源或指定 Mod 脚本目录；已有业务入口不会被直接重写。

恢复已有依赖：点击“同步项目依赖”，按声明与锁文件恢复项目。移除依赖：先在列表中选中项目，再点击“移除选中依赖”；移除本地引用不会删除源目录。

依赖变化不会自动替换正在运行的游戏代码。来源、锁文件和组装规则见依赖与 QuMod。

创建 Mod 与准备运行环境

顶部的“新建 Mod”用于选择框架、名称和脚本目录并生成模板。已有文件需要保留时，先核对目标目录；框架依赖也可以从左侧 QuMod 入口加入。

“运行环境”用于准备游戏资源。在 Apple Silicon Mac 上，默认自动获取原生运行包和匹配的网易开发者 APK；已有本地 APK 或自定义运行包来源时，展开“高级安装选项”。

运行环境的默认准备与高级选项放大查看 ↗

1. 1

   默认来源无需填写；自定义运行包或已有开发者 APK 才需要展开并填写高级选项。

2. 2

   核对准备说明后使用“安装／修复”；安装新资源不会自动迁移已有世界。

资源缺失时，首次运行也会进入准备流程，下载和提取信息会显示进度。已有世界固定的运行资源不会因为安装新资源而自动迁移，详见 macOS 平台。

Windows 上“使用 MCEditor 编辑”打开 MC Studio Editor；macOS 上会明确禁用这个入口。

新建或继续测试世界

1. 在“游戏实例列表”中选择已有世界，点击“启动选中实例”，继续原存档。
2. 需要新的独立测试存档时，点击“新建实例”。
3. 在确认框中展开“世界设置”，填写名称、种子、地形、模式、难度和游戏规则，再点击“创建并运行”。

新建实例时展开世界设置放大查看 ↗

1. 1

   点击“世界设置”展开表单；默认收起时也可以直接创建。

2. 2

   选择世界名称、种子、地形、模式、难度与权限；继续向下滚动可设置游戏规则。

3. 3

   核对顶部摘要后点击“创建并运行”；设置属于新实例，已有世界不会被改写。

“新建实例”右侧菜单还支持从 cppconfig 新建，或按选中实例配置新建。它们复用的是创建参数，不是复制原存档进度。已连接游戏时，先明确停止当前会话，再创建另一个世界。

“删除选中实例”和“清空所有实例”会涉及存档删除，不用于修复启动错误。创建参数的完整含义见本地世界。

接管会话与联调

游戏已由 CLI 或 VS Code 启动时，点击“接管已有会话…”，从列表选择会话或联调组。接入后即可查看日志和使用调试入口，无需重复启动游戏。

“连接服务器…”依次询问服务器地址、端口和本机客户端数量，用于无认证开发服务器测试。网络会话不装配本地 Addon，也不提供外部服务端 Python。详见连接服务器。

“双客户端联调”用于支持该能力的平台。本地主客机启动后，客机可能需要在游戏局域网卡片中手动加入；管理区提供成员选择、合并日志、重启或停止联调组。macOS 当前不支持本地主客机模式，不能以按钮存在判断能力已可用，详见双客户端。

查看与搜索日志

下方的三个标签用途不同：

• 操作：依赖准备、启动及操作结果。
• Debug 日志：持续查看游戏、引擎或启动器输出。
• Python / 热更：发送游戏内代码并读取结果。

在 Debug 日志中定位组件输出放大查看 ↗

1. 1

   选择 game、engine、worker 或 operations 来源；需要时展开协议详情。

2. 2

   输入组件名或错误关键词，使用上一个／下一个按钮跳转匹配结果。

3. 3

   结合实际组件日志确认加载结果；进程 running 本身不等于 Mod 已成功加载。

Debug 日志支持切换来源、展开协议详情、搜索与上下条匹配跳转。时间戳、错误、警告、引擎和 Mod 标签分别染色。切换视图使用同一份日志缓存，完整原始日志仍保存在项目会话目录中。

执行游戏内 Python

选择“Python / 热更”标签，核对当前会话，输入代码，明确选择 client 或 server 后执行。

选择端侧，执行代码，再看返回结果放大查看 ↗

1. 1

   先核对当前会话，再输入游戏内 Python。本例调用 Hello Addon 中的只读坐标查询函数。

2. 2

   选择 client 或 server，再点击“执行 Python”。两端使用各自的游戏运行环境。

3. 3

   在下方读取真实结果。本次游戏返回了玩家坐标；执行状态和玩法效果需要分别判断。

图中调用的是示例项目自己的 player_position() 函数。你的项目也可以直接使用 ModSDK，例如在客户端读取玩家坐标：

import mod.client.extraClientApi as clientApi
player_id = clientApi.GetLocalPlayerId()
position = clientApi.GetEngineCompFactory().CreatePos(player_id).GetPos()
print(position)

代码由所选游戏进程执行，受游戏内 Python 与 ModSDK 约束。网络会话只能选择可用的客户端能力。结果未知时先查询原会话，避免重复执行有副作用的代码。

手动热更、自动热更与重载世界

分清接管、热更和重载世界放大查看 ↗

1. 1

   “接管已有会话”连接已运行的游戏，方便找回日志与调试入口。

2. 2

   “热更文件”更新已加载模块；入口、类结构或事件注册变化时使用“重载世界”。

3. 3

   先确认监控端侧，再开启“自动热更”；停止监控会保留游戏。

操作	适合的变化
热更文件…	更新已加载 Python 模块；选择文件并核对执行端侧
自动热更	持续监控源码并更新支持热更的模块；先选择 client、server 或适合的 both
重载世界	停止游戏、重新部署并打开同一世界；用于事件注册、类结构、依赖或入口变化

启动前也可勾选“运行并监控 Python”，让游戏启动后进入监控。停止监控会保留游戏。模块热更不会重建已有对象、替换已注册回调或撤销旧副作用；文件删除和不支持的资源变化需要重载世界。更多说明见运行时调试。

紧凑调试小窗

连接会话后，点击“打开日志小窗”，可以把调试入口放在游戏旁边：

• 日志：展开或收起日志与 Python 标签。
• 操作：热更、重载世界、停止游戏及自动热更设置。
• 置顶：保持小窗在游戏上方。

小窗与主界面共用会话和日志，不会因为重新打开而另起一个游戏。普通交互式 mcpy run 也会打开辅助小窗；--no-gui、--detach、--json、--non-interactive 会抑制它。

关闭窗口与结束测试

关闭管理器或调试小窗会保留游戏；关闭管理器前会结束它创建的监控。明确结束测试时点击“停止游戏”或使用 CLI stop，重要存档先在游戏中正常保存。进行中的准备与操作需要先完成或取消，不能把窗口关闭当作退出已确认。

GUI 基于 Qt6；安装 mcpywrap 时会安装 PySide6-Essentials。Qt 自身的最低系统要求以实际依赖包为准，不能用游戏原生运行包的系统要求推断。