# Dreamin 联机 SDK 完整参考（llms-full）

适用对象：AI agent 与开发者。目标：让一个纯静态网页游戏（单个 HTML 即可）获得多人联机能力，无需任何后端。

服务端地址：`https://ws.dreamin.cn`（SDK 默认值，通常不需要显式传）
SDK 地址：`https://ai.dreamin.cn/sdk/v1/dreamin.js`（v1 大版本内向后兼容，bug 修复自动生效）

────────────────────────────────────────
1. 架构模型（先理解这个再写代码）
────────────────────────────────────────

- 服务端是**纯中继**：维护房间、转发消息，不做任何游戏判定。游戏逻辑（移动合法性、命中、计分）全部在客户端实现，即"客户端权威"模型。适合休闲/社交/合作类游戏，不要用于有真金白银输赢的竞技场景。
- 房间 key = `work:room`。`work` 是你的作品 slug，不同作品的同名房间完全隔离。
- 房间由第一个进入者创建并成为**房主**；房主退出自动移交给最早进房且仍在线的人。房间空了即销毁（含共享数据）。
- 身份：连接成功即获得临时 `id`（Socket.IO 连接 id）。**断线重连 id 会变**，不要用作存档主键或排行榜身份。

────────────────────────────────────────
2. 引入与初始化
────────────────────────────────────────

在作品 index.html 的 head 里加一个 script 标签，src 写 https://ai.dreamin.cn/sdk/v1/dreamin.js

SDK 依赖 socket.io-client v4：页面已引入则复用，未引入则自动从 jsDelivr 加载，无需手动处理。

```js
const dreamin = await Dreamin.init({
  work: 'my-game',        // 必填。作品 slug：小写字母/数字/连字符，≤63 字符
  nickname: '玩家1',      // 可选。缺省自动生成，≤24 字符
  // server: 'https://ws.dreamin.cn',  // 可选，默认值即线上地址
});
// dreamin.user → { id, nickname }（连接级临时身份）
```

`Dreamin.version` 可读 SDK 版本。

────────────────────────────────────────
3. 房间
────────────────────────────────────────

```js
const room = await dreamin.room.join('lobby');  // 房间名规则同 work
```

join 失败会 reject（`room-full` 房间满 / `bad-work` / `bad-room` 名不合法 / `server-full`），务必 catch 并给用户提示。

```js
room.leave();            // 主动离开（之后可再 join 其他房间）
room.peers();            // [{id, nickname}]，不含自己
room.isHost();           // 自己是否房主
room.hostId();           // 当前房主 id
```

**在场感知**

```js
room.onPeer(({ type, id, nickname }) => {
  // type: 'join' | 'leave'
});
room.onHost((id) => { /* 房主变更 */ });
```

进房时通过 `room.peers()` 拿全量快照，之后用 onPeer 增量维护，不要轮询。

────────────────────────────────────────
4. 状态同步（高频通道，≤30Hz）
────────────────────────────────────────

用于位置、朝向、动画等持续变化的数据。服务端限频 30Hz，**超频的消息被静默丢弃**，建议发送频率 10~20Hz，并在状态没变化时暂停发送。

```js
room.sendState({ pos: [x, y, z], rot, anim: 'walk' });  // 任意可 JSON 序列化数据，≤4KB
room.onState((state, fromId) => {
  // 更新 fromId 对应的远程玩家表现
});
```

远程玩家的渲染建议做插值（lerp），不要直接瞬移到最新坐标。

────────────────────────────────────────
5. 自定义消息（低频通道，≤10Hz）
────────────────────────────────────────

用于离散事件：开枪、开门、回合操作等。超频会收到 `error-msg`（code: `rate-limited`）。

```js
room.send({ type: 'shoot', dir: [0, 1, 0] });   // 广播给房间内其他人
room.sendTo(id, { type: 'trade', item: 3 });    // 定点发给某个人
room.onMessage((data, fromId) => { ... });
```

────────────────────────────────────────
6. 聊天
────────────────────────────────────────

```js
room.chat('你好');                               // 服务端截断到 200 字，限频 2Hz
room.onChat(({ id, nickname, text }) => { ... });
```

────────────────────────────────────────
7. 房间共享数据（仅房主可写）
────────────────────────────────────────

适合对局级状态：比分、回合号、地图种子。KV 结构，key ≤64 字符，value ≤4KB。

```js
room.data.set('score', { a: 3, b: 1 });   // 非房主调用会被拒（error-msg: not-host）
room.data.get('score');                   // 本地缓存，进房即含全量快照
room.onData((key, value) => { ... });     // 他人（房主）写入时触发
```

典型模式：房主当"裁判"，把判定结果写进共享数据，其他人以 onData 为准渲染。**注意：这不是持久存档**，房间空即销毁；需要持久化请等后续 save API。

────────────────────────────────────────
8. 错误处理
────────────────────────────────────────

```js
room.onError(({ code, message }) => { ... });
```

| code | 含义 |
|------|------|
| room-full | 房间已满（上限 20 人） |
| server-full | 服务器房间总数达上限 |
| bad-work / bad-room | 名字不合法 |
| not-host | 非房主写共享数据 |
| rate-limited | message 发送过快 |
| too-large | 单条数据超 4KB |

────────────────────────────────────────
9. 红线（违反会被限流/拒绝，agent 必须遵守）
────────────────────────────────────────

1. 单房间 ≤20 人。需要更多人就自己分房间（如 lobby-1、lobby-2），不要试图绕过。
2. sendState ≤30Hz、单条 ≤4KB；send ≤10Hz。把高频数据全塞 state，把事件塞 message，不要用 message 发位置流。
3. work/room 只用 `a-z 0-9 -`。把用户输入（如玩家自开房间名）先规范化：转小写、非法字符替换为 `-`。
4. 不要把 `dreamin.user.id` 当长期身份；不要往 state/message 里放敏感信息（传输内容对房间内所有人可见）。
5. 共享数据的写入只信 `onData` 回调，本地 `data.set` 是乐观更新——非房主调用不会生效。
6. 断线后 socket 会自动重连，但**房间不会自动恢复**：监听 `dreamin.socket.on('disconnect')` 给提示，重连（`'connect'` 事件）后在**同一个 dreamin 实例**上重新 `room.join(...)`——SDK（≥v0.1.2）会自动清理旧房间的事件监听，不会重复分发；随后一律使用新返回的 room 对象（旧 room 对象及其回调随重进失效）。

────────────────────────────────────────
9.5 不存在的 API（臆造黑名单，写代码前自查）
────────────────────────────────────────

以下写法都是**错误**的（已有多个作品因臆造 API 导致联机完全失败）：

- `DreaminSDK` / `new DreaminSDK()` —— 不存在。正确：`await Dreamin.init({ work, nickname })`
- `dreamin.joinRoom(...)` —— 不存在。正确：`await dreamin.room.join('lobby')`
- `dreamin.getUid()` —— 不存在。正确：`dreamin.user.id`
- 回调式进房 `joinRoom(id, { onJoin, onPlayerJoin, onPlayerLeave, onMessage })` —— 不存在。
  正确：先 `const room = await dreamin.room.join(...)`，再 `room.onPeer / onState / onMessage`
- 直接用 `io(...)` 连 socket.io —— 不需要，SDK 已封装（高级兜底才用 `dreamin.socket`）
- work / room 名含大写字母 —— 服务端拒绝（bad-work / bad-room），只允许 a-z 0-9 -

API 以本文件为准；不确定就查，不要猜。

────────────────────────────────────────
10. 常见玩法配方
────────────────────────────────────────

**多人在线逛场景（参考实现：gs.dreamin.cn 的 3DGS 大厅）**
进房 → onPeer 增删远程玩家化身 → 每 66ms sendState({pos, rot, anim}) → onState 插值渲染 → chat 聊天。

**回合制游戏**
房主作裁判：玩家操作用 send 发给房主（或广播），房主判定后 data.set('turn', ...) 与 data.set('board', ...)，全员以 onData 为准。

**合作 PvE**
怪物位置由房主每帧计算并通过 sendState 以 `{mobs: [...]}` 形式广播（注意 4KB 上限，怪物多时分片或用 message 发增量事件）。

**大厅 + 多房间**
固定房间名规则 `room-1` ~ `room-N`；客户端逐个 join 探测人数（join 成功即 leave 换下一个，或直接用 room-full 错误判断是否满员）。

────────────────────────────────────────
11. 本地开发
────────────────────────────────────────

页面用任意静态服务器跑起来即可（如 `python -m http.server`），SDK 默认连线上 `wss://ws.dreamin.cn`，无需本地起服务端。两个浏览器标签页即是两个玩家。

如需自托管服务端联调：`Dreamin.init({ work, server: 'http://localhost:3002' })`（传了 `server` 时 socket.io 走默认路径 `/socket.io/`；线上地址则自动走 Nginx 分流路径 `/relay/socket.io/`，也可用 `path` 参数显式覆盖）。服务端源码见 dreamin_realtime/server/。

────────────────────────────────────────
12. 发布作品（上传 API）
────────────────────────────────────────

把作品发布到 ai.dreamin.cn，无需 OSS 凭证。Agent 必须先问用户选择哪条路径：

**先问用户：「你想自己到上传页面提交，还是让我一键上传并测试？」**

**路径 A：用户自己提交（zip 由用户手动上传）**
1. 你把作品目录打成 zip（根目录必须含 index.html，资源全部相对路径），告诉用户文件位置。
2. 让用户打开 https://ai.dreamin.cn/upload/ 填写表单提交（提醒：slug 一经确定不要改，
   首次发布成功后页面会显示 updateToken，请用户保存好）。
3. 后续修改：重新打包交给用户，用**同一个 slug** 在同一页面提交；若作品已存在，
   页面会要求填 updateToken。

**路径 A'：单页粘贴（你没有打包/上传能力、或作品就是单个 HTML 文件时）**
如果你的运行环境无法发 HTTP POST、无法打 zip，或者作品是单文件网页：
直接把**完整的单页 HTML 源码**交给用户，让他打开 https://ai.dreamin.cn/upload/ ，
切到「单页 HTML 粘贴」通道，粘贴源码提交即可（无需 zip）。
用户还可以从页面的模板选择器里直接挑一个联机模板改：
https://ai.dreamin.cn/templates/ （鼠标派对 / 抢金币 / 聊天广场，均为完整可玩的
单文件多人游戏，也是学习 SDK 用法的精简范例；模板会持续增加）。

**路径 B：Agent 一键上传 + 测试**
1. **先向用户要一个用户名**（作为作者名 author，显示在首页作品卡片上）。
2. 调 API 上传（见下），保存返回的 slug 与 updateToken——**必须写入项目持久记录**
   （如在项目里创建 `PUBLISH.md` 记录 slug / url / updateToken），否则无法更新。
3. 打开返回的 url 验证：页面能打开、游戏能跑（建议实际测试核心操作）。
4. 后续修改：**必须用同一个 slug、同一条 API 路线**，并在请求里带 `token=<updateToken>`。
   服务端会用新 zip 覆盖并自动清理已删除的旧文件。

**端点**：`POST https://ws.dreamin.cn/upload/`（multipart/form-data，文本字段一律 UTF-8）

| 字段 | 必填 | 说明 |
|------|------|------|
| file | ✓ | 作品 zip：根目录必须含 index.html，资源相对路径 |
| slug | ✓ | 小写字母/数字/连字符 ≤63 字符，全网唯一；**记住它，更新复用** |
| title | ✓ | 作品名 ≤40 字符 |
| author | ✓ | 作者名 ≤24 字符（路径 B：向用户索要的用户名） |
| desc | | 一句话介绍 ≤60 字符 |
| online | | "1" = 用了 Dreamin 联机 SDK（卡片显示「联机」徽章） |
| html | 单页模式 | 完整单页 HTML 源码（≤1MB），与 file 二选一；服务端自动注入回流徽标 |
| token | 更新时必填 | 首次发布返回的 updateToken；缺失或错误返回 403 |

**限制**：zip ≤50MB；≤500 个文件；单文件 ≤20MB；解压总量 ≤100MB；每个 IP 每天 ≤20 次。

**成功返回**：

```json
{ "ok": true, "slug": "my-game",
  "url": "https://ai.dreamin.cn/works/my-game/",
  "cover": "https://ai.dreamin.cn/covers/u-my-game.svg",
  "files": 12, "updated": false,
  "updateToken": "b4c2…（保存好，更新必填）" }
```

**发布后的效果**：作品立即可通过 url 访问；封面与作品信息写入
`https://ai.dreamin.cn/api/works.json`，首页「最新上传」区实时展示。

**示例（curl）**：

```bash
cd 作品目录 && zip -r work.zip .
# 首发
curl -X POST https://ws.dreamin.cn/upload/ \
  -F "file=@work.zip" -F "slug=my-game" \
  -F "title=我的游戏" -F "author=用户名" -F "desc=一句话" -F "online=1"
# 修改后更新（同一 slug + token）
curl -X POST https://ws.dreamin.cn/upload/ \
  -F "file=@work.zip" -F "slug=my-game" \
  -F "title=我的游戏" -F "author=用户名" -F "token=<updateToken>"
```

**注意**：发布即公开，zip 内不要放任何密钥/私密信息；updateToken 是作品的唯一修改凭证，
泄露意味着他人可覆盖你的作品——只保存在项目本地，不要提交到公开仓库。

**回流徽标（约定，必须加）**：作品 index.html 里加一个 script 标签，
src 写 https://ai.dreamin.cn/badge/dreamin-badge.js ——右下角显示
「Made with Dreamin」并链接回首页——你的每个玩家都可能因此成为下一个创作者。

可选：`data-position="bottom-left"` 换角，`data-theme="dark"` 深色底。