리더보드

자동 초기화, 지난 기간 보관, 서버 측 치트 방지를 갖춘 점수 순위입니다.

코드 주석과 API 이름은 SDK와 일치하도록 영어로 유지합니다.

이 페이지의 내용

리더보드 만들기
점수 제출
순위 조회
초기화와 이전 기간
치트 방지
서버에서 제출

리더보드 만들기#

프로젝트의 리더보드 페이지에서 리더보드를 만들고, 코드에서는 슬러그를 사용합니다.

설정	옵션
슬러그	코드에서 사용하는 소문자 식별자입니다. 예: `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}'