@heybox/hb-sdk

Appearance

黑神话：悟空存档数据 ​

本文解释 getLatestStructuredData('2358720') 成功返回的 data：角色状态、收集、配装和战斗记录直接位于该对象下，没有额外的 slots 包装。

字段说明基于已保存业务数据的定义，示例不是真实账号响应，也不是所有字段必填的固定类型。实际记录可以包含表格之外的字段；旧记录可能缺少字段或返回 null。调用权限、返回状态及错误处理见游戏存档指南。

读取方式 ​

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

const result = await hbSDK.gameSaves.getLatestStructuredData('2358720')
if (result.status === 'ready') {
  const data = result.data
  console.log('等级', data.level)
  console.log('灵韵', data.totalMoney)
  if (typeof data.gameTotalTime === 'number') {
    console.log('游玩小时数', data.gameTotalTime / 3600)
  }
}

这里只演示 ready 分支。完整接入还需要处理 empty、unsupported、failed，并捕获登录、权限和账号变化等异常。

角色状态 ​

下表的类型描述已知字段，使用前仍需检查当前记录是否提供该值。

字段类型含义
level数字角色等级
newGamePlusCount数字存档记录的周目计数
playerDeathCount数字死亡次数
gameTotalTime数字总游玩时长，单位秒
totalMoney字符串灵韵数量；不要默认转成 JavaScript number

地图、解锁和收集 ​

这些集合提供 ID，不能直接当作名称或图片地址展示。

字段类型含义
meditationList数字 ID 数组打坐点记录
monsterCollectionList数字 ID 数组影神图记录
returnPointList数字 ID 数组传送点记录
activatedWeaponIdList字符串 ID 数组武器／装备解锁集合之一，保留原始 ID
activatedEquipIdList数字 ID 数组武器／装备解锁集合之一，保留原始 ID
magicArtifactList数字 ID 数组珍玩收集记录
soulSkillIdList数字 ID 数组精魄记录
huluIdLits数字 ID 数组葫芦记录
wineIdList数字 ID 数组酒记录
wineIdPartnerList数字 ID 数组酒食记录
cropIdList数字 ID 数组种子记录
recipeIdList数字 ID 数组丹方记录

当前配装与法术 ​

字段类型含义
wearedWaeponId字符串当前武器 ID
wearedMagicArtifact数字当前法宝 ID
wearedSoulSkill数字当前精魄 ID
wearedHead、wearedUpware、wearedArm、wearedFoot数字当前头部、衣服、臂部、脚部装备 ID
wearedHulu数字当前葫芦 ID
wearedAccessoryList数字 ID 数组当前装备的珍玩
spellQishu数字 ID 数组奇术记录
spellShenfa数字 ID 数组身法记录
spellHaomao数字 ID 数组毫毛记录
spellBianshen数字 ID 数组变身记录

huluIdLits、wearedWaeponId、wearedUpware 是实际字段拼写。访问时不要自行改成其他拼写。

连战与再战 ​

路径含义
bossRushBossgroup.bossGroups[]Boss 组的连战挑战记录
bossRushRefight.bossList[]单个 Boss 的再战挑战记录

连战记录的层次如下。此处是字段路径示意，省略了其他字段，不是可执行代码或完整响应。

text
bossRushBossgroup.bossGroups[]
├─ bossGroupId              Boss 组 ID
├─ isPassed                 是否通过
├─ encounterBossIndex       遭遇 Boss 的索引
├─ battleCount              战斗次数
└─ bestRecords[]            最佳记录
   ├─ battleId              战斗 ID
   └─ battleData
      ├─ totalTime          战斗时长值
      ├─ score              分数
      ├─ debuffList         挑战减益列表
      ├─ targetId           目标 ID
      ├─ archiveTime        记录时间值
      ├─ roleBase           等级、攻击、生命／体力／法力上限
      ├─ battleStyleInfo    技能、法宝、精魄及资源使用次数
      └─ damageInfo         伤害、承伤、暴击等统计

roleBase 的已知字段包括 level、atk、hpMax、staminaMax、mpMax。不要把角色总游玩时间的“秒”单位直接套到战斗记录中的 totalTime，也不要在未确认格式时直接把 archiveTime 当作毫秒时间戳。

使用边界 ​

  • 返回完整已保存业务对象，不按页面概览筛选字段，也不表示原始 ZIP 中的全部内容。
  • 大于 JavaScript 安全整数范围的整数会以字符串返回；不要对所有数字形态的字段统一执行 Number()。
  • 缺失集合与空数组含义可能不同：展示时可以使用空数组兜底，但不要据此断言玩家没有收集或完成。
  • 读取不会触发同步或解析；sync() 完成不保证结构化数据已经更新。

相关文档 ​