> For the complete documentation index, see [llms.txt](https://docs.overdare.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overdare.com/korean/manual/script-manual/advanced-gameplay-systems/worldrankservice.md).

# 앱 리더보드

## 개요

게임 플레이를 통해 획득한 킬 수, 보유 포인트 등 주요 지표를 점수로 변환해 **WorldRankService의 리더보드**에 등록할 수 있습니다.

등록된 점수와 랭크는 **앱(아웃게임)과 인게임(월드)** 모두에서 확인 가능하며, 이를 통해 플레이어 간의 경쟁심을 높이고, 월드의 참여도와 전반적인 활성화를 크게 향상시킬 수 있습니다.

## 사용 방법

### 랭크 시스템 활성화 및 아이콘 설정

월드 관리 페이지 하단의 Ranking System 항목에서 랭크 시스템 사용 여부와 랭크 아이콘을 설정할 수 있습니다.

<figure><img src="/files/mmMugyBN6pfhoF3OgBvh" alt=""><figcaption></figcaption></figure>

* 1️⃣ 랭크 시스템 활성화
  * true로 설정하면 앱(아웃게임)과 인게임에서 랭크가 표시되며, 플레이 점수가 기록됩니다.
  * false로 설정하면 랭크가 표시되지 않으며, 점수 기록 요청 또한 처리되지 않습니다.
* 2️⃣ 랭크 아이콘
  * 랭크를 표시할 아이콘을 설정합니다.
  * 메달, 축구공, 해골 등 게임의 콘셉트와 성격에 맞는 아이콘을 선택할 수 있습니다.
  * 기본 제공 아이콘 외에도 120 × 120 픽셀의 PNG 이미지를 사용하여 커스텀 아이콘을 설정할 수 있습니다.

### 기능 목록

다음 기능은 **서버 스크립트**에서만 사용할 수 있으며, 클라이언트에서는 호출할 수 없습니다.

<table><thead><tr><th width="390">기능</th><th>설명</th></tr></thead><tbody><tr><td>WorldRankService:IncrementScore(player, delta)</td><td>지정한 player의 점수 변화량을 리더보드에 등록합니다. 점수는 정수만 허용되며, 변화량은 양수만 입력할 수 있습니다. 입력 가능한 최대 변화량은 100,000이며, 이 값을 초과한 요청은 처리되지 않습니다.</td></tr><tr><td>WorldRankService:GetScore(player)</td><td>리더보드에 등록된 해당 player의 현재 점수를 반환합니다.</td></tr><tr><td>WorldRankService:SetDisplayEnabled(bool)</td><td>캐릭터 상단에 순위와 점수를 표시할지 여부를 설정합니다.</td></tr><tr><td>WorldRankService:GetDisplayEnabled()</td><td>캐릭터 상단에 순위와 점수를 표시하도록 설정되어 있는지 여부를 반환합니다.</td></tr></tbody></table>

### 점수 정렬

리더보드의 점수는 항상 **내림차순으로 정렬**되며, 이 정렬 방식은 변경할 수 없습니다.

### 전체 코드 예시

다음 코드는 게임 종료 시점을 기준으로, 플레이어가 게임 진행 중에 획득한 **추가 점수**를 WorldRankService 리더보드에 등록하고, 등록된 **최종 점수**를 불러와 ResultUI에 표시하는 예시입니다.

IncrementScore 함수는 리더보드에 최종 점수 전체가 아닌 **‘증가한 점수의 변화량’**&#xC744; 전달하므로, 사용 시 이 점을 반드시 유의해야 합니다.

```lua
local WorldRankService = game:GetService("WorldRankService")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local UIRemoteEvent = ReplicatedStorage:WaitForChild("UIRemoteEvent")

local function EndRound(player, eventName, delta)
    print(player, eventName)	
	
		WorldRankService:IncrementScore(player, delta)
		
		local score = WorldRankService:GetScore(player)
		UIRemoteEvent:FireClient(player, "SendMyScoreToResultUI", score)
end
```

### 퍼블리시 및 테스트 환경의 동작 차이

퍼블리시 후 모바일 환경에서는 실제 서버에 데이터를 저장하고 불러옵니다. 반면, 스튜디오 테스트 환경에서는 해당 기능이 동작하지 않으며, 호출 시 `WorldRank API is not available in the editor. It only works in the live game environment.` 로그가 출력됩니다.

## 순위 및 점수 표시

리더보드에 플레이어의 점수가 등록되어 있는 경우, 캐릭터 상단에 현재 순위와 점수가 표시됩니다.

점수가 변경된 후에는 **월드에 다시 접속**해야 최신 정보로 갱신되어 표시됩니다.

<figure><img src="/files/FmrBjZcF33yEE9AsPuTS" alt=""><figcaption></figcaption></figure>

앱(아웃게임)에서는 월드 상세 화면에 **Top Scorer** **섹션**이 노출되며, 해당 월드의 플레이어 순위와 점수가 리스트 형태로 표시됩니다.

<figure><img src="/files/TybmXnLN15y09Uu4FwkX" alt=""><figcaption></figcaption></figure>

## 활용 예시

* 처치 수 등을 점수화해 리더보드에 등록하여 경쟁 요소를 강화할 수 있습니다.
* 월드 입장 전 아웃게임 Top Scorer 섹션을 통해 “이 월드의 상위 플레이어는 이 정도 점수를 달성했다”와 같은 목표 의식을 제공할 수 있습니다.
* 누적 점수를 활용해 스킨/코스튬 등 보상을 제공하는 경제 구조를 만들면 장기 플레이 유도 효과를 기대할 수 있습니다.
* 기간 한정 이벤트에서 누적 포인트를 집계해 상위권 플레이어에게 보상을 지급하는 방식으로 월드 참여도를 높일 수 있습니다.

## 주의 사항

* 리더보드에 전달되는 값은 최종 점수 전체가 아닌, **증가한 점수의 변화량**입니다.
* 리더보드에 등록된 점수는 **차감**하거나 **삭제(초기화)**&#xD560; 수 없습니다.