Phigros

本页是 phigros 在 RankHub 上的字段级格式说明。phigros 有一条区别于其他游戏的硬约定： rating（单曲 rks）由调用方给——服务端只做上界校验与「只升不降」合并，不代算。

Profile 格式复制标题链接

身份字段（建档用）复制标题链接

• 建档走 POST /v1/games/phigros/profiles：只落库。
• 同一 objectId 已有未解绑档案 ⇒ 409（… is already linked）。
• 字段式建档不写 session_token_ciphertext ⇒ syncCapable: false；只有用户在 RankHub 取值以字段为准。
• name 也是建档必填项，但它是统一字段（player.name）而不是身份键，所以不在上表；10 个游戏一致。

统一字段（player）复制标题链接

GET .../bests 里的两个 totals 键都源自 summary.rks：totals.officialRks 读的是存下来的那一份， totals.rks 是每次请求现算的（calculated rks）。所以「official」指的是「已落库的值」， 不是「永远等于游戏内显示」——导入时两者可能不等，推过成绩后通常收敛。

原生字段（player.native）复制标题链接

档案里还有 avatar / avatarName / backgroundSongId 等展示字段，不在 player.native 里； summary 里的 levels（各难度通关/FC/ϕ 计数）、save_version、level_records 也不透传到 wire。

Score 格式复制标题链接

成绩键与比较值复制标题链接

• difficulty 是 5 值枚举，不是数字；推成绩时写 "IN" 这类字符串，或写数字下标 （EZ=0、HD=1、IN=2、AT=3、Legacy=4），认不出来直接 400。
• 比较值用 score（不是 acc）：同样 acc 可以对应不同 score（连击分不同）。

本页 keyFields / compareField / ratingField 里的名字都是 v1 wire 字段名（GameScoreDto 的顶层字段）；游戏原生列名写在说明列。

统一字段复制标题链接

phigros 会填的统一字段：

恒为 null 的字段：type（非 maimai）、level、fs、dxScore / dxStar。

原生字段（score.native）复制标题链接

phigros 的 score.native 只有两个键（其余原生字段都进了统一字段）：

原生成绩里还有 rks、acc、fc、rating（评级字母）、chart.level（定数）等， 它们分别落到 rating / achievements / fc / rank / native.constant；song_name 落到 songName。

评分语义与量纲复制标题链接

单曲 rks 由「acc + 谱面定数」唯一决定：

single_rks =
    acc < 70   ->  0
    acc >= 70  ->  ((acc - 55) / 45) ^ 2 × constant

• P1~P3 与 B27 可以重叠（同一首既评 ϕ 又进前 27 会被算两次），所以「分母 30」不等于 「30 首不同曲子」；没有 ϕ 成绩时前三项记 0，仍除以 30。
• 总分口径按 v3.11.0 起的 30 项平均（ϕ 曲定数前 3 + 单曲 rks 前 27）；旧档案无法从字段上区分分母 20 的旧口径。
• 官方从未发布 rks 白皮书：上表是官方版本说明 + 社区复算的口径（证据等级 community）。

最佳成绩桶复制标题链接

GET /v1/games/phigros/profiles/{profileId}/bests 返回两个桶（可能重叠）：

• totals.rks = 服务端按上面的 30 项平均重算的 rks（round3）。
• totals.officialRks = 档案里游戏自己算的 rks（player.rating 同源）。
• buckets[].total = 桶内 rating 之和，不是 rks。
• 两个桶可以重叠：同一首既是 ϕ 又在前 27 时会同时出现在两个桶里（这正是官方口径）。

写入（第三方）复制标题链接

写入只有两种形状：RankHub 格式（上文两张统一字段表里的字段）与游戏原生格式（native）。 共享字段、批量上限与失败语义见写入格式；本节只列 phigros 真正会读的字段。

建档（POST /v1/games/phigros/profiles）复制标题链接

player 用上文的身份字段（objectId 必填，shortId 可选）+ name。可以同时带 scores[]， 返回的 player.rating 以落库后的汇总（rks）为准。身份重复 ⇒ 409。

推成绩（POST .../profiles/{profileId}/scores）复制标题链接

curl -sS -X POST https://api.rankhub.cc/v1/games/phigros/profiles/$PROFILE_ID/scores \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "scores": [
      {
        "songId": "Introduction",
        "difficulty": "IN",
        "score": 1000000,
        "accuracy": 100,
        "rating": 15.3,
        "constant": 15.3,
        "artist": "Sample Artist",
        "rank": "ϕ",
        "fullCombo": true
      }
    ]
  }'

以上为示意数据：字段真实，数值虚构。

原生数据（native）复制标题链接

player.native / scores[].native 是游戏原生格式：与顶层同名字段同时出现时 native 优先（浅合并）。 只给 native 时，顶层的 name / objectId 可以省略。

建档（player.native）

推成绩（scores[].native）

可写字段 / 不可改

• 不可改：身份字段 object_id / short_id（与现值不同 ⇒ 400 common.invalidArgument）； 成绩唯一键 song_id + difficulty（native 里必须给，换了就是另一条成绩）。

本游戏的写入规则复制标题链接

• 必给：songId + difficulty + score + accuracy + rating；只有 difficulty 缺失 / 非法会直接 400。
• 比较值是 score：新值不高于现值 ⇒ 不覆盖，回 improved: false + ignored（notImproved）。
• 谁算分：单曲 rks 由调用方给（rating，服务端不复算、不与 acc × constant 对账）；总分由服务端重算。
• difficulty 是 5 值枚举，accuracy 是百分数 0~100（不是 0~1）—— 量纲写错会直接算错 rks。

消费者注意事项复制标题链接

1. achievements 是 acc，量纲 0~100（百分数）。它不是 0~1，也不是评级。
2. rank 装的是评级字母（ϕ / V / S / A / B / C / F），不是分数档位字符串； 最低档的实现值是 F（社区文本常写 False），跨源比对时要归一。
3. ϕ 的码位不统一：实现里用 ϕ（U+03D5），社区文本常用 φ（U+03C6）/ Φ（U+03A6）。 严格字符串比较会漏掉全部 ϕ，导致「前三」恒为 0。
4. rating 由调用方给：推成绩时 scores[].rating 会原样入库并参与总分， 服务端不复算、也不与 acc × constant 对账。错的值会一路算进 totals.rks。
5. phi 桶的成员是按单曲 rks 排序取的，而官方口径是按定数取前三；定数高但 acc 略低的 ϕ 曲可能落在不同位置。
6. best30 只有 27 条：不要按 30 硬编码长度；phi 最多 3 条。
7. 两个 rks 并存：player.rating 与 totals.officialRks 读同一份 summary.rks （导入时是游戏算的，推成绩后被服务端重算值覆盖），totals.rks 是请求时现算的。 两者不等是正常现象，展示时选一个并标注用的是哪一个。
8. playTime 恒 null：phigros 的存档不带游玩时间。

相关复制标题链接

• 游戏数据格式总览：三层模型、统一字段语义、null 与量纲规则
• 游戏档案：档案读取、建档、来源标记与删除申请
• 成绩读取与写入：成绩读取、批量写入、只升不降与最佳成绩