跳到主要内容

RhythMC-Reborn WebSocket PVP 协议文档

目录​

  1. 协议概述
  2. 消息类型
  3. 实时同步流程
  4. 数据包详解

协议概述​

架构位置​

当前实现原则​

  • invoke_game 只负责通知客户端“创建对局实例并开始加载资源”。
  • 客户端资源加载完成后发送 ready_game。
  • 服务端在房间内双方都 ready 后发送 launch_game，客户端收到后才真正开始播放音乐与进入判定循环。
  • 对局结束或中断时客户端发送 end_game，服务端清理房间占用。
  • 对局进行中通过 sync_rival 双向同步实时成绩。
  • WebSocket 意外断开时服务端向房间内其他玩家发送 rival_disconnect。

消息类型​

1. ReadyGame​

方向: Client → Server

用途: 客户端完成谱面与资源准备，通知服务端自己可以开局。

{
  "type": "ready_game",
  "playerId": 12345
}
字段类型描述
typeString固定值 "ready_game"
playerIdint已准备完成的玩家 UID

2. LaunchGame​

方向: Server → Client

用途: 服务端确认该玩家所在房间可以正式开局。

{
  "type": "launch_game",
  "playerId": 12345
}
字段类型描述
typeString固定值 "launch_game"
playerIdint应启动对局的玩家 UID

3. EndGame​

方向: Client → Server

用途: 告知服务端本地对局实例已结束，服务端释放该玩家的房间占用。

{
  "type": "end_game",
  "playerId": 12345
}
字段类型描述
typeString固定值 "end_game"
playerIdint已结束对局的玩家 UID

4. SyncRival​

方向: 双向 (Client ↔ Server)

用途: 实时同步对手游戏数据。

{
  "type": "sync_rival",
  "playerId": 12345,
  "data": {
    "chart_id": "100091",
    "lvl": "IN 15",
    "dura": "01:23",
    "length": "02:14",
    "dura_percent": 0.62,
    "combo": 127,
    "max_combo": 127,
    "acc": 99.12,
    "max_acc": 100.0,
    "perfect": 120,
    "great": 6,
    "miss": 1,
    "tot_hit": 127,
    "tot_notes": 321,
    "hit_percent": 0.39,
    "latency": 42
  }
}
字段类型描述
typeString固定值 "sync_rival"
playerIdint发送数据的玩家 UID
dataGameData当前实时对局数据

5. RivalDisconnect​

方向: Server → Client

用途: 通知客户端对手的 WebSocket 已断开或异常退出。

{
  "type": "rival_disconnect",
  "playerId": 12345
}
字段类型描述
typeString固定值 "rival_disconnect"
playerIdint断开连接的玩家 UID

实时同步流程​

匹配模式流程​

决斗模式流程​

断线流程​

数据包详解​

WsPayload 接口​

public sealed interface WsPayload
        permits DuelAck, DuelRequest, EndGame, InvokeGame, JoinQueue,
                LaunchGame, Ping, Pong, ReadyGame, ResumeSession,
                RivalDisconnect, SyncRival {
    String type();
}

GameData 结构​

public record GameData(
    String chart_id,
    String lvl,
    String dura,
    String length,
    float dura_percent,
    int combo,
    int max_combo,
    double acc,
    double max_acc,
    int perfect,
    int great,
    int miss,
    int tot_hit,
    int tot_notes,
    float hit_percent,
    long latency
) {}

完整类型定义​

public record ReadyGame(String type, int playerId) implements WsPayload {
    public static final String TYPE = "ready_game";
}

public record LaunchGame(String type, int playerId) implements WsPayload {
    public static final String TYPE = "launch_game";
}

public record EndGame(String type, int playerId) implements WsPayload {
    public static final String TYPE = "end_game";
}

public record SyncRival(String type, int playerId, GameData data) implements WsPayload {
    public static final String TYPE = "sync_rival";
}

public record RivalDisconnect(String type, int playerId) implements WsPayload {
    public static final String TYPE = "rival_disconnect";
}

消息类型常量表​

类型常量值方向用途
ReadyGame.TYPE"ready_game"C→S客户端完成资源准备
LaunchGame.TYPE"launch_game"S→C服务端允许正式开局
EndGame.TYPE"end_game"C→S客户端结束并清理房间
SyncRival.TYPE"sync_rival"双向对手数据同步
RivalDisconnect.TYPE"rival_disconnect"S→C对手断开通知