统一可交换祈愿记录标准 v2.2

Uniformed Interchangeable GachaLog Format standard (UIGF)

前言

由于原神的祈愿卡池与记录越来越多,越来越复杂,各个App间进行数据交换的代价越来越大,于是 我们

(上述名称以字典顺序排序,不代表其他任何意义)
在此一起,制定了此项标准,旨在加强各个原神相关的App间的数据可交换性
如果今后出现了新的需要在各App间交换的数据,我们也会进行规范

注意事项

在采用此格式时,需要特别注意某些字段名称中可能存在的下划线 _ 或空格字符
此格式仅适用于简体中文环境

Id

原神的祈愿记录物品内包含了一项较为特殊的字段: id ,该值在 1.3版本后加入
所以先前查询出的物品若无特殊兼容性修改则不会包含相应的 id
导出时

  • 需要确保每个物品的 id 的有效性。
  • 推荐从最后一个自带有效 id 的物品开始,向前(相对于时间)依次递减 id 的值,每次递减的值应保持为 1
  • 生成的 id 值不应大于 1612303200000000000
  • App不应假设所有的 gacha_item 都有有效的 id
  • App应具有处理 id 字段为 null或 `` 空字符串的能力

GachaType

祈愿包含了会共享保底与概率的卡池,所以需要一个额外的字段来界定
我们在UIGF的所有格式中注入了uigf_gacha_type字段
在导出到UIGF格式时需要注意添加对应的uigf_gacha_type字段

uigf_gacha_type 映射关系

uigf_gacha_typegacha_type
100100
200200
301301|400
302302

Excel 工作簿 (Workbook Format)

Uniformed Interchangeable GachaLog Format standard of Workbook (UIGF.W)

文件的名称

我们建议:

  • 在名称中包含导出数据所属用户的 uid
  • 用户在导出操作发生前应具有修改文件名称的权力

单元格的格式

  • 在填充单元格内的数据时,应统一转换到String字符串类型后填入

表名及内容

表名内容类型是否必要
统计分析统计分析内容等任意
角色活动祈愿gacha_type : 301|400 的祈愿数据祈愿表否,但是应该导出
武器活动祈愿gacha_type : 302 的祈愿数据祈愿表否,但是应该导出
常驻祈愿gacha_type : 200 的祈愿数据祈愿表否,但是应该导出
新手祈愿gacha_type : 100 的祈愿数据祈愿表否,但是应该导出
原始数据全部祈愿数据数据表详见下方原始数据表结构说明
  • 表的顺序可以是任意的
  • 可以隐藏部分表,防止用户随意篡改数据
  • Sheet 的名称应与游戏内祈愿记录页面显示的名称保持一致

App间应依据 原始数据表 的内容,来进行数据互通

祈愿表结构

本节内容是为了规范兼容分析类App

  • 表头对应的内容填充顺序需要严格按照下方说明排布
  • 共享保底的卡池按祈愿类型 (gacha_type) 区分
  • 此类 Sheet 存在的目的,是为了便于用户观看与祈愿分析工具的分析
表头内容是否必要
时间yyyy-MM-dd HH:mm:ss 格式的 time 时间
名称name物品名称
物品类型item_type
星级rank_type
祈愿类型gacha_type 的转义名称是,尽管部分工具不会分析此项
......

如果你认为有必要的话,可以额外增加其他表头,但请确保表头的前几列为上表规范的内容
表内的数据通常按祈愿Id升序或降序排列,分析App不应假设表内的顺序为特定的升序与降序

gacha_type 转义名称

gacha_type名称
100新手祈愿
200常驻祈愿
301角色活动祈愿
400角色活动祈愿-2
302武器活动祈愿

示例

时间名称类别星级祈愿类型...
2021-02-17 18:45:09以理服人武器3角色活动祈愿-2...
..................

原始数据表结构

导出时

  • App 在导出时应尽可能询问用户是否应包含原始数据表
  • 一旦在工作簿内包含了名为 原始数据 的表,即表示支持本格式
  • 该表内的内容应严格按照本格式所述填充
  • 表头的顺序需严格按照下表设置
  • 现有的字段采用字典顺序递增排序,后续新增的字段依添加的顺序排在后侧。
  • 若无特殊需求,我们建议导出所有json 数据内包含的字段

导入时

  • 强烈建议您编写不依赖于列的顺序位置便可实现导入的程序,以达到最大化的兼容。
  • 如果省略了其中某些非必要字段的值,请保持表头存在,对应的列则空置。
表头是否必要
count否,但是建议保留,不排除后续会有count不为1的情况
gacha_type
id是,且大部分App按此字段排序数据
item_id否,目前官方已经弃用了此字段
item_type
lang否,但建议保留,以便国际化
name
rank_type否,但建议保留,以便分析
time否,但建议保留,以便分析
uid否,但建议将选择权交予用户,保留以便分析
uigf_gacha_type

示例

countgacha_typeiditem_iditem_typelangnamerank_typetimeuiduigf_gacha_type
13011613556360008291100武器zh-cn以理服人32021-02-17 18:45:09123456789301
.................................

Json 格式

Uniformed Interchangeable GachaLog Format standard of Json (UIGF.J)

Json 格式 由于 与从官方接口获取到的格式一致
更便于各App的导入与导出,我们也在此做出规范
该格式应仅用于各App间的数据互通

导出的格式

以同值字段提取至上层的思想,我们拟定了以下json格式

{
    "info" : {
        "uid" : "000000000",
        "lang" : "zh-cn",
        ...
    },
    "list" : [
        {
            "gacha_type": "000",
            "item_id": "",
            "count": "1",
            "time": "yyyy-MM-dd HH:mm:ss",
            "name": "以理服人",
            "item_type": "武器",
            "rank_type": "3",
            "id": "1600099200004770203",
            "uigf_gacha_type": "000",
        },
        ...
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

info

除了从 {gacha_item} 中提取的 uid,lang字段,还可以包含我们认可的以下字段

字段名说明
export_time导出时间 : yyyy-MM-dd HH:mm:ss
export_timestamp导出UNIX时间戳v2.2+
export_app导出此份记录的App名称,详见下方表格
export_app_version导出此份记录的App版本号
uigf_version所应用的 UIGF 的版本,包含此字段以防 UIGF 出现中断性变更时,App无法处理

uigf_version

合法值

说明兼容
v2.0首个正式版本v2.0
v2.1简化了部分语言表述,与 v2.0在数据格式上完全一致v2.1 and lower
v2.2新增 info.export_timestamp 填充 UNIX 时间戳v2.2 and lower

export_app

未实现导出支持的以 - 代替

导出 Appexport_app 的值
biuuu/genshin wish exportopen in new windowgenshin-wish-export
DGP Studio/Snap.Genshinopen in new windowSnap Genshin
MUK/应急食品open in new windowMUKGenshinTool
Scighost/KeqingNiuzaopen in new window-
Scighost/Xunkongopen in new windowXunkong.Desktop
sunfkny/genshin gacha exportopen in new windowgenshin-gacha-export
TremblingMoeNew/DodocoTalesopen in new window-
voderl/genshin gacha analyzeropen in new window-