Network Packets

网络包文档

BlockOffensive 使用 FPSMatch 的 NetworkPacketRegister 注册自定义网络通道。

网络通道

项	值
Channel	blockoffensive:main
Protocol Version	1.6.0
注册位置	BOPacketRegistration.register(...)，由 BlockOffensive.commonSetup 调用

BOPacketRegistration 是 discriminator 顺序的唯一来源。旧包保持原有顺序，新包追加到表尾，避免破坏同协议版本内的编号兼容。

包分组

net/
├─ bomb/
├─ dm/
├─ intro/
├─ mvp/
├─ ping/
├─ shop/
├─ spec/
├─ vote/
└─ *.java

分组	说明
bomb	C4、拆弹动作、拆弹进度。
dm	死斗模式客户端输入同步。
intro	入场/换边演出序列与客户端完成回执。
mvp	MVP HUD 与消息。
ping	队友 Ping 请求与标记同步。
shop	商店状态、附近掉落查询和拾取。
spec	旁观、击杀回放、观战者名单、C4 引信、武器数据。
vote	投票状态和玩家投票。
根目录	比赛设置、比分板、TAB、死亡消息、Physics Mod 兼容。

当前注册表

以下 33 个 packet 按源码注册顺序列出。方向为注册时的实际网络方向；CSScoreboardSync 虽然类名没有 S2C 后缀，也被显式限制为 Server -> Client。

#	Packet	方向	主要用途
0	BombActionC2SPacket	C2S	提交拆弹动作。
1	BombActionS2CPacket	S2C	同步 C4 动作反馈。
2	BombDemolitionProgressS2CPacket	S2C	同步拆弹进度。
3	MvpHUDCloseS2CPacket	S2C	关闭 MVP HUD。
4	MvpMessageS2CPacket	S2C	同步 MVP 消息。
5	CSScoreboardS2CPacket	S2C	同步比赛比分板数据。
6	ShopStatesS2CPacket	S2C	同步商店开放状态和时间。
7	CSGameSettingsS2CPacket	S2C	同步比赛主状态。
8	CSTabRemovalS2CPacket	S2C	从客户端 TAB 缓存移除玩家。
9	DeathMessageS2CPacket	S2C	同步击杀消息。
10	PxDeathCompatS2CPacket	S2C	Physics Mod 死亡兼容。
11	PxRagdollRemovalCompatS2CPacket	S2C	Physics Mod ragdoll 清理。
12	CSGameWeaponDataS2CPacket	S2C	同步武器与护甲数据。
13	BombFuseS2CPacket	S2C	同步 C4 引信。
14	PlayerMoveC2SPacket	C2S	提交死斗移动输入。
15	KillCamS2CPacket	S2C	启动击杀回放。
16	RequestAttachTeammateC2SPacket	C2S	请求附身队友。
17	RequestKillCamFallbackC2SPacket	C2S	请求击杀回放降级路径。
18	SwitchSpectateC2SPacket	C2S	切换观战目标。
19	SpectatorRosterS2CPacket	S2C	同步观战者名单。
20	VoteSyncS2CPacket	S2C	同步投票主题、票数和剩余时间。
21	VoteCastC2SPacket	C2S	玩家提交赞成或反对票。
22	PingC2SPacket	C2S	玩家请求创建队伍 Ping。
23	PingS2CPacket	S2C	向队友同步 Ping 标记。
24	MvpMusicUploadC2SPacket	C2S	上传自定义 MVP 音乐元数据或数据。
25	MvpMusicChunkS2CPacket	S2C	分块下发 MVP 音乐。
26	ShopDropPickupC2SPacket	C2S	请求拾取商店相关掉落物。
27	ShopNearbyDropsRequestC2SPacket	C2S	请求附近可拾取掉落列表。
28	ShopDropPickupResultS2CPacket	S2C	返回拾取结果。
29	ShopNearbyDropsS2CPacket	S2C	返回附近掉落列表。
30	CSScoreboardSync	S2C	同步新版比分板快照。
31	IntroSequenceS2CPacket	S2C	下发入场或换边演出。
32	IntroClientDoneC2SPacket	C2S	客户端回报演出完成。

C2S 网络包

BombActionC2SPacket

路径：net/bomb/BombActionC2SPacket.java

方向：Client -> Server

字段：

字段	类型	说明
action	boolean	拆弹动作状态，通常表示开始或停止。

服务端处理：

• 获取发送玩家。
• 检查玩家视线命中的 C4。
• 根据 action 更新拆弹逻辑。
• 需要在服务端校验玩家状态和目标实体，不能信任客户端。

PlayerMoveC2SPacket

路径：net/dm/PlayerMoveC2SPacket.java

方向：Client -> Server

用途：

• csdm 中客户端检测移动输入后发送。
• 服务端用于死斗模式活跃状态、重生保护或相关运动逻辑。

字段：当前实现无显式业务字段。

RequestAttachTeammateC2SPacket

路径：net/spec/RequestAttachTeammateC2SPacket.java

方向：Client -> Server

用途：

• 旁观者请求附身或跟随队友。
• 服务端要求发送者为旁观者。
• 调用 BOSpecManager.requestAttachTeammate(sp)。

字段：无。

RequestKillCamFallbackC2SPacket

路径：net/spec/RequestKillCamFallbackC2SPacket.java

方向：Client -> Server

字段：

字段	类型	说明
killerId	UUID	请求 fallback 的击杀者 UUID。

用途：

• 客户端请求击杀回放 fallback。
• 服务端检查玩家是否为旁观者、是否在地图中，再处理请求。

SwitchSpectateC2SPacket

路径：net/spec/SwitchSpectateC2SPacket.java

方向：Client -> Server

字段：

字段	类型	说明
direction	enum SwitchDirection	PREV 或 NEXT。

用途：

• 旁观者切换上一个或下一个可观察目标。
• 服务端要求发送者为旁观者，并检查玩家当前地图。

S2C 网络包

BombActionS2CPacket

路径：net/bomb/BombActionS2CPacket.java

方向：Server -> Client

用途：

• 服务端同步 C4 动作反馈。
• 当前 record 无字段。

BombDemolitionProgressS2CPacket

路径：net/bomb/BombDemolitionProgressS2CPacket.java

方向：Server -> Client

字段：

字段	类型	说明
progress	float	拆弹进度。

用途：

• 同步到 CSClientData.dismantleBombProgress。
• 供 HUD 和 Web API 使用。

MvpHUDCloseS2CPacket

路径：net/mvp/MvpHUDCloseS2CPacket.java

方向：Server -> Client

用途：关闭客户端 MVP HUD。

字段：无。

MvpMessageS2CPacket

路径：net/mvp/MvpMessageS2CPacket.java

方向：Server -> Client

字段：

字段	类型	说明
mvpReason	MvpReason	MVP 原因。
其他消息字段	依实现	用于客户端展示 MVP 信息。

用途：触发 MVP 消息和 HUD 动画。

ShopStatesS2CPacket

路径：net/shop/ShopStatesS2CPacket.java

方向：Server -> Client

字段：

字段	类型	说明
canOpenShop	boolean	是否可打开商店。
nextRoundMoney	int	下一回合最低经济。
shopCloseTime	int	商店关闭时间。

用途：同步商店状态到 CSClientData。

CSGameSettingsS2CPacket

路径：net/CSGameSettingsS2CPacket.java

方向：Server -> Client

字段：

字段	类型	说明
cTWinnerRounds	int	CT 胜利回合数。
tWinnerRounds	int	T 胜利回合数。
time	int	当前时间。
isDebug	boolean	debug 状态。
isStart	boolean	是否开始。
isError	boolean	是否错误。
isPause	boolean	是否暂停。
isWaiting	boolean	是否等待。
isWarmTime	boolean	是否热身。
isWaitingWinner	boolean	是否等待胜者。

用途：同步比赛主状态到 CSClientData。

CSTabRemovalS2CPacket

路径：net/CSTabRemovalS2CPacket.java

方向：Server -> Client

字段：

字段	类型	说明
uuid	UUID	需要从客户端 TAB 数据移除的玩家 UUID。

DeathMessageS2CPacket

路径：net/DeathMessageS2CPacket.java

方向：Server -> Client

字段：

字段	类型	说明
deathMessage	DeathMessage	击杀/死亡消息数据。

用途：客户端显示击杀消息、死亡反馈、爆头等信息。

PxDeathCompatS2CPacket

路径：net/PxDeathCompatS2CPacket.java

方向：Server -> Client

字段：

字段	类型	说明
entityId	int	Physics Mod 死亡兼容相关实体 ID。

PxRagdollRemovalCompatS2CPacket

路径：net/PxRagdollRemovalCompatS2CPacket.java

方向：Server -> Client

字段：

字段	类型	说明
uuid	UUID	需要移除 ragdoll 的玩家 UUID。特殊值 00000000-0000-0000-0000-000000000000 表示全部。

CSGameWeaponDataS2CPacket

路径：net/spec/CSGameWeaponDataS2CPacket.java

方向：Server -> Client

字段：

字段	类型	说明
weaponDataMap	Map<UUID, WeaponData>	玩家武器与护甲数据。

WeaponData 包含：

字段	类型	说明
weaponData	Map<String, List<String>>	按类别组织的武器数据。
bpAttributeHasHelmet	boolean	是否有头盔。
bpAttributeDurability	int	防弹护甲耐久。

用途：同步 TAB、HUD 和 Web API 需要的武器/护甲状态。

BombFuseS2CPacket

路径：net/spec/BombFuseS2CPacket.java

方向：Server -> Client

字段：

字段	类型	说明
fuseTime	int	C4 剩余引信。
totalFuseTime	int	C4 总引信。

用途：同步 C4 倒计时到 HUD 和 Web API。

KillCamS2CPacket

路径：net/spec/KillCamS2CPacket.java

方向：Server -> Client

字段：

字段	类型	说明
killerId	UUID	击杀者 UUID。
killerName	String	击杀者名称。
weapon	ItemStack	击杀使用武器。
killerPos	Vec3	击杀者位置。
victimPos	Vec3	受害者位置。

用途：启动客户端 KillCam/击杀回放。

IntroSequenceS2CPacket

路径：intro/net/IntroSequenceS2CPacket.java

方向：Server -> Client

主要字段：

字段	类型	说明
sequenceId	UUID	演出实例 ID，用于拒绝过期停止或完成消息。
startGameTime	long	服务端开始 game time，客户端用它计算迟到追帧。
gameType / mapName	String	演出所属地图。
phase	IntroPhase	START、SWITCH、PREVIEW、PREVIEW5、PREARM 或 STOP。
side	IntroTeamSide	CT 或 T。
durationTicks	int	演出总时长。
preRollTicks	int	正式运动前的预备时长。
cinematicReadyAtTick	int	镜头可开始呈现的时间点。
cameraStart / cameraEnd	Vec3	镜头起止位置。
cameraStartYaw/Pitch / cameraEndYaw/Pitch	float	镜头起止朝向。
players	List	最多 10 条演员移动路径和最终出生位置。
heldItems	List	与演员对应的展示物品。

客户端只接受当前有效序列，使用 FPSMatch CameraDirector 播放，并按 startGameTime 追到服务端进度。该同步依赖原版 game time，不是独立的高精度时钟协议。

IntroClientDoneC2SPacket

路径：intro/net/IntroClientDoneC2SPacket.java

方向：Client -> Server

字段	类型	说明
sequenceId	UUID	客户端完成的演出 ID。
reason	String	最长 128 字符的完成原因。

服务端通过 IntroRuntimeController 校验发送者与当前序列，只处理匹配的完成回执。

新增网络包清单

新增包时建议按以下步骤：

1. 放入合适目录。
2. 定义字段和构造器。
3. 实现 encode。
4. 实现 decode。
5. 实现 handle，并使用 ctx.enqueueWork 切回主线程。
6. 对 C2S 包检查 ctx.getSender()、玩家状态、地图状态和权限。
7. 在 BOPacketRegistration.register(...) 的末尾注册；不要插入旧 discriminator 中间。
8. 编译验证。
9. 更新本页面。

安全与兼容建议

• C2S 包不能信任客户端传来的位置、目标、状态或权限。
• 只允许服务端作为比赛状态权威来源。
• S2C 包应尽量只同步客户端显示所需字段。
• 协议字段变更会影响客户端/服务端兼容性，需要同步更新协议版本或保持兼容读取。
• 对旁观、拆弹、商店、C4 等涉及比赛结果的包必须 fail closed。