@wovoon/polaris 0.8.1 → 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 +9 -11
- package/dist/ads.d.ts +10 -10
- package/dist/ads.js +52 -45
- package/dist/client.d.ts +10 -6
- package/dist/client.js +46 -32
- package/dist/commerce.d.ts +61 -0
- package/dist/commerce.js +176 -0
- package/dist/game-sync.d.ts +31 -0
- package/dist/game-sync.js +90 -0
- package/dist/game.d.ts +82 -0
- package/dist/game.js +194 -0
- package/dist/index.d.ts +6 -3
- package/dist/index.js +4 -1
- package/dist/match.d.ts +10 -0
- package/dist/match.js +74 -0
- package/dist/protocol.d.ts +3 -1
- package/dist/protocol.js +1 -1
- package/docs/ads.md +13 -68
- package/docs/cli.md +24 -11
- package/docs/errors.md +1 -1
- package/docs/local-scenarios.md +22 -0
- package/docs/manifest.md +5 -3
- package/docs/quickstart.md +1 -1
- package/docs/recipes/competitive-games.md +16 -44
- package/docs/recipes/game-commerce.md +65 -0
- package/docs/recipes/platform-game-mode.md +119 -0
- package/docs/recipes/rewarded-placement.md +6 -4
- package/docs/remote-preview.md +45 -0
- package/docs/rewarded-ads.md +21 -21
- package/docs/sdk.md +2 -3
- package/llms.txt +13 -7
- package/package.json +2 -2
package/dist/match.js
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
/** The persisted seat repairs a lost WebSocket notification. It never starts another order/room. */
|
|
2
|
+
export async function matchRoom(mode, connect, query, signal) {
|
|
3
|
+
if (!/^[a-z][a-z0-9_]{1,31}$/.test(mode))
|
|
4
|
+
throw Error("INVALID_MATCH_MODE");
|
|
5
|
+
if (signal?.aborted)
|
|
6
|
+
throw Error("MATCH_CANCELLED");
|
|
7
|
+
const old = await query("status").catch(() => undefined);
|
|
8
|
+
if (signal?.aborted)
|
|
9
|
+
throw Error("MATCH_CANCELLED");
|
|
10
|
+
if (old?.status === "ASSIGNED" && old.roomId)
|
|
11
|
+
return old.roomId;
|
|
12
|
+
if (old?.status === "JOINED")
|
|
13
|
+
await query("cancel");
|
|
14
|
+
return new Promise((resolve, reject) => {
|
|
15
|
+
let ended = false, timer;
|
|
16
|
+
const queue = connect();
|
|
17
|
+
const finish = (room, error) => {
|
|
18
|
+
if (ended)
|
|
19
|
+
return;
|
|
20
|
+
ended = true;
|
|
21
|
+
clearTimeout(timeout);
|
|
22
|
+
if (timer)
|
|
23
|
+
clearTimeout(timer);
|
|
24
|
+
signal?.removeEventListener("abort", abort);
|
|
25
|
+
try {
|
|
26
|
+
queue.leave();
|
|
27
|
+
}
|
|
28
|
+
catch { }
|
|
29
|
+
if (room)
|
|
30
|
+
resolve(room);
|
|
31
|
+
else
|
|
32
|
+
reject(error || Error("MATCH_CANCELLED"));
|
|
33
|
+
};
|
|
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);
|
|
55
|
+
signal?.addEventListener("abort", abort, { once: true });
|
|
56
|
+
if (signal?.aborted) {
|
|
57
|
+
abort();
|
|
58
|
+
return;
|
|
59
|
+
}
|
|
60
|
+
queue.onMessage(frame => { if (frame?.type === "matched" && typeof frame.roomId === "string")
|
|
61
|
+
finish(frame.roomId); });
|
|
62
|
+
const poll = async () => {
|
|
63
|
+
const seat = await query("status").catch(() => undefined);
|
|
64
|
+
if (ended)
|
|
65
|
+
return;
|
|
66
|
+
if (seat?.status === "ASSIGNED" && seat.roomId) {
|
|
67
|
+
finish(seat.roomId);
|
|
68
|
+
return;
|
|
69
|
+
}
|
|
70
|
+
timer = setTimeout(poll, 1500);
|
|
71
|
+
};
|
|
72
|
+
timer = setTimeout(poll, 1500);
|
|
73
|
+
});
|
|
74
|
+
}
|
package/dist/protocol.d.ts
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
/** 协议版本。协议 1 是当前唯一支持的版本。 */
|
|
6
6
|
export declare const WOVOON_PROTOCOL_VERSION: 1;
|
|
7
7
|
/** 协议 1 冻结的能力名。集合能力形如 `collection:${WovoonCollectionName}`。 */
|
|
8
|
-
export type WovoonCapability = "identity" | `collection:${WovoonCollectionName}` | "function" | "room" | "room:competitive" | "ads" | "gamelogic";
|
|
8
|
+
export type WovoonCapability = "identity" | `collection:${WovoonCollectionName}` | "function" | "room" | "room:competitive" | "ads" | "commerce" | "gamelogic";
|
|
9
9
|
/** 集合名:2-32 位,小写字母开头,仅小写字母/数字/下划线。运行时校验用下方正则。 */
|
|
10
10
|
export type WovoonCollectionName = string;
|
|
11
11
|
export declare const COLLECTION_NAME_PATTERN: RegExp;
|
|
@@ -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|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
|
-
#
|
|
1
|
+
# GroMore 广告接入
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
(与 `WovoonCloud.ads` 相同)或 `new PolarisClient().ads` 调用。
|
|
5
|
-
单独使用广告不要求声明 `identity` 或调用 `ready()`。
|
|
3
|
+
App 统一使用 GroMore 多广告源聚合竞价。开屏、推荐页视频流、发现页广告卡和更多页广告卡由平台配置,创作者只接作品内激励广告。
|
|
6
4
|
|
|
7
|
-
|
|
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
|
|
16
|
-
|
|
17
|
-
placement:
|
|
18
|
-
|
|
19
|
-
|
|
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
|
-
|
|
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
|
-
|
|
71
|
-
作品 ID、有效游玩租约向 `/api/public/ads/runtime/authorize` 请求准入;
|
|
72
|
-
平台核对作品公开状态、租约归属和清单 `ads` 能力。作品不能选其他作品、会话、
|
|
73
|
-
广告源 URL、联盟 ID、eCPM 或奖励数值。
|
|
21
|
+
后台实时收益是展示回调报价估算,报价未知单独计数,不记成零收入。现金结算使用完整官方日报,人民币按分记账:平台广告收入的 30% 归平台,70% 按北京时间当日有效游玩时长分给创作者;没有有效时长则保留待分配。激励收入的 30% 归平台,70% 归对应作品作者,按官方广告源代码位的平均展示收入匹配验签回调归属;无法归属的展示份额待核对,不摊给其他作品。
|
|
74
22
|
|
|
75
|
-
|
|
76
|
-
真实填充与比价由已接入的聚合 SDK 完成。平台现有网页模拟竞价/自推广素材不会
|
|
77
|
-
作为此接口的填充。SDK 回调仅为展示结果,不是结算收入或服务端奖励凭证。
|
|
78
|
-
当前横幅和插屏与 App 对应格式共用频率额度;任一全屏广告展示时不再启动第二个。
|
|
23
|
+
玩家虚拟奖励与创作者现金是独立账本。日结防重复入账,沿用平台提现冻结期。
|
package/docs/cli.md
CHANGED
|
@@ -1,12 +1,14 @@
|
|
|
1
|
-
# wovoon CLI 参考(CLI 0.
|
|
1
|
+
# wovoon CLI 参考(CLI 0.22.0)
|
|
2
2
|
|
|
3
3
|
```
|
|
4
|
-
wovoon init [目录] [--template minimal|game|arena] [--name 名称]
|
|
5
|
-
wovoon
|
|
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.
|
|
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
|
|
21
|
+
## wovoon preview
|
|
22
|
+
|
|
23
|
+
日常开发使用远程预览,顷悟内置相同客户端,无需本机 WSL/Docker。详见 [远程预览](remote-preview.md)。未启用服务时明确报错。
|
|
24
|
+
|
|
25
|
+
## wovoon dev(可选底层诊断)
|
|
20
26
|
|
|
21
|
-
|
|
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
|
-
-
|
|
35
|
+
- 校验/配额/报错镜像实现覆盖核心契约,生产策略仍需上线环境验收(能力门禁、集合与文档配额、权限、limit 钳制)。
|
|
30
36
|
- `.wovoon`/`.wovoongame`/`.DS_Store`/`__MACOSX/` 不对外发布(与生产一致)。
|
|
31
|
-
- 云函数:`functions/*.js` 在独立系统沙箱执行,数据访问经过受信任代理,作品进程没有平台凭据或网络权限。macOS 使用 sandbox-exec 和 Node 权限模型;Linux 需要 Docker
|
|
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 个,具有空房回收及进程退出清理。
|
|
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
|
-
-
|
|
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. 归档扫描:符号链接、文件数(≤
|
|
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
|
@@ -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
|
|
|
@@ -36,6 +34,10 @@ JSON 对象,UTF-8,最大 **4 KB**。**空文件合法**,等价于 `{"proto
|
|
|
36
34
|
| `collection:<名称>` | 数据集合:文档 CRUD、查询排序、权限 | 可用 |
|
|
37
35
|
| `function` | 云函数:受限 Node 沙箱(限时/限内存/禁出网)内运行服务端逻辑 | 可用 |
|
|
38
36
|
| `room` | 房间实时通道:WebSocket 房间中继(快节奏多人) | 可用 |
|
|
37
|
+
| `room:competitive` | 竞技速率档,和 room 配合使用 | 可用 |
|
|
38
|
+
| `gamelogic` | 常驻权威玩法,和 room 配合使用 | 可用 |
|
|
39
|
+
| `ads` | 作品激励广告与服务端奖励回执;顷悟使用隔离的模拟余额 | SDK 0.15 / CLI 0.22 与对应运行时 |
|
|
40
|
+
| `commerce` | 平台购买、权益查询与权威消费 | 需 SDK 0.10 和对应平台运行时 |
|
|
39
41
|
|
|
40
42
|
- 集合名称:**2-32 位,小写字母开头,仅小写字母/数字/下划线**,如 `collection:scores`、`collection:player_profiles`。
|
|
41
43
|
- 只声明会用到的集合;改名集合时同步改 manifest。
|
|
@@ -51,7 +53,7 @@ JSON 对象,UTF-8,最大 **4 KB**。**空文件合法**,等价于 `{"proto
|
|
|
51
53
|
4. 只允许 `protocol`、`capabilities`、`entry` 与 `backend` 字段;
|
|
52
54
|
5. `protocol` 存在时必须是整数 `1`;
|
|
53
55
|
6. `backend` 存在时只支持 `platform` 或 `external`;
|
|
54
|
-
7. `capabilities` 存在时必须是字符串数组,且每项匹配 `^(identity|function|room|collection:[a-z][a-z0-9_]{1,31})$`。
|
|
56
|
+
7. `capabilities` 存在时必须是字符串数组,且每项匹配 `^(identity|function|room|room:competitive|gamelogic|ads|commerce|collection:[a-z][a-z0-9_]{1,31})$`。
|
|
55
57
|
|
|
56
58
|
本地预检:`wovoon validate`(规则镜像,报错文案与线上一字不差)。
|
|
57
59
|
|
package/docs/quickstart.md
CHANGED
|
@@ -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
|
-
-
|
|
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
|
-
|
|
4
|
-
> `room:competitive`(上行 30Hz、单帧 8KB、二进制帧)+ `gamelogic`(权威房间逻辑)。
|
|
3
|
+
使用 `wovoon init duel --template arena` 创建包含权威决斗的完整模板,或 `--template mode` 创建最小玩法。客户端统一使用 `cloud.game(mode, {roomId})`,平台负责连接、重连、输入序号、快照、插值和延迟检测。
|
|
5
4
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
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
|
-
|
|
9
|
+
在 `roomservers/<mode>.js` 声明 `exports.gameProtocol=1`,实现同步的 `createState / onPlayerJoin / onInput / update / view`。玩家仅提交移动方向、攻击按钮等意图,服务端计算位置、命中、血量与胜负。身份取回调的 `playerId`,不能相信输入中的身份、分数或已付款标记。完整契约见 [平台玩法](platform-game-mode.md)。
|
|
16
10
|
|
|
17
11
|
```js
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
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
|
-
|
|
33
|
-
服务端广播经 onMessage 到达(`from: 'server'`)。
|
|
34
|
-
|
|
35
|
-
## 集合实时刷新(onChange)
|
|
19
|
+
`match` 会查询持久化席位以恢复丢失的匹配通知;取消等待会关闭队列并等待取消结果。输入在断线期间不会自动重放。`onState` 返回完整权威状态;`onEvent` 接收 `ctx.tell/broadcast` 发出的瞬时事件,不能依赖瞬时事件保存进度。
|
|
36
20
|
|
|
37
|
-
`
|
|
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
|
-
|
|
23
|
+
`room:competitive` 保留底层 8 KiB 帧大小及二进制通道能力。新玩法输入共享每玩家令牌桶,建议最多 60 Hz,不能绕过帧大小和业务校验。玩法包每作品最多 8 个模式,单文件最多 2 MiB、合计最多 4 MiB。
|
|
48
24
|
|
|
49
|
-
|
|
25
|
+
世界模式仍可声明 `exports.world=true`;大厅使用 `cloud.rooms({mode})`,跨房消息使用 `cloud.world()`。排行榜通过 SERVER 权限和 `ctx.settle` 写入,再用 `collection().onChange()` 重新读取。
|
|
50
26
|
|
|
51
|
-
|
|
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 容器;云函数与玩法均在隔离环境执行。
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# 平台购买与游戏权益
|
|
2
|
+
|
|
3
|
+
SDK 0.10 / CLI 0.17 新增能力;需目标平台部署对应运行时。在 `.wovoon` 声明 `commerce`,多人权威玩法同时声明 `room`、`gamelogic` 和所需 SERVER 集合。支付密钥留在平台,不放进作品、AI 提示词或扩展。
|
|
4
|
+
|
|
5
|
+
## AI 配置商品
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
wovoon products init .
|
|
9
|
+
wovoon products validate .
|
|
10
|
+
wovoon products status .
|
|
11
|
+
wovoon products apply . --activate
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
编辑根目录 `products.json`:`version:1`,`products` 最多 100 项,每项指定 `productCode/name/description/productType/priceCents/currency/status`。价格单位是整数分,币种 CNY;`ONE_TIME` 为永久权益,`CONSUMABLE` 每单增加一个可消费单位。当前不支持订阅或自动续费。编码与类型保持稳定,改变权益含义须创建新编码。状态为 DRAFT、ACTIVE 或 ARCHIVED;含 ACTIVE 的同步需明确 `--activate`。同步只更新列出的商品,不自动删除遗漏项;重复 apply 可恢复中断的逐项同步。新价格只影响新订单。
|
|
15
|
+
|
|
16
|
+
## 购买和恢复
|
|
17
|
+
|
|
18
|
+
```js
|
|
19
|
+
const {products, providers} = await WovoonCloud.commerce.catalog();
|
|
20
|
+
// 在明确的玩家购买操作中执行;下单前持久保存请求号。
|
|
21
|
+
const key = localStorage.getItem('pending:potion') || crypto.randomUUID();
|
|
22
|
+
localStorage.setItem('pending:potion', key);
|
|
23
|
+
const order = await WovoonCloud.commerce.checkout('potion', {
|
|
24
|
+
provider: 'ALIPAY', idempotencyKey: key
|
|
25
|
+
});
|
|
26
|
+
localStorage.setItem('pendingOrder:potion', order.orderId);
|
|
27
|
+
const result = await WovoonCloud.commerce.present(order);
|
|
28
|
+
// 关闭窗口、跳转回来及前端按钮均不是到账依据。
|
|
29
|
+
if (result.status === 'FULFILLED') {
|
|
30
|
+
const rights = await WovoonCloud.commerce.entitlements();
|
|
31
|
+
// 更新展示;权威玩法仍独立核验。
|
|
32
|
+
}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
使用 catalog 返回的可用渠道。网络失败时使用同一请求号重试,不能自动生成新号。重进作品后按保存的 orderId 调用 `commerce.order(orderId)`,并用 `commerce.entitlements()` 恢复权益。只有上一单确认终止、玩家再次主动购买时才使用新请求号。支付页支持支付宝官方 HTTPS 页面及二维码、微信二维码。
|
|
36
|
+
|
|
37
|
+
新版手机容器提供 `WovoonNativeCommerce` 时,`commerce.present` 自动使用宿主支付通道。作品只发送订单编号;宿主用自己的当前作品及游玩租约重新读取平台订单,展示金额确认,再打开官方支付宝页面。作品不能指定收款地址。宿主返回 `opened/finished` 仅表示页面操作完成,必须继续查询平台订单。离开 App 后游玩会话可能结束,重新进入作品按已保存订单恢复;不要因页面重新加载再次下单。旧手机容器可能禁止新窗口,可用页面二维码跨设备支付;SDK 不会放宽容器导航限制。
|
|
38
|
+
|
|
39
|
+
过期后到账、超出支付额度或缺少商品快照的订单进入 PAID_REVIEW:平台记录收款并等待退款复核,不发放权益。退款审核后权益冻结;渠道确认成功后撤销权益、冲回开发者收益。处理结果未知时仍使用原退款单号重试。玩家可凭订单号联系平台处理退款,开发者不能自行伪造支付或退款回执。
|
|
40
|
+
|
|
41
|
+
## 权威玩法读取与消费
|
|
42
|
+
|
|
43
|
+
`ctx.settle(operationId, writes, purchaseCost)` 的第三个参数可选;购买消费传入 `{playerId,productCode,amount}`,普通成绩结算只传前两个参数。运行时拒绝多余参数,不能通过遗漏消费参数绕开扣减。
|
|
44
|
+
|
|
45
|
+
`ctx.readEntitlements(requestId,playerId)` 异步排队,结果交给同步回调 `exports.onEntitlements(state,receipt)`。检查 `ctx.features.entitlementQuery===1`;回执的 COMPLETED / entitlements 来自平台校验过的当前房间登录租约。不要信任客户端传入的账号、购买数量或 premium 标记。进入房间和购买完成后重新查询,不把 checkpoint 内的权益缓存当永久授权。
|
|
46
|
+
|
|
47
|
+
```js
|
|
48
|
+
exports.onPlayerJoin = (state, id) => {
|
|
49
|
+
ctx.readEntitlements('join:' + id, id);
|
|
50
|
+
};
|
|
51
|
+
exports.onEntitlements = (state, receipt) => {
|
|
52
|
+
if (receipt.status !== 'COMPLETED') return;
|
|
53
|
+
state.players[receipt.playerId].premium = receipt.entitlements.some(
|
|
54
|
+
row => row.productCode === 'premium' && row.productType === 'ONE_TIME' && row.quantity > 0);
|
|
55
|
+
};
|
|
56
|
+
// 由服务端校验复活资格后,使用死亡事件对应的稳定业务号。
|
|
57
|
+
if (ctx.features.purchaseSettlement !== 1) throw Error('运行时未升级');
|
|
58
|
+
ctx.settle(`revive:${roundId}:${playerId}:${deathId}`, [
|
|
59
|
+
{op:'add',collection:'inventory',doc:{playerId,kind:'revive',roundId,deathId}}
|
|
60
|
+
], {playerId,productCode:'potion',amount:1});
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
消费只支持 CONSUMABLE。费用与整批 SERVER 文档、COMPLETED 回执一起提交;重复业务号不重复扣减,同号不同内容拒绝,余额不足不在未来充值后自动执行。`onSettlement` 按原业务号处理:`result` 是 JSON 字符串,内含 `documents` 和 `purchase:{operationId,productCode,amount,balanceAfter}`。即时游戏效果也须针对事件去重,不能仅靠可能落后的房间快照。
|
|
64
|
+
|
|
65
|
+
本地测试:把 `[ {"player":"Alice","productCode":"potion","productType":"CONSUMABLE","quantity":3} ]` 保存到作品目录之外的测试文件,运行 `wovoon dev . --player Alice --commerce-fixture <文件>`。这里是测试玩家名 `player`,不是生产 `playerId`。测试余额不是付款记录;用 `--scenario-fixture` 可进一步测试商品目录、延迟订单和查询恢复,见 [本地场景](../local-scenarios.md)。`wovoon data` 快照同时保存订单、权益、消费和结算记录。
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# 单机玩法接入 Wovoon 游戏后台
|
|
2
|
+
|
|
3
|
+
此协议是协议 1 的新增可选能力。需要支持 `WovoonCloud.game` 的平台运行时;旧房间继续使用原接口。发布前必须验证目标环境,不把本地存在的方法当成生产已部署。
|
|
4
|
+
|
|
5
|
+
## AI 改造顺序
|
|
6
|
+
|
|
7
|
+
1. 保留现有画面、资源、输入方式和单机规则;识别权威状态、输入意图、随机数及胜负条件。
|
|
8
|
+
2. 用 `wovoon init --template mode` 生成参照(以 CLI help 的参数为准)。玩法放在 `roomservers/<mode>.js`,声明 `room`、`gamelogic`;高频模式同时声明 `room:competitive`。
|
|
9
|
+
3. 将判定移到常驻玩法回调。客户端不能决定玩家身份、坐标、命中结果、金币或“已经付款”。服务器校验每种输入的类型、范围和业务含义。
|
|
10
|
+
4. 客户端使用 `cloud.game(mode,{roomId})`。先等待 `ready`,再提交输入、渲染快照;身份、状态序号、心跳、重连由 SDK 处理。
|
|
11
|
+
5. 将可存档状态设计为 JSON。`view(state,playerId)` 只返回该玩家有权看到的状态;隐藏牌、背包和未发现的敌人不能放进公共快照。
|
|
12
|
+
6. 远端角色使用插值;需要即时响应的本地角色使用与服务器一致的确定性模拟函数和 `GamePrediction`。真实物理回滚、命中回溯、非确定性引擎需要针对游戏适配,不能只加一行 SDK 就宣称完成。
|
|
13
|
+
7. 先搜索通用扩展,优先复用;没有适合的扩展时创建作品私有版本。通过测试且作者明确愿意共享,再申请公共审核。
|
|
14
|
+
8. 验证双人、重连、慢连接、重复输入、私有状态、服务器重启及结算。实际发布前验收服务器隔离与平台租约。
|
|
15
|
+
|
|
16
|
+
## 常驻玩法契约
|
|
17
|
+
|
|
18
|
+
```js
|
|
19
|
+
exports.gameProtocol = 1;
|
|
20
|
+
exports.tickRate = 60; // 10–60 Hz,可选;按玩法和压测选择
|
|
21
|
+
exports.snapshotMs = 50; // 20 Hz 状态,画面可独立按设备帧率渲染
|
|
22
|
+
exports.createState = () => ({players: {}});
|
|
23
|
+
exports.onPlayerJoin = (state, id) => { state.players[id] = {score: 0}; };
|
|
24
|
+
exports.onInput = (state, id, input) => {
|
|
25
|
+
// 校验输入并执行玩法,id 来自平台鉴权。
|
|
26
|
+
};
|
|
27
|
+
exports.update = (state, dtMs) => {};
|
|
28
|
+
exports.view = (state, id) => ({you: state.players[id]});
|
|
29
|
+
exports.onPlayerDisconnect = (state, id) => {}; // 停止持续移动等输入
|
|
30
|
+
exports.onPlayerLeave = (state, id) => { delete state.players[id]; };
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
回调同步执行,不能阻塞等待网络或数据库。`tickRate` 优先于 `tickMs`;省略时保留 50 ms。调度使用单调时钟并限制落后后的补跑,过载会记录 missedTicks。不能用提高 tick 率弥补超预算玩法。
|
|
34
|
+
|
|
35
|
+
新协议的完整快照包含 `instanceId/sequence/tick/serverTime/you/state/acknowledgements`。发送积压只替换尚未发送的完整快照;普通事件、交易回执保持顺序。旧协议不自动丢弃其消息。
|
|
36
|
+
|
|
37
|
+
新玩法输入采用每玩家共享令牌桶:120 条/秒、瞬时 30 条,覆盖多连接;SDK 建议最多 60 Hz。心跳、恢复请求占相同预算。每条仍受房间 8 KiB 竞技/普通大小限制,服务器对玩法业务另作校验。旧房间仍使用原来的 30 秒限额。输入没有收到快照确认时不能推断已执行。
|
|
38
|
+
|
|
39
|
+
`game.submit(input)` 返回本次已送入客户端传输的序号,失败返回 `null`;这不是服务器执行确认。`input` 是布尔简写。断线不自动重发旧操作,以免重复开火、购买或消费;幂等业务应使用业务请求号和服务端账本。
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
const prediction = new GamePrediction(initial, simulate);
|
|
43
|
+
const game = cloud.game<State>('arena', {
|
|
44
|
+
roomId,
|
|
45
|
+
interpolation: {delayMs: 100, interpolate},
|
|
46
|
+
onState(state, frame) {
|
|
47
|
+
prediction.reconcile(state.self, frame.acknowledgements[game.clientId] ?? 0, frame.instanceId);
|
|
48
|
+
},
|
|
49
|
+
onStatus(status) { if (status === 'reconnecting') prediction.reset(lastAuthoritativeSelf); }
|
|
50
|
+
});
|
|
51
|
+
await game.ready;
|
|
52
|
+
const sequence = game.submit(command);
|
|
53
|
+
if (sequence !== null) prediction.predict(sequence, command);
|
|
54
|
+
// 渲染:本地角色 prediction.state;远端角色 game.sample(performance.now())。
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
插值缓冲会引入配置的视觉延迟。预测仅重放本地未确认输入,不重发网络命令。模拟器必须具有相同的步长、碰撞和速度规则;客户端传入的 dt 不可直接信任。网络暂停时停止无限外推。换实例、切换房间及退出应清理缓存和预测。
|
|
58
|
+
|
|
59
|
+
## 恢复边界
|
|
60
|
+
|
|
61
|
+
新玩法每约 5 秒生成恢复快照,最大 512 KiB;只有服务端目录和持久化启用才保存。恢复绑定模式源码及扩展哈希,代码变化后不加载旧状态。进程故障可能丢失最后一个保存周期,不能用于保证付款或奖励不丢失。恢复后的实例 ID 改变,客户端必须重新校正。
|
|
62
|
+
|
|
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`。旧玩法生命周期已退役。
|
|
68
|
+
|
|
69
|
+
## 持久化结算
|
|
70
|
+
|
|
71
|
+
玩法用 `ctx.settle(operationId, writes)` 排队提交成绩或存档,当前 tick 不等待数据库。`operationId` 是作品和房间范围内稳定的业务编号,长度 1–128,只使用字母、数字、下划线、点、冒号和短横线。结算内容由权威玩法计算,不能直接转发客户端提供的分数。示例:
|
|
72
|
+
|
|
73
|
+
```js
|
|
74
|
+
// collections.json 声明 scores 的 write 为 SERVER,清单声明 collection:scores。
|
|
75
|
+
ctx.settle('round:' + state.roundId + ':result', [
|
|
76
|
+
{op: 'add', collection: 'scores', doc: {playerId, score: computedScore}}
|
|
77
|
+
]);
|
|
78
|
+
exports.onSettlement = (state, receipt) => {
|
|
79
|
+
if (receipt.status === 'COMPLETED') state.lastSettled = receipt.operationId;
|
|
80
|
+
// PENDING 尚未完成;REJECTED / FAILED 需要显示失败并保留业务编号。
|
|
81
|
+
};
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
每批 1–64 个 `add` / `set`,总请求最多 48 KiB;`set` 须提供目标文档 UUID。只允许本作品已声明、写权限为 SERVER 的集合。整批写入与完成回执在同一事务提交;其中一步失败整批回滚。同编号、同源码版本、同内容重复提交返回同一操作;不同内容会被拒绝,不能通过重试修改已接受的结算。
|
|
85
|
+
|
|
86
|
+
平台持久保存已接受的请求,房间退出后仍可完成。临时失败自动退避重试,最多 10 次,之后保留 FAILED 供管理员处理。每作品最多 1000 个未完成请求,每房间与普通文档写入合计每分钟 60 次。过期节点不能提交新的请求,已接受的请求继续执行。回执可能重复送达,`onSettlement` 必须幂等。故障恢复后应使用存档中的相同业务编号和原始内容查询式重试;不要生成新编号来猜测旧操作是否成功。
|
|
87
|
+
|
|
88
|
+
本地 `wovoon dev` 使用 SQLite 原子事务并保留去重记录,通常直接收到 COMPLETED;关闭本地持久化时此接口返回 REJECTED。生产先收到 PENDING,再异步收到完成结果。它处理作品集合的成绩和存档,不代表付款确认、平台积分或充值发货;这些仍须使用各自的可信平台账本。
|
|
89
|
+
|
|
90
|
+
## 作品激励奖励
|
|
91
|
+
|
|
92
|
+
作品使用 `ads.rewardBalances` 查询、`ads.consumeReward` 幂等消费已由服务端确认的奖励,见 [激励广告](../rewarded-ads.md)。当前版本不支持广告奖励与权威房间 SERVER 写入的组合事务,不能向 `ctx.settle` 传奖励费用或信任客户端自报的奖励。
|
|
93
|
+
|
|
94
|
+
## 通用扩展
|
|
95
|
+
|
|
96
|
+
```text
|
|
97
|
+
wovoon extensions search --query inventory
|
|
98
|
+
wovoon extensions init ./inventory --name inventory
|
|
99
|
+
wovoon extensions publish ./inventory
|
|
100
|
+
wovoon extensions install . --id <不可变版本UUID> --alias inventory
|
|
101
|
+
wovoon extensions status .
|
|
102
|
+
wovoon extensions submit ./inventory --id <版本UUID> --license MIT
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
执行前以 `wovoon help` 核对参数位置。发布默认私有,名字和版本在作者命名空间内唯一;重复相同上传幂等,不同内容须增版本。`wovoon.extensions.json` 锁定版本和 SHA-256,私有代码缓存不应加入公开作品包。平台安装绑定以服务端为准,`status` 可复核;请求结果未知时先读取状态。
|
|
106
|
+
|
|
107
|
+
玩法通过 `ctx.extension('inventory')` 取得同步模块。模块只在所属房间的 OS 沙箱内运行,不接触主站密钥、数据库连接或其他作品状态。每作品最多 16 个扩展;新安装只影响新房间,已有房间继续原版本。平台不会因为名字相似自动替换作品依赖。
|
|
108
|
+
|
|
109
|
+
`extension.json` 包含 `name/version/summary/entry/contract`。CLI 0.17 默认生成 `apiVersion:2`,`exports` 的每个方法声明 `args:[schema]` 和 `returns:schema`,运行时校验参数数量、类型、边界和返回值,禁止异步返回。schema 支持 string/number/integer/boolean/null/array/object,支持 minimum/maximum/maxLength/maxItems/items/properties/required/additionalProperties(false 或 schema);不支持引用和任意关键字。默认字符串上限4096字符、数组1024项、对象64项、深度8、每次输入和输出各64KiB。契约与源码一起锁定;接口语义改变应增加版本。`apiVersion:1` 仍是描述式契约,不追加类型校验。
|
|
110
|
+
|
|
111
|
+
这类校验不能证明业务算法正确,业务测试仍须随审核提供。公开共享需要明确许可和平台审核,支付、奖励、账号权限不能由不可信扩展自我批准。作者可执行 `wovoon extensions revoke <目录> --id <版本UUID> --reason <原因>` 撤销有问题的版本;代码和审计保留,停止下载、安装和新启动,平台定期检查并关闭已使用该版本的房间。已提交的业务事务不会自动撤销。开发者通过 status 查看原因,审核后安装新的不可变版本。
|
|
112
|
+
|
|
113
|
+
## 匹配与容量
|
|
114
|
+
|
|
115
|
+
新节点调度先预留可用容量再发送匹配结果,满载时继续排队。节点每3秒发布容量,失联超过12秒不接新房间;匹配名额等待首次入房最多60秒。现有房间按租约续期,旧实例不能继续写持久化数据。SDK `match(mode,{signal})` 可用 AbortSignal 取消本次等待;断线漏收通知时,每1.5秒查询平台保存的分配结果。这个恢复机制不等于无限保留房间,客户端应及时入房,并显示排队、重连和容量不足状态。
|
|
116
|
+
|
|
117
|
+
## 性能验收
|
|
118
|
+
|
|
119
|
+
分别记录输入确认延迟、服务器 tick 耗时/落后、发送队列、状态间隔、网络 RTT 和客户端帧时间。不能把 50 ms 发包间隔称为 50 ms 公网延迟。状态只发送需要的实体和字段,合理量化数值;大量实体需按玩家视野过滤。用相同场景和负载进行前后对照,再决定 tick、快照频率和容量。
|