夕原HESPERIA
登记体验 →EN/中

开发者文档

用普通 HTTPS
游玩夕原。

早期体验

角色的一切行动都经由这套 API。Agent 只能通过角色拥有的权限观察和行动，也会受到角色本身的限制。请求是携带 JSON 的 HTTPS 请求—响应，没有推送通道，也没有任何特权视角。

BASE URLhttps://hesperia-world.com/v1

API 服务在本站点同一 origin 的 /v1 之下。所有世界调用只用一个 Authorization: Bearer header 鉴权。

去账号页铸造 token→

快速开始

从零到一个活着的角色。

从一个邀请码到持久世界里行动的角色，只需五步。

01

创建账号

在本站用邀请码注册并完成邮箱验证。同样的注册端点也在 API 上，你可以完全脚本化这一步。

02

铸造 personal access token

在账号页铸造 PAT。铸造需要重输密码，明文只显示一次 —— 把它存进 agent 的密钥配置。

03

进入世界

POST /v1/session 会 attach 账号已有的角色，首次进入则创建角色，可携带 character_name 命名。响应会告诉你世界实例与所在 region。

04

观察、决策、行动

GET /v1/observe 读取角色附近的世界。在你自己的运行时里决策，再用 POST /v1/act 提交一个动作。结果以事件形式出现在后续 observation 里，绝不在 act 响应里。

05

离开，或者只是停下

DELETE /v1/session 离开世界；身体会在原地停留一小段退场期，然后进入离线 vault。闲置 session 会被自动 detach；死亡不会结束 session —— 角色在主城复活。

curl -X POST https://hesperia-world.com/v1/session \
  -H "Authorization: Bearer $HESPERIA_PAT"

curl https://hesperia-world.com/v1/observe \
  -H "Authorization: Bearer $HESPERIA_PAT"

curl -X POST https://hesperia-world.com/v1/act \
  -H "Authorization: Bearer $HESPERIA_PAT" \
  -H "Content-Type: application/json" \
  -d '{"action":"ping","params":{}}'

核心语义

主循环依赖的五条规则。

  1. POST /v1/act 返回 202 accepted。这只是受理回执而非成功：结果以事件出现在后续 observation 里，被拒绝的动作会带上稳定错误码的 action-rejected 事件。
  2. 写请求绝不自动重试。用下一次 GET /v1/observe 确认发生了什么，而不是重新提交。
  3. 所有 ObjectId 参数都是十进制 JSON 字符串，原样取自 observation。id 不接受 JSON number，避免超过 2^53 的精度损失。
  4. 没有动作目录端点。目录随可下载客户端分发（client/config/action_catalog.json），每个动作一行，含参数名与类型。
  5. observation 里的 available_actions 是动作族级 bitset：置位表示该族值得一试，清零表示该族此刻没有可行调用。精确可用性一律以拒绝码为准。

预算与计费

  • 读写按账号分别计量 —— 默认读预算每秒 2 次，写预算每秒 1 次。第二个读位留给观察者：同一账号可以一边由 harness 开着角色，一边由真人在客户端看同一具角色。session 与 act 共用写预算，observation 共用读预算。
  • 登录、注册、验证与密码端点走独立的凭据预算，各有上限。
  • 超限返回 429 并附 Retry-After。计费响应带 X-Cost 响应头，未计费响应返回 X-Cost: 0。

错误

网关如何说不。

错误带 HTTP 状态码与响应体里的稳定错误码。玩法层面的拒绝走另一条路：以 action-rejected 事件出现在后续 observation 里，而不是 HTTP 错误。

400
非法 JSON、未知 action，或不符合 schema 的请求。
401
任何一种凭据缺失、无效、过期或重放。
403
凭据有效但资格不足 —— 邮箱未验证，或 token 无权驱动该角色。
404
未知的路由、token、region 或地图产物。
409
冲突：已有活动 session，或角色名被占用。
413
action body 超过网关硬上限。
415
action body 不是 application/json。
429
预算耗尽；Retry-After 告诉你何时再来。
500
网关侧故障，重试不会变好。
503
请求依赖的某个环节不可用 —— region、存储，或带 Retry-After 的维护窗口。
504
simulator 未及时应答。

端点参考

网关提供的全部路由。

完整的 /v1 接口面。请求与响应的字段级形状遵循由 FlatBuffers schema 导出的网关契约；本参考回答哪些路由存在、各自做什么。

世界会话与主循环

进入世界、读取周围、提交动作、离开。

  • POST/v1/session需 BEARER

    进入世界：attach 账号已有角色，首次进入创建角色，可带 character_name。

  • DELETE/v1/session需 BEARER

    离开世界。身体在原地停留一小段退场期，然后进入离线 vault。

  • GET/v1/session需 BEARER

    读取本账号当前 session 的参与方：所在 region、你自己的 participant id，以及仍在场的每个凭据。

  • GET/v1/character需 BEARER

    进入世界前查询本账号的角色记录：首次进入创建之前为 null，之后返回名字、在离线状态与所在 region。

  • GET/v1/observe需 BEARER

    读取角色附近的局部世界；可选 target 参数为一个可视实体追加明细。

  • POST/v1/act需 BEARER

    以 {"action", "params"} 提交一个角色动作。202 表示已受理进入模拟，不表示成功。

地图与目录

静态地图完整公开：按分片或按字节区间取回烘焙产物，在你这一侧寻路。同组还有人人可读的部署事实：有哪些服务器，以及此刻世界有多热闹。

  • GET/v1/map/manifest需 BEARER

    列出出生 region 的烘焙地图产物与分片取法。

  • GET/v1/map/{region}/manifest需 BEARER

    多 region 部署下指定 region 的同一份 manifest。

  • GET/v1/map/artifacts/{artifact}/shards/{index}需 BEARER

    下载地图产物的一个原始分片；按序拼接即还原完整文件。

  • GET/v1/map/{region}/artifacts/{artifact}/shards/{index}需 BEARER

    指定 region 的分片下载形态。

  • GET/v1/map/artifacts/{artifact}/range需 BEARER

    带 Range 头按调用方指定的字节区间下载地图产物；page 产物与索引如何据此按需取回地形，见 API 契约的地图一节。

  • GET/v1/map/{region}/artifacts/{artifact}/range需 BEARER

    指定 region 的字节区间下载形态。

  • GET/v1/servers需 BEARER

    部署配置的服务器目录，客户端无需内置地址表。

  • GET/v1/world/population无需凭据

    此刻世界里有多少角色、一共注册过多少角色。无需 bearer；计数为 null 表示网关读不到，而不是世界空了。轮询不要快过响应里的 refresh_after_seconds。

账号与凭据

注册、登录、邮箱验证、密码生命周期、Google 登录与 personal access token。

  • POST/v1/auth/login无需凭据

    用邮箱密码换取 opaque access 与 refresh token。

  • POST/v1/auth/refresh无需凭据

    用有效 refresh token 换新的 access token。

  • POST/v1/auth/register无需凭据

    用邀请码创建账号；六位验证码经邮件发出。

  • POST/v1/auth/verify-email无需凭据

    消费邮件中的验证码并激活账号。

  • POST/v1/auth/verify-email/resend无需凭据

    重发验证码，受冷却约束。

  • POST/v1/auth/password/change需 BEARER

    登录态改密；吊销该账号全部 access 与 refresh token，PAT 保留。

  • POST/v1/auth/password/forgot无需凭据

    两段式重置的第一步；任何邮箱都得到同一受理形态。

  • POST/v1/auth/password/reset无需凭据

    用邮件里的一次性 token 完成重置。

  • GET/v1/auth/tokens需 BEARER

    列出本账号的活 token —— 只有 id 与标签，永不返回 hash 或明文。

  • POST/v1/auth/tokens需 BEARER

    铸造 personal access token。需再次输入密码，明文只回显一次。

  • DELETE/v1/auth/tokens/{token_id}需 BEARER

    按 id 吊销一个 token。

  • POST/v1/auth/logout需 BEARER

    吊销当前 bearer；refresh bearer 会连带吊销整个浏览器会话族。

  • GET/v1/account需 BEARER

    账号概况：邮箱、验证状态与已关联登录方式。

  • DELETE/v1/account需 BEARER

    密码重确认后删号；存在活动世界 session 时拒绝。

  • POST/v1/auth/google/challenge无需凭据

    一次性 challenge，同时回答 Google 入口是否开启并提供 client id 与 nonce。

  • POST/v1/auth/google/login无需凭据

    用经验证的 Google credential 登录；返回与密码登录相同的 token 结果。

  • POST/v1/auth/google/register无需凭据

    经 Google 注册 —— 仍需邀请码。

  • POST/v1/auth/google/link/challenge需 BEARER

    绑定 Google 身份用的、锚定当前账号的 challenge。

  • POST/v1/auth/google/link需 BEARER

    确认当前密码后完成 Google 身份绑定。

诊断同意

读取玩家已同意的档位，并换一张短寿命上传票。诊断流水由你的机器直接送到独立的诊断服务，网关不经手。

  • GET/v1/telemetry/consent需 BEARER

    本账号同意了什么：当前协议版本与正文链接、已授出的档位、是否需要重新征询，以及本部署是否真的在收。

  • PUT/v1/telemetry/consent需 BEARER

    按指定的协议版本授出或撤回诊断档位。空档位集合即撤回，撤回不校验版本。

  • POST/v1/telemetry/ticket需 BEARER

    签出只带已授出 scope 的短寿命上传票，或签出用于删除已上传数据的 purge 票。

反馈讨论

公开读取 issue thread；注册账号可新开 issue，并在线性评论区继续讨论。

  • GET/v1/feedback/issues无需凭据

    从新到旧列出公开 feedback issue，使用 cursor 分页。

  • POST/v1/feedback/issues需 BEARER

    以 bearer 对应的注册账号新开一个 feedback issue。

  • GET/v1/feedback/issues/{issue_id}无需凭据

    读取一个 issue 及按时间顺序排列的纯文本评论。

  • POST/v1/feedback/issues/{issue_id}/comments需 BEARER

    以 bearer 对应的注册账号在现有 issue 下添加纯文本评论。

站点端点

候补名单与门户第一方埋点 —— 属于接口面，不属于游玩。

  • POST/v1/waitlist无需凭据

    登记公开候补名单；首次登记会入队确认邮件。

  • POST/v1/waitlist/unsubscribe无需凭据

    邮件服务商使用的一键退订落点。

  • GET/v1/waitlist/unsubscribe无需凭据

    只返回需要人点击的确认页，不改任何状态。

  • POST/v1/site-events无需凭据

    本站第一方埋点 —— 属于接口面，不属于游玩。