Skip to content

Repository files navigation

EnderBridge

如果这个项目对你有帮助, 请点一个 ⭐ Star 支持一下吧!
If you find this project useful, please give it a ⭐ Star — it means a lot!

Star EnderBridge Fork EnderBridge Watch EnderBridge

License: GPL-3.0 Release Release Date Python 3.12+ Node.js Required Last Commit Issues


⛏️ EnderBridge

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.


✨ 特性 / Features

  • 🧩 模组加载框架 / 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 统一相对路径写法

📦 环境要求 / Requirements

项目 / 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):websocketsPillowmidoopenaiwebsocket-client


🚀 快速开始 / Quick Start

1. 安装依赖 / Install dependencies

python setup.py

直接运行 python main.py 时也会自动检测依赖, 缺失会自动调用 setup.py 安装。 Running python main.py also auto-detects missing dependencies and invokes setup.py.

2. 启动 / Start the server

python main.py

首次运行(或 config.example.jsonis_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 $spam mod)
  • 玩家权限(服主 / 管理员 / 普通用户 / 屏蔽名单)/ 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 管理界面 / Web Management Console

每次启动服务器时, 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.jsonwebuiConfig 块:

{
  "webuiConfig": {
    "enabled": true,
    "port": 18888
  }
}

首次运行时终端会显示 admin 的随机密码。访客账户 guest 无需密码, 仅可查看仪表盘和 Mod 列表。

建议在非本机访问时修改 admin 密码。部分设置(如名称 / 端口)保存后需重启服务器生效, 权限与 Mod 重载即时生效。

3. 在游戏内连接 / Connect from the game

  1. 让游戏客户端连接到 WebSocket 服务器(端口与向导中配置的一致, 默认 8800)/ Connect your game client to the WebSocket server (port as configured, default 8800)
  2. 第一个连接成为主客户端 / The first connection becomes the main client
  3. 在游戏内使用命令前缀(默认 $)调用各模组命令, 例如 $help 查看全部命令帮助 / Use the command prefix (default $) in-game to call mod commands, e.g. $help

4. 命令格式 / Command format

所有内置模组统一使用单入口命令<前缀><模组入口> <方法> <参数...>, 例如:

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, ...


🛠️ 常用命令 / Commands

命令 / 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

一键升级 / Upgrade

下载新版压缩包(GitHub Release 的 zip / tar.gz 均可), 然后运行:

python main.py update path/to/your/update/file.zip

升级过程:

  1. 自动识别压缩包内层目录(如 EnderBridge-main/)并剥离
  2. 校验压缩包确实是 EnderBridge(含 main.py / lib/)后才开始覆盖
  3. 覆盖代码文件, 保留 配置文件及其备份、resources/structures/logs/.git/ 和自定义文件
  4. 完成后提示重启:python main.py

校验失败或压缩包损坏时不会改动任何现有文件。若新版配置模板结构变化, 启动异常时可运行 python main.py --reset-all 重置配置。

一键导出 / Export

把当前项目代码打包成 zip, 方便分发/更新其他实例:

python main.py export
# 或指定输出路径
python main.py export D:/backup/enderbridge.zip

导出内容:

  1. 默认输出到项目上级目录 EnderBridge_export_<时间戳>.zip(不指定路径时)
  2. 打包全部代码与模板(main.py / lib/ / mod/ / webui/ / wiki/ / config.example.json / permission.example.json 等)
  3. 自动排除用户数据:config.py / permission.json 及其备份、logs/resources/structures/.git/__pycache__/
  4. 导出的压缩包可直接用于:python main.py update <该压缩包>

📁 项目结构 / Project Structure

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

🧩 内置模组 / Built-in Mods

模组 / 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 权限

⚙️ 配置说明 / Configuration

核心配置 / Core config(config.py

配置项 / 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.).

权限 / Permissions(permission.json

四级权限 / Four levels:owner(服主, 全部权限 / full access)→ op(管理员 / admin)→ user(普通用户 / normal user)→ blocker(屏蔽名单 / blocked)。可在配置向导中填写, 或由游戏内命令维护。Set in the wizard or via in-game commands.


🔌 架构速览 / Architecture

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]
Loading
  • 客户端 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

❓ 常见问题 / FAQ

Q:首次启动没有自动打开配置向导?/ The wizard doesn't open on first run? 检查 config.example.jsonis_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.pycommandPrefix 读取, 修改后需重启服务器。 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?

  1. 在配置向导或 WebUI 中启用 Bot Mod 并配置服务器地址(默认 127.0.0.1:19132
  2. 确保系统已安装 Node.js 16+
  3. 在游戏内执行 $bot start 启动 Bot 进程
  4. 执行 $bot spawn <玩家名> 生成假人
  5. 假人会出现在 Tab 列表和游戏世界中, 可通过 $bot move / $bot chat / $bot remove 管理 See wiki section "8. 内置模组详解 → Bot 假人详解" for details.

🤝 贡献 / Contributing

欢迎提交 Issue 和 Pull Request!请先阅读 贡献指南 / Contributing Guide

Issues and PRs are welcome! Please read the Contributing Guide first.


📄 许可 / License

本项目基于 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)

About

EnderBridge is a powerful and easy-to-use WebSocket server that comes with lots of built-in features and lets you load third-party mods.

Topics

Resources

Code of conduct

Contributing

Stars

126 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages