Studio Player Storage

为 mod 提供的云端玩家数据存储服务。你的 mod 可以用它替玩家保存配置、进度等数据，也可以发布所有玩家都能读到的公共数据。

服务地址：https://storage.bondage-studio.org

认证

除公共数据的读取外，所有请求都需要认证。游戏内装入 studio-oauth 后，全局会暴露 studioOauth 对象，用它生成 Authorization 头：

const res = await fetch('https://storage.bondage-studio.org/player/data/settings', {
  headers: { authorization: await studioOauth.header('https://storage.bondage-studio.org') },
});

每次发请求时调用一次 studioOauth.header() 即可，不要保存返回结果。服务会根据令牌识别玩家身份，数据自动按玩家隔离，你不需要（也无法）指定操作哪个玩家的私有数据。

私有数据

每个玩家自己的空间，只有本人能读写。

操作	请求
读取	GET /player/data/<key>
写入	PUT /player/data/<key>
删除	DELETE /player/data/<key>
列出全部 key	GET /player/data

await fetch('https://storage.bondage-studio.org/player/data/settings', {
  method: 'PUT',
  headers: { authorization: await studioOauth.header('https://storage.bondage-studio.org') },
  body: JSON.stringify({ volume: 0.8 }),
});

const res = await fetch('https://storage.bondage-studio.org/player/data/settings', {
  headers: { authorization: await studioOauth.header('https://storage.bondage-studio.org') },
});
const settings = JSON.parse(await res.text());

公共数据

想让自己的数据被其他玩家读到时，用公共空间。写入仍需认证（只能写自己的空间），读取无需认证，通过玩家 ID 访问：

操作	请求	需要认证
写入	PUT /public/data/<key>	是
删除	DELETE /public/data/<key>	是
读取某玩家的数据	GET /public/data/<ownerId>/<key>	否
列出某玩家的公共 key	GET /public/data/<ownerId>	否

例如读取玩家 12345 发布的 profile：GET /public/data/12345/profile

规则与限制

• key：1–256 个字符，只能包含字母、数字和 . _ - / :，且必须以字母或数字开头。可以用 / 组织层级，如 dungeon/save-1。
• value：请求体原样存储，单个最大 10 MiB。存什么格式由你决定，通常用 JSON。
• 列出：每页最多 1000 个 key，响应里的 cursor 不为 null 时，带上它再请求一次即可翻页。

错误

出错时返回 JSON：

{ "ok": false, "error": { "code": "key_not_found", "message": "该 key 不存在" } }

常见 code：invalid_key（key 不合法）、key_not_found（404）、value_too_large（413）、quota_exceeded（507，超出配额）、rate_limited（429，请求过于频繁）、missing_authorization（400，缺少认证头）、expired / bad_signature 等（401，认证问题）。