Matrix

FrontLeaves MC 玩家行为遥测插件——通过 gRPC Client Stream 将 Minecraft 服务器中 17 种玩家行为事件实时上报至 Go 后端。

架构

flowchart TB
    subgraph MC["Minecraft Server (Paper 1.21.1)"]
        MTP["MatrixTelemetryPlugin<br/>(主类 + ClientStreamHandler)"]
        PCL["PlayerConnectionListener<br/>(加入/离开)"]
        BEL["BlockEventListener<br/>(破坏/放置)"]
        CEL["CombatEventListener<br/>(击杀/伤害/死亡)"]
        IEL["ItemEventListener<br/>(丢弃/拾取/背包)"]
        PBL["PlayerBehaviorListener<br/>(聊天/命令/切换/传送/重生/游戏模式)"]
        CM["ConnectivityMonitor<br/>(连接状态监控)"]
    end

    PCL --> MTP
    BEL --> MTP
    CEL --> MTP
    IEL --> MTP
    PBL --> MTP
    CM --> MTP
    MTP -- "Client Stream (plugin-name + plugin-secret-key)" --> GO

    subgraph GO["frontleaves-plugin (Go 后端)"]
        MTS["MatrixTelemetryService"]
        RD["Redis"]
        API["RESTful API"]
    end

    MTS --> RD
    RD --> API

Loading

功能

• 连接事件：玩家加入/离开服务器
• 方块事件：方块破坏/放置
• 战斗事件：实体击杀/实体伤害/玩家伤害/玩家死亡
• 物品事件：物品丢弃/拾取/背包操作
• 行为事件：聊天/命令/切换状态(潜行/冲刺等)/传送/重生/游戏模式变更
• 心跳快照：定时上报在线玩家位置、生命值、饥饿值等状态
• 认证机制：通过 plugin-name + plugin-secret-key gRPC metadata 鉴权
• 连接监控：通过 ConnectivityMonitor 监控 gRPC 通道状态，断开时自动暂停上报
• 通道热重载：支持 /frontleaves-lib reload 无缝重建 gRPC 通道

技术栈

类别	技术
语言	Java 21
平台	Paper API 1.21.1
构建	Maven + Shade Plugin
通信	gRPC (Client Streaming RPC)
Protobuf	3.25.3
gRPC 版本	1.62.2
依赖库	frontleaves-lib

快速开始

环境要求

• JDK 21+
• Maven 3.8+
• frontleaves-lib 已安装到本地 Maven 仓库
• 运行中的 Go 后端 (frontleaves-plugin)

构建

mvn clean package

构建产物位于 target/matrix-1.0.0.jar。

配置

将 JAR 放入服务器的 plugins/ 目录，首次启动后编辑 plugins/matrix/config.yml：

grpc:
  server-name: "survival"     # 本服务器标识（集群内唯一）

telemetry:
  tick-interval-ticks: 20     # 心跳快照上报间隔（tick，20tick = 1秒）
  events:
    player-join: true
    player-quit: true
    block-break: true
    block-place: true
    entity-kill: true
    entity-damage: true
    player-damage: true
    player-death: true
    item-drop: true
    item-pickup: true
    inventory-action: true
    player-chat: true
    player-command: true
    player-toggle: true
    player-teleport: true
    player-respawn: true
    game-mode-change: true

目录结构

.
├── pom.xml                                          # Maven 构建（含 protobuf + shade 插件）
├── src/main/
│   ├── proto/
│   │   ├── link/base.proto                          # BaseResponse 统一响应定义
│   │   └── matrix/v1/matrix_telemetry.proto         # MatrixTelemetryService (Client Stream)
│   ├── java/.../matrix/
│   │   ├── MatrixTelemetryPlugin.java               # 主类：生命周期管理、流处理器、心跳任务
│   │   ├── util/ProtoBuilder.java                   # Proto 消息构建工具
│   │   └── listener/
│   │       ├── PlayerConnectionListener.java        # 玩家加入/离开
│   │       ├── BlockEventListener.java              # 方块破坏/放置
│   │       ├── CombatEventListener.java             # 击杀/伤害/死亡
│   │       ├── ItemEventListener.java               # 物品丢弃/拾取/背包
│   │       └── PlayerBehaviorListener.java          # 聊天/命令/切换/传送/重生/游戏模式
│   └── resources/
│       ├── config.yml                               # 默认配置
│       └── paper-plugin.yml                         # Paper 插件描述

事件列表

17 种玩家行为事件通过 Client Stream 实时上报至 Go 后端：

事件类型	Proto 消息	监听器	说明
player_join	PlayerJoinEvent	PlayerConnectionListener	玩家加入服务器
player_quit	PlayerQuitEvent	PlayerConnectionListener	玩家离开服务器
telemetry_tick	TelemetryTick	定时任务	心跳快照（位置/生命/饥饿/药水等）
block_break	BlockBreakEvent	BlockEventListener	方块破坏
block_place	BlockPlaceEvent	BlockEventListener	方块放置
entity_kill	EntityKillEvent	CombatEventListener	玩家击杀实体
entity_damage	EntityDamageEvent	CombatEventListener	实体受伤（玩家造成）
player_damage	PlayerDamageEvent	CombatEventListener	玩家受伤
player_death	PlayerDeathEvent	CombatEventListener	玩家死亡
item_drop	ItemDropEvent	ItemEventListener	玩家丢弃物品
item_pickup	ItemPickupEvent	ItemEventListener	玩家拾取物品
inventory_action	InventoryActionEvent	ItemEventListener	背包操作
player_chat	PlayerChatEvent	PlayerBehaviorListener	玩家聊天
player_command	PlayerCommandEvent	PlayerBehaviorListener	玩家执行命令
player_toggle	PlayerToggleEvent	PlayerBehaviorListener	切换状态（潜行/冲刺/飞行）
teleport	PlayerTeleportEvent	PlayerBehaviorListener	玩家传送
respawn	PlayerRespawnEvent	PlayerBehaviorListener	玩家重生
game_mode_change	GameModeChangeEvent	PlayerBehaviorListener	游戏模式变更

相关项目

项目	说明
frontleaves-plugin	Go 后端服务（gRPC Server + RESTful API）
frontleaves-lib	共享库插件（gRPC 通道管理 + 认证拦截器）
server-status	服务器状态监控插件（心跳 + 玩家事件）

许可证

MIT License