如果这个项目对你有帮助, 请点一个 ⭐ Star 支持一下吧!
If you find this project useful, please give it a ⭐ Star — it means a lot!
Minecraft 基岩版(Bedrock Edition)服务器端模组加载框架 —— 通过 WebSocket 桥接游戏客户端, 加载并运行你的自定义模组。 A mod loader framework for Minecraft Bedrock Edition — bridges the game client over WebSocket and loads your custom mods.
EnderBridge 是一个用 Python 编写的 MCBE 模组加载器, 它启动一个 WebSocket 服务器等待游戏客户端连入, 并以「客户端 Mod / 服务端 Mod」两层结构加载扩展。内置 AI 对话、QQ 群互通、音乐播放、图片转像素画、Ezmatic 建筑导入等模组, 开箱即用。
EnderBridge is a Python-based mod loader for Minecraft Bedrock Edition. It runs a WebSocket server waiting for game clients, then loads extensions in a two-layer architecture of Client Mods / Server Mods. It ships with built-in mods: AI chat, QQ bridge, music playback, image-to-pixel-art, and Ezmatic build import — ready to use out of the box.
- 🧩 模组加载框架 / Mod loading framework:客户端 Mod(每个连接实例化)与服务端 Mod(静态)两层架构, 动态导入 + 热重载
- 🌐 WebSocket 桥接 / WebSocket bridge:默认监听
8800端口, 支持多客户端并存, 首个连接自动成为主客户端 - 🌐 Web 管理界面 / Web console:每次启动自动监听
18888(可配置), 浏览器管理权限、功能开关与仪表盘 - 🤖 AI 对话 / AI chat:OpenAI 兼容接口(默认 DeepSeek), 支持对话 / 指令两种模式
- 💬 QQ 群互通 / QQ bridge:通过 NapCat(OneBot v11 协议)实现 QQ 群消息与游戏内消息双向转发
- 🎵 音乐播放 / Music playback:解析 MIDI/JSON 音乐, 映射为游戏内
playsound音效 - 🖼️ 图片像素画 / Image to pixel art:按 HSV/LAB 颜色匹配调色板, 自动生成 MC 像素画
- 🏗️ Ezmatic 导入 / Ezmatic import:解析 Java 版
.litematic建筑并转换为基岩版结构 - 🤖 假人 Bot / Fake player bot:通过
bedrock-protocol连接 MCBE 服务器, 生成出现在 Tab 列表和游戏世界中的假人玩家(离线模式无需 Xbox Live) - 🛡️ 权限系统 / Permission system:owner / op / user / blocker 四级权限, 命令分级执行
- 🚦 命令限流 / Command rate limit:按玩家分桶的窗口限流, 防刷屏
- 🔧 图形化配置向导 / Web setup wizard:首次运行自动打开浏览器向导(
http://127.0.0.1:18888), 无需手改配置 - 🩹 依赖自愈 / Dependency self-healing:缺少依赖自动安装;
config.py/permission.json缺失自动从模板生成 - 🔄 更新后自动跳转 / Auto-redirect after update:WebUI 更新完成后自动探测服务器恢复并跳转到仪表盘, 支持端口偏移检测与超时重试
- 🗺️ 跨平台路径兼容 / Cross-platform paths:Windows / Android / Linux 统一相对路径写法
| 项目 / Item | 要求 / Requirement |
|---|---|
| Python | 3.12+ |
| Node.js | 假人 Bot 功能需要 / Required for fake player bot feature |
| 游戏 / Game | Minecraft 基岩版(支持 WebSocket 连接, 如 BDS 服务器 / 基岩版客户端) Minecraft Bedrock with WebSocket support (e.g. BDS server / Bedrock client) |
| QQ(可选 / optional) | NapCat 等 OneBot v11 实现 / NapCat or other OneBot v11 implementations |
依赖清单 / Dependencies(requirements.txt):websockets、Pillow、mido、openai、websocket-client
python setup.py直接运行
python main.py时也会自动检测依赖, 缺失会自动调用setup.py安装。 Runningpython main.pyalso auto-detects missing dependencies and invokessetup.py.
python main.py首次运行(或 config.example.json 中 is_first_run = True)会自动启动图形化WebUI配置向导, 浏览器访问 http://127.0.0.1:18888 完成配置:
On first run (or when is_first_run = True in config.example.json), the web setup wizard starts automatically. Open http://127.0.0.1:18888 in your browser to configure:
- 服务器名称、WebSocket 端口、命令前缀、日志等级 / Server name, WebSocket port, command prefix, log level
- 基础模组 / 高级模组勾选:客户端 / 服务端各模组开关, 勾选后自动显示对应配置区(AI 对话、音乐、QQ 群互通、刷屏等)/ Toggle client / server mods; checking a mod reveals its config section (AI, music, QQ bridge, spam, etc.)
- AI API Key / Base URL / 对话模型 / 指令模型 / 对话冷却 / AI API Key / Base URL / chat model / command model / chat cooldown
- 音乐打击乐开关、QQ 桥接(群号 / 主机 / 端口 / 访问令牌)/ Music percussion toggle, QQ bridge (group ID / host / port / access token)
- 刷屏设置(攻击文本 / 广告文本 / 推送间隔, 用于
$spam模组)/ Spam settings (attack / ad text / interval, used by the$spammod) - 玩家权限(服主 / 管理员 / 普通用户 / 屏蔽名单)/ Player permissions (owner / op / user / blocker)
- 资源路径(音乐 / MCFunc / Ezmatic / 图片, 按勾选模组显示)/ Resource paths (music / MCFunc / Ezmatic / pictures, shown per enabled mod)
- 高级配置(折叠区):命令限流、Web 管理界面(端口 / 令牌)、SAPI 指令、Utils 开关 / Advanced (collapsible): rate limit, Web console (port / token), SAPI commands, Utils toggles
保存后自动生成配置文件(旧文件备份为 .bak), 服务器自动启动, 无需手动重启。
After saving, the config files are generated (old files backed up as .bak). The server starts automatically — no manual restart needed.
每次启动服务器时, Web 管理界面会自动监听配置的端口(默认 18888)。浏览器打开 http://127.0.0.1:18888 即可管理:
On every server start, the Web management console listens on the configured port (default 18888). Open http://127.0.0.1:18888 in your browser:
- 📊 仪表盘 / Dashboard:服务器名称、端口、客户端连接数、运行时间, 一键重启服务器(优雅关闭后自动以相同参数重启进程);根路径
/直接进入仪表盘 / Server name, port, connected clients, uptime, one-click server restart; root path/goes directly to dashboard - 👥 权限管理 / Permissions:基于用户名和密码的用户权限系统, 角色 + 细粒度权限覆盖, 保存后即时生效 / Username & password-based user permission system with role-based granular permissions, applied immediately
- ⚙️ 功能设置 / Settings:修改名称、端口、命令前缀、日志等级、音乐 / QQ 开关、命令限流与 Web 管理端口 / Edit server settings, feature toggles, rate limit and Web console port
- 🧩 Mod 管理 / Mods:查看已加载的客户端 / 服务端 Mod 及其可导入状态, 一键重载服务端 Mod / View loaded mods and reload server mods
配置存放于 config.json 的 webuiConfig 块:
{
"webuiConfig": {
"enabled": true,
"port": 18888
}
}首次运行时终端会显示 admin 的随机密码。访客账户 guest 无需密码, 仅可查看仪表盘和 Mod 列表。
建议在非本机访问时修改 admin 密码。部分设置(如名称 / 端口)保存后需重启服务器生效, 权限与 Mod 重载即时生效。
- 让游戏客户端连接到 WebSocket 服务器(端口与向导中配置的一致, 默认
8800)/ Connect your game client to the WebSocket server (port as configured, default8800) - 第一个连接成为主客户端 / The first connection becomes the main client
- 在游戏内使用命令前缀(默认
$)调用各模组命令, 例如$help查看全部命令帮助 / Use the command prefix (default$) in-game to call mod commands, e.g.$help
所有内置模组统一使用单入口命令:<前缀><模组入口> <方法> <参数...>, 例如:
All built-in mods share a single-entry command format: <prefix><entry> <method> <args...>.
| 模组 / Mod | 入口 / Entry | 示例 / Example |
|---|---|---|
| 工具 / Tool | tool |
$tool reload Ezmatic |
| 命令帮助 / Help | help |
$help 2(分页) |
| 图片 / Image | image |
$image create demo.png |
| 音乐 / Music | music |
$music run <文件> |
| 坐标 / Position | pos |
$pos a、$pos fill <方块> |
| 权限 / Permission | perm |
$perm query Steve |
| 函数 / MCFunc | function |
$function function <路径> |
| 外接 WebSocket / MoreWS | ws |
$ws connect ws://127.0.0.1:8080 |
| QQ 互通 / QQ | qq |
$qq send 你好 |
| AI 对话 / AI | ai |
$ai chat 你好 |
| 终端 / 聊天 / Terminal | chat |
$chat list(终端与游戏内均可用) |
| 刷屏 / Spam | spam |
$spam stop(终端与游戏内均可用) |
| 消息通知 / Message | message |
$message <消息内容>(仅终端可用) |
| Ezmatic 建筑 / Ezmatic | ezmatic |
$ezmatic preview <文件> |
| 假人 / Bot | bot |
$bot spawn Steve(需要 Node.js + 启用 Bot Mod) |
全局 help 命令($help [页码])分页显示全部命令;每个入口输入 help 可查看该模组的全部方法:$tool help、$music help……
The global help command ($help [page]) lists all commands with paging; type help after any entry to list its methods: $tool help, $music help, ...
| 命令 / Command | 说明 / Description |
|---|---|
python main.py |
正常启动服务器 / Start the server normally |
python main.py --load-without-config |
忽略配置文件, 直接启动服务器(仅用于调试)/ Start the server without loading config (debug only) |
python main.py --help |
显示帮助信息 / Show help information |
python main.py -h |
相当于--help参数 / Equivalent to the --help argument |
python main.py --reset-all |
一键重置:删除 config.py / permission.json 及其备份, 并将模板复位为首次运行状态 / Reset all configs and restore first-run state |
python main.py update <压缩包> |
一键升级:从新版本压缩包(zip / tar.gz)升级, 保留设置与用户数据 / Upgrade from a release archive, keeping your settings |
python main.py export [输出路径] |
一键导出:将项目代码打包为 zip(排除用户数据), 配合 update 使用 / Export code as a zip (user data excluded), pairs with update |
python main.py --version |
查看当前EnderBridge版本 / View the current version |
python main.py -v |
相当于--version参数 / Equivalent to the --version argument |
python setup.py |
安装 / 检测依赖 / Install / check dependencies |
python setup.py --check |
仅检测依赖是否齐全 / Check dependencies only |
下载新版压缩包(GitHub Release 的 zip / tar.gz 均可), 然后运行:
python main.py update path/to/your/update/file.zip升级过程:
- 自动识别压缩包内层目录(如
EnderBridge-main/)并剥离 - 校验压缩包确实是 EnderBridge(含
main.py/lib/)后才开始覆盖 - 覆盖代码文件, 保留 配置文件及其备份、
resources/、structures/、logs/、.git/和自定义文件 - 完成后提示重启:
python main.py
校验失败或压缩包损坏时不会改动任何现有文件。若新版配置模板结构变化, 启动异常时可运行
python main.py --reset-all重置配置。
把当前项目代码打包成 zip, 方便分发/更新其他实例:
python main.py export
# 或指定输出路径
python main.py export D:/backup/enderbridge.zip导出内容:
- 默认输出到项目上级目录
EnderBridge_export_<时间戳>.zip(不指定路径时) - 打包全部代码与模板(
main.py/lib//mod//webui//wiki//config.example.json/permission.example.json等) - 自动排除用户数据:
config.py/permission.json及其备份、logs/、resources/、structures/、.git/、__pycache__/等 - 导出的压缩包可直接用于:
python main.py update <该压缩包>
EnderBridge/
├── main.py # 入口:依赖自愈、配置生成、向导、WebSocket 服务器、Web 管理、一键升级 / Entry: self-healing, config gen, wizard, WS server, Web console, one-key upgrade
├── config.py # 真实配置(由向导生成)/ Actual config (generated by wizard)
├── config.example.json # 配置模板(含 is_first_run 标记)/ Config template
├── permission.json # 玩家权限(由向导生成)/ Player permissions (generated by wizard)
├── setup.py # 依赖安装器 / Dependency installer
├── lib/ # 核心库 / Core library
│ ├── command.py # 命令框架(前缀、参数解析、限流)/ Command framework
│ ├── mods.py # Mod 管理器(事件总线、动态导入、热重载)/ Mod manager
│ ├── utils.py # WebSocket 工具(命令发送、事件订阅)/ WebSocket utilities
│ ├── sapi.py # SAPI 桥接(gmsg / smsg 与服务器通信)/ SAPI bridge
│ ├── permission.py # 权限管理(四级权限、原子写入)/ Permission manager
│ ├── logger.py # 分级日志(控制台 + ./logs, 北京时间)/ Logging
│ ├── setup.py # 图形化配置向导(HTTP 18888, 仅首次运行)/ Setup wizard (first run only)
│ └── ...
├── webui/ # Web 管理界面 / Web management console
│ ├── server.py # 后端:HTTP 服务 + REST API(/api/config、/api/permissions、/api/mods 等)/ Backend: HTTP + REST API
│ └── index.html # 前端:登录 + 仪表盘 / 权限 / 功能设置 / Mod 管理(单文件)/ Frontend SPA (single file)
└── mod/ # 模组目录 / Mods directory
├── ai.py # AI 对话模组 / AI chat mod
├── mcfunc.py # .mcfunction 执行(嵌套、定时循环)/ .mcfunction executor
├── message.py # 消息通知 Mod / Message notification mod
├── morews.py # 扩展 WebSocket 双向转发 / Extra WebSocket forwarder
├── music.py # MIDI 音乐播放 / MIDI music player
├── permission.py # 游戏内权限命令 / In-game permission commands
├── position.py # 坐标 / 区域 / 结构操作 / Position & structure ops
├── read.py # 终端交互 / 聊天模组 / Terminal & chat mod
├── spam.py # 刷屏模组(attack/count/crash/clear/ad/repeat/stop)/ Spam mod
├── tool.py # 工具 / 命令帮助 / 管理 / Tools & command help
├── image/ # 图片转像素画 / Image to pixel art
├── ezmatic/ # Ezmatic 建筑导入 / Ezmatic build import
├── qq/ # QQ 群互通(NapCat)/ QQ bridge (NapCat)
└── bot/ # 假人 Bot(Node.js bedrock-protocol)/ Fake player bot
| 模组 / Mod | 加载位置 / Load | 功能 / Description |
|---|---|---|
AI |
客户端 + 服务端 / Client + Server | 与 AI 模型对话(单次 / 上下文模式)/ Chat with AI (single / context mode) |
Bot |
客户端 / Client | 假人管理:生成 / 移除 / 传送 / 聊天(通过 Node.js bedrock-protocol 连接 MCBE 服务器)/ Fake player: spawn / remove / move / chat |
PermissionCommands |
客户端 / Client | 游戏内权限查询与增删($perm query / $perm add / $perm remove)/ In-game permission management |
Tool |
客户端 / Client | 全局命令帮助($help 分页)、搜索、终端执行、SAPI 控制 / Command help, search, terminal exec |
Position |
客户端 / Client | A/B 点标记、距离计算、区域填充、结构复制 / 粘贴 / 剪切 / Coordinates & structure ops |
Music |
客户端 / Client | 解析 MIDI/JSON 并播放为游戏音效 / Play MIDI/JSON as in-game sounds |
MCFunc |
客户端 / Client | 加载执行 .mcfunction 文件, 支持嵌套与定时循环 / Run .mcfunction files |
MoreWS |
客户端 / Client | 同时连接多个外部 WebSocket 服务端并双向转发 / Multi-WebSocket forwarding |
Ezmatic |
客户端 / Client | .litematic 建筑导入、预览、修复、导出 .mcstructure / Build import & export |
ImageMod |
客户端 / Client | 图片转 MC 像素画(HSV/LAB 颜色匹配)/ Image to pixel art |
Message |
客户端 / Client | 消息通知:管理员从终端向全体玩家发送聊天广播(仅终端可用)/ Admin broadcast from the terminal to all players |
QQ |
客户端 / Client | QQ 群消息与游戏内消息互通 / QQ ↔ in-game chat bridge |
chat |
服务端 / Server | 终端交互与聊天命令:重载 Mod、列出连接、测试、换行发言等 / Terminal & chat commands: reload, list, test, line. 终端无权限限制;游戏内 line 方法需 op 权限 |
spam |
服务端 / Server | 刷屏命令:attack/count/crash/clear/ad/repeat/stop / Spam commands: attack/count/crash/clear/ad/repeat/stop. 终端无权限限制;游戏内方法均需 op 权限 |
| 配置项 / Key | 默认值 / Default | 说明 / Description |
|---|---|---|
wsConfig.name |
"EnderBridge" |
WebSocket 服务器名称 / Server name |
wsConfig.port |
8800 |
WebSocket 端口 / WebSocket port |
commandPrefix |
$ |
游戏内命令前缀 / In-game command prefix |
logLevel |
"info" |
日志等级 / Log level:debug < info < warning < error |
rateLimit.command |
enabled: False, windowMs: 1000, maxPerWindow: 20 |
命令限流:开关、时间窗口(毫秒)、窗口内最大次数 / Rate limit: toggle, window (ms), max per window |
features.qq |
关闭 / off | QQ 桥接:群号、主机、端口、访问令牌 / QQ bridge settings |
webuiConfig |
enabled: True, port: 18888, token: "" |
Web 管理界面:启用开关、监听端口、管理令牌(非空需登录)/ Web console: toggle, port, admin token |
AIConfig |
DeepSeek | AI 对话 / 指令模型、API Key、Base URL / AI models & API |
sapiConfig |
gmsg / smsg |
与服务器 SAPI 通信的命令名 / SAPI command names |
配置同时兼容驼峰与下划线写法(
rateLimit/rate_limit等), 方便不同习惯。 Both camelCase and snake_case keys are supported (rateLimit/rate_limit, etc.).
四级权限 / Four levels:owner(服主, 全部权限 / full access)→ op(管理员 / admin)→ user(普通用户 / normal user)→ blocker(屏蔽名单 / blocked)。可在配置向导中填写, 或由游戏内命令维护。Set in the wizard or via in-game commands.
graph LR
A[MCBE 客户端<br/>WebSocket 连接] --> B[EnderBridge 服务器<br/>端口 8800]
B --> C[lib/utils.py<br/>命令发送 / 事件订阅]
C --> D[客户端 Mod<br/>每个连接实例化]
B --> E[服务端 Mod<br/>静态加载]
B --> F[SAPI 桥接<br/>gmsg / smsg]
B --> G[NapCat OneBot<br/>QQ 群互通]
B --> H[OpenAI 兼容接口<br/>AI 对话]
B --> I[外部 WebSocket<br/>MoreWS 转发]
B --> J[Node.js Bot<br/>bedrock-protocol]
- 客户端 Mod / Client Mods:每个连接独立实例化, 处理游戏内命令(
onCommand)与消息(onPocket)/ Instantiated per connection, handle in-game commands and messages - 服务端 Mod / Server Mods:静态加载, 处理服务器侧消息(
on_message)/ Loaded statically, handle server-side messages - 主客户端断开后全局状态自动重置, 重连即恢复 / Global state resets when the main client disconnects; auto-recovers on reconnect
Q:首次启动没有自动打开配置向导?/ The wizard doesn't open on first run?
检查 config.example.json 中 is_first_run 是否为 True, 或运行 python main.py --reset-all 复位后重启(向导仅在首次运行时启动)。日常管理请使用 Web 管理界面:启动服务器后访问 http://127.0.0.1:18888。
Check is_first_run in config.example.json, or run python main.py --reset-all to reset and restart (the wizard only starts on first run). For daily management, use the Web console at http://127.0.0.1:18888 after starting the server.
Q:向导保存报「模板匹配失败」?/ Wizard reports "template match failed"?
确保 config.example.json 未被手动改动关键字段格式(向导按模板结构读取并填充用户输入)。
Ensure config.example.json keeps its original format (the wizard reads the template structure and fills in user input).
Q:命令前缀改了不生效?/ Command prefix change doesn't take effect?
前缀从 config.py 的 commandPrefix 读取, 修改后需重启服务器。
The prefix is read from commandPrefix in config.py; restart the server after changes.
Q:提示缺少依赖?/ Missing dependencies?
运行 python setup.py 手动安装, 或直接运行 python main.py 让其自动安装。
Run python setup.py, or just run python main.py to auto-install.
Q:如何在 Android / Linux 上运行?/ How to run on Android / Linux?
项目已内置平台检测与路径适配(resolvePath), 统一使用相对路径即可跨平台运行。
Platform detection and path adaptation (resolvePath) are built in; use relative paths to run anywhere.
Q:假人 Bot 怎么用?/ How to use the fake player bot?
- 在配置向导或 WebUI 中启用 Bot Mod 并配置服务器地址(默认
127.0.0.1:19132) - 确保系统已安装 Node.js 16+
- 在游戏内执行
$bot start启动 Bot 进程 - 执行
$bot spawn <玩家名>生成假人 - 假人会出现在 Tab 列表和游戏世界中, 可通过
$bot move/$bot chat/$bot remove管理 See wiki section "8. 内置模组详解 → Bot 假人详解" for details.
欢迎提交 Issue 和 Pull Request!请先阅读 贡献指南 / Contributing Guide。
Issues and PRs are welcome! Please read the Contributing Guide first.
本项目基于 GPL-3.0 许可证开源, 仅供学习交流使用。Minecraft 及相关名称、商标归 Mojang Studios 所有。
This project is open-sourced under the GPL-3.0 license. Minecraft and related names/trademarks belong to Mojang Studios.
You should try our sister project: ModLoader-WS-For-MCBE
EnderBridge · Minecraft Bedrock 服务器管理框架
Powerd by Hydrooxzgen(Hydrooxygen)