CHUNITHM

本页是 chunithm（中二节奏）在 RankHub 上的字段级格式说明。它属于「本地游戏」族 （chunithm / orzmic）：成绩是上游原始对象，服务端不做结构归一、也不代算任何评分。

Profile 格式复制标题链接

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

• 建档走 POST /v1/games/chunithm/profiles：只落库。
• 该好友码已有未解绑档案 ⇒ 409。
• chunithm 没有 externalId 这个身份字段（那是 orzmic 的）：对外身份就是 friendCode。
• name 也是建档必填项，但它是统一字段（player.name）而不是身份键，所以不在上表；10 个游戏一致。

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

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

player.native 是三个顶层键，其中两个是嵌套的原生 JSON（不摊平）：

player / summary 的内部键属于上游数据，不逐个声明为 nativeFields： 它们是嵌套 JSON，键集合可能随上游版本变化。对外契约只有这三个顶层键。

Score 格式复制标题链接

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

• 推成绩时 scores[].bucket 决定落哪个桶：best30 / selection10 / new20，缺省 best30。
• songId 的读取有候选键：song_id / id / music_id / songId；score 取 score，回落 achievement。

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

统一字段复制标题链接

chunithm 会填的统一字段：

恒为 null 的字段：type（非 maimai）、levelIndex（本地族没有下标）、level、fc / fs （full_combo / full_chain 只在 native 里）、dxScore / dxStar。

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

chunithm 的 score.native 没有固定字段集合：它是整份原生成绩对象原样透传， 键名可能随上游版本变化。

所以本页不列 score.native 字段表（nativeFields 为空数组；注意这与 maimai 的「native 恒 null」不同—— chunithm 的 native 有值，只是键集合不固定）。

成绩对象的候选键复制标题链接

服务端会按下面这些候选键读取（命中即用）：

原生成绩对象里还可能带：over_power、clear、full_combo（AJC/AJ/FC）、full_chain （fullchain=铂、fullchain2=金，字面与语义顺序不一致）、play_time、upload_time、 last_played_time、level。这些都只在 native 里，不进统一字段。

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

单曲 Rating 不是乘法，而是「定数 + 分数档加成」的分段线性函数（现行 VERSE 口径）：

• s = 分数（0~1,010,000，1,010,000 是 All Justice Critical 理论值）；c = 谱面定数。
• 单曲上限 c + 2.15（1,009,000 分起不再增长）；低分可能算出负数，最终 max(0, ·)。
• 精度：单曲值展示向下截断到 2 位小数；总分是否同样截断未见官方说明（未知项）。
• 官方总分口径（VERSE 起）：BEST 30 + NEW 20 共 50 张谱面（互不重复）的单曲值算术平均， 分母恒 50；旧制为 BEST 30 + RECENT 10，分母 40。

最佳成绩桶复制标题链接

chunithm 的桶直接来自上游快照分组（组名即 key），服务端不重算成员：

• 三个 key 总是存在（服务端按固定组名逐个输出），但对应数组可能为空。
• totals.total = best30 + new20 两组 rating 之和（不含 selection10），与官方 「50 张平均」口径不同源，也不等于推成绩响应里的 rating.before / rating.after （后者把全部组一起求和，含 selection10）。
• buckets[].total = 该桶内 rating 之和（不是条数）。
• label 是大写形式（BEST30 / SELECTION10 / NEW20），与 key 只差大小写。 按 key 渲染、label 只作参考（展示名可自行本地化）。
• 桶数与顺序不是契约：以响应里的 buckets 数组为准，不要按数组下标。

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

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

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

player 用上文的身份字段（friendCode 必填）+ name。建档不能带成绩：成绩必须用下面的端点单独推。

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

curl -sS -X POST https://api.rankhub.cc/v1/games/chunithm/profiles/$PROFILE_ID/scores \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "scores": [
      {
        "songId": "3",
        "difficulty": "4",
        "score": 1010000,
        "rating": 16.15,
        "bucket": "best30",
        "native": { "id": 3, "level_index": 4, "score": 1010000, "rating": 16.15, "clear": "clear" }
      }
    ]
  }'

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

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

chunithm 的 native 只用于 profile：player.native 里除身份字段外的键会原样写进档案的玩家块，读回在 player.native.player。 成绩不做 native → 字段的换算（scores[].native 只是原样存储的原始成绩对象）。

可写字段 / 不可改

• 不可改：身份字段 friend_code（与现值不同 ⇒ 400 common.invalidArgument）； 成绩唯一键 songId + difficulty —— 本游戏没有 native 换算，这两个只能由顶层字段给。

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

• 必给：songId + difficulty + rating + score；rating 尤其重要，缺了合计会用 score 兜底。
• 比较值是 score：新值不高于现值 ⇒ 不覆盖，回 improved: false + ignored（not-improved）。
• 谁算分：服务端不算分（chunithm 属于「调用方给」族）。单曲 Rating 用你给的 rating，总分是桶内求和。
• 桶：bucket 只接受 best30 / selection10 / new20（缺省 best30）；拼错 ⇒ 400。
• 两处合计口径不同：推成绩响应的 rating.before / after 把全部组（含 selection10）求和； 读侧 totals.total 只加 best30 + new20。两者不能互相校对，也都不是官方 Rating。

从 LXNS 迁移复制标题链接

落雪 API 的通用差异（认证、包络、端点、限速）见如果你熟悉落雪查分器 API 的开发。 这里只保留 chunithm 最容易被迁移写错的一处：Rating 由哪几个桶构成。

Player 字段对照复制标题链接

Score 字段对照复制标题链接

Rating 构成对照（最容易踩）复制标题链接

注意：RankHub 的 totals.total 是 best30 + new20 的桶内求和，不是官方「50 张平均」的 Rating； 两者量级不同（见「最佳成绩桶」）。

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

1. 桶合计不是玩家 Rating：buckets[].total / totals.total 是「和」；官方是「50 张平均」。
2. 两处合计口径不同：totals.total 只加 best30 + new20，而推成绩响应的 rating.before / rating.after 把全部组（含 selection10）一起求和。 两者不能互相校对，也都不是官方 Rating。
3. achievements 与 score 同值：本地游戏没有独立达成率字段，两者都填分数 （0~1,010,000）。不要把它当百分比。
4. rating 不是服务端算的：它是调用方给的值，服务端只存不算；缺 rating 时合计会 按 score 兜底（量级会爆），所以推成绩时务必给 rating。
5. difficulty 必须显式给：成绩键是 songId + difficulty；不传会被并成一键，多个难度塌成一条。
6. playTime 恒 null：原生 play_time 留在 native 里，统一字段不映射。
7. full_combo / full_chain 只在 native：且 fullchain=铂、fullchain2=金， 枚举字面与语义顺序不一致，不要按字面推断高低。
8. score.native 没有固定字段集合：键名由数据源决定，读之前先判空、再按候选键取。

相关复制标题链接

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