minecraft

README

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: ""

字段说明：

字段	说明
groups	启用插件的群号。为空时使用框架允许的所有群。
admins	插件管理员 QQ 号。目前主要命令依赖绑定用户，这个字段留给后续权限扩展。
server.name	传给 QueQiao 的服务端名称。必须以小写字母开头，可包含数字、_、.、-。
server.bridge.url	QueQiao WebSocket 地址。
server.bridge.access_token	QueQiao WebSocket 令牌。未启用鉴权时留空。

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

字段说明：

字段	说明
root	Minecraft 服务端工作目录。
start	启动命令及参数。
restart	退出后的重启策略。

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>，再获取一个验证码即可。

Documentation

Overview

Package minecraft 包含内置的 Minecraft 桥接插件。

Index

• Constants
• func DefaultConfigYAML() []byte
• type BridgeConfig
• type Config
  • func DefaultConfig() Config
• type Context
• type Plugin
  • func (p *Plugin) DefaultConfigYAML() []byte
  • func (a *Plugin) HandleMCEvent(ctx context.Context, e event.Event)
  • func (p *Plugin) Init(ctx *bot.PluginContext) error
  • func (p *Plugin) Name() string
  • func (p *Plugin) Start(ctx context.Context) error
  • func (p *Plugin) Stop(context.Context) error
• type ServerConfig
  • func (c ServerConfig) ToMC(configPath string) (mc.ServerConfig, error)
• type SupervisorConfig

Constants

const Module = "github.com/tty00a381/micq/src/core/plugins/minecraft"

const Name = "minecraft"

Functions

func DefaultConfigYAML

func DefaultConfigYAML() []byte

Types

type BridgeConfig

type BridgeConfig struct {
	URL         string `yaml:"url,omitempty"`
	AccessToken string `yaml:"access_token,omitempty"`
}

type Config

type Config struct {
	Server ServerConfig `yaml:"server,omitempty"`
	Admins []int64      `yaml:"admins,omitempty"`
	Groups []int64      `yaml:"groups,omitempty"`
}

func DefaultConfig

func DefaultConfig() Config

type Context

type Context = bot.Context

type Plugin

type Plugin struct {
	// contains filtered or unexported fields
}

func (*Plugin) DefaultConfigYAML

func (p *Plugin) DefaultConfigYAML() []byte

func (*Plugin) HandleMCEvent

func (a *Plugin) HandleMCEvent(ctx context.Context, e event.Event)

func (*Plugin) Init

func (p *Plugin) Init(ctx *bot.PluginContext) error

func (*Plugin) Name

func (p *Plugin) Name() string

func (*Plugin) Start

func (p *Plugin) Start(ctx context.Context) error

func (*Plugin) Stop

func (p *Plugin) Stop(context.Context) error

type ServerConfig

type ServerConfig struct {
	Name       string           `yaml:"name,omitempty"`
	Supervisor SupervisorConfig `yaml:"supervisor,omitempty"`
	Bridge     *BridgeConfig    `yaml:"bridge,omitempty"`
}

func (ServerConfig) ToMC

func (c ServerConfig) ToMC(configPath string) (mc.ServerConfig, error)

type SupervisorConfig

type SupervisorConfig struct {
	Root    string           `yaml:"root,omitempty"`
	Start   []string         `yaml:"start,omitempty"`
	Restart mc.RestartPolicy `yaml:"restart,omitempty"`
}