feat(net): 优化高延迟下的多人交互体验

- Break/Place 协议升级至 v4，携带 input_tick 和点击时玩家位置
- Remote 挖放增加本地乐观更新，拒绝时沿用 rollback 还原
- 服务端按点击时位置校验挖放，减少高 RTT 下的误拒
- 平滑 Host 时钟同步，并为远端玩家插值增加短外推
- 更新协议、预测和模块文档

Author: NOVIIC

crates/client/src/app.rs

@@ -311,9 +311,11 @@ pub struct Game {
     pub input_history: InputHistory,
     /// 中等位置误差的剩余软修正量。每个渲染帧应用一小段，避免高 RTT 下画面回弹。
     pub pending_position_correction: Vec3,
-    /// Host 时钟与本地时钟的瞬态偏移（ms）：server_time_ms - local_now_ms。
-    /// PlayerTick 每帧覆盖；远端的 rendering target 用。
-    pub server_clock_offset_ms: i64,
+    /// Host 时钟与本地时钟的平滑偏移（ms）：server_time_ms - local_now_ms。
+    /// Pong 按半 RTT 估算，PlayerTick 提供低权重补充样本；远端插值 target 使用它。
+    pub server_clock_offset_ms: f64,
+    /// 是否已经吃过至少一条 Host 时钟样本。第一条样本直接采用，后续再指数平滑。
+    pub server_clock_synced: bool,
     /// Phase 8：Local/Host 的 OPFS 存储句柄。Remote 不写存档。
     pub storage: Option<OpfsStorage>,
     pub known_persisted: HashSet<voxweb_core::ChunkPos>,
@@ -455,7 +457,8 @@ impl Game {
             local_input_tick: 0,
             input_history: InputHistory::new(120),
             pending_position_correction: Vec3::ZERO,
-            server_clock_offset_ms: 0,
+            server_clock_offset_ms: 0.0,
+            server_clock_synced: false,
             storage: None,
             known_persisted: HashSet::new(),
             last_persist_ms: 0.0,

crates/client/src/interp.rs

@@ -4,15 +4,20 @@
 //! 每渲染帧以 `server_time_ms - interp_delay` 作为渲染 target，
 //! 找出 bracket `[a.time, b.time]` 后 lerp position / yaw / pitch。
 //!
-//! Phase 5 不做外推（若 render_time 超出最新快照直接返回最新）；
-//! Phase 7 可加 50ms 外推窗口。
+//! Phase 8 起在缺少未来快照时允许最多 50ms 短外推，降低丢一两帧时的冻结感。
 
 use std::collections::HashMap;
 
 use glam::Vec3;
 
 use voxweb_core::protocol::EntityId;
 
+/// 没有未来快照时允许的短外推窗口。超过该窗口仍停在外推 50ms 的位置，
+/// 避免丢包时远端玩家立刻冻结，同时避免长时间猜测导致穿墙。
+const MAX_EXTRAPOLATE_MS: f64 = 50.0;
+/// 相邻快照距离超过该阈值视为传送或大纠偏，不做插值/外推。
+const TELEPORT_SNAP_DISTANCE_M: f32 = 10.0;
+
 /// 单条远端玩家快照。由 `apply_server_message::PlayerTick` 推入。
 #[derive(Copy, Clone, Debug)]
 struct Sample {
@@ -54,7 +59,7 @@ impl RemoteBuffer {
 
     /// 给定渲染 target（server 时间 ms），返回插值后的 (position, yaw, pitch)。
     /// - target 早于最早样本 → 返回最早
-    /// - target 晚于最新样本 → 返回最新（不外推）
+    /// - target 晚于最新样本 → 按最近速度短外推（最多 50ms）
     /// - 在 [a, b] 之间 → lerp
     fn get(&self, render_server_time_ms: f64) -> Option<(Vec3, f32, f32)> {
         if self.buf.is_empty() {
@@ -74,11 +79,13 @@ impl RemoteBuffer {
             let s = &self.buf[0];
             Some((s.position, s.yaw, s.pitch))
         } else if idx >= self.buf.len() {
-            let s = &self.buf[self.buf.len() - 1];
-            Some((s.position, s.yaw, s.pitch))
+            Some(self.latest_or_extrapolated(render_server_time_ms))
         } else {
             let a = &self.buf[idx - 1];
             let b = &self.buf[idx];
+            if a.position.distance(b.position) > TELEPORT_SNAP_DISTANCE_M {
+                return Some((b.position, b.yaw, b.pitch));
+            }
             let denom = (b.server_time_ms - a.server_time_ms) as f64;
             if denom <= 0.0 {
                 return Some((a.position, a.yaw, a.pitch));
@@ -92,6 +99,29 @@ impl RemoteBuffer {
             Some((position, yaw, pitch))
         }
     }
+
+    fn latest_or_extrapolated(&self, render_server_time_ms: f64) -> (Vec3, f32, f32) {
+        let latest = &self.buf[self.buf.len() - 1];
+        if self.buf.len() < 2 {
+            return (latest.position, latest.yaw, latest.pitch);
+        }
+        let prev = &self.buf[self.buf.len() - 2];
+        if prev.server_time_ms >= latest.server_time_ms
+            || prev.position.distance(latest.position) > TELEPORT_SNAP_DISTANCE_M
+        {
+            return (latest.position, latest.yaw, latest.pitch);
+        }
+
+        let sample_dt_s = (latest.server_time_ms - prev.server_time_ms) as f32 * 0.001;
+        if sample_dt_s <= f32::EPSILON {
+            return (latest.position, latest.yaw, latest.pitch);
+        }
+        let extrapolate_ms =
+            (render_server_time_ms - latest.server_time_ms as f64).clamp(0.0, MAX_EXTRAPOLATE_MS);
+        let velocity = (latest.position - prev.position) / sample_dt_s;
+        let position = latest.position + velocity * (extrapolate_ms as f32 * 0.001);
+        (position, latest.yaw, latest.pitch)
+    }
 }
 
 /// 整个房间的远端玩家插值状态。
@@ -238,14 +268,25 @@ mod tests {
     }
 
     #[test]
-    fn interp_clamps_to_latest_when_render_time_after_all() {
+    fn interp_short_extrapolates_when_render_time_after_latest() {
         let mut interp = PlayerInterp::new();
         interp.delay_ms = 0.0;
         interp.ingest_tick(1, 1000, Vec3::new(0.0, 64.0, 0.0), 0.5, 0.0);
         interp.ingest_tick(1, 2000, Vec3::new(10.0, 64.0, 10.0), 1.0, 0.0);
-        // render 3000 > 最新 2000 → 返回最新
+        // render 3000 > 最新 2000 → 只短外推 50ms，速度为 10m/s
         let (pos, yaw, _) = interp.advance(1, 3000.0).expect("should return latest");
-        assert!((pos - Vec3::new(10.0, 64.0, 10.0)).length() < 0.01);
+        assert!((pos - Vec3::new(10.5, 64.0, 10.5)).length() < 0.01);
         assert!((yaw - 1.0).abs() < 0.01);
     }
+
+    #[test]
+    fn interp_does_not_extrapolate_teleports() {
+        let mut interp = PlayerInterp::new();
+        interp.delay_ms = 0.0;
+        interp.ingest_tick(1, 1000, Vec3::ZERO, 0.0, 0.0);
+        interp.ingest_tick(1, 2000, Vec3::new(20.0, 64.0, 0.0), 0.0, 0.0);
+
+        let (pos, _, _) = interp.advance(1, 2050.0).expect("should return latest");
+        assert!((pos - Vec3::new(20.0, 64.0, 0.0)).length() < 0.01);
+    }
 }

crates/client/src/lib.rs

@@ -58,6 +58,11 @@ const MAX_REACH: f32 = 6.0;
 /// Ping 间隔（毫秒）。
 const PING_INTERVAL_MS: f64 = 5000.0;
 
+/// Pong 校时样本权重。Pong 带 RTT 信息，可信度高于裸 PlayerTick。
+const CLOCK_PONG_ALPHA: f64 = 0.2;
+/// PlayerTick 校时样本权重。它可能受单向排队延迟影响，只作为低权重补充。
+const CLOCK_TICK_ALPHA: f64 = 0.05;
+
 /// 信令服务 URL meta tag 名称。
 const SIGNALING_META_NAME: &str = "signaling-url";
 
@@ -1846,7 +1851,10 @@ fn render_game_frame(
             return Ok(());
         };
         let now = now_ms();
-        if game.entity_id != 0 && now - game.last_ping_sent_ms >= PING_INTERVAL_MS {
+        if game.mode != GameMode::Local
+            && game.entity_id != 0
+            && now - game.last_ping_sent_ms >= PING_INTERVAL_MS
+        {
             let client_time_ms = now as u64;
             game.pending_pings.insert(client_time_ms, now);
             // 上限 16 个待办，避免长期不通时无限增长
@@ -2114,7 +2122,7 @@ fn render_game_frame(
         let mut view_proj_for_np = glam::Mat4::IDENTITY;
         if let Some(g) = a.game.as_mut() {
             view_proj_for_np = g.camera.vp_matrix();
-            let render_target = now_local + g.server_clock_offset_ms as f64 - g.interp.delay_ms;
+            let render_target = now_local + g.server_clock_offset_ms - g.interp.delay_ms;
             let cam_pos = g.camera.position;
             let eids: Vec<EntityId> = g.interp.ids().collect();
             for eid in eids {
@@ -2322,8 +2330,7 @@ fn render_game_frame(
             let now = now_ms();
             let mut instances: Vec<voxweb_render::passes::player::PlayerInstance> = Vec::new();
             if let Some(ref mut game) = a.game {
-                let render_server_time =
-                    now + game.server_clock_offset_ms as f64 - game.interp.delay_ms;
+                let render_server_time = now + game.server_clock_offset_ms - game.interp.delay_ms;
                 let eids: Vec<voxweb_core::protocol::EntityId> = game.interp.ids().collect();
                 for eid in eids {
                     if let Some((pos, _yaw, _pitch)) = game.interp.advance(eid, render_server_time)
@@ -2509,9 +2516,16 @@ fn dispatch_actions(game: &mut Game, input: &InputState) {
             let server = game.server.borrow();
             server.world.get_block(pos)
         };
-        // Local 模式 client 和 server 共享同一份 world，乐观更新会干扰 server 校验
-        // （server 读回 AIR 误判 BlockNotEmpty 拒绝）。因此跳过乐观 set_block；
-        // BlockUpdate 返回后再重 mesh。Phase 5 Remote 端加独立 WorldView 时再加乐观路径。
+        let input_tick = game.local_input_tick;
+        let player_position = game.physics.feet_position;
+        // Remote 的 server.world 只是本地世界视图，可以安全乐观修改；
+        // Local/Host 与权威 server 共享同一份 world，仍等 BlockUpdate，避免提前改世界干扰校验。
+        if game.mode == GameMode::Remote {
+            game.server.borrow_mut().world.set_block(pos, BlockID::AIR);
+            for cp in affected_chunks(pos) {
+                game.mesh_jobs.enqueue(cp, MeshPriority::High);
+            }
+        }
         let request_id = game.pending.next_request_id();
         game.pending.insert(
             request_id,
@@ -2521,8 +2535,12 @@ fn dispatch_actions(game: &mut Game, input: &InputState) {
                 backup,
             },
         );
-        game.net
-            .send_client_message(ClientMessage::Break { pos, request_id });
+        game.net.send_client_message(ClientMessage::Break {
+            pos,
+            request_id,
+            input_tick,
+            player_position,
+        });
         game.last_break_at_ms = now;
     }
 
@@ -2551,6 +2569,8 @@ fn dispatch_actions(game: &mut Game, input: &InputState) {
             return;
         }
         let request_id = game.pending.next_request_id();
+        let input_tick = game.local_input_tick;
+        let player_position = game.physics.feet_position;
         game.pending.insert(
             request_id,
             PendingAction {
@@ -2559,10 +2579,18 @@ fn dispatch_actions(game: &mut Game, input: &InputState) {
                 backup,
             },
         );
+        if game.mode == GameMode::Remote {
+            game.server.borrow_mut().world.set_block(neighbor, block);
+            for cp in affected_chunks(neighbor) {
+                game.mesh_jobs.enqueue(cp, MeshPriority::High);
+            }
+        }
         game.net.send_client_message(ClientMessage::Place {
             pos: neighbor,
             block,
             request_id,
+            input_tick,
+            player_position,
         });
     }
 }
@@ -2581,6 +2609,21 @@ fn send_chat(game: &mut Game, content: String) {
         .send_client_message(ClientMessage::Chat { content });
 }
 
+/// 摄入一条 Host 时钟偏移样本。
+///
+/// 高延迟网络下，直接用最新 `server_time_ms - now` 覆盖偏移会让远端玩家插值 target
+/// 来回抖动。这里第一条样本直接采用，后续做指数平滑；Pong 样本权重较高，
+/// PlayerTick 样本只做低权重微调。
+fn ingest_server_clock_sample(game: &mut Game, estimated_offset_ms: f64, alpha: f64) {
+    if !game.server_clock_synced {
+        game.server_clock_offset_ms = estimated_offset_ms;
+        game.server_clock_synced = true;
+        return;
+    }
+    let a = alpha.clamp(0.0, 1.0);
+    game.server_clock_offset_ms = game.server_clock_offset_ms * (1.0 - a) + estimated_offset_ms * a;
+}
+
 fn apply_server_message(game: &mut Game, msg: ServerMessage) {
     match msg {
         ServerMessage::Welcome {
@@ -2678,8 +2721,12 @@ fn apply_server_message(game: &mut Game, msg: ServerMessage) {
             players,
             server_time_ms,
         } => {
-            let now = (now_ms()) as i64;
-            game.server_clock_offset_ms = server_time_ms as i64 - now;
+            let now = now_ms();
+            if game.mode != GameMode::Local {
+                let one_way_ms = game.rtt_ms.map(|rtt| rtt as f64 * 0.5).unwrap_or(0.0);
+                let estimated_offset = server_time_ms as f64 + one_way_ms - now;
+                ingest_server_clock_sample(game, estimated_offset, CLOCK_TICK_ALPHA);
+            }
 
             for snap in &players {
                 if snap.entity_id == game.entity_id {
@@ -2750,11 +2797,17 @@ fn apply_server_message(game: &mut Game, msg: ServerMessage) {
         }
         ServerMessage::Pong {
             client_time_ms,
-            server_time_ms: _,
+            server_time_ms,
         } => {
             if let Some(sent_ms) = game.pending_pings.remove(&client_time_ms) {
-                let rtt = (now_ms() - sent_ms) as f32;
-                game.rtt_ms = Some(rtt);
+                let now = now_ms();
+                let rtt = (now - sent_ms) as f32;
+                game.rtt_ms = Some(match game.rtt_ms {
+                    Some(prev) => prev * 0.8 + rtt * 0.2,
+                    None => rtt,
+                });
+                let estimated_offset = server_time_ms as f64 + (rtt as f64 * 0.5) - now;
+                ingest_server_clock_sample(game, estimated_offset, CLOCK_PONG_ALPHA);
             }
         }
     }

crates/core/src/protocol.rs

@@ -12,9 +12,9 @@ use crate::chunk::{ChunkPos, Position};
 /// 协议版本号。Hello.version 与之不一致时 Host 拒绝接入。
 /// 任何破坏性消息字段变更必须递增此版本。
 ///
-/// v3（Phase 8）：PlayerSnapshot 携带 last_input_tick，
-/// 让客户端按同一条本地输入记录做预测协调，避免高延迟时被旧位置回声拉回。
-pub const PROTOCOL_VERSION: u32 = 3;
+/// v4（Phase 8）：Break/Place 携带点击时 input_tick 与 player_position，
+/// 让 Host 在高延迟下按玩家实际点击时的位置做挖放范围校验。
+pub const PROTOCOL_VERSION: u32 = 4;
 
 /// ChunkSnapshot 单片 payload 上限（字节）。
 /// 浏览器 SCTP 用户消息上限约 16 KB；保守留 14 KB，剩余给 frag_index/frag_total/bincode header。
@@ -65,12 +65,24 @@ pub enum ClientMessage {
         pitch: f32,
     },
     /// 挖掘方块请求
-    Break { pos: Position, request_id: u32 },
+    Break {
+        pos: Position,
+        request_id: u32,
+        /// 玩家点击时的本地输入序号，用于让服务端把操作与预测历史对齐。
+        input_tick: u32,
+        /// 玩家点击时的脚底位置。可靠操作包可能先于最新 PlayerInput 到达，
+        /// 服务端用它做范围校验，避免高 RTT 下误判 OutOfRange。
+        player_position: Vec3,
+    },
     /// 放置方块请求
     Place {
         pos: Position,
         block: BlockID,
         request_id: u32,
+        /// 玩家点击时的本地输入序号。
+        input_tick: u32,
+        /// 玩家点击时的脚底位置，用于范围与玩家 AABB 重叠校验。
+        player_position: Vec3,
     },
     /// 文本聊天
     Chat { content: String },
@@ -238,6 +250,8 @@ mod tests {
         roundtrip(&ClientMessage::Break {
             pos: Position::new(10, 64, -5),
             request_id: 42,
+            input_tick: 9,
+            player_position: Vec3::new(8.0, 65.0, 8.0),
         });
     }
 
@@ -247,6 +261,8 @@ mod tests {
             pos: Position::new(10, 65, -5),
             block: BlockID::STONE,
             request_id: 43,
+            input_tick: 10,
+            player_position: Vec3::new(8.0, 65.0, 8.0),
         });
     }
 
@@ -287,9 +303,9 @@ mod tests {
     }
 
     #[test]
-    fn protocol_version_is_three() {
-        // Phase 8 起为 3；任何破坏性变更应同步更新此测试与版本号。
-        assert_eq!(PROTOCOL_VERSION, 3);
+    fn protocol_version_is_four() {
+        // Phase 8 高延迟挖放优化为 v4；任何破坏性变更应同步更新此测试与版本号。
+        assert_eq!(PROTOCOL_VERSION, 4);
     }
 
     #[test]

crates/net/src/transport.rs

@@ -96,6 +96,8 @@ mod tests {
             channel_for_client_message(&ClientMessage::Break {
                 pos: Position::new(0, 0, 0),
                 request_id: 0,
+                input_tick: 0,
+                player_position: Vec3::ZERO,
             }),
             ChannelKind::Reliable
         );
@@ -150,6 +152,8 @@ mod tests {
             pos: Position::new(1, 2, 3),
             block: BlockID::STONE,
             request_id: 7,
+            input_tick: 8,
+            player_position: Vec3::new(1.0, 64.0, 1.0),
         };
         let bytes = encode_client_message(&msg).unwrap();
         let back = decode_client_message(&bytes).unwrap();