# Dreamin 联机 SDK

> ai.dreamin.cn 为静态网页游戏提供的实时联机基础设施。一行 script 引入，无需自建后端：进房、状态同步、自定义消息、聊天、房间共享数据。服务端是纯中继，游戏逻辑全部在客户端实现。

## 必读

- [SDK 完整参考（llms-full）](https://ai.dreamin.cn/dev/llms-full.txt): API 全集、协议细节、红线限制，开发前完整阅读
- [SDK 本体 dreamin.js](https://ai.dreamin.cn/sdk/v1/dreamin.js): 浏览器直接引入，自动加载 socket.io-client
- [开发文档（人类可读版）](https://ai.dreamin.cn/dev/): 与 llms-full 内容一致的可视化页面

## 最小示例

在 HTML 里用一个 script 标签引入上面的 SDK 地址（SDK 会自动加载 socket.io-client），然后：

```js
const dreamin = await Dreamin.init({ work: 'my-game', nickname: '玩家1' });
const room = await dreamin.room.join('lobby');
room.onState((state, fromId) => updateRemotePlayer(fromId, state));
setInterval(() => room.sendState({ pos: [x, y, z], rot }), 66); // ~15Hz
```

## 关键约束（红线）

- 房间人数上限 20；state ≤30Hz 且 ≤4KB；message ≤10Hz 且 ≤4KB；聊天 200 字且 ≤2Hz
- 身份是连接级临时 id，断线重连会变，不可作存档主键
- work / room 名仅允许小写字母、数字、连字符，≤63 字符
- 房间共享数据仅房主可写；空房后数据销毁，不是持久存档
- 断线重连后房间不自动恢复：在同一个 dreamin 实例上重新 `room.join(...)` 即可
  （SDK 会清理旧房间监听），并使用新返回的 room 对象

## 发布作品（上传 API）

Agent 先问用户选路径：**A. 用户自己到 https://ai.dreamin.cn/upload/ 提交 zip**，
还是 **B. Agent 一键上传并测试**（需先向用户要一个用户名作为作者名）。

```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"   # 用了 Dreamin 联机 SDK 才带，卡片显示「联机」徽章
# 返回 {"ok":true,"url":"https://ai.dreamin.cn/works/my-game/","updateToken":"...", ...}
```

**记住 slug 与 updateToken**（写入项目持久记录如 PUBLISH.md）：后续修改必须复用
同一 slug 走同一 API 路线，并带 `-F "token=<updateToken>"`（覆盖更新并自动清理旧文件）。

**没有打包/上传能力、或作品是单个 HTML？** 把完整单页源码交给用户，到
https://ai.dreamin.cn/upload/ 的「单页 HTML 粘贴」通道提交（也可用 API 的 `html` 字段）。
单页联机模板参考：https://ai.dreamin.cn/templates/ （鼠标派对/抢金币/聊天广场，持续增加）。

约束：slug 小写字母/数字/连字符且全网唯一；zip ≤50MB、≤500 个文件、
单文件 ≤20MB；每个 IP 每天 ≤20 次。详见 llms-full.txt 第 12 节。

**回流徽标（必须加）**：作品 index.html 里加一个 script 标签，
src 写 https://ai.dreamin.cn/badge/dreamin-badge.js ，
右下角显示 Made with Dreamin 链接回首页。