@heybox/hb-sdk

Appearance

影之刃零存档数据 ​

本文解释 getLatestStructuredData('4115450') 成功返回的 data。它包含当前账号全部已保存槽位，以及用于默认展示的槽位名。

字段说明基于已保存业务数据的定义，以下结构示意不是真实账号响应。调用权限、返回状态及错误处理见游戏存档指南。

多槽位结构 ​

ts
import hbSDK from '@heybox/hb-sdk'

const result = await hbSDK.gameSaves.getLatestStructuredData('4115450')
if (result.status === 'ready') {
  const slots = Array.isArray(result.data.slots) ? result.data.slots : []
  const defaultSlot = slots.find(slot =>
    slot && typeof slot === 'object' && slot.slot === result.data.defaultSlot,
  )
  console.log('默认槽位', defaultSlot)
  console.log('全部槽位', slots)
}

这里只演示 ready 分支；完整接入还需处理其他状态及调用异常。返回的 data 结构为：

text
data
├─ defaultSlot          默认槽位名，例如 AutoSave0
└─ slots[]              全部已持久化槽位
   ├─ slot              槽位名
   ├─ head              保存时间、关卡、周目、难度
   ├─ firstClear        通关时间及各周目结算
   ├─ progress          时长、章节、剧情进度
   ├─ combat            配装、死亡、Boss 击杀
   ├─ achievements      成就汇总
   ├─ bosses            Boss 分组及挑战记录
   ├─ collectibles      收集进度
   ├─ detail            分类明细
   ├─ quest_details     任务动态状态，旧记录可能为 null
   └─ inventory_details 背包物品，旧记录可能为 null

slots 按 head.saveTime 字符串倒序排列，缺失或 null 排在最后；同一时间按槽位名升序。defaultSlot 是排序后的第一个槽位名，不固定优先选择自动或手动存档。没有槽位时返回 empty，不是包含空数组的 ready。

基础信息、结算与进度 ​

以下路径均相对于 slots[] 中的单个槽位。

路径含义
head.saveTime存档保存时间字符串，沿用游戏格式
head.currentLevel当前关卡字符串
head.cycle当前周目字符串
head.difficulty.raw、head.difficulty.name原始难度值与已保存的名称
firstClear.clearDate通关时间的可用性对象，包含 value、reason
firstClear.cycles[]各周目结算记录，保留原字段及大小写
progress.playTimeSeconds游玩时长，单位秒
progress.playTime已保存的时长展示字符串
progress.lastLaunch最近启动时间的可用性对象，包含 value、reason
progress.narrativePercentage剧情进度数值
progress.chapter章节字符串
progress.remainingDays剩余天数

clearDate、lastLaunch 不保证有非空值。应展示 reason 或缺失提示，不要把 value: null 当作时间戳 0。

firstClear.cycles[] 的已知原字段包括 Cycle（周目键）、Ending（结局值）、Difficulty（难度值）、GameTime（游戏时间值）、Completion（完成度）、DiedTimes（死亡次数）。不要按数组下标推断周目，也不要给未确认格式的 GameTime 强行套用其他时间字段的单位。

配装、成就与 Boss ​

路径含义
combat.loadout已保存配装状态，可能缺失
combat.totalDeaths、combat.cycleDeaths累计死亡次数、当前周目死亡次数
combat.bossKillTotalBoss 击杀总数
combat.currentMainWeapon、combat.currentShaqi当前主武器、杀器信息，可能为 null
combat.mainWeapon、combat.shaqi主武器、杀器的收集计数
achievements.unlocked、achievements.total已解锁成就数、成就总数
achievements.reason成就统计的补充说明
bosses.groups[]Boss 分组，包含 map、mapName、count 和 bosses

每个 bosses.groups[].bosses[] 的已知字段：

字段含义
id、classPathBoss ID、游戏类路径
map、mapName已保存的地图标识与名称
encountered、killed是否遭遇、是否击杀
kill、attempt击杀次数、尝试次数
bestTimeMs最佳时间，单位毫秒
records[]分周目／难度挑战记录：cycle、diff、diffName、kill、attempt、bestTimeMs

收集汇总与分类明细 ​

路径含义
collectibles.overall按类别汇总的收集情况
collectibles.craneBellCount鹤铃数量
collectibles.byBigMap[]大地图收集进度，包括 mapID、name、pct、done、total、subMaps
collectibles.currentChapter当前章节收集进度，包括 mapID、pct、done、total、reason

计数对象中的 done、total 分别表示已完成和总量；可选的 unknown 表示未知数量。未知不等于未完成。

detail 按类别保存明细数组，各类别的元素结构不完全相同：

字段分类
bell铃类收集
weapon、shaqi武器、杀器
accessory、medicine饰品、药品
challenge挑战
hupo、heishi对应 hupo、heishi 类收集项，保留游戏分类标识
flower记忆之花收集项
achievements成就明细

部分物品明细有 id、done、equip，以及可选的 level（等级）、soul_forged（铸魂状态）、reincarnation_count（重复获取强化次数）。不要把强化次数与等级合并，也不要把可选字段缺失当作 false 或 0。各项名称、图片或位置不保证已保存。

任务与背包 ​

quest_details 字段含义
CurrentMainQuestPath、CurrentTutorialQuestPath当前主线、教程任务路径
TrackedQuestPath、TrackedBranchID、TrackedTaskPointID当前追踪任务、分支和任务点
ManualTrackingOptOut手动退出追踪的标记
NarrativeSavedQuests[]已记录任务，包含 QuestClass、QuestCompletion、QuestBranches、CompletedBranches、ReachedStateNames

QuestBranches[] 包含 BranchID、TasksProgress、BranchType。这些是任务动态状态，不附带完整攻略文案；不要只根据数组顺序判断任务步骤是否完成。

inventory_details 为 { id, amount }[]，分别表示背包物品 ID 与数量。旧记录可能没有任务或背包模块，此时对应字段为 null。

使用边界 ​

  • 只返回已入库业务模块，不是完整解密 JSON；不补查静态图鉴来填充名称、说明和图片。
  • 字段混用驼峰、下划线与大写开头的原始命名，大小写必须严格保留。
  • 超出 JavaScript 安全整数范围的整数返回字符串；旧记录可能缺少字段，请兼容 null 和未知字段。
  • 本方法不触发同步或解析；支持影之刃零需要配套后端与 Host Runtime，沿用现有 SDK 方法。

相关文档 ​