koishi-plugin-minecraft-adapter

Koishi 的 Minecraft 适配器插件，基于 鹊桥 (QueQiao) V2 协议，通过 WebSocket 与 Minecraft 服务器交互。

功能特性

• 鹊桥 V2 协议: 完整支持鹊桥 V2 WebSocket 协议
• WebSocket 连接: 通过鹊桥 WebSocket Server 实时接收/发送事件和消息
• RCON 命令执行: 通过鹊桥 WebSocket API send_rcon_command 执行服务器命令
• 多服务器支持: 通过 servers 数组配置多个 Minecraft 服务器，每个服务器独立运行
• 完整事件支持:
  • 玩家聊天 (PlayerChatEvent)
  • 玩家命令 (PlayerCommandEvent)
  • 玩家加入 (PlayerJoinEvent)
  • 玩家离开 (PlayerQuitEvent)
  • 玩家死亡 (PlayerDeathEvent)
  • 玩家成就 (PlayerAchievementEvent)
• 完整 API 支持:
  • 广播消息 (broadcast)
  • 私聊消息 (send_private_msg)
  • RCON 命令 (send_rcon_command)
  • 标题显示 (title)
  • 动画栏 (action_bar)
• 自动重连: WebSocket 断开后指数退避自动重连
• ChatImage 支持: 按服务器独立配置 ChatImage CICode 图片显示

前置需求

• Koishi v4.17.9+
• 鹊桥 (QueQiao) v0.3.0+ 服务端插件/Mod

安装

npm install koishi-plugin-minecraft-adapter

配置

全局配置

服务器配置 (servers[])

每个服务器对应一个独立的 bot 实例。

WebSocket 配置 (servers[].websocket)

RCON（通过鹊桥 WebSocket）

插件侧不再直连 TCP RCON。执行命令时会通过鹊桥 V2 WebSocket API send_rcon_command 发送。

RCON 的启用与密码/端口等配置请在鹊桥端 config.yml 中完成。

ChatImage 配置 (servers[].chatImage)

完整配置示例

单服务器

plugins:
  minecraft-adapter:
    debug: false
    tokenizeMode: split
    servers:
      - selfId: 'mc-server-1'
        serverName: 'TestServer'
        websocket:
          url: 'ws://127.0.0.1:8080'
          accessToken: 'your_token'
        chatImage:
          enabled: true
          defaultImageName: '图片'

多服务器

plugins:
  minecraft-adapter:
    debug: false
    servers:
      - selfId: 'survival'
        serverName: 'SurvivalServer'
        websocket:
          url: 'ws://192.168.1.10:8080'
          accessToken: 'token_survival'
        chatImage:
          enabled: true
      - selfId: 'creative'
        serverName: 'CreativeServer'
        websocket:
          url: 'ws://192.168.1.11:8080'
          accessToken: 'token_creative'

从旧版配置迁移

如果你使用的是旧版配置格式（bots + 全局 chatImage），插件会自动迁移并在日志中提示。建议尽快手动迁移到新格式：

旧格式（已弃用）：

plugins:
  minecraft-adapter:
    chatImage:
      enabled: true
    bots:
      - selfId: 'mc-1'
        websocket:
          url: 'ws://127.0.0.1:8080'

新格式：

plugins:
  minecraft-adapter:
    servers:
      - selfId: 'mc-1'
        websocket:
          url: 'ws://127.0.0.1:8080'
        chatImage:
          enabled: true

主要变更：

• bots → servers
• 全局 chatImage → 每服务器 chatImage
• websocket 现在是必填项

使用方法

监听事件

ctx.on('message', (session) => {
  if (session.platform === 'minecraft') {
    console.log(`[${session.event.guild?.name}] ${session.event.user?.name}: ${session.content}`)
  }
})

ctx.on('guild-member-added', (session) => {
  if (session.platform === 'minecraft') {
    console.log(`${session.event.user?.name} 加入了服务器`)
  }
})

ctx.on('guild-member-removed', (session) => {
  if (session.platform === 'minecraft') {
    console.log(`${session.event.user?.name} 离开了服务器`)
  }
})

发送消息

// 广播消息（通过 bot 实例自动定位到对应服务器）
await bot.sendMessage('server-channel', '服务器即将重启')

// 向指定玩家发送私聊消息
await bot.sendPrivateMessage('Steve', '你好')

// 执行 RCON 命令（通过鹊桥 WebSocket API 执行）
const result = await bot.executeCommand('list')

鹊桥 V2 事件映射

鹊桥 V2 API 映射

调试

启用 debug: true 后会输出详细日志，包括：

• 适配器初始化过程
• WebSocket 连接状态
• 接收到的原始消息数据
• 事件解析和会话创建过程
• API 请求和响应
• 断线重连过程
• 错误详情和堆栈跟踪

注意: 调试模式会产生大量日志，请仅在排查问题时启用。

协议参考

• 鹊桥文档
• 鹊桥 API 文档
• 鹊桥 GitHub

许可证

MIT