@wovoon/polaris 0.6.0 → 0.6.2
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/LICENSE +21 -0
- package/PROTOCOL.md +114 -0
- package/README.md +12 -2
- package/dist/client.d.ts +16 -0
- package/dist/client.js +56 -13
- package/dist/index.d.ts +1 -4
- package/dist/index.js +1 -4
- package/dist/protocol.d.ts +11 -2
- package/docs/cli.md +105 -0
- package/docs/errors.md +184 -0
- package/docs/index.md +65 -0
- package/docs/manifest.md +74 -0
- package/docs/quickstart.md +194 -0
- package/docs/recipes/competitive-games.md +55 -0
- package/docs/recipes/express-to-cloud.md +70 -0
- package/docs/recipes/localstorage-to-cloud.md +68 -0
- package/docs/recipes/relational-data.md +89 -0
- package/docs/recipes/static-site-add-manifest.md +50 -0
- package/docs/recipes/taptap-h5.md +41 -0
- package/docs/recipes/web-asset-optimization.md +77 -0
- package/docs/sdk.md +165 -0
- package/llms.txt +42 -0
- package/package.json +11 -4
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# 配方:localStorage 存档 → wovoon 云存档
|
|
2
|
+
|
|
3
|
+
适用:单机游戏/应用用 `localStorage` 保存进度,想变成"跨设备、卸载不丢"的云存档。
|
|
4
|
+
核心思路:**每个玩家一条文档**,登录读、变更写、游客降级回 localStorage。
|
|
5
|
+
|
|
6
|
+
前置:`.wovoon` 声明 `identity` 与你的存档集合(示例用 `saves`):
|
|
7
|
+
|
|
8
|
+
```json
|
|
9
|
+
{ "protocol": 1, "capabilities": ["identity", "collection:saves"] }
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## 改造前
|
|
13
|
+
|
|
14
|
+
```js
|
|
15
|
+
// 旧代码:本地存档
|
|
16
|
+
const save = () => localStorage.setItem('progress', JSON.stringify(state));
|
|
17
|
+
const load = () => JSON.parse(localStorage.getItem('progress') || 'null');
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## 改造后
|
|
21
|
+
|
|
22
|
+
```html
|
|
23
|
+
<script src="/api/cloud/sdk.js"></script>
|
|
24
|
+
<script>
|
|
25
|
+
let session = null;
|
|
26
|
+
|
|
27
|
+
async function boot() {
|
|
28
|
+
// 游客也能玩:只是不写云
|
|
29
|
+
try { session = await WovoonCloud.ready(); } catch (e) { session = null; }
|
|
30
|
+
const local = JSON.parse(localStorage.getItem('progress') || 'null');
|
|
31
|
+
let cloud = null;
|
|
32
|
+
if (session && session.loggedIn) {
|
|
33
|
+
const saves = WovoonCloud.collection('saves');
|
|
34
|
+
const mine = await saves.query({ ownerOnly: true, limit: 1 });
|
|
35
|
+
cloud = mine.length ? JSON.parse(mine[0].data) : null;
|
|
36
|
+
if (!cloud && local) await saves.add(local); // 首次上云:迁移本地存档
|
|
37
|
+
if (cloud) localStorage.setItem('progress', JSON.stringify(cloud)); // 离线兜底
|
|
38
|
+
}
|
|
39
|
+
state = cloud || local || initialState;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
async function save() {
|
|
43
|
+
localStorage.setItem('progress', JSON.stringify(state)); // 离线永远可写
|
|
44
|
+
if (!session || !session.loggedIn) return; // 游客:下次登录再迁移
|
|
45
|
+
const saves = WovoonCloud.collection('saves');
|
|
46
|
+
const mine = await saves.query({ ownerOnly: true, limit: 1 });
|
|
47
|
+
if (mine.length) await saves.set(mine[0].id, state);
|
|
48
|
+
else await saves.add(state);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
boot();
|
|
52
|
+
</script>
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
## 要点
|
|
56
|
+
|
|
57
|
+
- **一个玩家一条文档**:`query({ownerOnly:true, limit:1})` 找到自己的文档后 `set` 整体替换,天然幂等。
|
|
58
|
+
- **游客可玩**:云能力写操作要求登录(`登录后才能写入云数据`);把 localStorage 留作游客/离线通道,登录后自动迁移上云。
|
|
59
|
+
- **单文档 ≤ 64 KB**:大存档(关卡编辑器等)按槽位拆成多条文档(`slot:1`、`slot:2`…),用 `data` 里的字段区分。
|
|
60
|
+
- **排行榜别混用**:排行榜是"每人最高分",单独一个集合(如 `collection:scores`)更好查(`orderBy` 数值排序)。
|
|
61
|
+
- 本地全程可用 `wovoon dev --player 阿明` 验证登录写、`wovoon dev` 验证游客降级。
|
|
62
|
+
|
|
63
|
+
## 验证清单
|
|
64
|
+
|
|
65
|
+
1. `wovoon validate` exit 0;
|
|
66
|
+
2. `wovoon dev` 游客态:读默认进度、localStorage 写入、不报云错误;
|
|
67
|
+
3. `wovoon dev --player 阿明`:`add` → 改状态 → `set` → 重开页面 `query` 读回一致;
|
|
68
|
+
4. 平台上传发布后真机复测 2、3。
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# 配方:关系型数据 → wovoon join 连接
|
|
2
|
+
|
|
3
|
+
> 适用:作品里有一对多 / 多对一数据(帖子↔评论、战队↔选手、订单↔用户、帖子↔标签),
|
|
4
|
+
> 原来靠 SQL JOIN 或多次请求拼装。协议 1 的查询自带 `join` 嵌入连接:一次请求,
|
|
5
|
+
> 服务端把关联文档拍平拼装好返回。
|
|
6
|
+
|
|
7
|
+
## 建模规则
|
|
8
|
+
|
|
9
|
+
| 关系 | 存法 | 查询 |
|
|
10
|
+
| --- | --- | --- |
|
|
11
|
+
| 多对一(订单→用户) | 订单文档存 `userId` 字段 = 用户文档 id | `orders.query({ join: { user: 'users.userId' } })` |
|
|
12
|
+
| 一对多(帖子→评论) | 评论文档存 `postId` 字段 = 帖子文档 id | `posts.query({ join: { comments: ['comments', 'postId'] } })` |
|
|
13
|
+
|
|
14
|
+
单值连接结果嵌入**对象或 null**(关联缺失/不可见);多值连接嵌入**数组**(按插入序,每侧 ≤200 条)。
|
|
15
|
+
两种方向可以同用(每次查询最多 2 个 join)。
|
|
16
|
+
|
|
17
|
+
## 第 1 步:`.wovoon` 声明两个集合的能力
|
|
18
|
+
|
|
19
|
+
```json
|
|
20
|
+
{ "protocol": 1, "capabilities": ["identity", "collection:posts", "collection:comments"] }
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
被连接集合**必须同样声明**,否则运行时报
|
|
24
|
+
[能力未声明](../errors.md#capability-not-declared)。
|
|
25
|
+
|
|
26
|
+
## 第 2 步:`collections.json` 声明权限
|
|
27
|
+
|
|
28
|
+
```json
|
|
29
|
+
{
|
|
30
|
+
"posts": { "read": "WORLD", "write": "OWNER" },
|
|
31
|
+
"comments": { "read": "WORLD", "write": "OWNER" }
|
|
32
|
+
}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
玩家面对 `read:PLAYER` 的目标集合逐文档过滤——join 只会嵌入请求玩家自己的文档;
|
|
36
|
+
需要全量可见的数据(排行榜、公示评论)用 `WORLD`,服务端权威数据用 `"write":"SERVER"`。
|
|
37
|
+
|
|
38
|
+
## 第 3 步:前端查询
|
|
39
|
+
|
|
40
|
+
```js
|
|
41
|
+
const cloud = await WovoonCloud.configure({});
|
|
42
|
+
|
|
43
|
+
// 发帖(保存返回的 id)
|
|
44
|
+
const post = await cloud.collection('posts').add({ title: '第一帖' });
|
|
45
|
+
|
|
46
|
+
// 评论:字段值 = 帖子文档 id
|
|
47
|
+
await cloud.collection('comments').add({ postId: post.id, text: '沙发' });
|
|
48
|
+
|
|
49
|
+
// 一次查询:帖子 + 它的全部评论(数组)+ 作者信息(对象)
|
|
50
|
+
const rows = await cloud.collection('posts').query({
|
|
51
|
+
limit: 10,
|
|
52
|
+
join: {
|
|
53
|
+
comments: ['comments', 'postId'],
|
|
54
|
+
author: 'users.authorId',
|
|
55
|
+
},
|
|
56
|
+
});
|
|
57
|
+
for (const row of rows) {
|
|
58
|
+
const post = JSON.parse(row.data);
|
|
59
|
+
post.title; // 主文档字段原样
|
|
60
|
+
post.comments[0].text; // 嵌入数组:评论数据字段拍平 + id/seq 等平台字段
|
|
61
|
+
post.author?.displayName; // 嵌入对象;无关联或不可见时为 null
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
注意:SDK 的文档视图 `data` 是 JSON 字符串,`join` 嵌入的结果也在其中(parse 后访问)。
|
|
66
|
+
`@wovoon/polaris` TS 客户端会自动 parse 并给出 `WovoonJoinClause` 类型。
|
|
67
|
+
|
|
68
|
+
## 嵌入形态与边界
|
|
69
|
+
|
|
70
|
+
- 嵌入对象 = 目标文档数据字段拍平 + `id`/`ownerPlayerId`/`seq`/`createdAt`/`updatedAt` 平台字段(同名时平台字段优先);
|
|
71
|
+
- join 别名不要与文档自身字段重名(重名时嵌入值覆盖原字段);
|
|
72
|
+
- `join` 只做嵌入,不改变主查询的 `where`/`orderBy`/`limit`;要对连接结果过滤、聚合、分页,
|
|
73
|
+
改用云函数:`context.cloud.collection(...).query({ join: {...} })` 同样可用。
|
|
74
|
+
|
|
75
|
+
## 从 SQL 迁移对照
|
|
76
|
+
|
|
77
|
+
| SQL | wovoon |
|
|
78
|
+
| --- | --- |
|
|
79
|
+
| `SELECT * FROM orders JOIN users ON orders.user_id = users.id` | `orders.query({ join: { user: 'users.userId' } })` |
|
|
80
|
+
| `SELECT * FROM posts p LEFT JOIN comments c ON c.post_id = p.id` | `posts.query({ join: { comments: ['comments', 'postId'] } })` |
|
|
81
|
+
| `JOIN ... WHERE users.vip = true`(连接字段过滤) | 云函数里两次 query + 代码过滤 |
|
|
82
|
+
| 多表 JOIN(≥3 表) | 链式:先查 A join B,再用函数取 C 拼装 |
|
|
83
|
+
|
|
84
|
+
## 验证
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
wovoon validate # collections.json / manifest 预检
|
|
88
|
+
wovoon dev # 本地全链路:join 语义与生产逐字一致(含错误文案)
|
|
89
|
+
```
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# 配方:存量静态网站加 `.wovoon`(零改造上架)
|
|
2
|
+
|
|
3
|
+
适用:已经是纯静态站(HTML/CSS/JS、vite/CRA/webpack 构建产物)的应用。**不改动任何业务代码**即可上架 wovoon;声明能力后才按需接入云能力。
|
|
4
|
+
|
|
5
|
+
## 步骤
|
|
6
|
+
|
|
7
|
+
### 1) 确认你要上传的是构建产物
|
|
8
|
+
|
|
9
|
+
上传的是 `dist/`(或 `build/`)的内容:包内必须**直接包含 `index.html`**(不要外面再套一层文件夹导致多个并列入口)。
|
|
10
|
+
|
|
11
|
+
### 2) 在站点根目录创建 `.wovoon`
|
|
12
|
+
|
|
13
|
+
只上架、暂不用云能力——空文件即可:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
cd dist
|
|
17
|
+
touch .wovoon
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
要用云能力则写声明(本配方以云存档为例):
|
|
21
|
+
|
|
22
|
+
```json
|
|
23
|
+
{
|
|
24
|
+
"protocol": 1,
|
|
25
|
+
"capabilities": ["identity", "collection:saves"]
|
|
26
|
+
}
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
### 3) 本地校验
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
wovoon validate dist
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
通过标准:exit 0、`标识文件 : .wovoon`、手机预检 PASS。
|
|
36
|
+
若报 `静态包中没有 index.html` → 你压的是源码目录,改压构建产物。
|
|
37
|
+
|
|
38
|
+
### 4) 打包上传
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
cd dist && zip -r ../app.zip . && cd ..
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
在 wovoon 创作者平台创建作品、上传 `app.zip`、提交审核。机审通过后开通静态托管,平台分配运行地址。
|
|
45
|
+
|
|
46
|
+
## 注意
|
|
47
|
+
|
|
48
|
+
- `.wovoon` 不会对外发布,游客也拿不到它的内容。
|
|
49
|
+
- 站点里如果有 `localStorage` 存档,想变跨设备云存档见下一份配方([localStorage → 云存档](localstorage-to-cloud.md))。
|
|
50
|
+
- 不要把 `.env`、`node_modules`、`.git` 打进包(`wovoon validate` 会拦密钥文件;体积超限也会被拒)。
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# 改造配方:TapTap H5 导出游戏 → wovoon 应用
|
|
2
|
+
|
|
3
|
+
> 适用:已有 TapTap H5 版本的游戏(Godot/Unity/Cocos 导出 + TapTap 加载器壳),
|
|
4
|
+
> 目标:不改动游戏本体的前提下在 wovoon 上线。
|
|
5
|
+
|
|
6
|
+
## 包结构特征(识别要点)
|
|
7
|
+
|
|
8
|
+
TapTap H5 导出包通常长这样:
|
|
9
|
+
|
|
10
|
+
```
|
|
11
|
+
/ ← TapTap 加载器壳(index.html 引用 ../static-loader.js,离开 TapTap 必挂)
|
|
12
|
+
/game/index.html ← 真实游戏入口(引擎导出)
|
|
13
|
+
/game/index.js|.wasm|payload/…
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## 改造三步
|
|
17
|
+
|
|
18
|
+
1. **保留 `game/` 目录原样**——不要试图把壳提为入口,也不要移动游戏文件(引擎的相对引用会断)。
|
|
19
|
+
2. **包根写 `.wovoon` 清单并声明真实入口**:
|
|
20
|
+
|
|
21
|
+
```json
|
|
22
|
+
{"protocol":1,"entry":"game/index.html","capabilities":["identity","collection:scores"]}
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
3. **清理镜像残留**(如果包是从旧站点镜像下来的):`__wovoon_runtime__/…`、
|
|
26
|
+
`*.md`、`.DS_Store`、`__MACOSX/` 会被平台静默剔除,不必手动删,但建议保持干净。
|
|
27
|
+
|
|
28
|
+
## 验证
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
npx -y @wovoon/cli validate # 会输出"入口体检"结论:声明生效或自动识别建议
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
不声明 `entry` 也能通过(平台按引用完整度自动选 `game/index.html`),但**多入口结构一律建议显式声明**,
|
|
35
|
+
消除自动识别的歧义空间。托管预检接口(`POST /api/hosting/manifests/preview`)返回
|
|
36
|
+
`entrySource`(manifest=声明生效 / auto=自动识别)与 `indexPath`,供工具自闭环核对。
|
|
37
|
+
|
|
38
|
+
## 云能力接入
|
|
39
|
+
|
|
40
|
+
游戏侧加载 `/api/cloud/sdk.js`(相对当前源,同源直连);Godot 可经
|
|
41
|
+
`JavaScriptBridge` 调用 `WovoonCloud.*`。集合/函数/房间用法见 `../sdk.md`。
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# 改造配方:大游戏瘦身与正确资源打包(网页加载提速)
|
|
2
|
+
|
|
3
|
+
> 适用:包体偏大(>50MB)或加载超过 30 秒的网页游戏;被导出工具转成
|
|
4
|
+
> base64-JS 分片(`static-data/*.wasm.000.js` 这类命名)的游戏必读。
|
|
5
|
+
> 这是 `wovoon validate` "性能提示" 与平台发布扫描 `performanceWarnings` 的修复指引。
|
|
6
|
+
|
|
7
|
+
## 为什么慢:两类根因
|
|
8
|
+
|
|
9
|
+
1. **base64-JS 分片反模式**:部分导出工具(为兼容 `file://` 或不支持 WASM MIME 的静态托管)
|
|
10
|
+
会把 `.wasm`/`.pck` 等二进制切成 `xxx.000.js`、`xxx.001.js` 脚本分片,每片是一段
|
|
11
|
+
base64 字符串。后果:体积膨胀约 33%、浏览器只能逐片下载→解码→拼接(串行)、
|
|
12
|
+
无法流式编译。**wovoon 托管不需要这种兼容层**。
|
|
13
|
+
2. **包体本身大**:引擎未裁剪、纹理未压缩、全量资源打进首包。
|
|
14
|
+
|
|
15
|
+
## 平台已提供的能力(直接用,别再包一层)
|
|
16
|
+
|
|
17
|
+
| 能力 | 说明 |
|
|
18
|
+
|---|---|
|
|
19
|
+
| `.wasm` 正确 MIME | `application/wasm`,满足 `WebAssembly.instantiateStreaming` 的硬前提 |
|
|
20
|
+
| Range 分段 | 非 HTML 资产支持 `Accept-Ranges: bytes`,可并行分段下载 |
|
|
21
|
+
| Brotli 边缘压缩 | CDN 对 js/wasm/pck 等自动 br 压缩(实测约减 60%),源站无需预压缩 |
|
|
22
|
+
| 长缓存 | 资产按部署不可变缓存(浏览器 1 年 + CDN 边缘),同部署重复访问免下载 |
|
|
23
|
+
|
|
24
|
+
## 改造步骤
|
|
25
|
+
|
|
26
|
+
### 第一步:还原原始二进制(去 base64-JS 分片)
|
|
27
|
+
|
|
28
|
+
以 Godot 导出为例,直接使用导出产物里的原始文件:
|
|
29
|
+
|
|
30
|
+
```
|
|
31
|
+
/index.html 引用 index.js
|
|
32
|
+
/index.js 引擎胶水代码(原样保留)
|
|
33
|
+
/index.wasm 引擎二进制(原始文件,不要转 JS 分片)
|
|
34
|
+
/index.pck 游戏资源包(原始文件)
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
若手上只有分片版(如 TapTap H5 包的 `static-data/` 目录):从 Godot 重新导出
|
|
38
|
+
"Web (Runnable)" 产物,或用分片清单(`static-loader.js` 内的 `resources` 表,含
|
|
39
|
+
size 与 sha256)拼回原始二进制后按上表放置。TapTap 壳结构的入口处理见
|
|
40
|
+
[taptap-h5.md](./taptap-h5.md)。
|
|
41
|
+
|
|
42
|
+
### 第二步:加载器姿势(自写加载逻辑时)
|
|
43
|
+
|
|
44
|
+
```js
|
|
45
|
+
// 并行下载 + 流式编译:不要 for-await 逐个 <script> 串行加载
|
|
46
|
+
const [wasmResponse, pckResponse] = await Promise.all([
|
|
47
|
+
fetch("index.wasm"), // 同源相对路径,凭据自动携带
|
|
48
|
+
fetch("index.pck"),
|
|
49
|
+
]);
|
|
50
|
+
const module = await WebAssembly.instantiateStreaming(wasmResponse, importObject);
|
|
51
|
+
// pck 交给引擎挂载(Godot: Engine 的 onExecute / pck 数据入口)
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
要点:
|
|
55
|
+
- 多个大文件用 `Promise.all` 并行;HTTP/2 下同源并发无需分域名。
|
|
56
|
+
- wasm 用 `instantiateStreaming`(边下载边编译);平台 MIME 已保证可用。
|
|
57
|
+
- 加载进度直接用 response body reader 统计字节数,给用户真实进度条。
|
|
58
|
+
|
|
59
|
+
### 第三步:首包拆分(包 >30MB 时)
|
|
60
|
+
|
|
61
|
+
- 首包只放:入口 HTML + 引擎 + 开场资源,控制在 **1~3MB**;
|
|
62
|
+
- 其余按场景/关卡分包,进入对应场景时再 fetch;
|
|
63
|
+
- Godot:导出时勾选分离资源或手动拆 `.pck`;Unity WebGL:AssetBundle 按场景切;
|
|
64
|
+
- 音频 wav → mp3/opus;纹理用引擎压缩格式(ETC2/ASTC/Basis)。
|
|
65
|
+
|
|
66
|
+
## 验证
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
npx -y @wovoon/cli validate
|
|
70
|
+
# 通过时关注 "性能提示" 行:
|
|
71
|
+
# - 出现 "base64-JS 分片" 提示 → 第一步没做完
|
|
72
|
+
# - 出现 "包体 XX MB 偏大" 提示 → 继续第三步
|
|
73
|
+
# 两者都是 WARN,不阻断发布;发布后平台扫描报告(packageContentAudit.performanceWarnings)同文案提示
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
完成标准:validate 无性能提示,或包体确实无法再减且已知会慢(详情页会按包体
|
|
77
|
+
标注 "建议 Wi-Fi 环境" 给玩家预期)。
|
package/docs/sdk.md
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
# 云能力 SDK(协议 1)
|
|
2
|
+
|
|
3
|
+
两种形态,同一套能力 API:
|
|
4
|
+
|
|
5
|
+
| 形态 | 引入方式 | 适合 |
|
|
6
|
+
|---|---|---|
|
|
7
|
+
| **平台下发版** `WovoonCloud` | `<script src="/api/cloud/sdk.js"></script>` | 页面/模板/零构建项目(推荐起步) |
|
|
8
|
+
| **TypeScript 客户端** `@wovoon/polaris` | `npm i @wovoon/polaris` | 有构建管线的项目、Node 侧脚本 |
|
|
9
|
+
|
|
10
|
+
两个版本都只依赖 `fetch`,凭据模式 `credentials: 'include'`(平台运行域同源,无需额外配置)。
|
|
11
|
+
|
|
12
|
+
## 平台下发版:`WovoonCloud`
|
|
13
|
+
|
|
14
|
+
```html
|
|
15
|
+
<script src="/api/cloud/sdk.js"></script>
|
|
16
|
+
<script>
|
|
17
|
+
// 1) 会话(identity 能力)
|
|
18
|
+
const session = await WovoonCloud.ready();
|
|
19
|
+
// => { appId, playerId, loggedIn, displayName, avatarUrl }
|
|
20
|
+
|
|
21
|
+
// 2) 集合(collection:<name> 能力)
|
|
22
|
+
const scores = WovoonCloud.collection('scores');
|
|
23
|
+
await scores.add({ score: 42, name: '玩家' }); // 新增文档(需登录)
|
|
24
|
+
const top = await scores.query({ orderBy: 'score', // 按数值字段降序
|
|
25
|
+
order: 'desc', limit: 5 });
|
|
26
|
+
const mine = await scores.query({ ownerOnly: true, limit: 1 });
|
|
27
|
+
await scores.set(mine[0].id, { score: 99 }); // 整体替换自己的文档
|
|
28
|
+
await scores.remove(mine[0].id); // 删除自己的文档
|
|
29
|
+
const one = await scores.get(docId); // 按 id 读取
|
|
30
|
+
</script>
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
- 作品识别:SDK 从运行地址 `/api/public/static/{deploymentId}/` 自动识别;脱离平台运行时需 `WovoonCloud.configure({ deploymentId })`。
|
|
34
|
+
- 全局别名:`WovoonCloud` 与 `WovoonPolaris` 指向同一对象。
|
|
35
|
+
- 文档 `data` 字段是 **JSON 字符串**(协议传输形态),业务侧自行 `JSON.parse`;`@wovoon/polaris` 的 `parseData()` 帮你做了。
|
|
36
|
+
|
|
37
|
+
### TypeScript 客户端:`@wovoon/polaris`
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
import { PolarisClient, parseData } from "@wovoon/polaris";
|
|
41
|
+
|
|
42
|
+
const polaris = new PolarisClient(); // 浏览器:同源自动识别
|
|
43
|
+
const session = await polaris.ready();
|
|
44
|
+
const scores = polaris.collection("scores");
|
|
45
|
+
await scores.add({ score: 42 });
|
|
46
|
+
const docs = await scores.query({ orderBy: "score", order: "desc", limit: 10 });
|
|
47
|
+
const rows = docs.map(d => parseData(d)); // data 字符串 → 对象
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
类型定义(`WovoonManifest`/`WovoonSession`/`WovoonDocument`/`WovoonQueryOptions`)与协议逐字对应,是协议的机器可读正典之一。
|
|
51
|
+
|
|
52
|
+
## 语义与限制
|
|
53
|
+
|
|
54
|
+
| 主题 | 规则 |
|
|
55
|
+
|---|---|
|
|
56
|
+
| playerId | "账号 × 作品"稳定(同账号同作品恒定,跨作品不可关联);未登录为游客态 |
|
|
57
|
+
| 游客 | 可读 WORLD 集合;**不可写**(`登录后才能写入云数据`) |
|
|
58
|
+
| 权限 | 读 `WORLD`(默认,任何人)/ `PLAYER`(仅登录);写 `OWNER`(默认,本人文档)/ `SERVER`(云函数,M3) |
|
|
59
|
+
| 配额 | 每作品 8 个集合;每集合 10,000 条文档;单文档 64 KB;查询 limit ≤ 100(默认 20) |
|
|
60
|
+
| 排序 | `orderBy` 按文档**数值字段**应用层排序(`order: 'asc'|'desc'`),排行榜场景 |
|
|
61
|
+
| 文档形态 | JSON 对象(不能是数组/标量);`id`/`seq`/`createdAt`/`updatedAt` 平台维护 |
|
|
62
|
+
| 能力门禁 | 每次调用比对 `.wovoon` 声明,未声明即拒绝并附修复指引(见 [errors.md](errors.md#cloud)) |
|
|
63
|
+
|
|
64
|
+
## 查询过滤(where)
|
|
65
|
+
|
|
66
|
+
```js
|
|
67
|
+
// 范围:score 在 100~500 之间且 level 不等于 3
|
|
68
|
+
const docs = await scores.query({
|
|
69
|
+
where: { score: { gte: 100, lte: 500 }, level: { ne: 3 } },
|
|
70
|
+
orderBy: 'score', order: 'desc', limit: 20,
|
|
71
|
+
});
|
|
72
|
+
// 等值 / 集合
|
|
73
|
+
scores.query({ where: { status: 'active', role: ['admin', 'op'] } });
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## 嵌入连接(join,v0.3.0+)
|
|
77
|
+
|
|
78
|
+
查询主集合时声明 `join`,服务端批量取关联集合并拼装进文档返回(每次最多 2 个):
|
|
79
|
+
|
|
80
|
+
```js
|
|
81
|
+
// 多值反向连接:每个帖子嵌入它的全部评论(数组,按插入序,每侧 ≤200 条)
|
|
82
|
+
posts.query({ limit: 10, join: { comments: ['comments', 'postId'] } });
|
|
83
|
+
// 单值正向连接:每张订单卡嵌入所属用户(对象;无关联或不可见时为 null)
|
|
84
|
+
orders.query({ limit: 10, join: { user: 'users.userId' } });
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
- 单值 `"集合.字段"`:主文档该**字段的值** = 目标集合文档 id → 嵌入拍平对象或 `null`;
|
|
88
|
+
- 多值 `["集合", "字段"]`:目标集合该字段的值 = 主文档 id → 嵌入数组;
|
|
89
|
+
- 嵌入形态 = 目标文档数据字段拍平 + `id`/`ownerPlayerId`/`seq`/`createdAt`/`updatedAt` 平台字段(同名时平台字段优先);
|
|
90
|
+
- 被连接集合必须同样在 `.wovoon` 的 capabilities 中声明;玩家面对 PLAYER 读规则的目标集合逐文档过滤(只见自己的);
|
|
91
|
+
- `join` 只做嵌入,不改变主查询的 where/orderBy/limit;要对连接结果过滤/聚合,用云函数组合多个查询。
|
|
92
|
+
|
|
93
|
+
云函数里同样可用:`context.cloud.collection('teams').query({ join: { members: ['cards', 'teamId'] } })`。
|
|
94
|
+
|
|
95
|
+
## 云函数(function 能力)
|
|
96
|
+
|
|
97
|
+
```js
|
|
98
|
+
const r = await WovoonCloud.call('settle', { score: 99 }); // → 函数返回值(对象)
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
函数源码放在作品包站点根 `functions/settle.js`(详见 PROTOCOL.md);沙箱内 `context.cloud`
|
|
102
|
+
可读写 `writeRule=SERVER` 的集合——防作弊结算的标准姿势:玩家集合存客户端分数,SERVER 集合存服务端结算结果。
|
|
103
|
+
|
|
104
|
+
### 常驻效果:声明即触发(配置写在函数代码里,协议不动)
|
|
105
|
+
|
|
106
|
+
```js
|
|
107
|
+
exports.timeoutMs = 30000; // 长任务档:默认 3s,最长可声明 60s
|
|
108
|
+
exports.cron = '*/5 * * * *'; // 定时触发:五字段 cron(分 时 日 月 周)
|
|
109
|
+
exports.onDocs = ['scores']; // 数据触发:scores 集合任何写入后自动运行
|
|
110
|
+
exports.main = async (event, context) => {
|
|
111
|
+
// event.type === 'cron' | 'doc',常驻后台任务/派生计算在这里做
|
|
112
|
+
};
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
cron 每分钟由平台调度(分钟粒度);onDocs 在事务提交后异步触发、不阻塞写请求。
|
|
116
|
+
|
|
117
|
+
## 房间实时通道(room 能力)
|
|
118
|
+
|
|
119
|
+
```js
|
|
120
|
+
const room = WovoonCloud.room('lobby');
|
|
121
|
+
room.onPresence(f => console.log(f.type, f.playerId)); // joined/join/leave
|
|
122
|
+
room.onMessage(m => console.log(m.from, m.data)); // {from, data}
|
|
123
|
+
room.send({ text: '你好' }); // 广播给房内所有人
|
|
124
|
+
room.leave();
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
同源 WebSocket,凭运行会话鉴权;房间 256 人、消息 4KB、300 帧/30 秒。
|
|
128
|
+
|
|
129
|
+
**在线状态按玩家(playerId)计**:join/leave 广播只在"新玩家进房 / 玩家最后一条连接离开"时
|
|
130
|
+
发出,同一玩家开多条连接不会重复计人。做"重连房间"按钮时**直接再调一次
|
|
131
|
+
`WovoonCloud.room(roomId)`**——SDK(≥0.4.0)会自动断开同房号的旧连接;不要绕过 SDK 自建
|
|
132
|
+
WebSocket,也不要保留旧 handle 不关(连接数有上限,超限平台会淘汰最旧连接)。
|
|
133
|
+
|
|
134
|
+
## 声明式集合(collections.json,AI 工具推荐路径)
|
|
135
|
+
|
|
136
|
+
作品包站点根放 `collections.json`,发布时平台自动建好集合与权限——AI coding 工具全程只写文件,不需要任何控制台交互:
|
|
137
|
+
|
|
138
|
+
```json
|
|
139
|
+
{
|
|
140
|
+
"scores": { "read": "WORLD", "write": "OWNER" },
|
|
141
|
+
"rankings": { "read": "WORLD", "write": "SERVER" },
|
|
142
|
+
"player_profiles": { "read": "PLAYER", "write": "OWNER" }
|
|
143
|
+
}
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
- 未声明的集合在游戏首次读写时按默认权限(WORLD/OWNER)自动创建;
|
|
147
|
+
- `write: SERVER` 的集合只有云函数能写(防作弊),玩家只读;
|
|
148
|
+
- `wovoon dev` 启动即按声明建好,`wovoon validate` 会预检格式;
|
|
149
|
+
- 发布后仍可在创作者平台「云开发」控制台调整权限或浏览数据。
|
|
150
|
+
|
|
151
|
+
## 云开发控制台(创作者)
|
|
152
|
+
|
|
153
|
+
创作者平台「云开发」页(/cloud)提供微信小程序云开发同类体验:
|
|
154
|
+
|
|
155
|
+
- **集合与数据**:自建集合、切换读(WORLD/PLAYER)写(OWNER/SERVER)权限、数据浏览器(最近 50 条文档);
|
|
156
|
+
- **云函数**:在线编辑代码并**保存即部署**(不重传作品包)、查看函数自描述元数据、测试运行(系统身份)。
|
|
157
|
+
|
|
158
|
+
对应 REST API(创作者登录态):`GET/PUT/DELETE /api/cloud/manage/{app}/functions[/{name}]`、
|
|
159
|
+
`POST .../functions/{name}/test`、`GET .../collections/{name}/docs?limit=`。本地 `wovoon dev` 模拟器提供同形接口。
|
|
160
|
+
|
|
161
|
+
## 本地开发
|
|
162
|
+
|
|
163
|
+
wovoon dev --player 测试玩家
|
|
164
|
+
|
|
165
|
+
本地模拟器与生产共用同一 URL 空间与校验文案,页面代码零改动即可两端运行。
|
package/llms.txt
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# wovoon Polaris
|
|
2
|
+
|
|
3
|
+
> wovoon 是面向创作者的应用平台:静态前端托管 + 大后台云能力(身份/数据集合/云函数/实时房间)。
|
|
4
|
+
> 本站文档面向 AI coding 工具与人类开发者,机器可执行、报错自带修复指引。
|
|
5
|
+
> 协议版本 1。把存量程序改造成 wovoon 应用通常只需要:加一个 `.wovoon` 清单 + 把后端状态迁到云集合。
|
|
6
|
+
|
|
7
|
+
## 必读(按顺序)
|
|
8
|
+
|
|
9
|
+
- [协议正典](PROTOCOL.md): 包契约、运行契约、能力 API 与错误风格的完整定义。改造前先读完这一篇。
|
|
10
|
+
- [快速开始](docs/index.md): 五分钟从零发布一个带云存档与排行榜的应用(init → dev → validate → 上传)。
|
|
11
|
+
- [`.wovoon` 清单规范](docs/manifest.md): 标识文件字段、能力命名、合法示例与全部校验规则。
|
|
12
|
+
- 声明式集合与云函数:包根 `collections.json` 声明集合权限、`functions/*.js` 放云函数——发布全自动,无需控制台。
|
|
13
|
+
- 查询支持 `where` 过滤与 `join` 嵌入连接(单值 `"集合.字段"` / 多值 `["集合","字段"]`,每次 ≤2 个)。
|
|
14
|
+
|
|
15
|
+
- [快速上手(人类与 AI 通用)](docs/quickstart.md): 契约速览 + AI 提示词模板;可单文件分发。
|
|
16
|
+
|
|
17
|
+
## 工具
|
|
18
|
+
|
|
19
|
+
- [wovoon CLI](docs/cli.md): `wovoon init / dev / validate / login / deploy / rollback / versions`;
|
|
20
|
+
本地模拟大后台;生产规则镜像校验;一条命令发布(内置默认图标/视频,非多模态 AI 也可发布;
|
|
21
|
+
每次发版可随时 rollback)。
|
|
22
|
+
- [云能力 SDK](docs/sdk.md): 页面内 `WovoonCloud`(平台同源下发)与 `@wovoon/polaris`(TypeScript 客户端)完整 API。
|
|
23
|
+
|
|
24
|
+
## 改造配方(存量程序 → wovoon)
|
|
25
|
+
|
|
26
|
+
- [静态网站加 manifest](docs/recipes/static-site-add-manifest.md): 零改造上架;声明能力即启用云能力。
|
|
27
|
+
- [localStorage → 云存档](docs/recipes/localstorage-to-cloud.md): 本地存档换成跨设备云集合,附逐行对照。
|
|
28
|
+
- [Express 后端 → wovoon 云能力](docs/recipes/express-to-cloud.md): 路由 → 集合/云函数 的映射策略(云函数为 M3 能力)。
|
|
29
|
+
- [关系型数据 → join 连接](docs/recipes/relational-data.md): 一对多/多对一建模,查询时 join 嵌入拼装(协议 v1 查询能力)。
|
|
30
|
+
- [TapTap H5 导出游戏改造](docs/recipes/taptap-h5.md): 保留 game/ 子目录 + .wovoon 声明 entry 真实入口,零改动上线。
|
|
31
|
+
- [多人竞技游戏(权威房间)](docs/recipes/competitive-games.md): room:competitive 竞技速率档(30Hz/8KB/二进制帧)、gamelogic 权威房间逻辑(roomservers/<mode>.js,服务端权威判定+SERVER集合写入)、集合变更推送 onChange。
|
|
32
|
+
- [大游戏瘦身与资源打包](docs/recipes/web-asset-optimization.md): 去掉 base64-JS 分片(wasm/pck 直接发原始二进制)、fetch 并行 + instantiateStreaming 流式编译、首包拆分;validate "性能提示" 与平台 performanceWarnings 的修复指引。
|
|
33
|
+
|
|
34
|
+
## 排错
|
|
35
|
+
|
|
36
|
+
- [错误目录](docs/errors.md): 所有协议/结构类错误的原文、触发条件与修复步骤,锚点可直接引用。
|
|
37
|
+
|
|
38
|
+
## 约定
|
|
39
|
+
|
|
40
|
+
- 协议字段只加不改不删;空 `.wovoon` 文件等价于 `{"protocol":1}`。
|
|
41
|
+
- 能力命名冻结:`identity` / `function` / `room` / `collection:<名称>`(名称 2-32 位小写字母/数字/下划线)。
|
|
42
|
+
- 一切报错必须"缺什么 + 怎么修";AI 工具遇到未收录错误应以 PROTOCOL.md 为准并向平台反馈。
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wovoon/polaris",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.2",
|
|
4
4
|
"description": "wovoon Polaris SDK——wovoon 大后台云能力客户端(身份/数据集合/云函数/房间实时),协议 1",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -8,11 +8,15 @@
|
|
|
8
8
|
"files": [
|
|
9
9
|
"dist",
|
|
10
10
|
"PROTOCOL.md",
|
|
11
|
-
"README.md"
|
|
11
|
+
"README.md",
|
|
12
|
+
"llms.txt",
|
|
13
|
+
"docs",
|
|
14
|
+
"LICENSE"
|
|
12
15
|
],
|
|
13
16
|
"scripts": {
|
|
14
17
|
"build": "tsc -p tsconfig.json",
|
|
15
|
-
"check": "tsc --noEmit"
|
|
18
|
+
"check": "tsc --noEmit",
|
|
19
|
+
"prepack": "node ../../scripts/package-docs.mjs"
|
|
16
20
|
},
|
|
17
21
|
"keywords": [
|
|
18
22
|
"wovoon",
|
|
@@ -33,5 +37,8 @@
|
|
|
33
37
|
"publishConfig": {
|
|
34
38
|
"access": "public",
|
|
35
39
|
"registry": "https://registry.npmjs.org/"
|
|
40
|
+
},
|
|
41
|
+
"engines": {
|
|
42
|
+
"node": ">=22.13"
|
|
36
43
|
}
|
|
37
|
-
}
|
|
44
|
+
}
|