新增基岩版封包
本指南介紹如何在 Pumpkin 中實現、編碼、解碼和處理新的 Minecraft:基岩版封包。
命名約定
- 用戶端接收封包(伺服器 → 用戶端)必須以
C開頭(例如CChunkRadiusUpdated、CContainerOpen)。 - 伺服器接收封包(用戶端 → 伺服器)必須以
S開頭(例如SRequestChunkRadius、SPlayerAction)。
第 1 步:確定封包 ID
在基岩版協定中,封包 ID 是由 Mojang 分配的固定整數常量。請透過官方協定文件或網路封包跟蹤確認數字 ID。
例如:
Disconnect封包 ID:5RequestChunkRadius封包 ID:69
第 2 步:實現用戶端接收封包
用戶端接收封包實現 pumpkin-protocol::serial 中的 PacketWrite trait。
1. 建立封包檔案
將檔案放在 crates/pumpkin-protocol/src/bedrock/client/<packet_name>.rs:
use std::io::{Error, Write};
use pumpkin_macros::packet;
use crate::{codec::var_int::VarInt, serial::PacketWrite};
#[packet(5)]
pub struct CDisconnect {
pub reason: VarInt,
pub skip_message: bool,
pub message: String,
pub filtered_message: String,
}
impl CDisconnect {
#[must_use]
pub const fn new(reason: i32, message: String) -> Self {
Self {
reason: VarInt(reason),
skip_message: message.is_empty(),
message,
filtered_message: String::new(),
}
}
}
impl PacketWrite for CDisconnect {
fn write<W: Write>(&self, writer: &mut W) -> Result<(), Error> {
self.reason.write(writer)?;
self.skip_message.write(writer)?;
if !self.skip_message {
self.message.write(writer)?;
self.filtered_message.write(writer)?;
}
Ok(())
}
}2. 匯出模組
在 crates/pumpkin-protocol/src/bedrock/client/mod.rs 中:
pub mod disconnect;
pub use disconnect::*;第 3 步:實現伺服器接收封包
伺服器接收封包實現 PacketRead trait。當欄位實現 PacketRead 時,Pumpkin 提供過程派生巨集 #[derive(PacketRead)] 用於自動反序列化。
1. 建立封包檔案
將檔案放在 crates/pumpkin-protocol/src/bedrock/server/<packet_name>.rs:
use pumpkin_macros::packet;
use crate::{codec::var_int::VarInt, serial::PacketRead};
#[derive(PacketRead, Debug)]
#[packet(69)]
pub struct SRequestChunkRadius {
pub chunk_radius: VarInt,
pub max_chunk_radius: u8,
}如果封包需要自訂解析邏輯,請手動實現 PacketRead:
use std::io::{Error, Read};
use crate::serial::PacketRead;
impl PacketRead for SMyCustomPacket {
fn read<R: Read>(reader: &mut R) -> Result<Self, Error> {
let chunk_radius = VarInt::read(reader)?;
let max_chunk_radius = u8::read(reader)?;
Ok(Self { chunk_radius, max_chunk_radius })
}
}2. 匯出模組
在 crates/pumpkin-protocol/src/bedrock/server/mod.rs 中:
pub mod request_chunk_radius;
pub use request_chunk_radius::*;第 4 步:在 pumpkin 中分發傳入封包
傳入封包在 crates/pumpkin/src/net/bedrock/mod.rs 中分發:
// 位於 BedrockClient::handle_game_packet 內
match packet.id {
SRequestChunkRadius::PACKET_ID => {
let packet = SRequestChunkRadius::read(reader)?;
self.handle_request_chunk_radius(player, &packet);
}
_ => {}
}第 5 步:實現處理函式
在 crates/pumpkin/src/net/bedrock/play/<packet_name>.rs 中實現處理邏輯:
use super::*;
use pumpkin_protocol::bedrock::server::request_chunk_radius::SRequestChunkRadius;
impl BedrockClient {
pub fn handle_request_chunk_radius(&self, player: &Arc<Player>, packet: &SRequestChunkRadius) {
let requested_radius = packet.chunk_radius.0;
// 將視距限制在伺服器設定範圍內
let clamped = requested_radius.clamp(2, 16);
// 通知用戶端視野半徑已被接受
self.try_enqueue_client_packet(&CChunkRadiusUpdated {
chunk_radius: VarInt(clamped),
});
}
}記得在 crates/pumpkin/src/net/bedrock/play/mod.rs 中註冊新模組:
pub mod request_chunk_radius;第 6 步:傳送傳出封包
向已連線的用戶端傳送基岩版封包:
// 將封包加入用戶端的傳出批次佇列
self.try_enqueue_client_packet(&CChunkRadiusUpdated {
chunk_radius: VarInt(view_distance),
});批處理封包會自動壓縮,使用 0xfe 分幀,並透過 RakNet/NetherNet 通訊端傳輸。