Arcaea

本页是 arcaea 在 RankHub 上的字段级格式说明。arcaea 与 maimai 一样属于 服务端算分族：单曲潜力值（ptt）由服务端按 score + 曲库定数重算，不看调用方传的 rating。

Profile 格式复制标题链接

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

• character 虽然来自「玩家资料」而不是「账号标识」，但建档必须有它（既有服务校验）， 所以它是身份字段而不是可选展示字段。
• syncCapable 恒为 false。
• name 也是建档必填项，但它是统一字段（player.name）而不是身份键，所以不在上表；10 个游戏一致。

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

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

• avatar / nameplate 是档案里的可空展示字段，不在 player.native 里。
• potential.potential 走统一字段 player.rating；其余 potential 统计（b10_avg、 speculate_r10_avg、max_potential）只在 bests.totals 里出现，不重复进 native。

Score 格式复制标题链接

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

• difficulty 取值：0=PST、1=PRS、2=FTR、3=BYD、4=ETR、5=INS。
• wire 上 difficulty 是数字的字符串（如 "2"），levelIndex 是同一个数字的数值形式； 要按难度过滤（?difficulty=2）时传 "2"。
• 比 score 时不要用 achievements：arcaea 的 achievements 恒 null。

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

统一字段复制标题链接

arcaea 会填的统一字段：

恒为 null 的字段：achievements（arcaea 没有达成率概念）、songName、type、level、 fc / fs（全连语义在 native.clearType 里）、dxScore / dxStar。

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

arcaea 的 score.native 是固定的 9 个键：

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

单曲潜力值（现行移动版口径）分三段 + 通关奖励，结果 round3（3 位小数）：

base(S, C) =
    S >= 10,000,000              ->  C + 2
    9,800,000 <= S < 10,000,000  ->  C + 1 + (S - 9,800,000) / 200,000
    S < 9,800,000                ->  max(0, C + (S - 9,500,000) / 300,000)

chart_ptt = round3( base(S, C) + clear_bonus )

clear_bonus = 0.2   若 clearType 不是 0（即通关：Full Recall / Pure Memory / Normal / Easy / Hard Clear）
            = 0.0   若 clearType = 0（Track Lost）

• 算分口径按移动版现行版本（Best 50 + Best 10，分母 60）；历史档案无法从字段上区分旧口径（Best 30 + Recent 10）。
• 官方从未公开 potential 公式：上表是社区口径（证据等级 community），不是官方规范。

最佳成绩桶复制标题链接

GET /v1/games/arcaea/profiles/{profileId}/bests 返回一个桶：

• totals.potential = 档案的 potential（round3）；不等于 buckets[0].total。
• buckets[0].total = 桶内 50 条 rating 的和，不是 potential。
• totals.b30Avg / b50Avg / maxPotential 都是原生没有的派生指标： b30Avg = 前 30 之和 / 30、b50Avg = 前 50 之和 / 50； maxPotential 仍按旧口径 (Σ前30 + Σ前10) / 40 计算，与 totals.potential 不同源。
• 桶内排序：potential 降序 → score 降序 → songId 升序 → difficulty 升序。

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

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

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

player 用上文的身份字段（arcaeaId、character 必填，friendCode 可选）+ name，可另给 course / avatar / nameplate 与 potential（snake_case 子键，缺省按 0）。可以同时带 scores[]，返回的 player.rating 已是重算后的 potential。身份重复 ⇒ 409。

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

curl -sS -X POST https://api.rankhub.cc/v1/games/arcaea/profiles/$PROFILE_ID/scores \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "scores": [
      {
        "songId": "tiferet",
        "difficulty": 2,
        "score": 9968755,
        "scoreBelowMax": 31245,
        "shinyPerfectCount": 984,
        "perfectCount": 97,
        "nearCount": 3,
        "missCount": 2,
        "clearType": 3,
        "bestClearType": 3,
        "health": 100
      }
    ]
  }'

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

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

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

建档（player.native）

推成绩（scores[].native）

可写字段 / 不可改

• potential 不属于可写字段：它是服务端算分汇总，只能在建档时随 player.native 一起给。
• 不可改：身份字段 arcaea_id / character / friend_code（与现值不同 ⇒ 400 common.invalidArgument）； 成绩唯一键 song_id + difficulty（native 里必须给，换了就是另一条成绩）。

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

• 必给：songId + difficulty + score；clearType / bestClearType 建议给（缺省 0 会参与算分）。
• 比较值是 score：新值不更高 ⇒ 不覆盖，回 improved: false + ignored（notImproved）。
• 谁算分：单曲 ptt 与 potential 都由服务端算（maimai / arcaea 属于这一类），scores[].rating 被忽略。
• scoreBelowMax 独立：只校验取值域 0~11,000,000，不与 score 做加和；读侧它是「距理论值的差值」，不要反推 score。
• 建档身份：character 缺 / 空 ⇒ 400 character is required；同一身份重复建档 ⇒ 409。

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

1. achievements 恒 null：arcaea 没有达成率字段；要准度信息请读 native 的四个计数。
2. difficulty 是数字串（"2"），不是 FTR 这类标签；标签映射见本页「成绩键」段。
3. score 可能超过 1,000 万（每个大 Pure +1 分）。任何「分数 ≤ 10,000,000」的假设都会错。
4. 通关奖励看 clearType，不是 bestClearType：单曲 ptt 与「本次成绩」的通关状态绑定， 用历史最高通关类型会系统性偏高。
5. totals.potential 与 buckets[].total 不是一个数：前者是按 Best 50 口径算的 potential， 后者是桶内合计（和）。maxPotential 是旧口径派生值，不要拿它跟 potential 比大小。
6. b30Avg / b50Avg / maxPotential 原生都没有：它们是 RankHub 自算的展示字段， 跨客户端比对时不要假设其他数据源也有。
7. native.scoreBelowMax 不是 10,000,000 - score：理论值含大 Pure 加分， 两者在满分级成绩上会不一致。
8. syncCapable 恒 false，不是漏实现。

相关复制标题链接

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