Dreamin 联机 SDK

给静态网页游戏接入多人联机 —— 进房、状态同步、自定义消息、聊天、房间共享数据，无需自建后端。

SDK: ai.dreamin.cn/sdk/v1/dreamin.js 服务端: wss://ws.dreamin.cn

给 AI 用 🤖

开发前先让 agent 读 llms.txt（索引）与 llms-full.txt（完整参考与红线）。把下面这段引导词复制给你的 agent 即可：

我要做一个网页多人游戏，部署为纯静态页面。联机功能使用 Dreamin 联机 SDK：
先完整阅读 https://ai.dreamin.cn/dev/llms.txt 和 https://ai.dreamin.cn/dev/llms-full.txt ，
严格遵守其中的频率/大小/房间人数红线，然后帮我实现游戏。

30 秒上手

SDK 会自动加载 socket.io-client，一个 script 标签即可：

<script src="https://ai.dreamin.cn/sdk/v1/dreamin.js"></script>
<script>
  // 1. 初始化（work 是你的作品 slug，小写字母/数字/连字符）
  const dreamin = await Dreamin.init({ work: 'my-game', nickname: '玩家1' });

  // 2. 进房（房间自动创建，先进房者是房主）
  const room = await dreamin.room.join('lobby');

  // 3. 状态同步（高频通道，≤30Hz，适合位置/动画）
  room.onState((state, fromId) => updateRemotePlayer(fromId, state));
  setInterval(() => room.sendState({ pos: [x, y, z], rot }), 66); // ~15Hz

  // 4. 自定义消息（低频通道，≤10Hz，适合动作事件）
  room.onMessage((data, fromId) => console.log(data));
  room.send({ type: 'shoot' });            // 广播
  room.sendTo(someId, { type: 'trade' });  // 定点

  // 5. 聊天
  room.onChat(({ nickname, text }) => addChatLine(nickname, text));
  room.chat('大家好');

  // 6. 房间共享数据（仅房主可写，适合比分/回合）
  room.data.set('score', { a: 3, b: 1 });
  room.onData((key, value) => renderScore(value));
</script>

架构模型

服务端是纯中继：维护房间、转发消息，不做游戏判定。游戏逻辑全部在客户端（客户端权威），适合休闲/社交/合作类游戏。
房间：key 为 作品slug:房间名，不同作品完全隔离。房间自动创建，先进房者是房主；房主退出自动移交给最早进房者；空房即销毁。
身份：连接级临时 id，断线重连会变，不要用作存档主键。重连后需重新 room.join。

API 速查

API	说明
`await Dreamin.init({work, nickname?})`	连接服务端，返回 `{user, room, socket}`
`await dreamin.room.join(name)`	进房，失败 reject（room-full 等）
`room.peers() / isHost() / hostId()`	在场成员快照 / 房主判断
`room.onPeer(({type,id,nickname}))`	成员进出（'join' \| 'leave'）
`room.onHost((id))`	房主变更
`room.sendState(state)` / `onState(fn)`	高频状态通道（≤30Hz，≤4KB）
`room.send(data)` / `sendTo(id,data)` / `onMessage(fn)`	低频消息通道（≤10Hz，≤4KB）
`room.chat(text)` / `onChat(fn)`	聊天（200 字，2Hz）
`room.data.set/get` / `onData(fn)`	房间共享数据（仅房主可写）
`room.onError(fn)`	业务错误（room-full / not-host / rate-limited / too-large）
`room.leave()`	离开当前房间

红线

限制	值	超限后果
单房间人数	20	join 被拒（room-full）
sendState 频率 / 大小	30Hz / 4KB	静默丢弃 / too-large
send 频率 / 大小	10Hz / 4KB	rate-limited / too-large
聊天	200 字 / 2Hz	截断 / 丢弃
work、room 命名	`a-z 0-9 -`，≤63 字符	bad-work / bad-room
共享数据	仅房主写，key ≤64 字符，value ≤4KB	not-host / too-large

共享数据随空房销毁，不是持久存档；传输内容对房间内所有人可见，不要放敏感信息。需要更多人同场就自己分房间（room-1、room-2……）。

常见玩法配方

多人逛场景：onPeer 增删远程化身 → 每 66ms sendState({pos,rot,anim}) → onState 插值渲染（不要瞬移）。
回合制：房主当裁判，玩家操作 send 给房主，房主判定后 data.set('board', …)，全员以 onData 为准。
合作 PvE：怪物状态由房主计算并广播；量大时分片或用 message 发增量事件。
大厅分房：固定 room-1 ~ room-N，遇到 room-full 就试下一个。

本地开发

页面用任意静态服务器运行（如 python -m http.server），SDK 默认连线上 wss://ws.dreamin.cn。开两个浏览器标签页就是两个玩家。

发布作品（上传 API）

两条路径任选：

用户自己提交：打开 /upload/ 页面填表（支持 zip 打包或单页 HTML 直接粘贴——后者适合 AI 生成的单文件游戏，无需打包；页面还内置了可改的单页联机模板，见 /templates/）。首次发布成功后会显示 updateToken，请保存好。
Agent 一键上传 + 测试：先向用户要一个用户名（作者名），调 API 上传，保存 slug 与 updateToken，然后打开网址实际测试。

如果你的 Agent 环境无法打包或发 HTTP POST：让它把完整单页 HTML 源码交给你，你自己到上传页的「单页 HTML 粘贴」通道提交即可。Agent 也可走 API 的 html 字段直接提交源码。

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（服务端覆盖并自动清理旧文件）
curl -X POST https://ws.dreamin.cn/upload/ \
  -F "file=@work.zip" -F "slug=my-game" \
  -F "title=我的游戏" -F "author=用户名" -F "token=<updateToken>"

记住 slug 与 updateToken：建议写入项目的 PUBLISH.md。后续修改必须复用同一 slug 走同一路线；updateToken 是作品的唯一修改凭证，泄露意味着他人可覆盖你的作品。

限制	值
slug 规则	小写字母/数字/连字符 ≤63 字符，全网唯一（更新需 updateToken，否则 403）
zip 大小	≤50MB，≤500 个文件，单文件 ≤20MB，解压总量 ≤100MB
频率	每个 IP 每天 ≤200 次
字段编码	文本字段一律 UTF-8

发布即公开：zip 内不要放任何密钥或私密信息。

回流徽标（约定）

发布的作品请在 index.html 加一行，右下角会显示「Made with Dreamin」并链接回首页——你的每个玩家都可能因此成为下一个创作者：

<script src="https://ai.dreamin.cn/badge/dreamin-badge.js"></script>

可选配置：data-position="bottom-left"（换角）、data-theme="dark"（深色底）。