@wovoon/polaris 0.5.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -26,6 +26,16 @@ room.send({ text: "你好" });
26
26
 
27
27
  零构建页面可直接用平台同源下发的全局版:`<script src="/api/cloud/sdk.js"></script>` → `WovoonCloud.*`。
28
28
 
29
+ ## 自建后端 Web 应用
30
+
31
+ 从 0.6.1 起,`WovoonManifest` 类型支持可选的 `backend: "platform" | "external"`。自建后端模式将 Web 静态前端上传并托管到 wovoon,后端和数据库由作者自行部署:
32
+
33
+ ```json
34
+ {"protocol":1,"backend":"external","capabilities":[]}
35
+ ```
36
+
37
+ 纯自建后端无需平台 SDK;同时调用平台能力时按实际用途声明 `capabilities`。前端使用绝对 HTTPS API / WSS 地址,后端配置实际运行域名的 CORS、WebSocket Origin 和独立身份校验。服务端密钥不进入前端包,平台 Cookie、令牌与运行票据不发送给外部后端。本地清单校验使用 `@wovoon/cli` 0.12.6 或更高版本。
38
+
29
39
  ## 资源打包最佳实践(大游戏必读)
30
40
 
31
41
  SDK 只负责云能力;**游戏资源的加载速度取决于打包方式**。两条硬规则:
package/dist/client.d.ts CHANGED
@@ -82,6 +82,28 @@ export declare class PolarisClient {
82
82
  onPresence: (callback: (frame: unknown) => void) => void;
83
83
  onClose: (callback: (payload: unknown) => void) => void;
84
84
  };
85
+ /** 世界总线:全服事件流(权威房间 ctx.worldBroadcast 广播到此),用法同房间。 */
86
+ world(): {
87
+ send: (data: unknown) => void;
88
+ leave: () => void;
89
+ onMessage: (callback: (payload: {
90
+ from: string;
91
+ data: unknown;
92
+ }) => void) => void;
93
+ onPresence: (callback: (frame: unknown) => void) => void;
94
+ onClose: (callback: (payload: unknown) => void) => void;
95
+ };
96
+ /** 内置匹配:凑满 exports.matchSize 人成局 → resolve 目标房间号(再 room(roomId, {mode}) 进入)。 */
97
+ match(mode: string): Promise<string>;
98
+ /** 房间列表(大厅/分线选择)。 */
99
+ rooms(options?: {
100
+ mode?: string;
101
+ }): Promise<Array<{
102
+ roomId: string;
103
+ mode: string;
104
+ players: number;
105
+ world: boolean;
106
+ }>>;
85
107
  collection<T = Record<string, unknown>>(name: string): {
86
108
  query: (options?: PolarisQueryOptions) => Promise<PolarisDocumentView[]>;
87
109
  get: (id: string) => Promise<PolarisDocumentView>;
package/dist/client.js CHANGED
@@ -184,6 +184,8 @@ export class PolarisClient {
184
184
  emit("presence", frame);
185
185
  else if (frame.type === "error")
186
186
  emit("message", { error: frame.message });
187
+ else if (frame.type === "matched")
188
+ emit("message", frame);
187
189
  };
188
190
  socket.onclose = () => {
189
191
  if (this.activeRooms.get(roomId) === handle)
@@ -198,6 +200,48 @@ export class PolarisClient {
198
200
  }).catch((error) => emit("close", { error: error.message }));
199
201
  return handle;
200
202
  }
203
+ /** 世界总线:全服事件流(权威房间 ctx.worldBroadcast 广播到此),用法同房间。 */
204
+ world() {
205
+ return this.room("__world");
206
+ }
207
+ /** 内置匹配:凑满 exports.matchSize 人成局 → resolve 目标房间号(再 room(roomId, {mode}) 进入)。 */
208
+ match(mode) {
209
+ if (!mode)
210
+ throw new PolarisError("match(mode) 需要模式名", "WOVOON_ARGUMENT");
211
+ return new Promise((resolve, reject) => {
212
+ this.session().then(() => {
213
+ const queue = this.room(`__match_${mode}`);
214
+ let done = false;
215
+ const timer = setTimeout(() => {
216
+ if (done)
217
+ return;
218
+ done = true;
219
+ try {
220
+ queue.leave();
221
+ }
222
+ catch { /* 已关 */ }
223
+ reject(new PolarisError("匹配等待超时(120 秒)", "WOVOON_MATCH_TIMEOUT"));
224
+ }, 120000);
225
+ queue.onMessage((payload) => {
226
+ const frame = payload;
227
+ if (done || frame?.type !== "matched" || !frame.roomId)
228
+ return;
229
+ done = true;
230
+ clearTimeout(timer);
231
+ try {
232
+ queue.leave();
233
+ }
234
+ catch { /* 已关 */ }
235
+ resolve(frame.roomId);
236
+ });
237
+ }).catch(reject);
238
+ });
239
+ }
240
+ /** 房间列表(大厅/分线选择)。 */
241
+ rooms(options) {
242
+ const query = options?.mode ? `?mode=${encodeURIComponent(options.mode)}` : "";
243
+ return this.session().then((data) => this.request("GET", `/api/cloud/${data.appId}/rooms${query}`));
244
+ }
201
245
  collection(name) {
202
246
  if (!name)
203
247
  throw new PolarisError("collection(name) 需要集合名", "WOVOON_ARGUMENT");
@@ -17,6 +17,8 @@ export declare function isValidCapability(value: string): boolean;
17
17
  export interface WovoonManifest {
18
18
  /** 协议版本,当前仅支持 1,缺省为 1。 */
19
19
  protocol?: typeof WOVOON_PROTOCOL_VERSION;
20
+ /** Web 前端仍由平台托管;external 表示使用创作者自行部署的后端,可同时声明实际使用的平台能力。 */
21
+ backend?: "platform" | "external";
20
22
  /** 声明使用的能力;未声明的能力在对应服务上线后不可调用。 */
21
23
  capabilities?: WovoonCapability[];
22
24
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wovoon/polaris",
3
- "version": "0.5.0",
3
+ "version": "0.6.1",
4
4
  "description": "wovoon Polaris SDK——wovoon 大后台云能力客户端(身份/数据集合/云函数/房间实时),协议 1",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -34,4 +34,4 @@
34
34
  "access": "public",
35
35
  "registry": "https://registry.npmjs.org/"
36
36
  }
37
- }
37
+ }