Orzmic

orzmic 属于本地文档存储族：整份档案是一个 JSON 文档，player.native 与 score.native 装的都是 上游原样对象，服务端不计算任何 rating。官方算法从未公开，社区与逆向实现之间存在冲突。

Profile 格式复制标题链接

一张 orzmic 档案 = 一个 RankHub 用户在 orzmic 上的一张卡，整份文档存在一行 JSON 里。对外主键是 profileId（uuid）。

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

• 缺失 ⇒ 400；服务端只落库；syncCapable 恒为 false；
• player.name 必填（展示名，可来自原生 name / userName / playerName / nickname）。

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

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

本地游戏的 player.native 是三层嵌套，不是扁平字段：

上游玩家块里值得注意的原生键：

Score 格式复制标题链接

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

统一字段复制标题链接

恒为 null（原生没有或无映射）：type、levelIndex、level、dxScore、dxStar、fc、fs、playTime。

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

除上面的常见键外，score.native 里可能还有调用方自己塞进来的任意键（原样存）。 本页只承诺上面几个稳定键的语义；其余字段的增减不视为破坏性变更。

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

单曲 Rating（社区 / 逆向口径，无官方文档）：单曲 Rating = 定数 + 分数补偿(mod) + 金/银加成

• 定数（Constant）：社区值域约 1.0 ~ 16.x，精度 0.1；
• mod 是分段函数，随 Score 变化。两个来源在分段边界上互相冲突，仅两处在 Score = 1,000,000 收敛：

• 金/银加成：ex_score = 0（金）为 +0.05（Score ≥ 1,000,000 时 +0.10）； ex_score = 1（银）为 +0.02（Score ≥ 1,000,000 时社区说 +0.05、逆向实现算 +0.04）；
• 单曲聚合：一首歌只贡献一个分数 —— 取它所有难度里最高的那个，四舍五入保留 3 位小数；
• 个人 Rating：社区现行口径是 floor2( Σ 单曲 Rating 前 30 / 30 )（向下取整保留 2 位小数）； 历史上长期是 b20，改成 b30 的确切版本未知。原生存档字段名叫 B30Scores，是「30 条」的旁证。

最佳成绩桶复制标题链接

GET /v1/games/orzmic/profiles/{profileId}/bests 的桶来自上游快照分组，不是服务端重新选桶：

• label 由桶键大写生成（best30 → BEST30）；
• 上游快照没有分组时会退化成单桶（key 为 best，label 取快照给的标签），保证 buckets 非空；
• totals.total：桶内各条 rating（缺失则 score）之和。它不是原生个人 Rating （那是前 N 名的平均）—— 两者量纲完全不同（和 vs 均值）。

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

请求体形状、idempotencyKey、批量上限、428/403 等通用规则见写入格式； 这里只写 orzmic 真正特殊的部分。

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

• 必给：songId + difficulty + rating + score + native。 服务端不做任何评分计算（rating 一律由调用方给 —— maimai / arcaea 之外的游戏都是这样，只有那两者服务端算）， rating 不给就是 null（桶内排序会退化成按 score）。
• 比较值是 score；同一 (songId, difficulty) 只有分数更高才会覆盖。
• difficulty 原样字符串化：1=Special / 2=Hard / 3=Normal / 4=Easy，数值不是顺序，1 最难。
• bucket 是固定词汇：只接受 best30，拼错直接 400 orzmic best bucket must be one of best30（不是默默归桶）。
• 不会重算玩家头部：推送只补成绩，不改 player / summary（player.rating 需要你自己维护或重新建档）。
• 409：本地游戏一个用户只能有一份未解绑档案 ⇒ 重复建档返回 orzmic profile already exists for this identity （重复调用请改用推成绩）。
• 通用上界（写入守卫开启时生效，默认 off）：score 越界 400，rating 越界或 playTime 晚于现在 1 小时 422。

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

对 orzmic 来说，native 就是那条上游成绩 JSON 本身：服务端按既有推送契约挑出必要字段， 并把整份对象原样存进成绩的 native（读侧 score.native 就是它）。

• 可写字段（native，除身份与唯一键外全部）：profile 侧 name / userName / playerName / nickname （→ name）+ 其余任意键（建档或 PATCH /v1/games/orzmic/profiles/{profileId} 的 native， 其余键原样进 playerJson，读回 player.native.player.<键>）；score 侧除 song_id + difficulty 外的全部键。
• 不可改：身份 externalId —— PATCH 的 native 里给了不同的 externalId / external_id ⇒ 400， message = native.externalId cannot be changed (identity field)；成绩唯一键 song_id + difficulty 顶层与 native 都给时必须一致，不一致以 native 为准（会写到另一张谱面上）。

示例（示意数据） —— 一条推成绩请求（原生格式）：

curl -sS -X POST https://api.rankhub.cc/v1/games/orzmic/profiles/$PROFILE_ID/scores \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scores": [
      {
        "native": {
          "music_id": 10023,
          "difficulty": "2",
          "score": 1004820,
          "rating": 15.83,
          "play_status": 2,
          "ex_score": 0
        }
      }
    ]
  }'

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

1. rating 不是服务端算的：来自写入方/上游，服务端只排序、只落库。要拿「官方 Rating」得自己按社区公式算，或让写入方带上。
2. totals.total 是桶内求和，不是原生个人 Rating：原生是前 N 名的平均，这里是和，差 N 倍。
3. achievements 与 score 同源，且 orzmic 满分是 1,000,000 + 物量，score 会大于 1,000,000 —— 当百分比用会错。
4. 难度编码不是顺序：1 = Special、2 = Hard、3 = Normal、4 = Easy，1 是最难的，直接当数组下标会全错。
5. 曲目键名有 4 个候选（song_id / id / music_id / songId），服务端按顺序猜；同一档案里可能混着两种拼法。
6. bucket 是固定词汇：只接受 best30；拼错会 400（不是默默丢进 best30）。
7. playTime 恒为 null，rank 通常也是 null。
8. 桶的成员关系由游戏决定：社区公式不重新选桶，本平台也不重选（只在推成绩时按评分降序截断到 30）。
9. 没有同步能力：syncCapable 恒 false，数据只能靠建档后的推成绩或重新导入维护。
10. 推成绩时 native 原样存：服务端把它与 song_id / difficulty / score / rating 合并写进成绩存储， 读回的 native 是「你的 native + 这几个补齐键」。

相关复制标题链接

• 游戏数据格式总览：三层模型、统一字段语义、null 与量纲规则
• 怎么传数据（速查）：先判断用 RankHub 格式还是原生格式
• 游戏档案：读取、建档、删除申请
• 成绩读取与写入：成绩列表、批量写入、最佳成绩
• 其他游戏：notanote · musedash · rizline · osu