排行榜

分数排名，支持自动重置、历史周期归档和服务器端防作弊。

代码注释和 API 名称保留英文，以便与 SDK 保持一致。

本页内容

创建排行榜
提交分数
读取排名
重置和历史周期
防作弊
从服务器提交

创建排行榜#

在项目的排行榜页面中创建排行榜，并在代码中使用其标识符。

设置	选项
标识符（slug）	代码中使用的小写标识符，例如 `coins`。
排序方式	`DESC`（从高到低）或 `ASC`（从低到高，例如竞速用时）。
分数模式	`BEST` 保留每位玩家的最佳分数；`LATEST` 总是用新分数替换。
重置	`NONE`、`DAILY`、`WEEKLY` 或 `MONTHLY`。
最低 / 最高分数	可接受的最低和最高分数（可选）。
提交冷却时间	同一玩家两次提交之间的最短秒数（可选）。

提交分数#

玩家名称来自账号，因此客户端无法替他人提交分数。

var submit = await Majacloud.Leaderboards.SubmitScoreAsync("coins", 340);
if (submit.Ok && submit.Value.Accepted)
    Debug.Log("New rank #" + submit.Value.Entry.Rank);

GDScript

var submit := await Majacloud.leaderboards.submit_score("coins", 340)
if submit.ok and submit.value.accepted:
	print("New rank #", submit.value.entry.rank)

JavaScript

const submit = await mc.leaderboards.submitScore('coins', 340);
if (submit.ok && submit.value.accepted) console.log('New rank #' + submit.value.entry.rank);

curl

curl -X POST https://majacloud.majanite.com/v1/leaderboards/coins/scores -H "X-Project-ID: $PROJECT_ID" -H "X-Client-Key: $CLIENT_KEY" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"score": 340}'

读取排名#

读取排名靠前的条目无需登录；读取玩家自己的排名及其附近的条目则需要玩家已登录。

var top = await Majacloud.Leaderboards.GetTopAsync("coins", limit: 10);
var me = await Majacloud.Leaderboards.GetMyRankAsync("coins");
var around = await Majacloud.Leaderboards.GetAroundMeAsync("coins", radius: 3);

if (me.Ok && me.Value.Entry != null) Debug.Log("You are #" + me.Value.Entry.Rank + " of " + me.Value.Total);

GDScript

var top := await Majacloud.leaderboards.get_top("coins", 10)
var me := await Majacloud.leaderboards.get_my_rank("coins")
var around := await Majacloud.leaderboards.get_around_me("coins", 3)

if me.ok and me.value.entry != null:
	print("You are #%d of %d" % [me.value.entry.rank, me.value.total])

JavaScript

const top = await mc.leaderboards.getTop('coins', { limit: 10 });
const me = await mc.leaderboards.getMyRank('coins');
const around = await mc.leaderboards.getAroundMe('coins', { radius: 3 });

if (me.ok && me.value.entry) console.log(`You are #${me.value.entry.rank} of ${me.value.total}`);

curl

curl "https://majacloud.majanite.com/v1/leaderboards/coins/entries?limit=10" -H "X-Project-ID: $PROJECT_ID" -H "X-Client-Key: $CLIENT_KEY"
curl https://majacloud.majanite.com/v1/leaderboards/coins/me -H "X-Project-ID: $PROJECT_ID" -H "X-Client-Key: $CLIENT_KEY" \
  -H "Authorization: Bearer $TOKEN"
curl "https://majacloud.majanite.com/v1/leaderboards/coins/around-me?radius=3" -H "X-Project-ID: $PROJECT_ID" -H "X-Client-Key: $CLIENT_KEY" \
  -H "Authorization: Bearer $TOKEN"

重置和历史周期#

每日、每周（周一）和每月排行榜在 00:00 UTC 重置。已结束的周期会被归档；可通过 previous 周期读取：

var yesterday = await Majacloud.Leaderboards.GetTopAsync("coins", 10, 0, MajacloudLeaderboardPeriod.Previous);

GDScript

var yesterday := await Majacloud.leaderboards.get_top("coins", 10, 0, "previous")

JavaScript

const yesterday = await mc.leaderboards.getTop('coins', { limit: 10, period: 'previous' });

curl

curl "https://majacloud.majanite.com/v1/leaderboards/coins/entries?period=previous" -H "X-Project-ID: $PROJECT_ID" -H "X-Client-Key: $CLIENT_KEY"

保留多少个历史周期，以及排行榜返回多少条目，取决于套餐（参见限制）。

防作弊#

超出最低或最高分数的分数会被拒绝，并返回 validation。
提交频率超过冷却时间限制时会返回 rate_limited。
客户端只能为已登录的玩家提交分数。
对于竞技类游戏，请由你的服务器决定分数，并使用私密密钥提交。

从服务器提交#

使用私密密钥时，发送 player_id 和分数。该玩家必须已存在。

JavaScript

// Node.js with secretKey: submit after your server validated the match
await admin.server.submitScore('coins', 'player_3f9c…', 980);

curl

curl -X POST https://majacloud.majanite.com/v1/leaderboards/coins/scores \
  -H "X-Project-ID: $PROJECT_ID" -H "X-Secret-Key: $SECRET_KEY" \
  -H "Content-Type: application/json" -d '{"player_id": "player_3f9c…", "score": 980}'