@wovoon/polaris 0.15.0 → 0.16.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 +5 -10
- package/README.md +3 -7
- package/dist/client.d.ts +1 -1
- package/dist/protocol.d.ts +2 -2
- package/docs/cli.md +2 -2
- package/docs/errors.md +1 -1
- package/docs/manifest.md +5 -10
- package/docs/rewarded-ads.md +1 -1
- package/package.json +1 -1
package/PROTOCOL.md
CHANGED
|
@@ -34,7 +34,7 @@
|
|
|
34
34
|
|
|
35
35
|
| 字段 | 类型 | 必填 | 规则 |
|
|
36
36
|
|---|---|---|---|
|
|
37
|
-
| `backend` | string | 否 | `platform
|
|
37
|
+
| `backend` | string | 否 | 仅支持 `platform`;省略时使用平台默认模式 |
|
|
38
38
|
| `protocol` | integer | 否(默认 1) | 当前仅支持 `1`;其他值在上传扫描时被拒绝 |
|
|
39
39
|
| `capabilities` | string[] | 否 | 能力声明,见下表;集合能力形如 `collection:<name>`,name 为 2-32 位小写字母开头的小写字母/数字/下划线。竞技扩展(协议 1 追加):`room:competitive`(房间上行 30Hz/8KB/二进制帧)、`gamelogic`(权威房间逻辑 roomservers/<mode>.js,见 docs/recipes/competitive-games.md) |
|
|
40
40
|
| `entry` | string | 否 | **入口声明**:包内相对路径的 HTML(如 `game/index.html`,不得以 `/` 开头或含 `..`)。多入口/壳结构作品(典型:TapTap H5 导出包根目录是加载器壳、真游戏在 `game/` 子目录)必须声明真实入口;未声明时平台按"入口页本地引用可解析比例"自动识别并可能给出建议。声明了不存在/非 HTML 的入口会在托管时被拒绝(报错自带修复指引) |
|
|
@@ -56,7 +56,7 @@
|
|
|
56
56
|
|
|
57
57
|
- 作品经平台安全扫描与内容审核后,由平台静态托管(受控运行域),在**沙箱 iframe** 中运行(平台隔离运行域保留 allow-same-origin,平台前台同源场景使用不透明源);
|
|
58
58
|
- 玩家通过平台"开始游玩"获得**运行票据**;作品内 SDK 以票据换取身份与能力授权;
|
|
59
|
-
-
|
|
59
|
+
- 网络业务通过平台 SDK 使用 Wovoon 云能力,仍遵循沙箱与运行会话规则。
|
|
60
60
|
|
|
61
61
|
## 4. 能力契约(Capability APIs)
|
|
62
62
|
|
|
@@ -107,14 +107,9 @@
|
|
|
107
107
|
- `join` 只影响返回嵌入,不改变主查询的 where/orderBy/limit/分页;对连接字段做过滤请用云函数组合;
|
|
108
108
|
- 包体:静态托管默认上限 4GB / 100,000 文件(可配置覆盖)。
|
|
109
109
|
|
|
110
|
-
##
|
|
110
|
+
## 平台后端与迁移
|
|
111
111
|
|
|
112
|
-
|
|
112
|
+
作品的网络业务统一使用 Wovoon 平台云能力。`.wovoon` 的 `backend` 仅可省略或填写 `"platform"`;纯本地作品可保留空 `capabilities`,使用云能力时按实际调用声明。
|
|
113
113
|
|
|
114
|
-
|
|
115
|
-
{"protocol":1,"backend":"external","capabilities":[]}
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
前端包含 index.html 和资源,SSR 应用须导出静态前端或拆分服务端。API 使用绝对 HTTPS 地址,实时连接使用 WSS。后端按本作品实际运行 Origin 配置 CORS、预检方法与请求头,独立校验 WebSocket Origin、身份及数据权限。不要用整个运行域后缀作为可信身份范围;每次新版本的运行域可能变化。跨站 Cookie 须在真实 iframe / WebView 测试,平台不提供认证桥接,不接受仅凭 playerId 证明身份。密钥留在服务端,平台 Cookie、运行票据与令牌不发送至自建服务。
|
|
114
|
+
已有服务依赖须按实际功能迁移到平台集合、云函数、权威房间或平台扩展,先核对身份、权限、存档和玩法兼容性。不要仅删除清单字段来绕过校验,不自动迁移或清空正式玩家数据。无法适配的依赖须明确报告。
|
|
119
115
|
|
|
120
|
-
平台仍执行原有上传、审核、安全隔离与运行会话规则;此字段不会在 Wovoon 启动后端、开放外部网页入口或提供代理。平台已于 2026-10-09 上线此字段。本地校验使用 @wovoon/cli 0.12.6 或更高版本,清单类型由 @wovoon/polaris 0.6.1 提供。
|
package/README.md
CHANGED
|
@@ -26,15 +26,11 @@ room.send({ text: "你好" });
|
|
|
26
26
|
|
|
27
27
|
零构建页面可直接用平台同源下发的全局版:`<script src="/api/cloud/sdk.js"></script>` → `WovoonCloud.*`。
|
|
28
28
|
|
|
29
|
-
##
|
|
29
|
+
## 平台后端与迁移
|
|
30
30
|
|
|
31
|
-
|
|
31
|
+
作品的网络业务统一使用 Wovoon 平台云能力。`.wovoon` 的 `backend` 仅可省略或填写 `"platform"`;纯本地作品可保留空 `capabilities`,使用云能力时按实际调用声明。
|
|
32
32
|
|
|
33
|
-
|
|
34
|
-
{"protocol":1,"backend":"external","capabilities":[]}
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
纯自建后端无需平台 SDK;同时调用平台能力时按实际用途声明 `capabilities`。前端使用绝对 HTTPS API / WSS 地址,后端配置实际运行域名的 CORS、WebSocket Origin 和独立身份校验。服务端密钥不进入前端包,平台 Cookie、令牌与运行票据不发送给外部后端。本地清单校验使用 `@wovoon/cli` 0.12.6 或更高版本。
|
|
33
|
+
已有服务依赖须按实际功能迁移到平台集合、云函数、权威房间或平台扩展,先核对身份、权限、存档和玩法兼容性。不要仅删除清单字段来绕过校验,不自动迁移或清空正式玩家数据。无法适配的依赖须明确报告。
|
|
38
34
|
|
|
39
35
|
## 资源打包最佳实践(大游戏必读)
|
|
40
36
|
|
package/dist/client.d.ts
CHANGED
|
@@ -2,7 +2,7 @@ import { PolarisAds } from "./ads.js";
|
|
|
2
2
|
import { PolarisCommerce } from "./commerce.js";
|
|
3
3
|
import { PolarisGame, type GameOptions } from "./game.js";
|
|
4
4
|
export interface PolarisRequestInit {
|
|
5
|
-
/** 覆盖 API
|
|
5
|
+
/** 覆盖 API 基址(本地模拟器/平台测试环境用),默认同源。 */
|
|
6
6
|
baseUrl?: string;
|
|
7
7
|
}
|
|
8
8
|
export declare class PolarisError extends Error {
|
package/dist/protocol.d.ts
CHANGED
|
@@ -19,8 +19,8 @@ export interface WovoonManifest {
|
|
|
19
19
|
protocol?: typeof WOVOON_PROTOCOL_VERSION;
|
|
20
20
|
/** 包内 HTML 入口相对路径,例如 game/index.html;不可包含 .. 或以 / 开头。 */
|
|
21
21
|
entry?: string;
|
|
22
|
-
/**
|
|
23
|
-
backend?: "platform"
|
|
22
|
+
/** 在线玩法统一使用平台后端;省略时兼容已有平台作品。 */
|
|
23
|
+
backend?: "platform";
|
|
24
24
|
/** 声明使用的能力;未声明的能力在对应服务上线后不可调用。 */
|
|
25
25
|
capabilities?: WovoonCapability[];
|
|
26
26
|
}
|
package/docs/cli.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# wovoon CLI 参考(CLI 0.
|
|
1
|
+
# wovoon CLI 参考(CLI 0.23.0)
|
|
2
2
|
|
|
3
3
|
```
|
|
4
4
|
wovoon init [目录] [--template minimal|game|arena|mode|rewarded] [--name 名称]
|
|
@@ -6,7 +6,7 @@ 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.16.0(Node ≥ 22.13)。退出码:`0` 成功 / `1` 校验失败 / `2` 用法错误。
|
|
10
10
|
|
|
11
11
|
作品激励广告使用 `wovoon ads init/status/plan/apply` 管理 `wovoon.ads.json`,只有作品所有者可同步正式奖励规则。该文件不会随作品公开发布。`rewarded` 模板和顷悟模拟预览无需广告联盟密钥,见 [激励接入](ads.md)。
|
|
12
12
|
|
package/docs/errors.md
CHANGED
|
@@ -181,4 +181,4 @@ API 错误响应形态:`{"success":false,"message":"…","code":"…"}`,SDK
|
|
|
181
181
|
|
|
182
182
|
### manifest-backend
|
|
183
183
|
|
|
184
|
-
`backend`
|
|
184
|
+
`backend` 仅接受 `platform`;其他值均拒绝,需完成平台适配后重新打包。不是后端 URL,不接受对象、空值或其他字符串。
|
package/docs/manifest.md
CHANGED
|
@@ -19,7 +19,7 @@ JSON 对象,UTF-8,最大 **4 KB**。**空文件合法**,等价于 `{"proto
|
|
|
19
19
|
|
|
20
20
|
| 字段 | 类型 | 必填 | 说明 |
|
|
21
21
|
|---|---|---|---|
|
|
22
|
-
| `backend` |
|
|
22
|
+
| `backend` | string | 否 | 仅支持 `platform`;省略时使用平台默认模式 |
|
|
23
23
|
| `entry` | 字符串 | 否 | 包内 HTML 相对路径,不得以 `/` 开头或包含 `..` |
|
|
24
24
|
| `protocol` | 整数 | 否 | 协议版本,当前唯一支持 `1`;缺省为 1 |
|
|
25
25
|
| `capabilities` | 字符串数组 | 否 | 声明的能力;缺省为空 |
|
|
@@ -52,7 +52,7 @@ JSON 对象,UTF-8,最大 **4 KB**。**空文件合法**,等价于 `{"proto
|
|
|
52
52
|
3. 必须是 JSON 对象(不能是数组/字符串/数字);
|
|
53
53
|
4. 只允许 `protocol`、`capabilities`、`entry` 与 `backend` 字段;
|
|
54
54
|
5. `protocol` 存在时必须是整数 `1`;
|
|
55
|
-
6. `backend` 存在时只支持 `platform
|
|
55
|
+
6. `backend` 存在时只支持 `platform`;
|
|
56
56
|
7. `capabilities` 存在时必须是字符串数组,且每项匹配 `^(identity|function|room|room:competitive|gamelogic|ads|commerce|collection:[a-z][a-z0-9_]{1,31})$`。
|
|
57
57
|
|
|
58
58
|
本地预检:`wovoon validate`(规则镜像,报错文案与线上一字不差)。
|
|
@@ -66,14 +66,9 @@ JSON 对象,UTF-8,最大 **4 KB**。**空文件合法**,等价于 `{"proto
|
|
|
66
66
|
|
|
67
67
|
- **不发布**:`.wovoon` 只用于平台识别,不会随静态站点对外发布(`.wovoongame`、`.DS_Store`、`__MACOSX/` 同样跳过)。
|
|
68
68
|
|
|
69
|
-
##
|
|
69
|
+
## 平台后端与迁移
|
|
70
70
|
|
|
71
|
-
|
|
71
|
+
作品的网络业务统一使用 Wovoon 平台云能力。`.wovoon` 的 `backend` 仅可省略或填写 `"platform"`;纯本地作品可保留空 `capabilities`,使用云能力时按实际调用声明。
|
|
72
72
|
|
|
73
|
-
|
|
74
|
-
{"protocol":1,"backend":"external","capabilities":[]}
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
前端包含 index.html 和资源,SSR 应用须导出静态前端或拆分服务端。API 使用绝对 HTTPS 地址,实时连接使用 WSS。后端按本作品实际运行 Origin 配置 CORS、预检方法与请求头,独立校验 WebSocket Origin、身份及数据权限。不要用整个运行域后缀作为可信身份范围;每次新版本的运行域可能变化。跨站 Cookie 须在真实 iframe / WebView 测试,平台不提供认证桥接,不接受仅凭 playerId 证明身份。密钥留在服务端,平台 Cookie、运行票据与令牌不发送至自建服务。
|
|
73
|
+
已有服务依赖须按实际功能迁移到平台集合、云函数、权威房间或平台扩展,先核对身份、权限、存档和玩法兼容性。不要仅删除清单字段来绕过校验,不自动迁移或清空正式玩家数据。无法适配的依赖须明确报告。
|
|
78
74
|
|
|
79
|
-
平台仍执行原有上传、审核、安全隔离与运行会话规则;此字段不会在 Wovoon 启动后端、开放外部网页入口或提供代理。平台已于 2026-10-09 上线此字段。本地校验使用 @wovoon/cli 0.12.6 或更高版本,清单类型由 @wovoon/polaris 0.6.1 提供。
|
package/docs/rewarded-ads.md
CHANGED
|
@@ -59,7 +59,7 @@ renderBalance(spent.balanceAfter);
|
|
|
59
59
|
|
|
60
60
|
`consumeReward` 原子扣减、不允许负余额;同 ID 同参数返回原结果,不重复扣减;
|
|
61
61
|
同 ID 改参数拒绝。API 不向客户端提供加奖接口。余额属于服务器账本,不等同于任意游戏
|
|
62
|
-
|
|
62
|
+
存档里的金币;实际道具应由平台服务端逻辑按操作 ID 幂等处理,不能信任客户端通知。
|
|
63
63
|
|
|
64
64
|
当前版本通过 `ads.consumeReward` 幂等消费作品奖励;不提供把广告奖励消费与权威房间 SERVER 集合写入合并的 `ctx.settle` 接口。不要向 `ctx.settle` 传 `rewardKey`,也不能以客户端自报结果向权威房间发放道具。
|
|
65
65
|
|