界面协议

本页用于修改 plugins/Presence/ui/hud.yml、plugins/Presence/ui/rewards.yml，或重新制作 Presence 玩家界面。

打开流程

奖励面板打开后，服务端会：

1. 发送 stages，建立左侧阶段列表；
2. 优先选择第一份可领取奖励，否则选择下一份未解锁奖励；
3. 发送所选阶段的 stage_detail；
4. 在玩家选择其他阶段后，发送该阶段的新详情。

UI → 服务端

动作参数均为字符串：

Packet.send('select', 'online-30m')
Packet.send('claim', 'online-30m')

阶段 ID 必须符合 [a-z0-9][a-z0-9_.-]{0,63}。claim 回传的 ID 必须与当前详情一致；界面未打开、参数错误或操作过快时，服务端会忽略动作。

HUD：state

HUD 应在本地计算倒计时与进度：

clockOffset = serverEpochMillis - Time.currentTime()
now = Time.currentTime() + clockOffset
elapsed = Math.max(0, now - serverEpochMillis)
estimatedOnline = onlineMillis + elapsed
remaining = Math.max(0, claimAtEpochMillis - now)
progress = Math.max(0, Math.min(1,
  (estimatedOnline - previousThresholdMillis) /
  Math.max(1, thresholdMillis - previousThresholdMillis)
))

新的 state 会在玩家加入、资源加载完成、HUD 同步、阶段解锁、阶段修改或每日重置时发送；界面无需持续向服务端请求剩余时间。

阶段列表：stages

每个 stages[] 包含：

阶段详情：stage_detail

该处理器包含 cycleKey、serverEpochMillis、onlineMillis 和 stage。stage 字段如下：

每个 rewards[] 包含：

物品使用 Slot 与 setItemIcon 展示 content；货币和命令奖励使用 icon。

领取状态：

领取结果：claim_result

{
  "code": "delivered",
  "success": true,
  "message": "领取成功，请前往系统邮箱查看。",
  "stageId": "online-30m"
}

收到 claim_result 后直接显示 message。Presence 随后会重新发送 stages 与当前阶段的 stage_detail。