maimai

本页是 maimai（舞萌 DX）在 RankHub 上的字段级格式说明：建档要填什么、player / score 上有哪些统一字段、native 里装着哪些原生字段、机台原生成绩怎么写、单曲评分怎么算、最佳成绩怎么分桶。

Profile 格式复制标题链接

一条 profile = 一个 RankHub 用户的一张 maimai 档案。主键是对外的 profileId（uuid）， 不是机台侧的 friendCode / userId。

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

建档走 POST /v1/games/maimai/profiles，player 里至少要给出机台侧的两个标识之一：

• 两个标识必须至少给一个：都不给时该游戏既有服务返回 400（Either user_id or friend_code is required）。 单个字段本身都不是必填，所以格式端点把两者都标 required: false——「至少其一」这条约束只在响应 notes 与本页里表达。
• 重复身份 ⇒ 409（该身份已被占用）。
• courseRank / classRank / star 可以在建档时一起填（缺省 0），但它们不是身份， 填错不影响建号成败，只影响 player.native 的展示值。
• name 也是建档必填项，但它是统一字段（player.name）而不是身份键，所以不在上表；10 个游戏一致。

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

player.rating 是服务端按最佳成绩重算的整数（不是上游 dx_rating 的小数）， 与 GET .../bests 的 totals.total 同源；两者在曲库版本漂移时可能不一致（见文末「消费者注意事项」）。

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

player.native 是游戏原生格式的玩家块（camelCase）；机台原生玩家块里的收藏品（trophy / icon / name_plate / frame）不出现在读侧。

机台原生玩家块里的 trophy / icon / name_plate / frame（收藏品） 不出现在 player.native 里。

Score 格式复制标题链接

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

• type 取值 standard / dx / utage；utage（宴会场）不进最佳成绩桶。
• levelIndex 是 0~4 的整数：0=BASIC、1=ADVANCED、2=EXPERT、3=MASTER、4=Re:MASTER。
• 同一首曲的 standard 与 dx 谱面共用同一个 songId，靠 type 区分——只按 songId 合并会把两张谱面塌成一条。

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

统一字段复制标题链接

maimai 会填的统一字段（其余字段恒 null）：

恒为 null 的字段：score（maimai 没有「裸分」概念，DX 分在 dxScore）、difficulty （难度在 levelIndex + type）、native（见下）。

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

maimai 的 score.native 恒为 null：读侧只给统一字段，不透传原生对象（是 null，不是空对象）。

机台原生成绩另行支持：写入时可在 score item 里带 native（详见「写入（第三方）」），读取侧仍映射成上表字段。

原生字段与统一字段的对应复制标题链接

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

单曲 DX Rating 由「谱面定数 × 达成率 × 评级系数」决定，结果向下取整成整数：

single_rating = floor( level_value × min(achievements, 100.5) × coefficient / 100 )

• 我方系数表是14 档（按评级档一刀切），与社区口径（低分档细分、评级跃迁前的临界档、 Gen 3.5 的 AP+ +1）存在已知差异；这些差异只记录、不在本轮修，所以对外不要承诺「与机台完全一致」。

最佳成绩桶复制标题链接

GET /v1/games/maimai/profiles/{profileId}/bests 返回两个桶（按谱面版本二分）：

• totals.total = 两桶之和；totals.latest / totals.archive 分别是两桶的合计（不是条数）。
• 「最新版本」是数据驱动的（取曲库最大版本号），不是写死的版本常量。
• 桶内排序按 dx_rating 降序 → achievements 降序 → dx_score 降序；成员可能不足额（新号）。
• utage 谱面、曲库里查不到的谱面、disabled 曲目一律不进桶。

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

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

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

player 用上文的身份字段（friendCode / userId 至少一个）+ name，可另给 courseRank / classRank / star（缺省 0）。 可以同时带 scores[]：先建号、再落成绩，返回的 player.rating 已是重算后的值。身份重复 ⇒ 409。

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

curl -sS -X POST https://api.rankhub.cc/v1/games/maimai/profiles/$PROFILE_ID/scores \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "scores": [
      {
        "songId": 1234,
        "type": "dx",
        "levelIndex": 3,
        "achievements": 100.5125,
        "dxScore": 2500,
        "dxStar": 5,
        "fc": "ap",
        "fs": "fs",
        "playTime": "2026-10-20T12:00:00Z"
      }
    ]
  }'

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

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

native 是游戏原生格式：与 canonical 字段同时出现时 native 优先（游戏原生对象里没有的字段仍可走顶层）。

机台原生成绩（scores[].native）

• 越界 / 非整数（achievement 不在 0..1010000（普通谱）或 0..2020000（宴谱/BUDDY）、level 不在 0..4 且不为 10）⇒ 400 common.invalidArgument。
• dxStar 与 playTime 不是原生键：dxStar 在 native 路径恒写 0，playTime 走顶层字段。

可写字段

profile 的这些字段也可以用在 PATCH /v1/games/maimai/profiles/{profileId} 的 native 里，改完即时生效。 展示字段用 snake_case（course_rank / class_rank / star / name_plate），与 canonical 建档字段的 camelCase 不同。

不可改

• 身份字段：user_id / friend_code —— 与现值不同 ⇒ 400 common.invalidArgument（native.friendCode cannot be changed (identity field)）。
• 成绩唯一键：musicId + level 决定这行属于哪张谱面，native 里必须给；换了就是另一条成绩。

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

• 必给：songId + achievements。type / levelIndex 缺省 dx / 0 —— 不报错，但会写到错的谱面上。
• 比较值是 achievements（达成率），不是 dxScore：新值不更高 ⇒ 当前成绩不变。
• 谁算分：单曲 DX Rating 与总分都由服务端算（maimai / arcaea 属于这一类），scores[].rating 被忽略。
• 建档身份：friendCode 与 userId 至少给一个；同一身份重复建档 ⇒ 409。

从 LXNS 迁移复制标题链接

落雪 API 的认证、包络、端点、限速与通用坑见如果你熟悉落雪查分器 API 的开发， 这一节只保留 maimai 专有的字段对照（Player / Score / Best 50）。

Player 字段对照复制标题链接

// LXNS 返回的 Player（节选）
{ "name": "Player", "rating": 15234, "friend_code": 123456789012345,
  "course_rank": 0, "class_rank": 0, "star": 12 }

// RankHub 建档请求体（等价映射）
{ "player": { "name": "Player", "friendCode": "123456789012345",
              "courseRank": 0, "classRank": 0, "star": 12 } }

Score 字段对照复制标题链接

Best 50 结构对照复制标题链接

LXNS 的 GET .../bests 返回两个总分 + 两个列表（外加两个 selection 列表）：

{ "standard_total": 8000, "dx_total": 7234,
  "standard": [ /* Score[] */ ], "dx": [ /* Score[] */ ],
  "standard_selections": [ /* ... */ ], "dx_selections": [ /* ... */ ] }

RankHub 把它压成统一桶形状：

{ "game": "maimai", "computedAt": "…",
  "totals": { "total": 15234, "latest": 7234, "archive": 8000 },
  "buckets": [ { "key": "latest", "label": "当期", "total": 7234, "items": [] },
               { "key": "archive", "label": "往期", "total": 8000, "items": [] } ] }

想按单曲查成绩：LXNS 的 ?song_id=&song_type= 在 RankHub 没有对应查询参数 —— 直接拉 /scores（可按 difficulty 过滤，maimai 的 difficulty 传 levelIndex）后自行筛。

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

1. achievements 是百分比，不是 0~1：0~101.x，BUDDY 谱面到 202。直接乘除前先读本页。
2. 不要拿上游 dx_rating 覆盖 rating：maimai 的 rating 是服务端重算的整数； 上游小数精度在计算中被丢弃，两者可能差 1。
3. score 恒 null：maimai 没有「裸分」，比较与展示请用 achievements / dxScore。
4. score.native 恒 null：看不到原生 dx_rating / rate 原始值，只能读统一字段。
5. difficulty 恒 null：难度维度由 type + levelIndex 表达，level 只是展示标签。
6. totals.total 与 player.rating 同源但不同时刻：曲库版本变化（新曲入库/定数调整）会让 历史档案的展示值漂移；computedAt 是本次计算时刻。
7. 桶成员可能不足额：新档案或曲库缺失时 latest / archive 会少于 15 / 35 条，不要按 15/35 硬编码。
8. fc / fs 是档位字符串不是布尔：fc="ap" 表示 AP（不是「已全连」的真假）。

相关复制标题链接

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