@wovoon/polaris 0.10.0 → 0.15.0

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/PROTOCOL.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # wovoon 平台协议 v1(Polaris)
2
2
 
3
3
  > 本文件是 wovoon 开发者协议的**正典定义**(canonical spec)。前端永远静态托管;后端能力由 wovoon 大后台按本协议提供。
4
- > 版本规则:协议字段一经发布**只加不改不删**;破坏性变更必须升协议版本号。
4
+ > 版本规则:使用能力前须核对 SDK 版本、当前能力列表和宿主支持;退役能力不提供空实现,作品升级时须同步更新声明及调用。
5
5
  > 本协议面向人类与 AI coding 工具同等优化:任何 LLM 依据本文档即可完成开发与改造。
6
6
 
7
7
  > 协议 1 新增可选常驻玩法子协议 `wovoon.game/1`,其规范见 [平台玩法契约](docs/recipes/platform-game-mode.md)。旧房间接口保留;新玩法须确认目标环境已部署,声明 `gamelogic` 并导出 `gameProtocol=1` 后才启用新限频、快照与恢复语义。
@@ -47,7 +47,7 @@
47
47
  | `collection:<name>` | 数据集合:带权限规则(读 WORLD/PLAYER,写 OWNER/SERVER)的 JSON 文档 CRUD 与排序查询 | 已实现 |
48
48
  | `function` | 云函数:服务端权威逻辑(受限 Node 沙箱) | 已实现 |
49
49
  | `room` | 房间实时通道:WebSocket 消息中继(多人在线) | 已实现 |
50
- | `ads` | 可选作品广告容器:宿主按作品租约、平台配置和格式选择已授权广告源;无源立即跳过,不影响游戏 | SDK 0.8.0;Android 横幅/插屏/服务端校验激励,网页无源跳过 |
50
+ | `ads` | 作品激励广告:GroMore 原生 Android 广告与服务端验签奖励;顷悟提供隔离的模拟预览,不提供作品横幅或插屏 | SDK 0.15 / CLI 0.22,需对应运行时 |
51
51
 
52
52
  - 未知顶层字段、非法能力名、非法 JSON、不支持协议版本 → **上传扫描直接拒绝**,报错信息包含修复指引;
53
53
  - 能力声明将在对应服务上线后成为**调用前置条件**(未声明则接口拒绝)。
@@ -60,13 +60,6 @@
60
60
 
61
61
  ## 4. 能力契约(Capability APIs)
62
62
 
63
- 作品广告通过 `WovoonPolaris.ads.capabilities()`、`show()`、`mountBanner()` 调用,
64
- 独立于 `identity`。宿主处理权限、聚合位、频控、加载与关闭;作品仅提供场景名和
65
- 横幅容器,不提供广告源或价格。网页未授权时返回 `unavailable`,不得回退到模拟广告。
66
- 激励广告必须配置服务端验证与作品奖励规则,只信任服务端账本回执。缺配置时 `rewarded` 为 `false`。
67
- `rewardStatus / rewardBalances / consumeReward` 用于查询与幂等使用作品奖励,见 [激励广告](docs/rewarded-ads.md);开屏由 App 管理。
68
- 完整接口、结果和暂停恢复约定见 [作品广告容器](docs/ads.md)。
69
-
70
63
  协议 1 的能力 API 面由 `@wovoon/polaris` SDK(本仓库)承载,数据形状:
71
64
 
72
65
  - `identity`:`POST /api/cloud/session` → `{appId, playerId, loggedIn, displayName, avatarUrl}`;
package/dist/ads.d.ts CHANGED
@@ -1,7 +1,8 @@
1
1
  /** Optional host capability. Browsers and older/iOS hosts without an approved source skip immediately. */
2
- export type PolarisAdFormat = "banner" | "interstitial" | "rewarded";
2
+ export type PolarisAdFormat = "rewarded";
3
3
  export type PolarisAdStatus = "shown" | "closed" | "unavailable" | "no_fill" | "busy" | "frequency_capped" | "cancelled" | "error";
4
4
  export interface PolarisRewardReceipt {
5
+ simulated?: boolean;
5
6
  requestId: string;
6
7
  status: "pending" | "granted" | "expired";
7
8
  rewardKey: string;
@@ -20,6 +21,7 @@ export interface PolarisRewardSpend {
20
21
  balanceAfter: number;
21
22
  }
22
23
  export interface PolarisAdResult {
24
+ simulated?: boolean;
23
25
  status: PolarisAdStatus;
24
26
  reason?: string;
25
27
  requestId?: string;
@@ -28,11 +30,14 @@ export interface PolarisAdResult {
28
30
  }
29
31
  export type PolarisRewardRequest = (action: "status" | "balances" | "consume", body: object) => Promise<unknown>;
30
32
  export interface PolarisAdCapabilities {
31
- surface: "android" | "web";
33
+ simulated?: boolean;
34
+ surface: "android" | "ios" | "web" | "preview";
32
35
  banner: boolean;
33
36
  interstitial: boolean;
34
37
  rewarded: boolean;
35
38
  reason?: string;
39
+ /** A preview host tests the public contract; it is never native-device acceptance. */
40
+ previewTarget?: "web" | "mobile";
36
41
  }
37
42
  export interface PolarisAdOptions {
38
43
  /** Stable scene name, not a network ad-unit ID. */
@@ -40,11 +45,6 @@ export interface PolarisAdOptions {
40
45
  onPause?: () => void;
41
46
  onResume?: () => void;
42
47
  }
43
- export interface PolarisBanner {
44
- ready: Promise<PolarisAdResult>;
45
- closed: Promise<PolarisAdResult>;
46
- destroy(): void;
47
- }
48
48
  export declare class PolarisAds {
49
49
  private readonly host;
50
50
  private readonly rewardRequest?;
@@ -54,10 +54,11 @@ export declare class PolarisAds {
54
54
  private bridge;
55
55
  capabilities(): Promise<PolarisAdCapabilities>;
56
56
  show(options: PolarisAdOptions & {
57
- format: "interstitial" | "rewarded";
57
+ format: "rewarded";
58
58
  }): Promise<PolarisAdResult>;
59
59
  /** Query after a delayed callback, reconnect or reload. Reading a receipt never grants it again. */
60
60
  rewardStatus(requestId: string): Promise<PolarisRewardReceipt>;
61
+ private readReward;
61
62
  /** Durable, work-scoped virtual balances are available on web as well as Android. */
62
63
  rewardBalances(): Promise<PolarisRewardBalance[]>;
63
64
  /** Keep clientId for retries after uncertain network results. Never generate a new ID for a retry. */
@@ -67,8 +68,7 @@ export declare class PolarisAds {
67
68
  amount: number;
68
69
  }): Promise<PolarisRewardSpend>;
69
70
  private queryReward;
70
- mountBanner(container: HTMLElement, options: Pick<PolarisAdOptions, "placement">): PolarisBanner;
71
- /** Cancel outstanding requests when a game scene/client is replaced. */
71
+ /** Release a request and invalidate delayed replies when the work or player changes. */
72
72
  dispose(): void;
73
73
  private validPlacement;
74
74
  private result;
package/dist/ads.js CHANGED
@@ -15,14 +15,19 @@ export class PolarisAds {
15
15
  return { surface: "web", banner: false, interstitial: false, rewarded: false, reason: "NO_AUTHORIZED_SOURCE" };
16
16
  const response = await this.open("capabilities", {}).ready;
17
17
  const value = response;
18
- return { surface: "android", banner: value.banner === true, interstitial: value.interstitial === true,
18
+ const surface = ["android", "ios", "web", "preview"].includes(String(value.surface)) ? value.surface : "android";
19
+ return { surface, banner: false, interstitial: false,
20
+ ...(surface === "preview" ? { simulated: true } : {}),
19
21
  rewarded: !!this.rewardRequest && value.rewarded === true && value.rewardProtocol === 1,
22
+ ...(surface === "preview" && ["web", "mobile"].includes(String(value.previewTarget)) ? { previewTarget: value.previewTarget } : {}),
20
23
  ...(value.reason ? { reason: value.reason } : {}) };
21
24
  }
22
25
  show(options) {
23
- if (!options || !["interstitial", "rewarded"].includes(options.format) || !this.validPlacement(options.placement)) {
26
+ if (!options || !["rewarded"].includes(options.format) || !this.validPlacement(options.placement)) {
24
27
  return Promise.resolve(this.result("error", "INVALID_ARGUMENT"));
25
28
  }
29
+ if (options.format !== "rewarded")
30
+ return Promise.resolve(this.result("unavailable", "FORMAT_NOT_SUPPORTED"));
26
31
  const generation = this.generation;
27
32
  return this.open("show", { format: options.format, placement: options.placement }, options).closed.then(async (result) => {
28
33
  if (generation !== this.generation)
@@ -30,11 +35,25 @@ export class PolarisAds {
30
35
  if (options.format !== "rewarded" || !result.requestId || result.status !== "closed")
31
36
  return result;
32
37
  try {
33
- const reward = await this.rewardStatus(result.requestId);
38
+ let reward = await this.readReward(result.requestId, 2000);
39
+ // The native close can race the server callback. Poll the same receipt,
40
+ // never create another ad request or infer a grant from native/JS flags.
41
+ for (const delay of [250, 750, 1500]) {
42
+ if (reward.status !== "pending" || generation !== this.generation)
43
+ break;
44
+ await new Promise(resolve => {
45
+ const finish = () => { this.host.clearTimeout(timer); this.releases.delete(finish); resolve(); };
46
+ const timer = this.host.setTimeout(finish, delay);
47
+ this.releases.add(finish);
48
+ });
49
+ if (generation !== this.generation)
50
+ return this.result("cancelled");
51
+ reward = await this.readReward(result.requestId, 2000);
52
+ }
34
53
  if (generation !== this.generation)
35
54
  return this.result("cancelled");
36
55
  return { ...result, rewarded: reward.status === "granted", reward,
37
- ...(reward.status === "pending" ? { reason: "REWARD_PENDING" } : {}) };
56
+ reason: reward.status === "pending" ? "REWARD_PENDING" : reward.status === "expired" ? "REWARD_EXPIRED" : undefined };
38
57
  }
39
58
  catch {
40
59
  if (generation !== this.generation)
@@ -46,9 +65,12 @@ export class PolarisAds {
46
65
  }
47
66
  /** Query after a delayed callback, reconnect or reload. Reading a receipt never grants it again. */
48
67
  async rewardStatus(requestId) {
68
+ return this.readReward(requestId, 8000);
69
+ }
70
+ async readReward(requestId, timeout) {
49
71
  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(requestId))
50
72
  throw new Error("INVALID_REWARD_REQUEST");
51
- const value = await this.queryReward("status", { requestId });
73
+ const value = await this.queryReward("status", { requestId }, timeout);
52
74
  if (!value || value.requestId !== requestId || !["pending", "granted", "expired"].includes(value.status) ||
53
75
  !this.validPlacement(value.rewardKey) || typeof value.rewardName !== "string" ||
54
76
  !Number.isInteger(value.amount) || value.amount < 1 || value.amount > 10000 ||
@@ -76,14 +98,14 @@ export class PolarisAds {
76
98
  throw new Error("INVALID_REWARD_SPEND");
77
99
  return value;
78
100
  }
79
- async queryReward(action, input) {
101
+ async queryReward(action, input, timeout = 8000) {
80
102
  if (!this.rewardRequest)
81
103
  throw new Error("REWARD_API_UNAVAILABLE");
82
104
  let timer;
83
105
  const generation = this.generation;
84
106
  try {
85
107
  const result = await Promise.race([this.rewardRequest(action, input), new Promise((_, reject) => {
86
- timer = this.host.setTimeout(() => reject(new Error("REWARD_QUERY_TIMEOUT")), 8000);
108
+ timer = this.host.setTimeout(() => reject(new Error("REWARD_QUERY_TIMEOUT")), timeout);
87
109
  })]);
88
110
  if (generation !== this.generation)
89
111
  throw new Error("REWARD_CONTEXT_CHANGED");
@@ -94,42 +116,7 @@ export class PolarisAds {
94
116
  this.host.clearTimeout(timer);
95
117
  }
96
118
  }
97
- mountBanner(container, options) {
98
- // No DOM mutation, network request, timer or empty placeholder when no source exists.
99
- if (!this.bridge())
100
- return this.finished(this.result("unavailable", "NO_AUTHORIZED_SOURCE"));
101
- if (!container || typeof container.getBoundingClientRect !== "function" || !this.validPlacement(options?.placement)) {
102
- return this.finished(this.result("error", "INVALID_ARGUMENT"));
103
- }
104
- const rect = () => {
105
- const b = container.getBoundingClientRect();
106
- const style = this.host.getComputedStyle(container);
107
- const visible = container.isConnected && this.host.document.visibilityState === "visible" &&
108
- style.visibility === "visible" && style.display !== "none" && Number(style.opacity) > 0 &&
109
- b.top >= 0 && b.left >= 0 && b.bottom <= this.host.innerHeight && b.right <= this.host.innerWidth;
110
- return { x: b.left, y: b.top, width: b.width, height: b.height,
111
- viewportWidth: this.host.innerWidth, viewportHeight: this.host.innerHeight, visible };
112
- };
113
- const first = rect();
114
- if (!first.visible || first.width < 320 || first.height < 50) {
115
- return this.finished(this.result("unavailable", "CONTAINER_NOT_VISIBLE"));
116
- }
117
- const handle = this.open("show", { format: "banner", placement: options.placement, rect: first });
118
- const update = () => handle.send("resize", { rect: rect() });
119
- // Native expires the view if geometry stops arriving (navigation, frozen/hidden document).
120
- const timer = this.host.setInterval(update, 500);
121
- this.host.addEventListener("scroll", update, true);
122
- this.host.addEventListener("resize", update);
123
- this.host.document.addEventListener("visibilitychange", update);
124
- void handle.closed.then(() => {
125
- this.host.clearInterval(timer);
126
- this.host.removeEventListener("scroll", update, true);
127
- this.host.removeEventListener("resize", update);
128
- this.host.document.removeEventListener("visibilitychange", update);
129
- });
130
- return handle;
131
- }
132
- /** Cancel outstanding requests when a game scene/client is replaced. */
119
+ /** Release a request and invalidate delayed replies when the work or player changes. */
133
120
  dispose() { this.generation++; for (const release of [...this.releases])
134
121
  release(); }
135
122
  validPlacement(value) { return typeof value === "string" && /^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/.test(value); }
@@ -145,6 +132,7 @@ export class PolarisAds {
145
132
  const ready = new Promise(r => { resolveReady = r; });
146
133
  const closed = new Promise(r => { resolveClosed = r; });
147
134
  let done = false, paused = false;
135
+ let phase = "initial";
148
136
  const callback = (fn) => { try {
149
137
  fn?.();
150
138
  }
@@ -185,7 +173,23 @@ export class PolarisAds {
185
173
  }
186
174
  if (!value || value.channel !== "wovoon:ads:v1" || value.id !== id || done)
187
175
  return;
176
+ // Reading the native reward confirmation is not SDK loading or ad presentation.
177
+ // Accept each transition once so duplicate host events cannot extend its deadline.
178
+ if (value.event === "awaiting_confirmation" && action === "show" &&
179
+ params.format === "rewarded" && phase === "initial") {
180
+ phase = "confirmation";
181
+ this.host.clearTimeout(timer);
182
+ timer = this.host.setTimeout(timeout, 300000);
183
+ return;
184
+ }
185
+ if (value.event === "loading" && phase === "confirmation") {
186
+ phase = "loading";
187
+ this.host.clearTimeout(timer);
188
+ timer = this.host.setTimeout(timeout, 30000);
189
+ return;
190
+ }
188
191
  if (value.event === "presenting") {
192
+ phase = "presenting";
189
193
  this.host.clearTimeout(timer);
190
194
  if (!paused) {
191
195
  paused = true;
@@ -200,20 +204,23 @@ export class PolarisAds {
200
204
  const safe = { ...result, rewarded: action === "capabilities" && result.rewarded === true };
201
205
  delete safe.reward;
202
206
  if (value.event === "shown" && action !== "capabilities") {
207
+ phase = "presenting";
203
208
  resolveReady(safe);
204
209
  this.host.clearTimeout(timer);
205
210
  }
206
211
  else
207
212
  finish(safe);
208
213
  };
209
- const timer = this.host.setTimeout(() => {
214
+ const timeout = () => {
210
215
  try {
211
216
  send("destroy");
212
217
  }
218
+ catch { /* a detached host must still settle the request */ }
213
219
  finally {
214
220
  finish(this.result("unavailable", "HOST_TIMEOUT"));
215
221
  }
216
- }, action === "capabilities" ? 6000 : 30000);
222
+ };
223
+ let timer = this.host.setTimeout(timeout, action === "capabilities" ? 6000 : 30000);
217
224
  bridge.addEventListener("message", listener);
218
225
  this.releases.add(destroy);
219
226
  this.host.addEventListener?.("pagehide", destroy);
package/dist/client.d.ts CHANGED
@@ -1,8 +1,3 @@
1
- /**
2
- * @wovoon/polaris 运行时客户端(协议 1)。
3
- * 在作品内通过 <script> 引入平台下发的 /api/cloud/sdk.js(全局 WovoonCloud)即可使用,
4
- * 本模块提供同一 API 的 TypeScript 实现,供构建型项目以模块方式引入。
5
- */
6
1
  import { PolarisAds } from "./ads.js";
7
2
  import { PolarisCommerce } from "./commerce.js";
8
3
  import { PolarisGame, type GameOptions } from "./game.js";
package/dist/client.js CHANGED
@@ -1,9 +1,9 @@
1
+ import { PolarisAds } from "./ads.js";
1
2
  /**
2
3
  * @wovoon/polaris 运行时客户端(协议 1)。
3
4
  * 在作品内通过 <script> 引入平台下发的 /api/cloud/sdk.js(全局 WovoonCloud)即可使用,
4
5
  * 本模块提供同一 API 的 TypeScript 实现,供构建型项目以模块方式引入。
5
6
  */
6
- import { PolarisAds } from "./ads.js";
7
7
  import { matchRoom } from "./match.js";
8
8
  import { PolarisCommerce } from "./commerce.js";
9
9
  import { PolarisGame } from "./game.js";
@@ -11,6 +11,8 @@ export interface PurchaseOrder {
11
11
  checkoutType?: string | null;
12
12
  checkoutPayload?: string | null;
13
13
  checkoutQrCode?: string | null;
14
+ /** Only the localhost simulator sets this; it never denotes real money. */
15
+ localFixture?: boolean;
14
16
  }
15
17
  export interface PurchaseProduct {
16
18
  productCode: string;
package/dist/commerce.js CHANGED
@@ -70,9 +70,11 @@ export class PolarisCommerce {
70
70
  overlay.style.cssText = "position:fixed;inset:0;z-index:2147483647;background:#000b;display:grid;place-items:center;padding:16px";
71
71
  panel.style.cssText = "background:#fff;color:#15171b;padding:24px;border-radius:16px;max-width:380px;width:100%;font:16px system-ui;text-align:center";
72
72
  const title = doc.createElement("h2");
73
- title.textContent = `支付 ¥${(order.amountCents / 100).toFixed(2)}`;
73
+ title.textContent = order.localFixture ? "本地测试订单" : `支付 ¥${(order.amountCents / 100).toFixed(2)}`;
74
74
  const status = doc.createElement("p");
75
75
  status.textContent = "支付完成后,平台确认到账才会发放游戏权益。";
76
+ if (order.localFixture)
77
+ status.textContent = "此订单不收款。按测试场景模拟结果,点击查询验证权益回执。";
76
78
  panel.append(title, status);
77
79
  if (order.checkoutType === "QR_CODE_DATA_URL" && /^data:image\/png;base64,[A-Za-z0-9+/=]+$/.test(order.checkoutPayload || "")) {
78
80
  const image = doc.createElement("img");
@@ -143,7 +145,7 @@ export class PolarisCommerce {
143
145
  if (ended)
144
146
  return;
145
147
  if (current.status === "FULFILLED") {
146
- status.textContent = "支付成功,游戏权益已到账。";
148
+ status.textContent = current.localFixture ? "测试权益已到账(未发生付款)。" : "支付成功,游戏权益已到账。";
147
149
  close.textContent = "返回游戏";
148
150
  }
149
151
  else if (terminal.has(current.status)) {
package/dist/game.d.ts CHANGED
@@ -24,6 +24,8 @@ export interface GameSnapshot<State> {
24
24
  export interface GameOptions<State> {
25
25
  roomId: string;
26
26
  onState?: (state: State, snapshot: GameSnapshot<State>) => void;
27
+ /** Transient server events (chat, effects, RPC replies); durable state belongs in onState. */
28
+ onEvent?: (event: unknown) => void;
27
29
  onStatus?: (status: "connecting" | "connected" | "reconnecting" | "closed" | "error") => void;
28
30
  /** A new instance is a new server simulation, not a promise of crash recovery. */
29
31
  onReset?: (previousInstanceId: string, nextInstanceId: string) => void;
@@ -59,12 +61,16 @@ export declare class PolarisGame<State = unknown> {
59
61
  private settled;
60
62
  private resolveReady;
61
63
  private rejectReady;
64
+ private readonly events;
65
+ private readonly statuses;
62
66
  readonly clientId: string;
63
67
  constructor(openRoom: (id: string, options: {
64
68
  mode: string;
65
69
  }) => GameRoom, mode: string, options: GameOptions<State>);
66
70
  private emit;
67
71
  private status;
72
+ onEvent(listener: (event: unknown) => void): () => void;
73
+ onStatus(listener: NonNullable<GameOptions<State>["onStatus"]>): () => void;
68
74
  private connect;
69
75
  /** False means not submitted. Inputs are never silently queued/replayed across a disconnect. */
70
76
  input(input: unknown): boolean;
package/dist/game.js CHANGED
@@ -16,6 +16,8 @@ export class PolarisGame {
16
16
  this.attempts = 0;
17
17
  this.lastReceived = 0;
18
18
  this.settled = false;
19
+ this.events = new Set();
20
+ this.statuses = new Set();
19
21
  this.clientId = "game_" + Date.now().toString(36) + "_" + Math.random().toString(36).slice(2);
20
22
  if (!/^[a-z][a-z0-9_]{1,31}$/.test(mode) || !/^[a-zA-Z0-9_-]{1,64}$/.test(options.roomId))
21
23
  throw new Error("game(mode, {roomId}) requires a valid mode and room id");
@@ -32,7 +34,11 @@ export class PolarisGame {
32
34
  catch { /* callbacks do not break transport cleanup */ } }
33
35
  status(status) {
34
36
  this.emit(() => this.options.onStatus?.(status));
37
+ for (const listener of this.statuses)
38
+ this.emit(() => listener(status));
35
39
  }
40
+ onEvent(listener) { this.events.add(listener); return () => this.events.delete(listener); }
41
+ onStatus(listener) { this.statuses.add(listener); return () => this.statuses.delete(listener); }
36
42
  connect() {
37
43
  if (this.closed)
38
44
  return;
@@ -93,6 +99,14 @@ export class PolarisGame {
93
99
  const data = frame.data;
94
100
  if (data.protocol !== "wovoon.game/1")
95
101
  return;
102
+ if (data.kind === "event") {
103
+ this.lastReceived = Date.now();
104
+ const event = data.data;
105
+ this.emit(() => this.options.onEvent?.(event));
106
+ for (const listener of this.events)
107
+ this.emit(() => listener(event));
108
+ return;
109
+ }
96
110
  if (data.kind === "pong" && typeof data.clientTime === "number") {
97
111
  this.lastReceived = Date.now();
98
112
  this.emit(() => this.options.onLatency?.(Math.max(0, Date.now() - data.clientTime)));
@@ -166,6 +180,8 @@ export class PolarisGame {
166
180
  catch { /* cleanup must still settle ready */ }
167
181
  this.timeline?.reset();
168
182
  this.status(status);
183
+ this.events.clear();
184
+ this.statuses.clear();
169
185
  if (message)
170
186
  this.emit(() => this.options.onError?.(message));
171
187
  if (!this.settled) {
package/dist/index.d.ts CHANGED
@@ -4,10 +4,8 @@ export { PolarisClient, PolarisError, parseData } from "./client.js";
4
4
  export { GameTimeline, GamePrediction } from "./game-sync.js";
5
5
  export { PolarisGame } from "./game.js";
6
6
  export type { GameOptions, GameSnapshot, GameRoom } from "./game.js";
7
- export { PolarisAds } from "./ads.js";
8
7
  export { PolarisCommerce } from "./commerce.js";
8
+ export * from "./ads.js";
9
9
  export type { PurchaseOrder, PurchaseProduct, PurchaseEntitlement } from "./commerce.js";
10
- export type { PolarisAdFormat, PolarisAdStatus, PolarisAdResult, PolarisAdCapabilities, PolarisAdOptions, PolarisBanner } from "./ads.js";
11
- export type { PolarisRewardReceipt, PolarisRewardBalance, PolarisRewardSpend } from "./ads.js";
12
10
  export type { WovoonCapability, WovoonCollectionName, WovoonManifest, WovoonSession, WovoonDocument, WovoonQueryOptions, WovoonFunctionEvent, WovoonFunctionResult, WovoonRoomFrame, } from "./protocol.js";
13
11
  export type { PolarisRequestInit, PolarisSessionView, PolarisDocumentView, PolarisQueryOptions } from "./client.js";
package/dist/index.js CHANGED
@@ -3,5 +3,5 @@ export { WOVOON_PROTOCOL_VERSION, COLLECTION_NAME_PATTERN, isValidCollectionName
3
3
  export { PolarisClient, PolarisError, parseData } from "./client.js";
4
4
  export { GameTimeline, GamePrediction } from "./game-sync.js";
5
5
  export { PolarisGame } from "./game.js";
6
- export { PolarisAds } from "./ads.js";
7
6
  export { PolarisCommerce } from "./commerce.js";
7
+ export * from "./ads.js";
package/dist/match.js CHANGED
@@ -31,8 +31,27 @@ export async function matchRoom(mode, connect, query, signal) {
31
31
  else
32
32
  reject(error || Error("MATCH_CANCELLED"));
33
33
  };
34
- const abort = () => finish(undefined, Error("MATCH_CANCELLED"));
35
- const timeout = setTimeout(() => finish(undefined, Error("WOVOON_MATCH_TIMEOUT")), 120000);
34
+ const cancel = (error) => {
35
+ if (ended)
36
+ return;
37
+ // Settle cancellation before callers can begin another match for this player.
38
+ ended = true;
39
+ clearTimeout(timeout);
40
+ if (timer)
41
+ clearTimeout(timer);
42
+ signal?.removeEventListener("abort", abort);
43
+ try {
44
+ queue.leave();
45
+ }
46
+ catch { }
47
+ const deadline = setTimeout(() => reject(Object.assign(new Error("MATCH_CANCEL_UNCONFIRMED"), { cause: error })), 8000);
48
+ query("cancel").then(() => { clearTimeout(deadline); reject(error); }, cause => {
49
+ clearTimeout(deadline);
50
+ reject(Object.assign(new Error("MATCH_CANCEL_UNCONFIRMED"), { cause }));
51
+ });
52
+ };
53
+ const abort = () => cancel(Error("MATCH_CANCELLED"));
54
+ const timeout = setTimeout(() => cancel(Error("WOVOON_MATCH_TIMEOUT")), 120000);
36
55
  signal?.addEventListener("abort", abort, { once: true });
37
56
  if (signal?.aborted) {
38
57
  abort();
@@ -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
+ /** 包内 HTML 入口相对路径,例如 game/index.html;不可包含 .. 或以 / 开头。 */
21
+ entry?: string;
20
22
  /** Web 前端仍由平台托管;external 表示使用创作者自行部署的后端,可同时声明实际使用的平台能力。 */
21
23
  backend?: "platform" | "external";
22
24
  /** 声明使用的能力;未声明的能力在对应服务上线后不可调用。 */
package/dist/protocol.js CHANGED
@@ -9,7 +9,7 @@ export function isValidCollectionName(name) {
9
9
  return COLLECTION_NAME_PATTERN.test(name);
10
10
  }
11
11
  /** manifest 里单个能力名的完整合法形态(与平台 AssetSecurityScanner.parseContract 的校验一致)。 */
12
- export const CAPABILITY_PATTERN = /^(identity|function|room|room:competitive|gamelogic|ads|commerce|collection:[a-z][a-z0-9_]{1,31})$/;
12
+ export const CAPABILITY_PATTERN = /^(identity|function|room|room:competitive|gamelogic|commerce|ads|collection:[a-z][a-z0-9_]{1,31})$/;
13
13
  export function isValidCapability(value) {
14
14
  return CAPABILITY_PATTERN.test(value);
15
15
  }
package/docs/ads.md CHANGED
@@ -1,78 +1,23 @@
1
- # 作品广告容器(SDK 0.9.0,协议 1 追加)
1
+ # GroMore 广告接入
2
2
 
3
- 作品声明 `{"protocol":1,"capabilities":["ads"]}`,通过 `WovoonPolaris.ads`
4
- (与 `WovoonCloud.ads` 相同)或 `new PolarisClient().ads` 调用。
5
- 单独使用广告不要求声明 `identity` 或调用 `ready()`。
3
+ App 统一使用 GroMore 多广告源聚合竞价。开屏、推荐页视频流、发现页广告卡和更多页广告卡由平台配置,创作者只接作品内激励广告。
6
4
 
7
- 同一份作品代码可运行在网页和 Android。网页目前没有已授权广告源:
8
- SDK 立即返回 `unavailable / NO_AUTHORIZED_SOURCE`,不发广告请求、不创建空白占位、
9
- 不阻塞开始或过关。旧版 App、iOS 和没有原生广告桥的宿主也直接跳过。
10
- 后续网页联盟接入须增加经过授权的网页渲染通道,不能直接在网页运行原生联盟 SDK。
11
-
12
- ## 全屏广告
5
+ 在 `.wovoon` 声明 `{"protocol":1,"capabilities":["ads"]}`,使用 `wovoon ads init/status/plan/apply` 配置奖励规则。广告位与密钥由平台管理,不放入作品。配置方式见 [激励广告](rewarded-ads.md) 和 [接入示例](recipes/rewarded-placement.md)。
13
6
 
14
7
  ```js
15
- const result = await WovoonPolaris.ads.show({
16
- format: "interstitial",
17
- placement: "level_end",
18
- onPause: () => { game.pause(); game.mute(); },
19
- onResume: () => { game.resume(); game.restoreSound(); }
20
- });
21
- // 无广告、频控、失败都要继续游戏。只有实际进入展示才调用 onPause。
22
- goToNextLevel();
23
- ```
24
-
25
- `show` 在广告关闭或跳过后完成。只有关卡结算、菜单等自然停顿时请求插屏,
26
- 不要在操作中途弹出。作品应在回调中暂停/恢复自己的游戏循环和音频;
27
- SDK 不修改游戏引擎、不暂停云连接、不重新加载游戏。
28
-
29
- ## 横幅容器
30
-
31
- ```html
32
- <div id="game-ad"></div>
33
- <script>
34
- async function mountMenuAd() {
35
- const ads = WovoonPolaris.ads;
36
- const caps = await ads.capabilities();
37
- if (!caps.banner) return; // 网页不留空白区域
38
- const container = document.querySelector("#game-ad");
39
- container.style.cssText = "width:320px;min-height:250px;margin:auto";
40
- const banner = ads.mountBanner(container, { placement: "menu_footer" });
41
- const result = await banner.ready;
42
- if (result.status !== "shown") container.style.cssText = "";
43
- banner.closed.then(() => { container.style.cssText = ""; });
44
- // 离开当前界面前:banner.destroy()
8
+ const ads = WovoonPolaris.ads;
9
+ if ((await ads.capabilities()).rewarded) {
10
+ const result = await ads.show({format: 'rewarded', placement: 'revive',
11
+ onPause: () => game.pause(), onResume: () => game.resume()});
12
+ if (result.rewarded) renderRewardBalances(await ads.rewardBalances());
13
+ else if (result.reason === 'REWARD_PENDING') showPending(result.requestId);
45
14
  }
46
- </script>
47
15
  ```
48
16
 
49
- 容器须在主文档内、完全可见、宽至少 320 CSS 像素、高至少 50。
50
- 聚合源可能返回较高的信息流模板,建议预留 250 像素高度;若真实模板大于容器,
51
- 原生宿主会跳过,绝不裁掉广告标识或关闭入口。避免变换、覆盖、透明祖先、
52
- 滚动容器裁切和游戏操作区域重叠。移出屏幕、页面隐藏或销毁会关闭广告;
53
- 重新展示由作品显式请求,SDK 不自动刷新刷曝光。Android 横幅是宿主原生视图,
54
- 不支持把广告当成 Canvas/WebGL 纹理或嵌套 iframe 内容。
55
-
56
- ## 能力与结果
57
-
58
- - `capabilities()` → `{surface, banner, interstitial, rewarded, reason?}`。可用不代表必有填充。
59
- - `show({format:"interstitial"|"rewarded", placement, onPause?, onResume?})` → `Promise<AdResult>`。
60
- - `mountBanner(element,{placement})` → `{ready, closed, destroy()}`。
61
- - `dispose()` 取消该 SDK 客户端的所有请求;`configure()` 自动清理旧请求。
62
- - `AdResult.status`:`shown / closed / unavailable / no_fill / busy / frequency_capped / cancelled / error`。
63
- - `placement` 是作品内稳定的场景名(字母开头,字母/数字/下划线/点/横线,最多 64 字符),不是联盟广告位 ID。
64
- - `rewarded:true` 只表示服务器已确认到账;缺少 SSV/作品奖励规则时不可用。
65
- 配置、延迟回调恢复和幂等扣减见 [激励广告与作品奖励](rewarded-ads.md)。禁止用关闭、计时器或 `VIDEO_COMPLETE` 发奖。
66
- - 开屏由 App 启动流程统一管理,不提供给作品反复调用。
17
+ 玩家主动点击后才请求广告。取消、无填充或加载失败时继续游戏。只按服务端 `granted` 回执确认奖励,不能用广告关闭事件、本地计时或原生标记直接发奖。`banner`、`interstitial` 能力固定 false,SDK 不提供作品横幅接口。
67
18
 
68
- ## 平台与安全
19
+ 正式网页与原生 iOS 暂无授权广告宿主。顷悟网页及手机预览提供明确标注的**模拟激励广告**,可选择完整播放、提前关闭、无填充和加载失败;测试余额在工作区按玩家隔离并持久化,不请求真实广告、不产生广告收入。模拟结果带 `simulated:true`。
69
20
 
70
- Android 主文档通过精确运行域白名单的 WebMessage 桥请求宿主。宿主使用自己保存的
71
- 作品 ID、有效游玩租约向 `/api/public/ads/runtime/authorize` 请求准入;
72
- 平台核对作品公开状态、租约归属和清单 `ads` 能力。作品不能选其他作品、会话、
73
- 广告源 URL、联盟 ID、eCPM 或奖励数值。
21
+ 后台实时收益是展示回调报价估算,报价未知单独计数,不记成零收入。现金结算使用完整官方日报,人民币按分记账:平台广告收入的 30% 归平台,70% 按北京时间当日有效游玩时长分给创作者;没有有效时长则保留待分配。激励收入的 30% 归平台,70% 归对应作品作者,按官方广告源代码位的平均展示收入匹配验签回调归属;无法归属的展示份额待核对,不摊给其他作品。
74
22
 
75
- 平台沿用后台 Android 广告频率配置:选择对应格式的 GroMore 聚合位,统一频控,
76
- 真实填充与比价由已接入的聚合 SDK 完成。平台现有网页模拟竞价/自推广素材不会
77
- 作为此接口的填充。SDK 回调仅为展示结果,不是结算收入或服务端奖励凭证。
78
- 当前横幅和插屏与 App 对应格式共用频率额度;任一全屏广告展示时不再启动第二个。
23
+ 玩家虚拟奖励与创作者现金是独立账本。日结防重复入账,沿用平台提现冻结期。
package/docs/cli.md CHANGED
@@ -1,12 +1,14 @@
1
- # wovoon CLI 参考(CLI 0.12.4)
1
+ # wovoon CLI 参考(CLI 0.22.0)
2
2
 
3
3
  ```
4
- wovoon init [目录] [--template minimal|game|arena] [--name 名称]
5
- wovoon dev [目录] [--port 5179] [--player 玩家名]
4
+ wovoon init [目录] [--template minimal|game|arena|mode|rewarded] [--name 名称]
5
+ wovoon preview [目录] [--target web|mobile] [--player 玩家名]
6
6
  wovoon validate [目录] [--json]
7
7
  ```
8
8
 
9
- SDK 依赖固定为 @wovoon/polaris 0.6.0(Node ≥ 22.13)。退出码:`0` 成功 / `1` 校验失败 / `2` 用法错误。
9
+ SDK 依赖固定为 @wovoon/polaris 0.15.0(Node ≥ 22.13)。退出码:`0` 成功 / `1` 校验失败 / `2` 用法错误。
10
+
11
+ 作品激励广告使用 `wovoon ads init/status/plan/apply` 管理 `wovoon.ads.json`,只有作品所有者可同步正式奖励规则。该文件不会随作品公开发布。`rewarded` 模板和顷悟模拟预览无需广告联盟密钥,见 [激励接入](ads.md)。
10
12
 
11
13
  ## wovoon init
12
14
 
@@ -16,9 +18,13 @@ SDK 依赖固定为 @wovoon/polaris 0.6.0(Node ≥ 22.13)。退出码:`0`
16
18
 
17
19
  `--name` 会替换模板页面的 `<title>`。生成后 `cd` 进目录即可开发。
18
20
 
19
- ## wovoon dev
21
+ ## wovoon preview
22
+
23
+ 日常开发使用远程预览,顷悟内置相同客户端,无需本机 WSL/Docker。详见 [远程预览](remote-preview.md)。未启用服务时明确报错。
24
+
25
+ ## wovoon dev(可选底层诊断)
20
26
 
21
- 本地模拟大后台(localhost 全能力,无需登录):
27
+ 本地模拟身份、数据、房间和测试场景,无需平台账号;真实支付通道仍需对应环境验收:
22
28
 
23
29
  wovoon dev # 游客模式
24
30
  wovoon dev --player 阿明 # 模拟登录玩家(可写云数据)
@@ -26,19 +32,26 @@ SDK 依赖固定为 @wovoon/polaris 0.6.0(Node ≥ 22.13)。退出码:`0`
26
32
  - 静态托管:`/api/public/static/dec0de11-0000-4000-8000-000000000001/`(生产同路径,SDK 自动识别作品;根路径 `/` 会 302 过去)。
27
33
  - 平台 SDK:`GET /api/cloud/sdk.js`(与生产同源同路径)。
28
34
  - 云能力:`POST /api/cloud/session`、`GET|POST|PUT|DELETE /api/cloud/{app}/collections/{name}/docs[/{id}]`。
29
- - 校验/配额/报错与生产一字不差(能力门禁、集合与文档配额、权限、limit 钳制)。
35
+ - 校验/配额/报错镜像实现覆盖核心契约,生产策略仍需上线环境验收(能力门禁、集合与文档配额、权限、limit 钳制)。
30
36
  - `.wovoon`/`.wovoongame`/`.DS_Store`/`__MACOSX/` 不对外发布(与生产一致)。
31
- - 云函数:`functions/*.js` 在独立系统沙箱执行,数据访问经过受信任代理,作品进程没有平台凭据或网络权限。macOS 使用 sandbox-exec 和 Node 权限模型;Linux 需要 Docker 和预先拉取的 `node:20-alpine` 镜像。Windows 的云函数/权威房间执行暂不支持,静态服务和校验可用。
37
+ - 云函数:`functions/*.js` 在独立系统沙箱执行,数据访问经过受信任代理,作品进程没有平台凭据或网络权限。macOS 使用 sandbox-exec 和 Node 权限模型;Linux 需要 Docker;Windows 需要启用 WSL2 的 Docker Desktop(Linux 容器模式)。Docker 环境需先执行 `docker pull node:24-alpine`,再启动本地模拟器。
32
38
  - 管理接口需要 CLI 启动时显示的 Bearer 管理令牌;内部函数数据接口使用单独的随机令牌。服务只接受当前本地端口的 Host/Origin,静态文件和函数源文件不得通过符号链接越过项目目录。
33
- - 云函数同时最多 16 个,默认 3 秒、声明上限 60 秒;权威房间最多 64 个,具有空房回收及进程退出清理。Linux 单进程容器限制为 128 MB、0.5 CPU、16 PID、只读文件系统和无网络。macOS 开发环境使用 64 MB V8 堆上限,不能等同于容器总内存限额。
39
+ - 云函数同时最多 16 个,默认 3 秒、声明上限 60 秒;权威房间最多 64 个,具有空房回收及进程退出清理。Docker 单进程容器限制为 128 MiB、16 PID、只读文件系统和无网络;云函数 0.5 CPU,权威房间 1 CPU。macOS 开发环境使用 64 MiB V8 堆上限,不能等同于容器总内存限额。
34
40
  - 房间:`WS /api/cloud/rooms/{app}/{roomId}` 本机中继(协议同生产)。
35
- - 内存态存储:重启即清空;权限默认 WORLD 读 / OWNER 写。
41
+ - 数据默认持久化到作品目录外的 `~/.wovoon/dev-data`,重启保留;`--ephemeral` 才使用临时内存。权限默认 WORLD 读 / OWNER 写。`wovoon data` 可快照、恢复和重置,包含匹配席位、测试订单和权益。
42
+
43
+ ## 商品、扩展与本地数据
44
+
45
+ - `wovoon products init|validate|status|apply [目录] [--activate]`:商品配置和状态,显式激活收费。
46
+ - `wovoon extensions init|search|publish|submit|install|status|remove|revoke [目录]`:查找、私有发布、申请公开、按版本安装及撤销玩法扩展。
47
+ - `wovoon data list|create|restore|reset|delete [目录] [--id 快照ID] [--confirm]`:停止模拟器后管理完整快照;恢复、重置前自动备份。
48
+ - `wovoon dev --scenario-fixture <作品目录外的JSON路径>`:配置商品目录、延迟测试订单。格式与恢复语义见 [本地场景](local-scenarios.md)。`--commerce-fixture` 提供测试余额。
36
49
 
37
50
  ## wovoon validate
38
51
 
39
52
  生产规则镜像校验,顺序与平台一致:
40
53
 
41
- 1. 归档扫描:符号链接、文件数(≤20,000)、展开大小(≤1 GB)、凭据文件(`.env`/`id_rsa`/`.p12`…)、文本密钥泄露(私钥/AK/LTAK/token/连接串)、云元数据地址;
54
+ 1. 归档扫描:符号链接、文件数(≤100,000)、展开大小(≤4 GiB,与后台默认配置一致)、凭据文件(`.env`/`id_rsa`/`.p12`…)、文本密钥泄露(私钥/AK/LTAK/token/连接串)、云元数据地址;服务器管理员的自定义配额仍以部署环境为准。
42
55
  2. `.wovoon` 标识存在性;
43
56
  3. manifest 解析(4 KB / JSON 对象 / 未知字段 / protocol / 能力名);
44
57
  4. 静态托管结构(非空、`index.html` 存在且唯一根目录);
package/docs/errors.md CHANGED
@@ -90,7 +90,7 @@ API 错误响应形态:`{"success":false,"message":"…","code":"…"}`,SDK
90
90
 
91
91
  ### <a id="hosting-too-large"></a>包体超限
92
92
 
93
- > 静态包文件数超出限制 / 静态包展开后大小超出限制(默认 20,000 文件 / 1 GB)
93
+ > 静态包文件数超出限制 / 静态包展开后大小超出限制(默认 100,000 文件 / 4 GiB)
94
94
 
95
95
  ## 云能力(运行时)
96
96
 
@@ -0,0 +1,22 @@
1
+ # 本地联机场景
2
+
3
+ `wovoon dev . --player Alice --scenario-fixture ../scenario.json`
4
+
5
+ 测试文件必须在作品目录外,最多 64 KiB,并使用默认持久化模式。测试场景不调用支付渠道。作品仍须声明 `commerce` 等对应能力。
6
+
7
+ ```json
8
+ {
9
+ "version": 1,
10
+ "products": [{"productCode":"potion","name":"药水","productType":"CONSUMABLE","priceCents":100,"currency":"CNY","status":"ACTIVE"}],
11
+ "orderOutcome":"FULFILLED",
12
+ "orderDelayMs":3000
13
+ }
14
+ ```
15
+
16
+ - `commerce.catalog()` 返回测试商品;`checkout()` 返回带 `localFixture:true`、`checkoutType:LOCAL_TEST` 的测试订单,不含付款 URL。相同玩家和幂等键恢复原单,同键改商品或渠道拒绝。
17
+ - `order()` 在延迟到期后返回指定结果(FULFILLED / FAILED / EXPIRED)。只有 FULFILLED 增加测试权益;重复查询、重启不会重复发放。此模拟不代表支付通道验收通过。
18
+ - 不同测试玩家不能查询彼此的订单、回执。`player` 是 `--player` 或 `wovoon_player` 对应的名字。
19
+ - 匹配 `status/cancel` 无需夹具。两位玩家进入同一匹配模式后,分配席位保留 60 秒,断线或模拟器重启可读回;进入权威房后状态为 JOINED。取消同时退出等待连接。
20
+ - `wovoon data` 快照统一保存文档、房间 checkpoint、席位、回执、订单及权益。恢复旧快照会恢复其全部状态;这些数据不会放入发布包。
21
+
22
+ Windows 沙箱需要官方 WSL2 / Docker Desktop,开启 Linux 容器并预拉取 `node:24-alpine`。模拟器保持无网络、只读挂载、128 MiB 内存和进程数限制;缺少隔离运行器会报错,不会退回无隔离执行。
package/docs/manifest.md CHANGED
@@ -1,7 +1,5 @@
1
1
  # `.wovoon` 清单规范(协议 1)
2
2
 
3
- 可选能力 `ads` 用于 [作品广告容器](ads.md),无需同时声明 `identity`。
4
- 无已授权广告源时作品必须继续游戏;声明本能力不保证广告填充。
5
3
 
6
4
  `.wovoon` 是 wovoon 作品包的平台契约标识文件,放在**包根目录**。它同时承担两个职责:
7
5
 
@@ -38,7 +36,7 @@ JSON 对象,UTF-8,最大 **4 KB**。**空文件合法**,等价于 `{"proto
38
36
  | `room` | 房间实时通道:WebSocket 房间中继(快节奏多人) | 可用 |
39
37
  | `room:competitive` | 竞技速率档,和 room 配合使用 | 可用 |
40
38
  | `gamelogic` | 常驻权威玩法,和 room 配合使用 | 可用 |
41
- | `ads` | 平台广告展示与经验证的奖励 | 已授权源可用 |
39
+ | `ads` | 作品激励广告与服务端奖励回执;顷悟使用隔离的模拟余额 | SDK 0.15 / CLI 0.22 与对应运行时 |
42
40
  | `commerce` | 平台购买、权益查询与权威消费 | 需 SDK 0.10 和对应平台运行时 |
43
41
 
44
42
  - 集合名称:**2-32 位,小写字母开头,仅小写字母/数字/下划线**,如 `collection:scores`、`collection:player_profiles`。
@@ -36,7 +36,7 @@ npx -y @wovoon/cli validate # 生产规则预检,PASS =
36
36
  "capabilities":["identity","function","room","collection:saves","collection:rankings"]}
37
37
  ```
38
38
 
39
- - 能力名固定:`identity` / `function` / `room` / `collection:<小写集合名>`(`^[a-z][a-z0-9_]{1,31}$`);
39
+ - 能力名包括:`identity` / `function` / `room` / `room:competitive` / `gamelogic` / `commerce` / `ads` / `collection:<小写集合名>`(`^[a-z][a-z0-9_]{1,31}$`);作品仅支持激励广告,见 [接入说明](ads.md);
40
40
  - 空文件 = protocol 1 全默认;未知字段/非法能力名会校验失败;
41
41
  - join 查询的被连接集合也必须声明(防能力旁路)。
42
42
 
@@ -1,55 +1,27 @@
1
- # 改造配方:多人竞技游戏(权威房间 + 竞技速率档)
1
+ # 多人竞技:统一权威玩法
2
2
 
3
- > 适用:需要联机对战、实时竞技、防作弊的游戏。协议 1 能力(`.wovoon` 声明,纯加法):
4
- > `room:competitive`(上行 30Hz、单帧 8KB、二进制帧)+ `gamelogic`(权威房间逻辑)。
3
+ 使用 `wovoon init duel --template arena` 创建包含权威决斗的完整模板,或 `--template mode` 创建最小玩法。客户端统一使用 `cloud.game(mode, {roomId})`,平台负责连接、重连、输入序号、快照、插值和延迟检测。
5
4
 
6
- ## 三层竞技模型
7
-
8
- 1. **中继房**(`room`):客户端互发,配合"受害者权威判定 + settle 云函数结算"——十人内、百毫秒级对战。
9
- 2. **竞技速率档**(`room:competitive`):声明后房间放宽上行限流并支持二进制帧——
10
- `send(Uint8Array)` 发二进制,`onMessage` 收到 `{binary:true, data:Uint8Array}`;用 MessagePack/自定义打包做 10~20Hz 状态同步。
11
- 3. **权威房间**(`gamelogic`):包根放 `roomservers/<mode>.js`,`cloud.room(roomId, {mode})` 加入。
12
- 逻辑跑在平台沙箱(服务端权威):命中/血量/得分外挂改客户端无效;最长 2 小时、空房 60 秒回收、每作品 50 房。
13
- 逻辑文件限制:每作品 ≤8 个 mode、**单文件 ≤2 MB、全部合计 ≤4 MB**(`wovoon validate` 本地即检,超限精简/压缩代码或把配置数据外置到集合)。
5
+ ```json
6
+ {"protocol":1,"capabilities":["identity","room","room:competitive","gamelogic","collection:rankings"]}
7
+ ```
14
8
 
15
- ## roomservers/duel.js 最小示例
9
+ 在 `roomservers/<mode>.js` 声明 `exports.gameProtocol=1`,实现同步的 `createState / onPlayerJoin / onInput / update / view`。玩家仅提交移动方向、攻击按钮等意图,服务端计算位置、命中、血量与胜负。身份取回调的 `playerId`,不能相信输入中的身份、分数或已付款标记。完整契约见 [平台玩法](platform-game-mode.md)。
16
10
 
17
11
  ```js
18
- exports.tickMs = 50; // 20~100ms(默认 50)
19
- exports.setup = () => ({ hp: {}, winner: null });
20
- exports.onJoin = (state, playerId) => { state.hp[playerId] = 100; ctx.broadcast({ hp: state.hp }); };
21
- exports.onMessage = (state, playerId, data) => {
22
- // 玩家输入只是"请求":命中在服务端判定
23
- if (data.hit) { const target = data.hit; if (state.hp[target] > 0) {
24
- state.hp[target] -= 10; ctx.broadcast({ hp: state.hp });
25
- if (state.hp[target] <= 0) { ctx.writeDoc("rankings", "add", undefined, { winner: playerId }); ctx.close(); }
26
- } }
27
- };
28
- exports.tick = (state, dt) => { /* 超时/复活等周期逻辑 */ };
29
- // ctx:broadcast(data) / tell(playerId, data) / writeDoc(集合, op, id, doc)(仅 write:SERVER 集合)/ close()
12
+ const roomId = await cloud.match('arena_duel');
13
+ const game = cloud.game('arena_duel', {roomId, onState: render});
14
+ await game.ready;
15
+ if (!game.input({action:'move', dx:1, dy:0})) showReconnecting();
16
+ // 退出:game.leave();重要结算由服务端 ctx.settle 提交。
30
17
  ```
31
18
 
32
- 客户端:`const r = cloud.room('duel-9527', { mode: 'duel' }); r.onMessage(...) r.send({hit: opponentId})`。
33
- 服务端广播经 onMessage 到达(`from: 'server'`)。
34
-
35
- ## 集合实时刷新(onChange)
19
+ `match` 会查询持久化席位以恢复丢失的匹配通知;取消等待会关闭队列并等待取消结果。输入在断线期间不会自动重放。`onState` 返回完整权威状态;`onEvent` 接收 `ctx.tell/broadcast` 发出的瞬时事件,不能依赖瞬时事件保存进度。
36
20
 
37
- `cloud.collection('rankings').onChange(({action, id}) => 重新查询())` ——
38
- 任何写入(玩家/云函数/权威房间)都会推送变更通知(不含文档负载,收到后重查)。
39
- 需要声明 `room` 能力(通知走系统房间通道)。
40
-
41
- ## 能力声明清单
42
-
43
- ```json
44
- {"protocol":1,"capabilities":["identity","room","room:competitive","gamelogic","function","collection:rankings"]}
45
- ```
21
+ 旧 `setup/onJoin/onMessage/tick` 玩法生命周期、客户端互认命中和客户端上报成绩结算已从模板与执行器移除。基础 `room()` / `world()` 保留,用于聊天、世界公告和集合通知。
46
22
 
47
- 验证:`wovoon validate` + `wovoon dev`(模拟器同语义)本地跑通再 deploy。
23
+ `room:competitive` 保留底层 8 KiB 帧大小及二进制通道能力。新玩法输入共享每玩家令牌桶,建议最多 60 Hz,不能绕过帧大小和业务校验。玩法包每作品最多 8 个模式,单文件最多 2 MiB、合计最多 4 MiB。
48
24
 
49
- ## MMO-lite 支撑(第三阶段:世界总线 / 匹配 / 房间列表)
25
+ 世界模式仍可声明 `exports.world=true`;大厅使用 `cloud.rooms({mode})`,跨房消息使用 `cloud.world()`。排行榜通过 SERVER 权限和 `ctx.settle` 写入,再用 `collection().onChange()` 重新读取。
50
26
 
51
- - **常驻世界**:roomserver 声明 `exports.world = true` → 寿命 24h、空房保活 10 分钟(每作品 ≤20 个世界实例);状态定期 `ctx.writeDoc` 落集合即持久化。
52
- - **世界总线**:逻辑里 `ctx.worldBroadcast(data)` 全服广播;客户端 `cloud.world().onMessage(...)` 订阅(跨房间、跨场景的世界事件/公告/拍卖成交)。
53
- - **内置匹配**:`exports.matchSize = N`(2~32,默认 2);客户端 `const roomId = await cloud.match('duel')`(凑满成局,120s 超时)→ `cloud.room(roomId, {mode:'duel'})` 进入。
54
- - **房间列表(大厅/分线)**:`cloud.rooms({mode:'world'})` → `[{roomId, mode, players, world}]`,选线进房。
55
- - MMO-lite 组合形态:大厅房 + 分线世界房(world)+ 集合存档 + onChange 世界事件 + match 副本匹配。上限参考:单场景 256 人、单作品 200 权威房(world ≤20)、单实例部署;千人同服/无缝大世界需要 UDP+多区编排(未提供)。
27
+ 本地执行 `wovoon validate` 与 `wovoon dev`,至少验证双人、断线重连、伪造身份/分数、重复输入及结算。Windows 需 Docker Desktop 的 WSL2 Linux 容器;云函数与玩法均在隔离环境执行。
@@ -40,6 +40,8 @@ if (result.status === 'FULFILLED') {
40
40
 
41
41
  ## 权威玩法读取与消费
42
42
 
43
+ `ctx.settle(operationId, writes, purchaseCost)` 的第三个参数可选;购买消费传入 `{playerId,productCode,amount}`,普通成绩结算只传前两个参数。运行时拒绝多余参数,不能通过遗漏消费参数绕开扣减。
44
+
43
45
  `ctx.readEntitlements(requestId,playerId)` 异步排队,结果交给同步回调 `exports.onEntitlements(state,receipt)`。检查 `ctx.features.entitlementQuery===1`;回执的 COMPLETED / entitlements 来自平台校验过的当前房间登录租约。不要信任客户端传入的账号、购买数量或 premium 标记。进入房间和购买完成后重新查询,不把 checkpoint 内的权益缓存当永久授权。
44
46
 
45
47
  ```js
@@ -55,9 +57,9 @@ exports.onEntitlements = (state, receipt) => {
55
57
  if (ctx.features.purchaseSettlement !== 1) throw Error('运行时未升级');
56
58
  ctx.settle(`revive:${roundId}:${playerId}:${deathId}`, [
57
59
  {op:'add',collection:'inventory',doc:{playerId,kind:'revive',roundId,deathId}}
58
- ], undefined, {playerId,productCode:'potion',amount:1});
60
+ ], {playerId,productCode:'potion',amount:1});
59
61
  ```
60
62
 
61
63
  消费只支持 CONSUMABLE。费用与整批 SERVER 文档、COMPLETED 回执一起提交;重复业务号不重复扣减,同号不同内容拒绝,余额不足不在未来充值后自动执行。`onSettlement` 按原业务号处理:`result` 是 JSON 字符串,内含 `documents` 和 `purchase:{operationId,productCode,amount,balanceAfter}`。即时游戏效果也须针对事件去重,不能仅靠可能落后的房间快照。
62
64
 
63
- 本地测试:把 `[ {"playerId":"Alice","productCode":"potion","productType":"CONSUMABLE","quantity":3} ]` 保存到作品目录之外的测试文件,运行 `wovoon dev . --player Alice --commerce-fixture <文件>`。测试余额不是付款记录;本地 checkout/order 不调用真实支付渠道。`wovoon data` 快照会同时保存权益、消费和结算记录,避免只恢复道具而重复消费。
65
+ 本地测试:把 `[ {"player":"Alice","productCode":"potion","productType":"CONSUMABLE","quantity":3} ]` 保存到作品目录之外的测试文件,运行 `wovoon dev . --player Alice --commerce-fixture <文件>`。这里是测试玩家名 `player`,不是生产 `playerId`。测试余额不是付款记录;用 `--scenario-fixture` 可进一步测试商品目录、延迟订单和查询恢复,见 [本地场景](../local-scenarios.md)。`wovoon data` 快照同时保存订单、权益、消费和结算记录。
@@ -60,7 +60,11 @@ if (sequence !== null) prediction.predict(sequence, command);
60
60
 
61
61
  新玩法每约 5 秒生成恢复快照,最大 512 KiB;只有服务端目录和持久化启用才保存。恢复绑定模式源码及扩展哈希,代码变化后不加载旧状态。进程故障可能丢失最后一个保存周期,不能用于保证付款或奖励不丢失。恢复后的实例 ID 改变,客户端必须重新校正。
62
62
 
63
- 重连玩家保留约 30 秒;离线回调应停止移动。持久存档、购买和重要结算必须使用平台事务及幂等接口,不能只放在房间 checkpoint。旧 `setup/onMessage` 闭包状态没有自动恢复承诺。
63
+ 重连玩家保留约 30 秒;离线回调 `onPlayerDisconnect` 应停止移动,返回原席位时调用 `onPlayerReconnect`,过期后调用 `onPlayerLeave`。持久存档、购买和重要结算必须使用平台事务及幂等接口,不能只放在房间 checkpoint。
64
+
65
+ 非 JSON 引擎可实现同步 `checkpointState(state)` 和 `restoreState(saved, context)` 来保存并重建状态;不能把 Promise、句柄或类实例原样序列化。确实没有恢复实现时显式 `exports.checkpoint=false`,此时仅支持原进程内重连,进程退出后重新开局,不会写入或恢复残缺快照。
66
+
67
+ `ctx.tell(playerId, data)` / `ctx.broadcast(data)` 通过游戏协议的事件帧送达 `game.onEvent(callback)` 或配置中的 `onEvent`;`game.onStatus(callback)` 订阅连接状态。两个订阅方法均返回取消订阅函数。业务事件仅接受已认证服务端来源;持久状态仍放在 `view/onState`。旧玩法生命周期已退役。
64
68
 
65
69
  ## 持久化结算
66
70
 
@@ -83,24 +87,9 @@ exports.onSettlement = (state, receipt) => {
83
87
 
84
88
  本地 `wovoon dev` 使用 SQLite 原子事务并保留去重记录,通常直接收到 COMPLETED;关闭本地持久化时此接口返回 REJECTED。生产先收到 PENDING,再异步收到完成结果。它处理作品集合的成绩和存档,不代表付款确认、平台积分或充值发货;这些仍须使用各自的可信平台账本。
85
89
 
86
- ## 奖励消费与游戏结算
87
-
88
- 激励广告的观看、原生展示和 SSV 验证沿用平台广告服务,成功回调才增加作品奖励账本。作品声明 `ads`,由作者/AI 用 `wovoon ads init/status/plan/apply` 配置奖励;玩法只消费已经到账的余额。
89
-
90
- ```js
91
- // 在 onInput 中先检查玩家死亡状态、当前局次和复活资格。
92
- // id 来自平台回调;deathId 由权威状态生成,不能直接接受客户端自报。
93
- if (ctx.features?.rewardSettlement !== 1) throw Error('当前运行时不支持奖励事务');
94
- ctx.settle(`revive:${state.roundId}:${id}:${player.deathId}`, [
95
- {op:'add', collection:'entitlements', doc:{playerId:id, kind:'revive', round:state.roundId, death:player.deathId}}
96
- ], {playerId:id, rewardKey:'life', amount:1});
97
- ```
98
-
99
- `entitlements` 须声明为 SERVER 写入集合。平台从房间有效登录租约解析账号,并验证 ads 能力;不接受作品指定账号或游客消费。消费与整批 SERVER 写入及 COMPLETED 回执在同一数据库事务提交。任一写入失败,消费也回滚;重试不重复扣款。同编号改金额、玩家或文档会被拒绝。余额不足直接 FAILED,不会在未来看广告到账后偷偷执行旧请求;玩家再次确认业务后使用新的事件编号。
100
-
101
- 带奖励的 COMPLETED 回执,其 `result` 是 JSON 字符串,结构为 `{documents:[文档ID],reward:{clientId,rewardKey,amount,balanceAfter}}`;普通结算仍返回文档 ID 数组。`onSettlement` 按 operationId 幂等处理。房间 checkpoint 可能落后于账本,重启后按相同编号重提原内容并恢复结果,不能仅凭 checkpoint 未记录成功而生成新编号。持久化道具以 SERVER 文档为准;即时复活必须针对死亡事件去重。
90
+ ## 作品激励奖励
102
91
 
103
- 这不是平台积分、现金、充值或开发者广告收入结算。新运行时专用能力必须检查上述 feature 标记,旧服务不支持时停止消费流程,不能忽略费用参数继续发道具。单机作品已有 `ads.consumeReward` 接口保留;需要权威道具时优先使用事务接口。完整广告接入和本地余额夹具见 [激励配置配方](rewarded-placement.md)。
92
+ 作品使用 `ads.rewardBalances` 查询、`ads.consumeReward` 幂等消费已由服务端确认的奖励,见 [激励广告](../rewarded-ads.md)。当前版本不支持广告奖励与权威房间 SERVER 写入的组合事务,不能向 `ctx.settle` 传奖励费用或信任客户端自报的奖励。
104
93
 
105
94
  ## 通用扩展
106
95
 
@@ -84,20 +84,7 @@ button.onclick = async () => {
84
84
 
85
85
  Canvas、Unity、Godot 的按钮回调同样调用 `ads.show`,不要求使用 HTML 按钮。运行 `wovoon init my-ad-demo --template rewarded` 创建完整可运行的双入口示例;奖励消费与延迟回调的恢复规则见 [激励广告协议](../rewarded-ads.md)。原生 iOS 目前没有广告宿主,能力不可用时展示暂不支持提示。
86
86
 
87
- ## dev 验收
88
87
 
89
- 权威联机游戏把消费交给 `roomservers/<mode>.js`:收到玩家的购买/复活意图后校验玩法条件,再调用 `ctx.settle` 的 `rewardCost` 参数。不要将客户端 `rewarded:true`、余额截图、账号 ID 或自报消费金额当作权限。操作编号应绑定服务器生成的局次、玩家和本次业务事件,断线重试保持相同编号及内容。只有 COMPLETED 才生效;回执可能重复,玩法也须去重。见 [平台玩法配方](platform-game-mode.md#奖励消费与游戏结算)。
88
+ ## 顷悟验收
90
89
 
91
- 本地可以验证余额和事务,但不会模拟广告展示或伪造广告回调。把以下测试文件放在作品目录之外:
92
-
93
- ```json
94
- [{"player":"Alice","rewardKey":"life","balance":7}]
95
- ```
96
-
97
- ```sh
98
- wovoon dev ./my-game --player Alice --reward-fixture /absolute/outside-project/rewards.json
99
- ```
100
-
101
- 作品必须声明 ads,并启用默认持久化。种子只在该玩家/奖励首次出现时写入,重启不会补满;不能给 guest 注入余额。用两名玩家验证隔离、重复消费、余额不足、文档失败回滚及重启恢复。测试文件不会发布;真实 SSV 验收仍按下述流程执行。
102
-
103
- 先确认 CLI 目标与原生 App 都是 dev,作品声明 ads 且由你拥有。用 status 验证配置与奖励数量,再在普通网页验证移动端提示,在 Android dev App 验证两个自定义入口、取消/关闭、实际到账、重查不增发和消费重试不重扣。没有真实广告源时记录无填充;不能以假广告或模拟回调冒充通过。通过后再单独决定生产发布。
90
+ 在调试页同步项目后,用登录测试玩家点击作品激励入口;模拟面板支持完成、取消、无填充和失败。核对只有完成增加测试余额、重复查询不重发、重复消费不重扣、玩家隔离和重开恢复。模拟验收不代表真实 GroMore 广告源验收。
@@ -0,0 +1,45 @@
1
+ # 顷悟与北极星远程预览
2
+
3
+ 顷悟的“实时预览”和 `wovoon preview` 使用同一协议连接 Wovoon 远程测试服务。开发者电脑不需要 WSL、Docker 或 Mac。代码在本机编辑,网页在内置浏览器呈现;顷悟的安卓预览由本地 Android 运行环境承载,iOS 选项暂使用同一个安卓宿主演示。云函数和常驻权威房间在远程隔离执行器运行,不使用云端安卓设备。
4
+
5
+ ## 开始
6
+
7
+ 先登录 Wovoon 开发者账号。CLI 复用 `wovoon login` 保存的令牌,顷悟使用已有创作者登录会话;凭据只经过主进程与测试服务,不进入作品页面。平台通过 `/api/public/preview` 公布测试服务入口。未配置时明确提示服务未启用,不回退到本机沙箱。
8
+
9
+ ```sh
10
+ wovoon preview ./game --target web --player Alice
11
+ wovoon preview ./game --target mobile --player Alice
12
+ wovoon preview status ./game
13
+ wovoon preview stop ./game
14
+ ```
15
+
16
+ 命令显示一次性打开链接并持续同步文件;Ctrl+C 停止测试会话。顷悟在“调试”页选择网页在线版、安卓在线版或 iOS 在线版,点击实时预览即可连接服务,也可开启两个独立玩家窗口;不再需要先去“运行”页启动。CLI 的 mobile 链接本身不会启动安卓内核。窗口随代码同步重新加载。修改客户端资源或规则会重启测试运行器;测试集合、订单和奖励数据保留,房间状态仅在检查点兼容时恢复。
17
+
18
+ 每个账号、项目工作区有独立运行域名和数据库。玩家身份由短期启动凭据绑定,URL 中的 `wovoon_player` 和客户端自行添加的身份头不能改变测试玩家。关闭最后一个预览窗口会停止远程会话;异常退出后,服务默认在 10 分钟无心跳时回收执行器。启动链接 60 秒内一次有效,浏览器测试身份最多持续 1 小时,过期后重新打开预览。
19
+
20
+ 文件通过内容哈希增量上传;路径穿越、符号链接、大小写冲突与不合法作品会被拒绝。包上限为 10 万文件、4 GiB。账号令牌、私有配置和文档不作为静态作品上传。函数、玩法服务端代码、扩展缓存和奖励配置不对玩家静态公开。扩展按锁文件哈希验证后进入同一沙箱,发布时仍须通过平台扩展管理接口绑定。
21
+
22
+ ## 商品
23
+
24
+
25
+
26
+
27
+ 商品测试仍使用隔离测试订单,不发生真实付款。
28
+
29
+ ## 与上线效果的边界
30
+
31
+ 预览使用相同的浏览器 SDK、游戏模式运行器、云函数沙箱协议。测试数据 API 由 CLI 的测试运行时实现,并不等于生产 Spring 服务的全部权限、套餐、实名、审核、统计和运营配置。联机效果还受真实网络与设备性能影响。
32
+
33
+
34
+ ## 运营部署
35
+
36
+ `wovoon preview-service --root /var/lib/wovoon-preview --control-origin https://preview-control.example --runtime-base https://preview-run.example --auth-api https://www.wovoon.com --host 127.0.0.1 --port 5180` 是服务端命令,不能在顷悟用户电脑上启动。
37
+
38
+ 服务优先部署在独立测试节点,使用平台同版受控沙箱,不接生产业务数据库。控制域名和 `*.preview-run.example` 分别配置 HTTPS;游戏域与正式账号域使用不同可注册域,不能共享父域 Cookie。网关必须原样传 Host、Origin 和 WebSocket 握手,禁止代理层缓存运行页面或记录启动凭据。控制接口只接受有效平台账号令牌。无认证公共模式仅存在于测试夹具,正式入口不得加载它。
39
+
40
+ 默认每账号同时 2 个会话、全服务 16 个、最多 20 个持久工作区;每次仅保留活动与待上传版本。上传至少保留 5 GiB 空间。生产启用前应给测试节点设置独立磁盘/数据库配额、网关限流、并发连接上限、监控与持久卷备份,按容量扩容。此版本单服务进程管理会话;多副本需先实现会话路由,不能用随机负载均衡。
41
+
42
+ 平台设置 `WOVOON_PREVIEW_CONTROL_URL` 后才会在服务发现中启用。先完成独立测试节点验收,再发布发现配置和顷悟安装包;不需要升级游戏生产运行器来启用预览。
43
+
44
+ 复用现有节点时,dev/prod 须分别使用非 root 用户、rootless Docker、独立限额文件系统和 cgroup v2 限制。服务参数支持 --max-running、--max-per-owner,以及必须配套使用的 --host-reserve-path、--host-reserve-bytes;宿主盘不足会拒绝新上传,同时计入正在接收的上传预留。--host 必须是 IP,默认为 127.0.0.1;--control 与 --runtime 为两个 origin 参数的简写。
45
+
@@ -1,4 +1,4 @@
1
- # 激励广告与作品奖励(SDK 0.9.0)
1
+ # 激励广告与作品奖励(GroMore)
2
2
 
3
3
  奖励是每个作品、每个登录玩家独立的虚拟额度,例如复活次数、游戏金币。
4
4
  它不会增加 Wovoon 平台积分、现金或创作者收益。没有服务器配置、未登录、没有广告源时跳过。
@@ -6,7 +6,7 @@
6
6
 
7
7
  ## 创作者配置
8
8
 
9
- 推荐在 AI 开发/改造会话中使用 CLI 0.16.0 的 `wovoon ads init/status/plan/apply` 和项目 `wovoon.ads.json` 配置,无需创作者中心广告页面。`init` 生成默认停用的规则;`apply` 全部成功后自动保存确认的 revision,检测到作者并发修改时保留作者文件。完整流程与双入口示例见 [AI 配置激励广告](recipes/rewarded-placement.md)。
9
+ 推荐在 AI 开发/改造会话中使用 北极星 CLI 的 `wovoon ads init/status/plan/apply` 和项目 `wovoon.ads.json` 配置,无需创作者中心广告页面。`init` 生成默认停用的规则;`apply` 全部成功后自动保存确认的 revision,检测到作者并发修改时保留作者文件。完整流程与双入口示例见 [AI 配置激励广告](recipes/rewarded-placement.md)。
10
10
 
11
11
  先声明 `.wovoon` 的 `ads` 能力。底层作者管理 API(也支持作者 PAT)为
12
12
  `GET /api/cloud/manage/{appId}/ad-rewards` 读取规则,或 `PUT` 同一地址保存:
@@ -18,7 +18,7 @@
18
18
  新增用 `revision:0`,修改必须带 GET 返回的当前 revision;只有作品拥有者可修改。
19
19
  场景名与 rewardKey 为字母开头、最长 64 字符的字母/数字/下划线/点/横线。
20
20
  数量 1–10000,每日请求上限 1–100,最小间隔 0–86400 秒(0 表示不限制间隔),奖励名称最多 40 字符。
21
- 每日按 UTC 计算,拒绝观看、无填充和失败请求也占已签发次数;不能靠断线绕过频控。
21
+ 每日按北京时间自然日计算,拒绝观看、无填充和失败请求也占已签发次数;不能靠断线绕过频控。
22
22
  已签发的 15 分钟请求使用当时的奖励快照。关闭规则阻止新请求,全局开关关闭则停止处理新回调。
23
23
 
24
24
  ## 游戏调用
@@ -39,10 +39,15 @@ if (result.reason === "REWARD_PENDING" && result.requestId) {
39
39
  ```
40
40
 
41
41
  `show` 关闭后查询服务端,只有 `reward.status === "granted"` 才返回 `rewarded:true`。
42
+ 回执仍为 `pending` 时,SDK 依次等待 250、750、1500 毫秒后重查同一 requestId,
43
+ 最多查询 4 次、每次最多等待 2 秒;不会重新请求广告。切换/销毁客户端会停止后续查询。
42
44
  `pending`、`expired`、网络失败都不能当成已到账;网络失败返回
43
- `REWARD_STATUS_UNAVAILABLE`,保留 requestId 供重试。查询超时为 8 秒。
45
+ `REWARD_STATUS_UNAVAILABLE`,保留 requestId 供重试。主动 `rewardStatus` 查询超时为 8 秒。
46
+ `REWARD_EXPIRED` 表示本次回执已失效,不是广告库存不可用。
47
+ `no_fill / NO_AD_AVAILABLE` 表示广告平台没有返回素材,避免立即反复请求;
48
+ `AD_TIMEOUT` 为广告加载/展示超时,`AD_LOAD_FAILED` 为其他原生广告错误。
44
49
  重启或关闭前未取得 requestId 时,可通过 `rewardBalances()` 恢复服务端总余额。
45
- 广告关闭、视频完成、客户端 onRewardArrived/onRewardVerify 都不会修改账本。
50
+ 广告关闭、视频完成、客户端原生领奖回调 都不会修改账本。
46
51
 
47
52
  ```js
48
53
  // 在发请求前持久化本次业务操作 ID;断网重试必须继续用同一个 ID。
@@ -56,7 +61,7 @@ renderBalance(spent.balanceAfter);
56
61
  同 ID 改参数拒绝。API 不向客户端提供加奖接口。余额属于服务器账本,不等同于任意游戏
57
62
  存档里的金币;有自建后端的游戏应由业务服务器按操作 ID 处理实际道具,不能信任客户端通知。
58
63
 
59
- 在平台权威玩法中,用 `ctx.settle(operationId, writes, {playerId,rewardKey,amount})` 将奖励消费与 SERVER 存档/道具写入放入同一事务;不要先在客户端扣余额,再请求服务器发道具。玩家身份来自当前房间的有效登录租约,作品不能指定账号。新玩法先检查 `ctx.features?.rewardSettlement === 1`,旧运行时不支持时停止该操作,禁止退化成免费发放。完整示例见 [奖励消费与游戏结算](recipes/platform-game-mode.md#奖励消费与游戏结算)。
64
+ 当前版本通过 `ads.consumeReward` 幂等消费作品奖励;不提供把广告奖励消费与权威房间 SERVER 集合写入合并的 `ctx.settle` 接口。不要向 `ctx.settle` 传 `rewardKey`,也不能以客户端自报结果向权威房间发放道具。
60
65
 
61
66
  玩家端 `consumeReward` 的 `clientId` 不得使用平台保留的 `game_` 前缀。
62
67
 
@@ -66,23 +71,12 @@ renderBalance(spent.balanceAfter);
66
71
 
67
72
  ## 平台开通和验收
68
73
 
69
- GroMore 聚合位需开启服务端激励验证,HTTPS GET 回调:
70
- `/api/public/ads/rewards/gromore`。每个环境应使用独立聚合位和 m-key,避免 dev/prod 回调串线。
71
- 只在后端 Secret 注入 `WOVOON_REWARD_SSV_ENABLED=true`、`WOVOON_REWARD_SSV_ENV=dev|prod`、
72
- `WOVOON_REWARD_SSV_SLOT`、`WOVOON_REWARD_SSV_KEY`;缺任一配置默认不可用。
73
- 广告格式总开关及 rewarded 格式也必须开启,slot 必须与后端配置一致。
74
- 不得把 m-key 放入作品、APK、SDK、Git 或普通日志。
74
+ GroMore 正式激励位启用服务端验证,HTTPS GET 回调为 `/api/public/ads/rewards/gromore`。服务端配置 `WOVOON_REWARD_SSV_ENABLED`、`WOVOON_REWARD_SSV_ENV`、`WOVOON_REWARD_SSV_SLOT` 和 `WOVOON_REWARD_SSV_KEY`;密钥不进入 APK、作品、SDK 或日志。
75
75
 
76
- 官方签名为 `SHA256(m-key + ":" + trans_id)`;回调还绑定服务器预签的环境、作品、玩家、
77
- 请求和奖励快照,交易 ID 唯一。事务将回执与余额一起写入,重复回调返回成功但不重复发奖。
78
- 本协议依赖 GroMore 的服务端事件语义,不把签名本身描述为完整观看或真人观看证明。
79
- 返回原始 `{"is_verify":true,"reason":0}`,不包裹平台 ApiResponse,并禁止缓存。
76
+ 平台验证 GroMore 签名、聚合广告位、一次性签发请求、玩家、环境和奖励快照,返回原始 `{"is_verify":true,"reason":0}`。重复回调不重发,提现现金结算另走官方日报。`prime_rit` 是聚合代码位,`mediation_rit` 为广告源代码位,后者用于官方收益归属核对。
80
77
 
81
- 先在 dev 使用已授权测试作品/账号实际观看,核对 provider 回调、到账、重复回调、关闭/跳过、
82
- 断线恢复及扣减,再启用 prod。模拟签名和单元测试不能代替广告平台真实回调验收。
83
- 新广告联盟或新环境应独立完成验收;不能将已有联盟的通过结果泛化。已验收并启用的生产链路不因开发文档示例而关闭。
78
+ ### 顷悟模拟预览
84
79
 
85
- 官方资料:[GroMore 服务端激励验证](https://www.csjplatform.com/supportcenter/26240)、
86
- [Android 激励广告](https://www.csjplatform.com/supportcenter/28661)。
80
+ 项目声明 ads 并准备 `wovoon.ads.json` 后,在顷悟“调试 → 实时预览”选择登录测试玩家。点击作品内激励按钮会出现模拟面板,可测试完整播放、提前关闭、无填充和加载失败。规则草稿可直接模拟,不必启用正式广告。仅完整播放记入测试工作区虚拟余额,重复完成不重发;重开工作区可恢复余额。网页和手机预览使用相同协议。
87
81
 
88
- 零间隔还需 Android 宿主支持,并将平台激励格式 minIntervalSeconds 配置为 0。旧版 App 最小值为 30 秒,应先升级宿主再启用;每日上限与同一时刻只展示一条广告不受影响。
82
+ 预览不会接触正式广告、生产游戏钱包或创作者现金。`simulated:true` 明确标记模拟结果。真实验收仍需在 Android App 中验证素材、官方回调、奖励到账、重复回调和提前关闭。
package/docs/sdk.md CHANGED
@@ -1,9 +1,8 @@
1
- SDK 0.8.0 新增 [服务端激励奖励](rewarded-ads.md):校验、账本、回执和幂等扣减。
2
1
 
3
2
  # 云能力 SDK(协议 1)
4
3
 
5
- SDK 0.7.0 新增 [作品广告容器](ads.md):`ads.capabilities / show / mountBanner`。
6
- 网页无授权广告源立即跳过;Android 按作品权限和平台聚合配置展示横幅/插屏。
4
+ 作品激励广告通过 `WovoonPolaris.ads` 或 TypeScript 客户端的 `client.ads` 调用,只支持 `rewarded`。先声明 `ads` 能力并配置奖励规则,能力查询成功后再展示;仅服务端 `granted` 回执代表到账。详见 [GroMore 广告接入](ads.md)。顷悟预览返回 `simulated:true`,与正式奖励和现金隔离。
5
+
7
6
 
8
7
  两种形态,同一套能力 API:
9
8
 
package/llms.txt CHANGED
@@ -1,13 +1,14 @@
1
1
  # wovoon Polaris
2
2
 
3
- > wovoon 提供统一游戏后台:身份、常驻权威玩法、实时同步、云存档和广告奖励;静态前端承载各个游戏模式。
3
+ > wovoon 提供统一游戏后台:身份、常驻权威玩法、实时同步、云存档;静态前端承载各个游戏模式。
4
4
  > 本站文档面向 AI coding 工具与人类开发者,机器可执行、报错自带修复指引。
5
5
  > 协议版本 1。单机作品可先托管;多人玩法还需把权威状态和规则迁到常驻服务端模式,通过 SDK 发送输入、接收状态。上传本身不会自动让单机游戏变为多人游戏。
6
6
 
7
7
  ## 必读(按顺序)
8
8
 
9
+
9
10
  - [协议正典](PROTOCOL.md): 包契约、运行契约、能力 API 与错误风格的完整定义。改造前先读完这一篇。
10
- - [快速开始](docs/index.md): 五分钟从零发布一个带云存档与排行榜的应用(init → dev → validate → 上传)。
11
+ - [快速开始](docs/index.md): 五分钟从零发布一个带云存档与排行榜的应用(init → preview → validate → 上传)。
11
12
  - [`.wovoon` 清单规范](docs/manifest.md): 标识文件字段、能力命名、合法示例与全部校验规则。
12
13
  - 声明式集合与云函数:包根 `collections.json` 声明集合权限、`functions/*.js` 放云函数——发布全自动,无需控制台。
13
14
  - 查询支持 `where` 过滤与 `join` 嵌入连接(单值 `"集合.字段"` / 多值 `["集合","字段"]`,每次 ≤2 个)。
@@ -16,13 +17,14 @@
16
17
 
17
18
  ## 工具
18
19
 
19
- - [wovoon CLI](docs/cli.md): `wovoon init / dev / validate / login / deploy / rollback / versions`;
20
+ - [作品激励广告](docs/ads.md):GroMore Android 激励广告、30/70 收益分成与顷悟模拟预览。规则配置和服务端回执见 [激励规则](docs/rewarded-ads.md),完整 [接入配方](docs/recipes/rewarded-placement.md)。需要 SDK 0.15 / CLI 0.22 与对应运行时。
21
+
22
+ - [wovoon CLI](docs/cli.md): `wovoon init / dev / validate / login / deploy / rollback / versions / products / extensions / data`;
20
23
  本地模拟大后台;生产规则镜像校验;一条命令发布(内置默认图标/视频,非多模态 AI 也可发布;
21
24
  每次发版可随时 rollback)。
22
25
  - [云能力 SDK](docs/sdk.md): 页面内 `WovoonCloud`(平台同源下发)与 `@wovoon/polaris`(TypeScript 客户端)完整 API。
23
- - [作品广告容器](docs/ads.md): `ads` 清单能力;网页无授权源立即跳过,Android 原生横幅/插屏;无填充继续游戏,激励视频未配置时不发奖。
26
+ - [本地测试场景](docs/local-scenarios.md): 匹配恢复、延迟奖励回执、商品目录和测试订单;默认持久化,Windows 使用 WSL2 / Docker Desktop。
24
27
 
25
- - [AI 配置激励广告](docs/recipes/rewarded-placement.md): CLI 0.16 的 ads init/status/plan/apply,作品自定义入口与奖励;网页提示仅移动端支持,Android 展示,服务端校验到账;权威玩法使用奖励消费与存档原子事务。
26
28
 
27
29
  ## 改造配方(存量程序 → wovoon)
28
30
 
@@ -45,5 +47,5 @@
45
47
  ## 约定
46
48
 
47
49
  - 协议字段只加不改不删;空 `.wovoon` 文件等价于 `{"protocol":1}`。
48
- - 能力命名冻结:`identity` / `function` / `room` / `collection:<名称>`(名称 2-32 位小写字母/数字/下划线)。
50
+ - 能力命名:`identity` / `function` / `room` / `room:competitive` / `gamelogic` / `commerce` / `ads` / `collection:<名称>`(名称 2-32 位小写字母/数字/下划线)。
49
51
  - 一切报错必须"缺什么 + 怎么修";AI 工具遇到未收录错误应以 PROTOCOL.md 为准并向平台反馈。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wovoon/polaris",
3
- "version": "0.10.0",
3
+ "version": "0.15.0",
4
4
  "description": "wovoon Polaris SDK——wovoon 大后台云能力客户端(身份/数据集合/云函数/房间实时),协议 1",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -14,7 +14,7 @@
14
14
  "LICENSE"
15
15
  ],
16
16
  "scripts": {
17
- "build": "tsc -p tsconfig.json && node ../../scripts/sync-ads-browser.mjs && node ../../scripts/sync-game-browser.mjs && node ../../scripts/sync-commerce-browser.mjs && node ../../scripts/sync-match-browser.mjs",
17
+ "build": "tsc -p tsconfig.json && node ../../scripts/sync-game-browser.mjs && node ../../scripts/sync-commerce-browser.mjs && node ../../scripts/sync-match-browser.mjs && node ../../scripts/sync-ads-browser.mjs",
18
18
  "check": "tsc --noEmit",
19
19
  "prepack": "node ../../scripts/package-docs.mjs"
20
20
  },