怎么传数据（速查）

建档、推成绩、改档案时到底该传哪套字段：RankHub 格式还是 native，每个游戏哪些字段必填、哪些不能传。

RankHub 的写入接口只认两种数据形状，二选一即可（也可以混用，native 优先）：

	RankHub 格式	游戏原生格式（`native`）
长什么样	顶层 `player` / `scores[]` 的 camelCase 字段	`player.native` / `scores[].native` 里放游戏原生对象
适合谁	你自己算好了字段、或从别处拿到归一数据	你手里直接是游戏存档 / 官方 API / 机台数据
谁做换算	你自己	服务端（每游戏一套固定规则）
身份 / 唯一键	顶层身份字段（必填）	仍然取顶层；native 里出现会被忽略或在 `PATCH` 时报 `400`

决策树

你手里的数据是什么？
├─ 已经是游戏原生对象（存档 / 官方 API / 机台导出）
│   ├─ 建档 → POST /v1/games/{game}/profiles      { player: { native: {...} } }
│   ├─ 推成绩 → POST .../profiles/{id}/scores     { scores: [ { native: {...} } ] }
│   └─ 改档案 → PATCH .../profiles/{id}           { native: {...} }
└─ 已经是你自己算好的归一字段
    ├─ 建档 → { player: { name, ...身份字段 } }
    ├─ 推成绩 → { scores: [{ songId, difficulty, score/rating, ... }] }
    └─ 改档案 → { name?, isPublic? }

请求示例

以 maimai 为例，同一件事两种写法（native 优先；顶层身份字段仍然必填）。

RankHub 格式

{ "player": { "friendCode": "1234567890123", "name": "Player" } }

游戏原生格式（native）

{ "player": { "native": { "friend_code": "1234567890123", "user_name": "Player" } } }

每游戏速查

游戏	建档身份字段（必填）	成绩唯一键（必填）	native 建档	native 成绩	详细
`maimai`	`friendCode` 或 `userId`	`songId` + `type` + `levelIndex`	支持（整份玩家对象）	支持机台载荷	maimai
`chunithm`	`friendCode`	`songId` + `difficulty`	支持（整份玩家对象）	—（只认 LXNS 兼容字段成绩）	chunithm
`arcaea`	`arcaeaId` + `character`	`songId` + `difficulty`	支持	支持	arcaea
`phigros`	`objectId`	`songId` + `difficulty`	支持	支持	phigros
`milthm`	`milthmUserId` + `region`	`songId`/`chartId`	支持	支持	milthm
`notanote`	`notanoteUid`	`chartKey`	支持	支持	notanote
`musedash`	`musedashUid`	`uid`	支持	支持	musedash
`rizline`	`playerId`	`trackId` + `difficulty`	支持	支持	rizline
`osu`	`osuUserId`	`songId`（beatmap id）	支持	支持	osu
`orzmic`	`externalId`	`songId` + `difficulty`	支持（整份玩家对象）	支持（原样进 `native`）	orzmic

身份字段与成绩唯一键不能通过 native 改；native 只负责其余字段（显示名、头像、名牌、potential、判定/评分等）。逐字段清单与示例见各游戏页的「原生数据（native）」与「写入（第三方）」。

每个游戏必给什么

游戏	`scores[]` 必给	单曲评分来源	比较值（只升不降）
`maimai`	`songId` + `achievements`（+`type`/`levelIndex`）	服务端算	`achievements`
`arcaea`	`songId` + `difficulty` + `score` + `clearType`	服务端算	`score`
`phigros`	`songId` + `difficulty` + `score` + `accuracy` + `rating`	调用方给	`score`
`milthm`	`songId` + `difficulty` + `score` + `accuracy` + `rating`	调用方给	`score`
`notanote`	`songId` + `difficulty` + `accuracy` + `rating`	调用方给	`score`
`musedash`	`songId` + `difficulty` + `score` + `accuracy` + `rating`	调用方给	`score`
`rizline`	`songId` + `difficulty` + `score` + `rating`	调用方给	`score`
`osu`	`songId` + `mode` + `rating`（pp）+ `accuracy` + `score`	调用方给	`rating`
`chunithm`	`songId` + `difficulty` + `rating` + `bucket`（建议带 `native`）	调用方给	`score`
`orzmic`	`songId` + `difficulty` + `rating` + `native`	调用方给	`score`

"必给" = 缺失会按 0/默认值落库并写出错误成绩（phigros 的 difficulty 不合法会直接 400）。字段精确类型/单位见各游戏格式页。

三条通用规则

native 与顶层字段同时出现时 native 优先；只给 native 时，顶层身份字段仍必须给。
非法值不静默丢弃：返回 400 common.invalidArgument，message 里带具体字段名（如 native.achievement）。
派生评分不代算：rating / rks / reality / nrk / performance 由你按既有契约给； maimai / arcaea 例外（服务端算）。

修改已有档案

PATCH /v1/games/{game}/profiles/{profileId}

可改 name / isPublic / native（native 里可放除身份字段外的所有展示字段）；身份字段变化 ⇒ 400。详见游戏档案 · 修改档案。

怎么传数据（速查）

决策树复制标题链接

请求示例复制标题链接

每游戏速查复制标题链接

每个游戏必给什么复制标题链接

三条通用规则复制标题链接

修改已有档案复制标题链接

本页内容

决策树

请求示例

每游戏速查

每个游戏必给什么

三条通用规则

修改已有档案