@wovoon/polaris 0.3.0 → 0.4.1

package/README.md

@@ -26,5 +26,18 @@ room.send({ text: "你好" });
 
 零构建页面可直接用平台同源下发的全局版：`<script src="/api/cloud/sdk.js"></script>` → `WovoonCloud.*`。
 
+## 资源打包最佳实践（大游戏必读）
+
+SDK 只负责云能力；**游戏资源的加载速度取决于打包方式**。两条硬规则：
+
+- `.wasm`/`.pck`/`.bundle` 等二进制**直接发原始文件**——平台托管有正确 MIME
+  （`application/wasm`）、Range 分段与 CDN Brotli。**不要**用导出工具的 base64-JS 分片
+  （`xxx.000.js` 串）：体积膨胀 33% 且只能串行解码，加载时间成倍增加。
+- 加载用 `Promise.all` 并行 fetch + `WebAssembly.instantiateStreaming` 流式编译；
+  首包（引擎+开场）控制在 3MB 内，其余按场景分包按需下载。
+
+完整配方（含 Godot/TapTap 导出还原步骤）：`docs/recipes/web-asset-optimization.md`。
+`wovoon validate` 与平台发布扫描会对以上反模式给出同文案 WARN。
+
 - 协议正典与完整能力说明见仓库 [PROTOCOL.md](https://gitea/wujiwanjie/wovoon-polaris-sdk) 与 [llms.txt](./llms.txt)
 - 本地开发与校验：`npx @wovoon/cli init / dev / validate`

package/dist/client.d.ts

@@ -45,6 +45,8 @@ export declare class PolarisClient {
     private readonly baseUrl;
     private sessionPromise;
     private target;
+    /** 同房号的活动连接登记：重复 room(同房号) 自动离开旧连接（重连安全）。 */
+    private readonly activeRooms;
     constructor(init?: PolarisRequestInit);
     /** 指定作品目标：deploymentId（运行地址自动识别）或 appId。 */
     configure(options: {
@@ -65,6 +67,8 @@ export declare class PolarisClient {
     /**
      * 房间实时通道（room 能力）。浏览器同源 WebSocket；返回的句柄与平台下发 SDK 行为一致：
      * send 广播、onMessage 收 {from, data}、onPresence 收 joined/join/leave、onClose 断开。
+     * 重连安全：同一客户端对同一房间再次调用 room(roomId) 会自动断开旧连接——
+     * 做"重连房间"按钮时直接再调一次 room() 即可，无需（但也不妨）先 leave() 旧的。
      */
     room(roomId: string): {
         send: (data: unknown) => void;

package/dist/client.js

@@ -22,6 +22,8 @@ export class PolarisClient {
     constructor(init = {}) {
         this.sessionPromise = null;
         this.target = "";
+        /** 同房号的活动连接登记：重复 room(同房号) 自动离开旧连接（重连安全）。 */
+        this.activeRooms = new Map();
         this.baseUrl = (init.baseUrl ?? "").replace(/\/$/, "");
     }
     /** 指定作品目标：deploymentId（运行地址自动识别）或 appId。 */
@@ -83,10 +85,13 @@ export class PolarisClient {
     /**
      * 房间实时通道（room 能力）。浏览器同源 WebSocket；返回的句柄与平台下发 SDK 行为一致：
      * send 广播、onMessage 收 {from, data}、onPresence 收 joined/join/leave、onClose 断开。
+     * 重连安全：同一客户端对同一房间再次调用 room(roomId) 会自动断开旧连接——
+     * 做"重连房间"按钮时直接再调一次 room() 即可，无需（但也不妨）先 leave() 旧的。
      */
     room(roomId) {
         if (!roomId)
             throw new PolarisError("room(roomId) 需要房间号", "WOVOON_ARGUMENT");
+        this.activeRooms.get(roomId)?.leave();
         const listeners = {
             message: [], presence: [], close: [],
         };
@@ -100,6 +105,24 @@ export class PolarisClient {
                 catch { /* 监听器异常不中断通道 */ }
             }
         };
+        const handle = {
+            send: (data) => {
+                if (socket && socket.readyState === 1)
+                    socket.send(JSON.stringify({ type: "msg", data }));
+            },
+            leave: () => {
+                left = true;
+                if (this.activeRooms.get(roomId) === handle)
+                    this.activeRooms.delete(roomId);
+                try {
+                    socket?.close();
+                }
+                catch { /* 已关闭 */ }
+            },
+            onMessage: (callback) => { listeners.message.push(callback); },
+            onPresence: (callback) => { listeners.presence.push(callback); },
+            onClose: (callback) => { listeners.close.push(callback); },
+        };
         this.session().then((data) => {
             if (left || typeof WebSocket === "undefined") {
                 if (!left)
@@ -109,6 +132,7 @@ export class PolarisClient {
             const origin = this.baseUrl || `${location.protocol}//${location.host}`;
             const scheme = origin.startsWith("https") ? "wss" : "ws";
             socket = new WebSocket(`${scheme}://${origin.replace(/^https?:\/\//, "")}/api/cloud/rooms/${data.appId}/${encodeURIComponent(roomId)}`);
+            socket.onopen = () => { this.activeRooms.set(roomId, handle); };
             socket.onmessage = (event) => {
                 let frame = null;
                 try {
@@ -126,25 +150,18 @@ export class PolarisClient {
                 else if (frame.type === "error")
                     emit("message", { error: frame.message });
             };
-            socket.onclose = () => emit("close", {});
-            socket.onerror = () => emit("close", {});
+            socket.onclose = () => {
+                if (this.activeRooms.get(roomId) === handle)
+                    this.activeRooms.delete(roomId);
+                emit("close", {});
+            };
+            socket.onerror = () => {
+                if (this.activeRooms.get(roomId) === handle)
+                    this.activeRooms.delete(roomId);
+                emit("close", {});
+            };
         }).catch((error) => emit("close", { error: error.message }));
-        return {
-            send: (data) => {
-                if (socket && socket.readyState === 1)
-                    socket.send(JSON.stringify({ type: "msg", data }));
-            },
-            leave: () => {
-                left = true;
-                try {
-                    socket?.close();
-                }
-                catch { /* 已关闭 */ }
-            },
-            onMessage: (callback) => { listeners.message.push(callback); },
-            onPresence: (callback) => { listeners.presence.push(callback); },
-            onClose: (callback) => { listeners.close.push(callback); },
-        };
+        return handle;
     }
     collection(name) {
         if (!name)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wovoon/polaris",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "wovoon Polaris SDK——wovoon 大后台云能力客户端（身份/数据集合/云函数/房间实时），协议 1",
   "type": "module",
   "main": "dist/index.js",
@@ -34,4 +34,4 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   }
-}
+}