Skip to main content
XBOX Game Development Kit(GDK)과 Steam 모두에서 업적은 이름, 설명, 아이콘, 현재 사용자에 대해 잠금 해제되었는지 여부, 그리고 선택적으로 완료까지의 진행도와 같은 정보를 가집니다. Steam은 또한 사용자의 진행을 미리 결정된 목표와 비교하고 이 목표를 초과할 때 업적을 잠금 해제하는 데 게임에서 사용되는 통계 API를 가지고 있습니다. 실제로 XBOX Game Development Kit(GDK)에는 두 개의 업적 API가 있습니다: 이벤트 기반(이전 명칭 Achievements 2013)과 타이틀 관리(이전 명칭 Achievements 2017). 두 시스템 모두 실행 가능한 옵션이지만, Steam에서 넘어왔다면 타이틀 관리 업적/통계가 훨씬 익숙할 것이며 게임에 이미 존재할 가능성이 높은 로직과 일치할 것입니다. 이런 이유로 이 항목에서는 그 API를 설명합니다. 두 API의 차이에 대한 자세한 내용은 이벤트 기반 vs. 타이틀 관리 업적을 참조하세요. 다음 섹션은 Steamworks API와 XBOX Game Development Kit(GDK) 간 업적의 차이를 설명합니다. 타이틀 관리 업적 API를 사용하려면 XBOX 서비스 Context 핸들을 생성해야 합니다. XblContextCreateHandle 함수와 XUserAddResult APIXUserHandle(사용자 인증과 소유권 항목 참조)을 사용해 이를 수행할 수 있습니다.

업적 진행 추적

Steam API에서는 ISteamUserStats::GetStat/ISteamUser::SetStat API를 사용해 사용자의 업적 진행을 추적할 수 있으며, Steam Stats API에 저장된 값이 현재 진행 값의 원본 소스가 됩니다. 타이틀 관리 업적에서는 게임이 유일한 원본 소스이며 사용자의 현재 진행을 자체적으로 추적해야 합니다. API 호출로 클라우드의 현재 진행을 업데이트하는 것은 일종의 “체크인”으로 수행되며, XBOX 생태계의 일부 표면에서 사용자의 진행을 보여주는 데 사용됩니다. 현재 진행 값이 어디에 존재해야 하는지에 대한 구체적인 지침은 없지만, 많은 게임이 세이브 파일(및 클라우드)에 저장하도록 선택하고, 다른 게임은 자체 백엔드 서비스에 저장할 수 있습니다. 클라우드와 게임의 내부 스탯 관리 시스템 간 값을 서로 동기화된 상태로 유지하세요.

모든 업적 열거

Steamworks API로 사용자의 모든 통계를 얻으려면 일반적으로 ISteamUserStats::RequestUserStats를 호출해 서버에서 최신 통계를 가져옵니다. 해당 콜백이 실행된 후, ISteamUserStats::GetStat/ISteamUserStats::GetAchievement 함수를 API 이름으로 사용해 각 업적을 반복하고 반환된 데이터를 사용해 게임 상태를 초기화할 수 있습니다. XBOX Game Development Kit(GDK)에서는 XblAchievementsGetAchievementsForTitleIdAsync 함수를 사용한 다음 XblAchievementsResultGetAchievements의 Out 매개변수로 제공된 배열의 각 업적 객체의 데이터를 사용해 게임 상태를 초기화할 수 있습니다. 각 업적은 XblAchievement 구조체로 제공됩니다. 이 구조체에 포함된 데이터에 대한 자세한 내용은 해당 레퍼런스 항목을 참조하세요.

Steamworks

XBOX Game Development Kit(GDK)

타이틀 관리 업적에 대한 자세한 내용은 타이틀 관리 업적 가져오기를 참조하세요.

업적의 진행 업데이트 및 업적 잠금 해제

XBOX Game Development Kit(GDK)과 Steam 모두에서 게임의 코드가 업적을 언제 잠금 해제할지 결정합니다. XBOX Game Development Kit(GDK)에서는 업적의 진행을 100으로 설정하면 잠금 해제됩니다. 다음 섹션은 두 API에서 지정된 업적에 대한 사용자 진행을 업데이트하는 데 필요한 단계를 설명합니다. 다음은 두 SDK에서 구현된 UpdateAchievement 메서드의 코드 예시이며, 업적 ID/API 이름(및 Steam의 스탯 API 이름), 업적을 증가시킬 양, 그 업적을 잠금 해제하기 위한 목표 값을 받아 그에 따라 업적의 진행과 잠금 해제 상태를 업데이트합니다.

Steamworks

XBOX Game Development Kit(GDK)

타이틀 관리 업적에 대한 자세한 내용은 타이틀 관리 업적 업데이트를 참조하세요.

오프라인 업적

XBOX 업적 잠금 해제는 네트워크 연결이 필요하지 않습니다. 사용자가 XBOX 네트워크(XBOX Live로도 알려짐)에 연결되어 있지 않다면 추가 코드 없이 나중에 서버와 자동으로 잠금 해제됩니다.

다른 사용자의 업적 가져오기

다른 사용자의 업적을 가져오려면, 업적을 가져올 사용자의 XBOX User ID(XUID)를 가지고 XblAchievementsGetAchievementsForTitleAsync/XblAchievementsGetAchievementAsync 함수를 호출하기만 하면 됩니다. 이는 Steam에서 ISteamUser::RequestUserStats, ISteamUserStats::GetUserStat, ISteamUserStats::GetUserAchievement 함수를 사용하는 것과 유사합니다.

업적 재설정

사용자의 모든 통계에 대한 진행을 재설정하는 데 사용할 수 있고, 지정된 경우 업적도 재설정할 수 있는 Steamworks API의 ISteamUserStats::ResetAllStats와 달리, XBOX Game Development Kit(GDK)에는 프로그래밍 방식으로 업적 진행이나 잠금 해제 상태를 재설정하는 문서화된 기능이 없습니다. XblAchievementsUpdateAchievementAsync를 진행 값 0으로 호출해도 진행 값은 변경되지 않습니다. 그러나 테스트할 때 이를 수행하기 위해 Player Data Reset 도구 (XblPlayerDataReset.exe)를 사용할 수 있습니다.

속도 제한

업적 진행을 업데이트할 때 XBOX Services API(XSAPI)를 너무 자주 호출하지 않도록 주의하세요. 그렇지 않으면 게임이 속도 제한에 걸릴 수 있습니다. 이는 예기치 못한 동작과 사용자에게 좋지 않은 경험을 초래할 수 있습니다. 자주 업데이트되는 통계를 추적하는 업적의 경우, API 호출을 특정 개수의 이벤트가 발생한 후 발행하거나 특정 시간 간격으로 서버에서 업데이트하도록 배치화해 보세요. XBOX services Trace Analyzer (XblTraceAnalyzer.exe)를 사용해 API 호출을 디버깅할 수 있습니다. XBOX 서비스에서의 속도 제한에 대한 자세한 내용은 세밀한 속도 제한을 참조하세요.
마지막 수정일 2026년 8월 24일