@wovoon/polaris 0.4.3 → 0.6.0

package/dist/client.d.ts

@@ -70,7 +70,9 @@ export declare class PolarisClient {
      * 重连安全：同一客户端对同一房间再次调用 room(roomId) 会自动断开旧连接——
      * 做"重连房间"按钮时直接再调一次 room() 即可，无需（但也不妨）先 leave() 旧的。
      */
-    room(roomId: string): {
+    room(roomId: string, options?: {
+        mode?: string;
+    }): {
         send: (data: unknown) => void;
         leave: () => void;
         onMessage: (callback: (payload: {
@@ -80,12 +82,41 @@ export declare class PolarisClient {
         onPresence: (callback: (frame: unknown) => void) => void;
         onClose: (callback: (payload: unknown) => void) => void;
     };
+    /** 世界总线：全服事件流（权威房间 ctx.worldBroadcast 广播到此），用法同房间。 */
+    world(): {
+        send: (data: unknown) => void;
+        leave: () => void;
+        onMessage: (callback: (payload: {
+            from: string;
+            data: unknown;
+        }) => void) => void;
+        onPresence: (callback: (frame: unknown) => void) => void;
+        onClose: (callback: (payload: unknown) => void) => void;
+    };
+    /** 内置匹配：凑满 exports.matchSize 人成局 → resolve 目标房间号（再 room(roomId, {mode}) 进入）。 */
+    match(mode: string): Promise<string>;
+    /** 房间列表（大厅/分线选择）。 */
+    rooms(options?: {
+        mode?: string;
+    }): Promise<Array<{
+        roomId: string;
+        mode: string;
+        players: number;
+        world: boolean;
+    }>>;
     collection<T = Record<string, unknown>>(name: string): {
         query: (options?: PolarisQueryOptions) => Promise<PolarisDocumentView[]>;
         get: (id: string) => Promise<PolarisDocumentView>;
         add: (data: T) => Promise<PolarisDocumentView>;
         set: (id: string, data: T) => Promise<PolarisDocumentView>;
         remove: (id: string) => Promise<unknown>;
+        /** onChange(cb)：集合被写入（玩家/云函数/权威房间）时回调 {action,id}——收到后重查。 */
+        onChange: (cb: (notice: {
+            action: string;
+            id: string;
+        }) => void) => {
+            close: () => void;
+        };
     };
 }
 export { parseData };

package/dist/client.js

@@ -102,7 +102,7 @@ export class PolarisClient {
      * 重连安全：同一客户端对同一房间再次调用 room(roomId) 会自动断开旧连接——
      * 做"重连房间"按钮时直接再调一次 room() 即可，无需（但也不妨）先 leave() 旧的。
      */
-    room(roomId) {
+    room(roomId, options) {
         if (!roomId)
             throw new PolarisError("room(roomId) 需要房间号", "WOVOON_ARGUMENT");
         this.activeRooms.get(roomId)?.leave();
@@ -121,7 +121,13 @@ export class PolarisClient {
         };
         const handle = {
             send: (data) => {
-                if (socket && socket.readyState === 1)
+                if (!socket || socket.readyState !== 1)
+                    return;
+                if (data instanceof ArrayBuffer)
+                    socket.send(data);
+                else if (data instanceof Uint8Array)
+                    socket.send(data.buffer);
+                else
                     socket.send(JSON.stringify({ type: "msg", data }));
             },
             leave: () => {
@@ -150,10 +156,19 @@ export class PolarisClient {
             const scheme = origin.startsWith("https") ? "wss" : "ws";
             const roomPath = `/api/cloud/rooms/${data.appId}/${encodeURIComponent(roomId)}`;
             const sid = /[?&#]wovoon_play_sid=([0-9a-fA-F-]{36})(?:&|$)/.exec(String(location.hash ?? ""))?.[1];
-            const query = sid ? `${roomPath.includes("?") ? "&" : "?"}wovoon_play_sid=${sid}` : "";
-            socket = new WebSocket(`${scheme}://${origin.replace(/^https?:\/\//, "")}${roomPath}${query}`);
+            const query = [];
+            if (sid)
+                query.push(`wovoon_play_sid=${sid}`);
+            if (options?.mode)
+                query.push(`mode=${encodeURIComponent(options.mode)}`);
+            socket = new WebSocket(`${scheme}://${origin.replace(/^https?:\/\//, "")}${roomPath}${query.length ? "?" + query.join("&") : ""}`);
+            socket.binaryType = "arraybuffer";
             socket.onopen = () => { this.activeRooms.set(roomId, handle); };
             socket.onmessage = (event) => {
+                if (event.data instanceof ArrayBuffer) {
+                    emit("message", { binary: true, data: new Uint8Array(event.data) });
+                    return;
+                }
                 let frame = null;
                 try {
                     frame = JSON.parse(String(event.data));
@@ -169,6 +184,8 @@ export class PolarisClient {
                     emit("presence", frame);
                 else if (frame.type === "error")
                     emit("message", { error: frame.message });
+                else if (frame.type === "matched")
+                    emit("message", frame);
             };
             socket.onclose = () => {
                 if (this.activeRooms.get(roomId) === handle)
@@ -183,6 +200,48 @@ export class PolarisClient {
         }).catch((error) => emit("close", { error: error.message }));
         return handle;
     }
+    /** 世界总线：全服事件流（权威房间 ctx.worldBroadcast 广播到此），用法同房间。 */
+    world() {
+        return this.room("__world");
+    }
+    /** 内置匹配：凑满 exports.matchSize 人成局 → resolve 目标房间号（再 room(roomId, {mode}) 进入）。 */
+    match(mode) {
+        if (!mode)
+            throw new PolarisError("match(mode) 需要模式名", "WOVOON_ARGUMENT");
+        return new Promise((resolve, reject) => {
+            this.session().then(() => {
+                const queue = this.room(`__match_${mode}`);
+                let done = false;
+                const timer = setTimeout(() => {
+                    if (done)
+                        return;
+                    done = true;
+                    try {
+                        queue.leave();
+                    }
+                    catch { /* 已关 */ }
+                    reject(new PolarisError("匹配等待超时（120 秒）", "WOVOON_MATCH_TIMEOUT"));
+                }, 120000);
+                queue.onMessage((payload) => {
+                    const frame = payload;
+                    if (done || frame?.type !== "matched" || !frame.roomId)
+                        return;
+                    done = true;
+                    clearTimeout(timer);
+                    try {
+                        queue.leave();
+                    }
+                    catch { /* 已关 */ }
+                    resolve(frame.roomId);
+                });
+            }).catch(reject);
+        });
+    }
+    /** 房间列表（大厅/分线选择）。 */
+    rooms(options) {
+        const query = options?.mode ? `?mode=${encodeURIComponent(options.mode)}` : "";
+        return this.session().then((data) => this.request("GET", `/api/cloud/${data.appId}/rooms${query}`));
+    }
     collection(name) {
         if (!name)
             throw new PolarisError("collection(name) 需要集合名", "WOVOON_ARGUMENT");
@@ -207,7 +266,58 @@ export class PolarisClient {
             add: (data) => docUrl().then((url) => client.request("POST", url, { data: JSON.stringify(data ?? {}) })),
             set: (id, data) => docUrl(id).then((url) => client.request("PUT", url, { data: JSON.stringify(data ?? {}) })),
             remove: (id) => docUrl(id).then((url) => client.request("DELETE", url)),
+            /** onChange(cb)：集合被写入（玩家/云函数/权威房间）时回调 {action,id}——收到后重查。 */
+            onChange: (cb) => {
+                return watchCollections(client, name, cb);
+            },
         };
     }
 }
+const collectionsWatch = { listeners: [], socket: null };
+function attachCollectionsWatch(client) {
+    if (collectionsWatch.socket || typeof WebSocket === "undefined")
+        return;
+    client.session().then((data) => {
+        const wsBase = String(globalThis.__wovoonRuntimeWsBase ?? "").replace(/\/+$/, "");
+        const origin = wsBase || `${location.protocol}//${location.host}`;
+        const scheme = origin.startsWith("https") ? "wss" : "ws";
+        const sid = /[?&#]wovoon_play_sid=([0-9a-fA-F-]{36})(?:&|$)/.exec(String(location.hash ?? ""))?.[1];
+        const query = sid ? `?wovoon_play_sid=${sid}` : "";
+        const socket = new WebSocket(`${scheme}://${origin.replace(/^https?:\/\//, "")}/api/cloud/rooms/${data.appId}/__collections${query}`);
+        collectionsWatch.socket = socket;
+        socket.onmessage = (event) => {
+            try {
+                const frame = JSON.parse(String(event.data));
+                if (frame?.type !== "docs")
+                    return;
+                for (const listener of collectionsWatch.listeners) {
+                    if (listener.collection === frame.collection && frame.action && frame.id) {
+                        try {
+                            listener.cb({ action: frame.action, id: frame.id });
+                        }
+                        catch { /* 监听器异常不中断 */ }
+                    }
+                }
+            }
+            catch { /* 非 JSON 帧忽略 */ }
+        };
+        socket.onclose = () => {
+            collectionsWatch.socket = null;
+            if (collectionsWatch.listeners.length)
+                setTimeout(() => attachCollectionsWatch(client), 2000);
+        };
+    }).catch(() => { });
+}
+function watchCollections(client, collection, cb) {
+    const listener = { collection, cb };
+    collectionsWatch.listeners.push(listener);
+    attachCollectionsWatch(client);
+    return {
+        close: () => {
+            const index = collectionsWatch.listeners.indexOf(listener);
+            if (index >= 0)
+                collectionsWatch.listeners.splice(index, 1);
+        },
+    };
+}
 export { parseData };

package/dist/protocol.js

@@ -9,7 +9,7 @@ export function isValidCollectionName(name) {
     return COLLECTION_NAME_PATTERN.test(name);
 }
 /** manifest 里单个能力名的完整合法形态（与平台 AssetSecurityScanner.parseContract 的校验一致）。 */
-export const CAPABILITY_PATTERN = /^(identity|function|room|collection:[a-z][a-z0-9_]{1,31})$/;
+export const CAPABILITY_PATTERN = /^(identity|function|room|room:competitive|gamelogic|collection:[a-z][a-z0-9_]{1,31})$/;
 export function isValidCapability(value) {
     return CAPABILITY_PATTERN.test(value);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wovoon/polaris",
-  "version": "0.4.3",
+  "version": "0.6.0",
   "description": "wovoon Polaris SDK——wovoon 大后台云能力客户端（身份/数据集合/云函数/房间实时），协议 1",
   "type": "module",
   "main": "dist/index.js",