fix: 返回大厅时清空遗留的缓存

- 不会再遗留之前世界的渲染
- 会刷新世界列表

Author: NOVIIC

crates/client/src/lib.rs

@@ -126,6 +126,8 @@ struct App {
     disconnect_reason: Option<String>,
 
     game: Option<Game>,
+    /// 当前世界会话编号。进入 / 离开世界时递增，异步存档回写前用它识别过期结果。
+    world_session_id: u64,
 
     /// 上一帧 performance.now()（毫秒）
     last_time_ms: f64,
@@ -206,6 +208,7 @@ pub async fn start() -> Result<(), JsValue> {
         connecting_error: None,
         disconnect_reason: None,
         game: None,
+        world_session_id: 0,
         last_time_ms: now_ms(),
         fps_frames: 0,
         fps_accum: 0.0,
@@ -224,6 +227,57 @@ pub async fn start() -> Result<(), JsValue> {
     Ok(())
 }
 
+/// 递增世界会话编号。所有跨 await 的世界相关异步任务都应捕获编号，回写前再次比对。
+fn bump_world_session(a: &mut App) -> u64 {
+    a.world_session_id = a.world_session_id.wrapping_add(1);
+    a.world_session_id
+}
+
+/// 清掉当前世界运行时资源。Renderer 是跨状态常驻对象，必须显式清空世界 GPU 缓存。
+fn clear_world_runtime(a: &mut App) -> u64 {
+    let session_id = bump_world_session(a);
+    a.game = None;
+    a.preload_state = None;
+    a.request_pointer_lock_next = false;
+    a.relayed_peers.clear();
+    a.notifications.clear();
+    a.perf = FramePerfStats::default();
+    a.egui_events.borrow_mut().clear();
+    a.renderer.clear_world_cache();
+    a.input.borrow_mut().clear_held();
+    if let Some(doc) = web_sys::window().and_then(|w| w.document()) {
+        doc.exit_pointer_lock();
+    }
+    session_id
+}
+
+/// 开始新世界前的统一入口：先结束旧会话，再返回新会话编号给异步存档任务使用。
+fn prepare_world_start(a: &mut App) -> u64 {
+    let session_id = clear_world_runtime(a);
+    a.disconnect_reason = None;
+    a.connecting_error = None;
+    session_id
+}
+
+/// 回大厅时让下一帧 Lobby 重新读取 OPFS 世界列表，避免显示退出前的旧缓存。
+fn mark_lobby_saves_stale(a: &mut App) {
+    a.lobby_state.saves_loaded = false;
+    a.lobby_state.saves_loading = false;
+    a.lobby_state.saved_worlds.clear();
+    a.lobby_state.selected_save = None;
+}
+
+/// 所有“返回大厅”路径的统一收口。
+fn return_to_lobby(a: &mut App) {
+    clear_world_runtime(a);
+    a.state = AppState::Lobby;
+    a.disconnect_reason = None;
+    a.connecting_error = None;
+    a.connecting_room_id.clear();
+    a.connecting_mode = GameMode::Local;
+    mark_lobby_saves_stale(a);
+}
+
 // ============================================================
 // 主循环 & 事件
 // ============================================================
@@ -953,26 +1007,29 @@ fn start_single_player(
     let rd = game.settings.render_distance as i32;
     let total = ((2 * rd + 1) * (2 * rd + 1)) as usize;
 
-    let mut a = app.borrow_mut();
-    a.game = Some(game);
-    a.connecting_mode = GameMode::Local;
-    a.connecting_room_id = String::new();
-    a.connecting_error = None;
-    a.preload_state = Some(PreloadState {
-        total,
-        received: 0,
-        meshed: 0,
-        active: true,
-    });
-    a.state = AppState::Connecting;
-    log::info!("[local] 进入加载界面，开始区块预载 (total={total})");
-    drop(a);
+    let session_id = {
+        let mut a = app.borrow_mut();
+        let session_id = prepare_world_start(&mut a);
+        a.game = Some(game);
+        a.connecting_mode = GameMode::Local;
+        a.connecting_room_id = String::new();
+        a.connecting_error = None;
+        a.preload_state = Some(PreloadState {
+            total,
+            received: 0,
+            meshed: 0,
+            active: true,
+        });
+        a.state = AppState::Connecting;
+        log::info!("[local] 进入加载界面，开始区块预载 (total={total})");
+        session_id
+    };
 
     // 如果有 save_key，使用 open_by_key 加载；否则创建新存档
     if let Some(key) = save_key {
-        attach_storage_for_load(app.clone(), key.to_string());
+        attach_storage_for_load(app.clone(), key.to_string(), session_id);
     } else {
-        attach_storage_for_new(app.clone(), seed);
+        attach_storage_for_new(app.clone(), seed, session_id);
     }
 }
 
@@ -1103,6 +1160,7 @@ fn start_host(
             game.camera.position = game.physics.eye_position();
             game.camera.pitch = -0.4;
 
+            let session_id = prepare_world_start(&mut a);
             a.game = Some(game);
             a.state = AppState::Connecting;
             a.connecting_mode = GameMode::Host;
@@ -1114,10 +1172,10 @@ fn start_host(
 
             // 如果有 save_key，使用 open_by_key 加载；否则创建新存档
             if let Some(key) = save_key {
-                attach_storage_for_load(app.clone(), key.to_string());
+                attach_storage_for_load(app.clone(), key.to_string(), session_id);
             } else {
                 // Host 模式：使用 room_id + seed 创建存档
-                attach_storage_async(app.clone(), room_id.to_string(), seed);
+                attach_storage_async(app.clone(), room_id.to_string(), seed, session_id);
             }
         }
         Err(e) => {
@@ -1151,6 +1209,7 @@ fn start_remote(app: &Rc<RefCell<App>>, room_id: &str, display_name: &str) {
             game.camera.position = game.physics.eye_position();
             game.camera.pitch = -0.4;
 
+            prepare_world_start(&mut a);
             a.game = Some(game);
             a.state = AppState::Connecting;
             a.connecting_mode = GameMode::Remote;
@@ -1166,7 +1225,7 @@ fn start_remote(app: &Rc<RefCell<App>>, room_id: &str, display_name: &str) {
     }
 }
 
-fn attach_storage_async(app: Rc<RefCell<App>>, room_id: String, seed: u64) {
+fn attach_storage_async(app: Rc<RefCell<App>>, room_id: String, seed: u64, session_id: u64) {
     wasm_bindgen_futures::spawn_local(async move {
         let _ = OpfsStorage::request_persistence().await;
         match OpfsStorage::open(&room_id, seed).await {
@@ -1193,6 +1252,10 @@ fn attach_storage_async(app: Rc<RefCell<App>>, room_id: String, seed: u64) {
                 }
                 let quota = storage.quota().await;
                 let mut a = app.borrow_mut();
+                if a.world_session_id != session_id {
+                    log::debug!("[storage] 丢弃过期 Host 存档加载结果");
+                    return;
+                }
                 if let Some(g) = a.game.as_mut() {
                     for (pos, chunk) in loaded {
                         g.server.borrow_mut().load_chunk_from_storage(pos, chunk);
@@ -1206,6 +1269,9 @@ fn attach_storage_async(app: Rc<RefCell<App>>, room_id: String, seed: u64) {
             }
             Err(e) => {
                 let mut a = app.borrow_mut();
+                if a.world_session_id != session_id {
+                    return;
+                }
                 if let Some(g) = a.game.as_mut() {
                     g.storage_error = Some(format!("{e:?}"));
                 }
@@ -1215,7 +1281,7 @@ fn attach_storage_async(app: Rc<RefCell<App>>, room_id: String, seed: u64) {
 }
 
 /// 创建新存档（用当前时间戳 + seed 生成 key）
-fn attach_storage_for_new(app: Rc<RefCell<App>>, seed: u64) {
+fn attach_storage_for_new(app: Rc<RefCell<App>>, seed: u64, session_id: u64) {
     wasm_bindgen_futures::spawn_local(async move {
         let _ = OpfsStorage::request_persistence().await;
         match OpfsStorage::create_new(seed).await {
@@ -1242,6 +1308,10 @@ fn attach_storage_for_new(app: Rc<RefCell<App>>, seed: u64) {
                 }
                 let quota = storage.quota().await;
                 let mut a = app.borrow_mut();
+                if a.world_session_id != session_id {
+                    log::debug!("[storage] 丢弃过期新存档加载结果");
+                    return;
+                }
                 if let Some(g) = a.game.as_mut() {
                     for (pos, chunk) in loaded {
                         g.server.borrow_mut().load_chunk_from_storage(pos, chunk);
@@ -1255,6 +1325,9 @@ fn attach_storage_for_new(app: Rc<RefCell<App>>, seed: u64) {
             }
             Err(e) => {
                 let mut a = app.borrow_mut();
+                if a.world_session_id != session_id {
+                    return;
+                }
                 if let Some(g) = a.game.as_mut() {
                     g.storage_error = Some(format!("{e:?}"));
                 }
@@ -1264,7 +1337,7 @@ fn attach_storage_for_new(app: Rc<RefCell<App>>, seed: u64) {
 }
 
 /// 通过 key 加载已有存档
-fn attach_storage_for_load(app: Rc<RefCell<App>>, key: String) {
+fn attach_storage_for_load(app: Rc<RefCell<App>>, key: String, session_id: u64) {
     wasm_bindgen_futures::spawn_local(async move {
         let _ = OpfsStorage::request_persistence().await;
         match OpfsStorage::open_by_key(&key).await {
@@ -1291,6 +1364,10 @@ fn attach_storage_for_load(app: Rc<RefCell<App>>, key: String) {
                 }
                 let quota = storage.quota().await;
                 let mut a = app.borrow_mut();
+                if a.world_session_id != session_id {
+                    log::debug!("[storage] 丢弃过期已有存档加载结果");
+                    return;
+                }
                 if let Some(g) = a.game.as_mut() {
                     for (pos, chunk) in loaded {
                         g.server.borrow_mut().load_chunk_from_storage(pos, chunk);
@@ -1304,6 +1381,9 @@ fn attach_storage_for_load(app: Rc<RefCell<App>>, key: String) {
             }
             Err(e) => {
                 let mut a = app.borrow_mut();
+                if a.world_session_id != session_id {
+                    return;
+                }
                 if let Some(g) = a.game.as_mut() {
                     g.storage_error = Some(format!("{e:?}"));
                 }
@@ -1484,12 +1564,8 @@ fn render_connecting_frame(app: &Rc<RefCell<App>>, cw: u32, ch: u32) -> Result<(
     };
 
     if matches!(cancel, Some(ConnectingAction::Cancel)) {
-        // 直接丢掉 game，回 Lobby
         let mut a = app.borrow_mut();
-        a.game = None;
-        a.preload_state = None;
-        a.state = AppState::Lobby;
-        a.connecting_error = None;
+        return_to_lobby(&mut a);
         return Ok(());
     }
 
@@ -1627,9 +1703,7 @@ fn render_disconnected_frame(app: &Rc<RefCell<App>>, cw: u32, ch: u32) -> Result
 
     if matches!(action, ui::disconnected::DisconnectedAction::BackToLobby) {
         let mut a = app.borrow_mut();
-        a.state = AppState::Lobby;
-        a.disconnect_reason = None;
-        a.connecting_error = None;
+        return_to_lobby(&mut a);
         return Ok(());
     }
 
@@ -1787,13 +1861,11 @@ fn apply_room_event(app: &Rc<RefCell<App>>, ev: RoomEvent) {
         }
         RoomEvent::Disconnected { reason } => {
             log::warn!("[net] Disconnected: {reason}");
+            clear_world_runtime(&mut a);
             a.disconnect_reason = Some(reason.clone());
             a.connecting_error = Some(reason);
-            a.preload_state = None;
-            a.relayed_peers.clear();
             // Phase 6：Connecting / InGame 失联都跳到 Disconnected 页让用户看到原因
             a.state = AppState::Disconnected;
-            a.game = None;
         }
         RoomEvent::RemoteLeft { peer_id } => {
             log::info!("[net] RemoteLeft: peer {peer_id}");
@@ -2338,10 +2410,7 @@ fn render_game_frame(
     }
     if pause_exit_to_lobby {
         let mut a = app.borrow_mut();
-        a.game = None;
-        a.state = AppState::Lobby;
-        a.disconnect_reason = None;
-        a.preload_state = None;
+        return_to_lobby(&mut a);
         return Ok(());
     }
 

crates/client/src/ui/disconnected.rs

@@ -8,7 +8,7 @@
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum DisconnectedAction {
     None,
-    /// 用户点了"返回大厅"。调用方设 `app.state = AppState::Lobby` 并清 `disconnect_reason`。
+    /// 用户点了"返回大厅"。调用方走统一的大厅重置流程。
     BackToLobby,
 }
 

crates/render/src/lib.rs

@@ -168,6 +168,16 @@ impl Renderer {
         self.transparent_meshes.remove(&pos);
     }
 
+    /// 清空当前世界上传过的渲染缓存。
+    ///
+    /// Renderer 跨 AppState 常驻；退出世界只销毁 client::Game 不会自动释放这里的
+    /// GPU 缓存，所以切换世界前必须显式清空，避免上一局内容继续参与绘制。
+    pub fn clear_world_cache(&mut self) {
+        self.chunk_meshes.clear();
+        self.transparent_meshes.clear();
+        self.player_pass.upload_instances(&self.queue, &[]);
+    }
+
     /// 查询某个 chunk 是否已有 GPU mesh。
     /// Phase 2 ChunkLoader 用其决定邻居是否需重网格化（跨区块剔除生效条件）。
     pub fn has_chunk_mesh(&self, pos: ChunkPos) -> bool {

docs/modules/client.md

@@ -172,6 +172,7 @@ struct App {
     disconnect_reason: Option<String>,
 
     game: Option<Game>,
+    world_session_id: u64,           // 每次进入/离开世界递增，用于丢弃旧异步回调
 
     last_time_ms: f64,
     fps_frames: u32, fps_accum: f32, fps_display: f32,
@@ -241,6 +242,12 @@ pub struct FrameClock { /* accumulator: f32, step: f32 */ }
 
 > Phase 2 不引入 `world_view`：Local 模式下 mesh 回调直接借 `server.world.get_block_world`。Phase 5 加入 Remote 模式时才有 `WorldView` 副本（由 ChunkSnapshot 喂数据）。
 
+### 世界会话清理
+
+进入新世界或离开当前世界时，client 会递增 `world_session_id`，并清理 `Game`、区块预载状态、输入事件、性能统计与 `Renderer` 内的世界 GPU 缓存。OPFS 存档加载等异步任务在回写前必须比对启动时捕获的 `world_session_id`；若会话已变化，直接丢弃结果，避免“退出再进入”后旧世界的 chunk 或 mesh 混入新世界。
+
+返回大厅统一清空当前存档列表缓存并标记为未加载，让下一帧 Lobby 自动重新读取 OPFS 世界列表。
+
 ---
 
 ## 五、主循环

docs/modules/render.md

@@ -295,6 +295,9 @@ impl Renderer {
     /// 卸载远处 chunk 网格
     pub fn drop_chunk_mesh(&mut self, pos: ChunkPos);
 
+    /// 退出当前世界 / 进入新世界前清空所有世界渲染缓存
+    pub fn clear_world_cache(&mut self);
+
     /// 查询某个 chunk 是否已有 GPU mesh
     pub fn has_chunk_mesh(&self, pos: ChunkPos) -> bool;
 
@@ -327,7 +330,7 @@ impl Renderer {
 |---|---|---|
 | `Surface` / `Device` / `Queue` | `Renderer::new` 一次 | Tab 关闭 |
 | `depth_texture` | 启动 + 每次 resize | 重建时 |
-| `chunk_mesh_gpu` | `upload_chunk_mesh` | `drop_chunk_mesh`（玩家走远）/ chunk 修改时（重建） |
+| `chunk_mesh_gpu` | `upload_chunk_mesh` | `drop_chunk_mesh`（玩家走远）/ `clear_world_cache`（退出或切换世界）/ chunk 修改时（重建） |
 | Pass pipelines | 各 Pass `new` 一次 | 程序退出 |
 
 **Chunk 网格更新规则**：