minecraft

Minecraft 插件

minecraft 是 MICQ 内置的 Minecraft 群聊桥接插件。Minecraft 侧通过 QueQiao 暴露 WebSocket，本插件接收并处理游戏事件。

功能

• 游戏聊天同步到 QQ 群。
• QQ 群消息转发到游戏内。
• 玩家上线、下线通知。
• 在线玩家查询。
• QQ 号与 Minecraft 游戏 ID 绑定。
• 绑定用户执行为自己的 give、gamemode 命令。
• 玩家活跃统计查询。
• gamerule 查询和设置。
• 可选的 Minecraft 服务端进程监管。

配置文件

配置路径：

config/plugins/minecraft.yaml

基础配置示例：

groups: [123456789]
admins: []
server:
  name: server
  bridge:
    url: ws://127.0.0.1:8080
    access_token: ""

字段说明：

Minecraft 进程监管

如果需要由 MICQ 启动 Minecraft 服务端，可以配置 supervisor：

server:
  name: server
  bridge:
    url: ws://127.0.0.1:8080
  supervisor:
    root: /srv/minecraft/server
    start: ["./start.sh"]
    restart: never

字段说明：

restart 可选值：

• never：不自动重启。
• on-failure：异常退出时重启。
• always：进程退出后总是重启。

不配置 supervisor.start 时，MICQ 不启动 Minecraft 进程，只连接 QueQiao。

群命令

以下示例假设命令前缀为 /m。

查询在线玩家：

/m list
/m ls

绑定 QQ 号与游戏 ID：

/m bind Steve

机器人会返回一次性验证码。玩家使用对应游戏 ID 进入服务器后，在游戏内发送：

.bind <验证码>

查询或解除绑定：

/m whoami
/m unbind

绑定用户可执行：

/m give minecraft:diamond
/m give minecraft:diamond 3
/m gamemode creative
/m gm survival

游戏规则：

/m gamerule keepInventory
/m gamerule keepInventory true
/m gr doDaylightCycle false

活跃统计：

/m active
/m activity

版本信息：

/m version
/m ver

没有匹配到插件命令的普通群消息，会尝试直接转发到游戏内。

常见问题

提示“当前未连接 Minecraft 服务端”

通常是 QueQiao 连接未建立。请检查：

• QueQiao 是否已启动。
• server.bridge.url 是否与 QueQiao WebSocket 地址一致。
• QueQiao 令牌是否与 server.bridge.access_token 一致。
• MICQ 日志中是否存在 component=bridge 的连接错误。

群内没有响应

请优先检查：

• config/core.yaml 的 onebot.groups 是否包含该群号。
• minecraft.yaml 的 groups 是否为空，或包含该群号。
• OneBot 适配器是否已连接，是否能够上报群消息。

绑定失败

• Minecraft 游戏 ID 只能包含 3 到 16 位字母、数字或下划线。
• 验证码有过期时间，过期后重新发送 /m bind <游戏ID>，再获取一个验证码即可。