QueQiao MCDR

A MCDReforged plugin bridging the QueQiao V2 protocol, supporting both forward WebSocket (client) and reverse WebSocket (server) connection modes for real-time message exchange between a Minecraft server and external systems (e.g. NoneBot / QueQiao server).

📖 Compatible Projects

This plugin follows the QueQiao V2 protocol and can interoperate with:

• UniBot — A cross-platform Minecraft bot; this plugin serves as its MCDR endpoint
• nonebot-adapter-minecraft — A NoneBot adapter for Minecraft that communicates with this plugin via the QueQiao protocol
• QueQiao — The official QueQiao protocol implementation

✨ Features

Connection

• 🔌 Dual-mode WebSocket: client mode actively connects to the QueQiao server; server mode passively waits for QueQiao clients
• 🔁 Auto-reconnect (client mode): configurable reconnect interval and max retry count
• 🔥 Hot reload: !!queqiao reload reloads config and reuses the existing connection without restarting the server

API Handling (QueQiao → MCDR)

API	Description
broadcast	Broadcast a message to the game
send_private_msg	Send a private message to a specific player
send_title	Send a title/subtitle (configurable fade-in/stay/fade-out)
send_actionbar	Send an ActionBar message
send_rcon_command	Execute a RCON command and return the result
get_status	Query server status (CPU/memory/players/MOTD, etc.)

Game Event Forwarding (MCDR → QueQiao)

Event	Source
Player join / quit	MCDR built-in events
Player chat / command	MCDR USER_INFO event
Player death	MoreGameEvents PlayerDeathEvent
Player advancement	MoreGameEvents PlayerAdvancementEvent

📦 Installation

Option 1: Download the .mcdr package

Download QueQiao-vX.X.X.mcdr from Releases and drop it into the MCDR plugins/ directory.

Option 2: From source

git clone https://github.com/Minecraft-UniBot/QueQiao.MCDReforged.git
cd QueQiao.MCDReforged
uv sync

Use the whole directory as a Directory Plugin, or pack it yourself:

uv run python -m mcdreforged pack

🎮 Commands

Command	Permission	Description
!!queqiao	2	Show help
!!queqiao status	2	View connection status (mode, players, CPU, memory, MOTD, etc.)
!!queqiao reload	2	Reload config and reconnect

📋 Dependencies

Runtime

• MCDReforged >= 2.15.0
• Python >= 3.12

Python packages

• websockets >= 16.0
• PyYAML >= 6.0
• psutil >= 5.9

MCDR plugin dependencies

Plugin	Usage	Required
MoreGameEvents	Player death & advancement events	✅
Minecraft Data API	Player coords, health, XP level	✅
online_player_api	Online player list	⚠️ Optional (falls back to MCDR built-in API if missing)

�📄 License

MIT