2025-05-19

---

Steamworks API 활용하기

스팀에 연동되는 리더보드를 구현하기 위해 Steamworks API 를 사용하는 과정을 정리해보았다.

Unity 와 Steamworks.NET 을 활용한 내용이며,
Facepunch.Steamworks 를 기반으로 한 프로젝트를 기준으로 한다.

Steamworks - Leaderboard 를 참고하였다.

• 이름 : 관리할 순위표의 이름
• 커뮤니티 이름 : 순위표를 커뮤니티 허브에 표시할 경우, 공개할 이름
• 정렬 방법 : 오름차순, 내림차순
• 표시 유형 : 순위표에 표시할 데이터의 종류 (숫자, 초 , 밀리 초)
• 쓰기 : Trusted (클라이언트가 순위표를 설정할 수 없고, Web API 를 통해서만 설정 가능)
• 읽기 : 친구 (Friends) 로 설정하면 사용자의 친구만 순위표를 읽을 수 있다.

---

1. 리더보드 생성하기

Steamworks 파트너 페이지에서 리더보드를 생성해야 한다.

Steamworks > 앱 선택 > Features > Leaderboards 메뉴로 이동하자.

리더보드 이름, 정렬 방식, 점수 저장 방식 등을 설정할 수 있다.
(이 설정은 Unity 코드에서도 동일하게 사용되어야 한다.)

2. Unity에서 리더보드 불러오기

Facepunch 기반으로 리더보드를 요청하려면, 아래와 같은 코드를 사용한다.

var leaderboard = await SteamUserStats.FindOrCreateLeaderboardAsync(
difficulty, LeaderboardSort.Descending, LeaderboardDisplay.Numeric);

리더보드의 이름 / 정렬 방법(오름차순, 내림차순) / 정렬 타입 (정수 값, 초 단위, 밀리 초 단위)

3. 리더보드에 점수 등록하기

리더보드에 유저의 점수와 유저의 국가 이미지를 표시해주기 위해
Facepunch.Steamworks 를 사용하였다.

또한, 기록되어 있는 점수보다 높을 때만 순위표에 업데이트하는 방식이다.

var result = await leaderboards[difficulty].Value.SubmitScoreAsync(score, details);

4. 점수 가져오기

상위 10명의 점수만을 가져와 UI 에 랭킹을 표시해준다.

var entries = await leaderboards[difficulty].Value.GetScoresAsync(10);

5. 주의할 점

Steam API 를 활용하기 위해서는 스팀 클라이언트가 연결된 상태여야 한다.

이를 위해

LeaderboardManager

• UI 상에서 리더보드 데이터를 받아와 유저에게 보여주기
• 국가 코드 데이터와 Web API 를 통해 유저의 국가 이미지를 받아와 출력하기

SteamworksManager

• 게임 시작 시, Steam 과 연동
• 리더보드 데이터를 요청
• 점수 업로드

로 구조를 나누었다.

---

결과물

Steamworks 리더보드

Easy 난이도 리더보드 (내 데이터가 있는 경우, 현재 순위 및 점수 표시)

Normal 난이도 리더보드 (내 데이터가 없는 경우, 0위로 표시)

---