mirror of
https://github.com/BTMuli/TeyvatGuide.git
synced 2025-12-10 08:58:15 +08:00
288 lines
8.8 KiB
Markdown
288 lines
8.8 KiB
Markdown
---
|
||
Author: 目棃
|
||
Date: 2023-04-07
|
||
Description: UIGF v2.3 Backup
|
||
Update: 2023-04-07
|
||
---
|
||
|
||
> 本文档 [`Front-matter`](https://github.com/BTMuli/Mucli#FrontMatter) 由 [MuCli](https://github.com/BTMuli/Mucli) 自动生成于`2023-04-07 19:51:40`
|
||
>
|
||
> 更新于 `2023-04-07 19:51:40`
|
||
|
||
> 本文档为 [`UIGF`](https://github.com/UIGF-org/UIGF-org.github.io/blob/main/docs/zh/standards/UIGF-pre-release.md) 的备份。
|
||
|
||
# 统一可交换祈愿记录标准 v2.3
|
||
|
||
> Uniformed Interchangeable GachaLog Format standard (UIGF) v2.3
|
||
|
||
## 更新记录
|
||
|
||
|版本|说明|兼容|
|
||
|-|-|-|
|
||
|`v2.0`| 首个正式版本 | v2.0 |
|
||
|`v2.1`| 简化了部分语言表述，与 v2.0在数据格式上完全一致 | v2.1 and lower |
|
||
|`v2.2`| 新增 `info.export_timestamp` 填充 UNIX 时间戳 | v2.2 and lower |
|
||
|`v2.3`| 扩充至非中文语境，使用 Json Schema 表述 | v2.3 and lower |
|
||
|
||
## Id
|
||
|
||
原神的祈愿记录物品内包含了一项较为特殊的字段: `id` ，该值在 1.3版本后加入
|
||
所以**先前查询出的物品**若无特殊兼容性修改则不会包含相应的 `id`
|
||
App 导出 UIGF 时
|
||
* 需要确保每个物品的 `id` 的有效性。
|
||
* 从最后一个自带有效 `id` 的物品开始，向前（相对于时间）依次递减 `id` 的值,每次递减的值应保持为 `1`
|
||
|
||
导入 UIGF 到 App 时
|
||
* App不应假设所有的 `gacha_item` 都有有效的 `id` 值
|
||
* App应具有处理 `id` 字段为 `null`或 `` 空字符串的能力
|
||
|
||
## GachaType
|
||
|
||
祈愿包含了会共享保底与概率的卡池，所以需要一个额外的字段来界定
|
||
我们在`UIGF`的所有格式中注入了`uigf_gacha_type`字段
|
||
在导出到`UIGF`格式时需要注意添加对应的`uigf_gacha_type`字段
|
||
|
||
### 映射关系
|
||
|
||
|`uigf_gacha_type`|`gacha_type`|
|
||
|-|-|
|
||
|`100`|`100`|
|
||
|`200`|`200`|
|
||
|`301`|`301` or `400`|
|
||
|`302`|`302`|
|
||
|
||
## Json 格式
|
||
|
||
> Uniformed Interchangeable GachaLog Format standard of Json (UIGF.J)
|
||
Json 格式 由于 与从官方接口获取到的格式一致
|
||
更便于各App的导入与导出，我们也在此做出规范
|
||
该格式应仅用于各App间的数据互通
|
||
|
||
### 导出的格式
|
||
|
||
```json
|
||
{
|
||
"type": "object",
|
||
"title": "UIGF object",
|
||
"properties": {
|
||
"info": {
|
||
"type": "object",
|
||
"properties": {
|
||
"uid": {
|
||
"type": "string",
|
||
"title": "Uid",
|
||
"description": "Uid"
|
||
},
|
||
"lang": {
|
||
"type": "string",
|
||
"title": "Language",
|
||
"description": "语言 ISO 3166"
|
||
},
|
||
"uigf_version": {
|
||
"type": "string",
|
||
"title": "UIGF Version",
|
||
"description": "UIGF 版本号"
|
||
},
|
||
"export_timestamp": {
|
||
"type": "number",
|
||
"title": "Export Timestamp",
|
||
"description": "导出时间戳（秒）"
|
||
},
|
||
"export_time": {
|
||
"type": "string",
|
||
"description": "导出时间",
|
||
"format": "date-time",
|
||
"pattern": "yyyy-MM-dd HH:mm:ss",
|
||
"title": "Export Time"
|
||
},
|
||
"export_app": {
|
||
"type": "string",
|
||
"title": "Export App",
|
||
"description": "导出应用"
|
||
},
|
||
"export_app_version": {
|
||
"type": "string",
|
||
"title": "Export App Version",
|
||
"description": "导出应用版本"
|
||
}
|
||
},
|
||
"title": "Infomation",
|
||
"required": [
|
||
"uid",
|
||
"lang",
|
||
"uigf_version"
|
||
],
|
||
"description": "包含导出方定义的基本信息"
|
||
},
|
||
"list": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"gacha_type": {
|
||
"type": "string",
|
||
"description": "祈愿类型"
|
||
},
|
||
"item_id": {
|
||
"type": "string",
|
||
"title": "Item Id",
|
||
"description": "空字符串"
|
||
},
|
||
"count": {
|
||
"type": "string",
|
||
"title": "Count",
|
||
"description": "数量"
|
||
},
|
||
"time": {
|
||
"type": "string",
|
||
"title": "Time",
|
||
"description": "物品获取时间",
|
||
"pattern": "yyyy-MM-dd HH:mm:ss",
|
||
"format": "date-time"
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"title": "Name",
|
||
"description": "名称"
|
||
},
|
||
"item_type": {
|
||
"type": "string",
|
||
"title": "Item Type",
|
||
"description": "物品类型"
|
||
},
|
||
"rank_type": {
|
||
"type": "string",
|
||
"title": "Item Quality",
|
||
"description": "物品星级"
|
||
},
|
||
"id": {
|
||
"type": "string",
|
||
"title": "Id",
|
||
"description": "内部数据库Id"
|
||
},
|
||
"uigf_gacha_type": {
|
||
"type": "string",
|
||
"title": "Query Type",
|
||
"description": "向接口查询时需要的 gacha_type"
|
||
}
|
||
},
|
||
"required": [
|
||
"gacha_type",
|
||
"name",
|
||
"id",
|
||
"uigf_gacha_type",
|
||
"time"
|
||
],
|
||
"title": "Gacha Item",
|
||
"description": "祈愿物品"
|
||
},
|
||
"title": "List",
|
||
"description": "物品列表"
|
||
}
|
||
},
|
||
"required": [
|
||
"info",
|
||
"list"
|
||
],
|
||
"description": "UIGF 根对象"
|
||
}
|
||
```
|
||
|
||
## Excel 工作簿 (Workbook Format)
|
||
|
||
> Uniformed Interchangeable GachaLog Format standard of Workbook (UIGF.W)
|
||
|
||
### 单元格的格式
|
||
|
||
* 在填充单元格内的数据时，应统一转换到 `String` 字符串类型后填入
|
||
|
||
### 表名及内容
|
||
|
||
|表名|内容|类型|是否必要|
|
||
|-|-|-|-|
|
||
|统计分析|统计分析内容等|任意|否|
|
||
|角色活动祈愿|`gacha_type` : `301 or 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`|是|
|
||
|
||
#### 示例
|
||
|
||
|count|gacha_type|id|item_id|item_type|lang|name|rank_type|time|uid|uigf_gacha_type|
|
||
|-|-|-|-|-|-|-|-|-|-|-|
|
||
|1|301|1613556360008291100||武器|zh-cn|以理服人|3|2021-02-17 18:45:09|123456789|301|
|
||
|...|...|...|...|...|...|...|...|...|...|...| |