Skip to content

玩家上传的图片 ​

玩家的图片用 api.media 保存,和它相关的小段 JSON 用 api.sessionStorage 保存。两样都属于当前这一局,同一个账号在另一台设备上登录也能读到。创作者自己提供的图片还是放在 面板 → 素材 里,用 @asset: 引用来使用。

玩家界面的模板里没有上传用的部件,所以这篇食谱要写界面代码(面板 → 界面代码)。

先想清楚数据放在哪 ​

数据API
玩家图片的文件本身和图库的元数据api.media
选中的图片 ID、有长度限制的笔记,或者别的只属于这个存档的 JSONapi.sessionStorage
只在这个浏览器里用的偏好,和丢了也没关系的缓存api.storage
规则或 AI 要用到的游戏状态声明好的游戏变量

不要把图片的 base64 塞进 JSON、游戏变量或浏览器存储。云端保存需要联网。这一局的图片和世界的导出包是分开的,别承诺导出世界就能把玩家的私人文件一起下载下来。

上传和显示 ​

在组件里先拿到 const api = useYumina()。打开的时候、改动之后,以及临时显示链接过期之前(五分钟),都重新读一遍列表:

tsx
const page = await api.media.list(0);
// page.items contains { id, entryId, metadata, version, url, thumbnailUrl, deleted, ... }.
// Load subsequent pages when page.hasMore is true.

if (!api.readOnly && page.uploadsEnabled) {
  const result = await api.media.pick({
    metadata: { title: "Character portrait" }
  });
  if (result) {
    // result is { mediaId, entryId }; null means the player canceled.
    // Reload the list to obtain its temporary display URL.
  }
}

显示的时候用没被删除的条目的 url 或 thumbnailUrl。文件被彻底删除以后,条目的 URL 可能是 null。请求被拒绝时要接住,留一个错误状态,promise 成功了才显示保存成功。要不要开放上传控件,看 api.readOnly 和 uploadsEnabled。

已经有文件输入框的话,调用 api.media.upload(file, { entryId, uploadId, metadata })。请求失败后,留着选中的 File,重试同一个文件或请求时用同一个 uploadId。千万别一边退回本地存储,一边说已经存到云端了。

保存选中的图片 ​

JSON 里只记一个稳定的条目 ID,显示时再去 media.list() 里找它。url 和 thumbnailUrl 不要存:

tsx
const previous = await api.sessionStorage.get("selected-portrait");
const saved = await api.sessionStorage.set(
  "selected-portrait",
  { entryId: selectedItem.entryId, mediaId: selectedItem.id },
  { expectedVersion: previous.version }
);
// Keep saved.version for later changes.

所有 JSON 方法都返回 { value, version, exists }。读的时候检查 exists。每次 set 和 remove 都必须带 { expectedVersion };要是另一台设备已经改过这条记录,写入会被 SESSION_STORAGE_CONFLICT 拒绝。这时留着草稿,重新读一遍,理清楚了再提交。不要拿着过期的选择盲目重试。

只想清掉选择,就用最新的版本号调用 api.sessionStorage.remove("selected-portrait", { expectedVersion })。想把一张图片从这一局里移走,就调用 api.media.remove(item.entryId, item.version)。这是两个独立的操作;清掉选择不会删除图片。文件的彻底删除在 我的库 → 资源 → 存档图片 里管理,可能会影响别的存档、存档点和分享。

限制和保存下来的副本 ​

  • 图片:静态的 JPEG/PNG/WebP,输入最大 16 MiB,解码后最多 4000 万像素。服务器会生成一张最长边 2048 像素的 WebP 显示图,外加一张缩略图。这不是原文件的备份。图片占用账号现有的素材容量。
  • JSON:每个值序列化成 UTF-8 后最多 32 KiB;每一局当前值合计 256 KiB、最多 128 个键(含删除标记)、值的历史最多 16 MiB;同一个所有者的全部会话每小时最多 1,000 次修改。
  • 恢复存档点时如果改动了 JSON,也受这些限制。容量超限返回 HTTP 413,每小时次数超限返回 429;整个恢复会回滚,图片和剧情状态也一起回滚。历史会保留。恢复时值没变的话,不会重复写历史,就算已经到了这些 JSON 上限也照样能恢复。
  • 存档点、同账号的分支和分享快照会把 JSON 和图片引用一起记下来。恢复存档点时两样一起恢复。分享只保留创建那一刻的快照,之后新增的私人内容不会进去。
  • 分享回放是只读的,沿用现有的可见性、世界的发布状态、隐藏或审核状态,以及内容分级规则。分享者和卡的创作者是快照的特权读者,隐藏、未发布或敏感的快照也能看;别的查看者要通过相应的检查。不公开列出的分享可以通过链接访问。这不会让创作者看到所有者私人的实时会话数据,那些还是只有所有者能看。

已有的浏览器图库 ​

兼容适配器能在任何世界里识别通过校验的现行 Oncin v2/v3/v4 和 gallery_data 格式。迁移要在存着原图的那个浏览器里进行,旧数据会保留。它不会去猜损坏或含糊的日志和备份,不会从另一台设备的浏览器里找回数据,不会抓取远程 URL,也不会自动转换任意 localStorage 键。

新卡请直接用上面这些明确的 SDK API。其他旧格式的话,在上传和云端保存都确认成功之前,保留本地的原件。

验证接入 ​

  1. 上传一张小的、受支持的图片,等确认成功后重新加载这一局。
  2. 用同一个账号在另一台设备上打开这一局,确认图片和选择都在。
  3. 保存一个存档点,换一个选择,再恢复存档点;确认图片引用和 JSON 一起回来了。
  4. 创建一个同账号的分支和一个分享快照;检查它们记下来的状态,以及回放是不是只读。
  5. 试一遍取消选择、上传失败、容量超限,还有另一台设备改动 JSON 造成的冲突。要留着草稿,并把失败显示出来。

方法签名见 API 参考。给 AI 看图片是另一个功能,走聊天附件;在界面上显示一张图片,不会把它的像素发给模型。