Skip to content
스토어 연동
마지막 업데이트

기본 연동

1. 연동 준비

이 장에서는 신규 C API 를 쓰기 전에 알아 두어야 할 공통 규칙을 설명해요. 패키지 구성, 프로젝트 설정, 파라미터 객체를 만들고 해제하는 규칙, 결과 확인, 비동기 콜백, 문자열 규칙, 호출 형식을 차례로 다뤄요. 2장부터 나오는 모든 예제가 이 규칙을 전제로 하니 먼저 읽어 주세요.

설명에 나오는 코드는 모두 예제 게임 Brick Smash 의 실제 소스에서 가져왔어요. 어느 파일의 코드인지는 설명에 밝혀 두었어요.

패키지 구성

PCSDK 다운로드 페이지에서 StovePCSDK_Full_C_3.5.3.0_x64.zip 을 내려받아 압축을 풀면 다음 구조예요. Brick Smash 는 이 구조를 그대로 third_party/StovePCSDK 에 두고 써요.

text
StovePCSDK
├ Include
│ ├ stove_api.h
│ ├ base_api.h
│ ├ base_types.h
│ ├ base_misc.h
│ ├ base_flat_api.h
│ ├ base_guard.h
│ ├ game_support_api.h / game_support_types.h / game_support_misc.h / game_support_flat_api.h
│ ├ iap_api.h / iap_types.h / iap_misc.h / iap_flat_api.h
│ ├ log_api.h / log_types.h / log_misc.h / log_flat_api.h
│ ├ ownership_api.h / ownership_types.h / ownership_misc.h / ownership_flat_api.h
│ ├ pcbang_*.h
│ └ view_*.h
├ lib
│ └ x64
│   └ BaseSDK.lib
└ dll
  └ x64
    └ BaseSDK.dll
파일설명
Include/stove_api.h우산 헤더예요. 이 헤더 하나만 include 하면 모든 모듈의 공개 API 가 들어와요.
Include/<모듈>_api.h모듈의 함수 선언이에요(예: Stove_FetchOwnerships).
Include/<모듈>_types.h모듈의 인터페이스(IStove 로 시작하는 이름)와 콜백 형식이에요.
Include/<모듈>_misc.h모듈의 열거형과 결과 코드예요.
Include/<모듈>_flat_api.h인터페이스의 메서드를 C 함수로 펼쳐 놓은 선언이에요. 호출 형식 2가지에서 설명해요.
Include/base_guard.hC++ 전용 RAII 도우미예요. 선택 사항이에요. RAII 도우미에서 설명해요.
lib/x64/BaseSDK.lib링크할 임포트 라이브러리예요.
dll/x64/BaseSDK.dll게임 실행 파일 옆에 두는 SDK 본체예요.

헤더에는 Base, GameSupport, IAP, Log, Ownership, PCBang, View 7개 모듈이 들어 있어요. 이 가이드는 스토어인디 게임이 쓰는 Base, Ownership, GameSupport, IAP 를 다뤄요. PCBang 과 View 모듈의 함수는 헤더에 보이더라도 스토어인디 게임에서 호출하지 않아요.

프로젝트 설정

지원 환경은 Windows 64비트(x64), C++17 이상이에요. Visual Studio 2022 를 권장해요. 32비트(x86) 연동이 필요하면 기술지원으로 문의해 주세요.

Visual Studio 프로젝트에는 다음을 설정해요.

설정 위치값
구성 속성 > C/C++ > 일반 > 추가 포함 디렉터리패키지의 Include 디렉터리 경로
구성 속성 > 링커 > 일반 > 추가 라이브러리 디렉터리패키지의 lib\x64 디렉터리 경로
구성 속성 > 링커 > 입력 > 추가 종속성BaseSDK.lib
빌드 후 이벤트dll\x64\BaseSDK.dll 을 실행 파일과 같은 폴더로 복사

소스 코드에서는 우산 헤더 하나만 include 해요.

cpp
#include "stove_api.h"

Brick Smash 는 Visual Studio 솔루션(BrickSmash.sln)과 CMake 프로젝트(CMakeLists.txt) 2가지를 함께 제공해요. 솔루션은 SDL3 와 Dear ImGui 바이너리까지 third_party 에 들어 있어서 CMake 나 vcpkg 없이 Visual Studio 2022 에서 바로 열어 빌드할 수 있어요. 두 프로젝트의 설정은 같고, BrickSmash.vcxproj 의 포함 디렉터리 · 추가 종속성 · 빌드 후 이벤트가 위 표와 하나씩 대응돼요. 다음은 같은 설정을 담은 CMakeLists.txt 의 발췌예요.

cmake
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

set(STOVE_SDK_DIR ${CMAKE_SOURCE_DIR}/third_party/StovePCSDK)

target_include_directories(BrickSmash PRIVATE
    ${CMAKE_SOURCE_DIR}/src
    ${STOVE_SDK_DIR}/Include
)

target_link_libraries(BrickSmash PRIVATE
    SDL3::SDL3
    imgui::imgui
    ${STOVE_SDK_DIR}/lib/x64/BaseSDK.lib
)

add_custom_command(TARGET BrickSmash POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_if_different
        ${STOVE_SDK_DIR}/dll/x64/BaseSDK.dll $<TARGET_FILE_DIR:BrickSmash>
)

Brick Smash 는 소스 파일을 UTF-8 로 저장하기 때문에 target_compile_options 에 /utf-8 도 지정했어요. 한글 문자열 리터럴을 L"..." 로 쓰는 프로젝트라면 소스 파일 인코딩과 컴파일러 옵션을 맞춰 주세요.

SDK 는 스토브 런처가 있어야 동작하기 때문에, 개발 PC 에도 런처가 설치되어 있어야 해요. 런처 없이 실행하면 2장의 런처 실행 확인 단계에서 런처가 게임을 다시 실행해요.

신규 API 의 특징

신규 API 는 Stove_ 로 시작하는 함수와 IStove 로 시작하는 인터페이스로 이루어져 있어요. ANSI C 에서도 쓸 수 있도록 만들어서, 다른 언어의 바인딩에도 적용할 수 있어요.

3.5.0 부터 PC SDK 는 하나의 바이너리로 합쳐졌어요. 연동할 때 알아 두어야 할 특징은 다음과 같아요.

항목내용
배포 파일BaseSDK.dll 과 BaseSDK.lib 하나씩이에요. 모듈별 dll 과 lib 는 따로 넣지 않아요.
헤더우산 헤더 stove_api.h 하나만 include 하면 모든 모듈의 공개 API 가 들어와요.
함수모든 공개 함수는 Stove_ 로 시작해요. 모듈 이름이 함수 이름에 들어가지 않아요(예: Stove_FetchOwnerships).
데이터 형식파라미터와 결과는 IStove 로 시작하는 인터페이스예요(예: IStoveUser, IStoveOwnershipList). 값은 Get · Set · Is 로 시작하는 메서드로 읽고 써요.
초기화와 종료Stove_Initialize() 한 번으로 소유권 · 업적 · 결제 · 로그 기능을 모두 쓸 수 있고, 종료도 Stove_Uninitialize() 하나예요. 모듈별 초기화 함수는 없어요.
콜백 처리모든 비동기 함수의 콜백은 Stove_RunCallback() 을 호출한 스레드에서 실행돼요.

파라미터 객체 만들기와 해제하기

ANSI C 환경에서도 쓸 수 있어야 하기 때문에, 신규 API 는 DLL 경계를 넘나드는 객체의 메모리를 SDK 가 직접 관리해요. 게임이 new 로 파라미터를 만들지 않고 Stove_CreateParam() 으로 SDK 에 만들어 달라고 요청하고, 다 쓰면 Destroy() 로 돌려줘요.

값을 넘겨야 하는 함수는 파라미터를 인터페이스 객체로 받아요. 파라미터를 쓰는 순서는 다음과 같아요.

  1. Stove_CreateParam(kind) 를 호출해 파라미터 객체를 만들어요. kind 에는 만들 파라미터의 종류 값(k_EStove*TypeKind_*Param)을 넣어요.
  2. 반환값이 nullptr 인지 확인해요. 종류 값이 잘못되었거나 파라미터가 아닌 종류를 넣으면 오류 대신 nullptr 이 반환돼요.
  3. 반환형이 IStoveTypeBase* 이므로 해당 파라미터 인터페이스로 형 변환해요.
  4. Setter 로 값을 채워요.
  5. 함수를 호출해요.
  6. 호출이 반환되면 바로 Destroy() 해요. 비동기 함수라도 콜백을 기다릴 필요가 없어요.

이 가이드에서 쓰는 파라미터 종류 값은 다음과 같아요.

종류 값만들어지는 인터페이스쓰는 함수
k_EStoveBaseTypeKind_RestartAppIfNecessaryParamIStoveRestartAppIfNecessaryParamStove_RestartAppIfNecessary
k_EStoveBaseTypeKind_InitializeParamIStoveInitializeParamStove_Initialize
k_EStoveBaseTypeKind_SetGameProfileParamIStoveSetGameProfileParamStove_SetGameProfile
k_EStoveGameSupportTypeKind_FetchStatParamIStoveFetchStatParamStove_FetchStat
k_EStoveGameSupportTypeKind_SetStatParamIStoveSetStatParamStove_SetStat
k_EStoveGameSupportTypeKind_FetchAchievementParamIStoveFetchAchievementParamStove_FetchAchievement
k_EStoveGameSupportTypeKind_FetchAchievementsParamIStoveFetchAchievementsParamStove_FetchAchievements
k_EStoveGameSupportTypeKind_FetchRankingParamIStoveFetchRankingParamStove_FetchRanking
k_EStoveIAPTypeKind_FetchProductsParamIStoveFetchProductsParamStove_FetchProducts
k_EStoveIAPTypeKind_OrderProductParamIStoveOrderProductParamStove_StartPurchase(상품 1개분 주문 정보)
k_EStoveIAPTypeKind_PurchaseParamIStovePurchaseParamStove_StartPurchase(결제 진행 방식)
k_EStoveIAPTypeKind_StartPurchaseParamIStoveStartPurchaseParamStove_StartPurchase
k_EStoveIAPTypeKind_ConfirmPurchaseParamIStoveConfirmPurchaseParamStove_ConfirmPurchase
k_EStoveLogTypeKind_SendLogParamIStoveSendLogParamStove_SendLog

파라미터 자리가 const IStoveTypeBase* param 으로 선언된 함수(Stove_FetchOwnerships · Stove_ShutdownNotification · Stove_OverImmersionNotification 등)는 SDK 가 쓰지 않는 인자라 nullptr 을 넘겨요.

해제 규칙

SDK 와 게임 사이를 오가는 객체는 모두 IStoveTypeBase 를 상속해요. 객체마다 누가 해제하는지가 정해져 있고, 규칙은 다음 한 문장으로 정리돼요.

게임이 받아서 갖게 된 객체는 게임이 Destroy() 하고, 콜백 인자로 잠시 빌려받은 객체는 해제하지 않아요.

객체예해제
Stove_CreateParam 으로 만든 파라미터IStoveInitializeParam*호출이 반환되면 게임이 Destroy() 해요.
동기 함수가 반환한 결과Stove_Initialize · Stove_GetUser 등이 반환한 IStoveResult*확인이 끝나면 게임이 Destroy() 해요.
out 파라미터로 받은 객체Stove_GetUser 의 IStoveUser*, Stove_GetGds 의 IStoveGds*, Stove_GetSignin 의 IStoveSignin*호출이 성공했든 실패했든 nullptr 이 아니면 값을 다 읽은 뒤 게임이 Destroy() 해요.
콜백 인자IStoveCallbackResult*, 콜백의 두 번째 인자(outcome · 목록 · 정보 객체), 그 안에서 꺼낸 객체SDK 가 소유해요. Destroy() 하지 않아요.

해제해야 하는지 헷갈리면 ShouldDestroy() 로 확인할 수 있어요. true 이면 게임이 정확히 한 번 Destroy() 하고, false 이면 SDK 가 관리하는 객체라 해제하지 않아요. ShouldDestroy() 를 항상 검사해서 true 일 때만 Destroy() 하면, 해제를 빠뜨리는 실수와 같은 객체를 두 번 해제하는 실수를 모두 막을 수 있어요.

해제를 빠뜨리면 메모리가 새요. SDK 소유 객체를 Destroy() 하거나 같은 객체를 두 번 Destroy() 하면 프로그램이 비정상 종료될 수 있어요.

도우미 없이 직접 해제하면 이런 모양이에요. 아래는 Brick Smash 가 쓰는 방식이 아니라, 해제 규칙을 보여 주는 원시 형태의 예시예요.

cpp
IStoveRestartAppIfNecessaryParam* param = static_cast<IStoveRestartAppIfNecessaryParam*>(
    Stove_CreateParam(k_EStoveBaseTypeKind_RestartAppIfNecessaryParam)); // 생성
if (param != nullptr)
{
    param->SetGameId(L"YOUR_GAME_ID");                                            // Setter
    Stove_RestartAppIfNecessary(param, OnRestartAppIfNecessaryFinished, nullptr); // 호출
}
if (param != nullptr && param->ShouldDestroy()) param->Destroy();                 // 해제

RAII 도우미

위처럼 해제 코드를 매번 쓰다 보면 중간에 return 하는 경로에서 해제를 빠뜨리기 쉬워요. 그래서 패키지에 base_guard.h 가 들어 있어요. 이 헤더는 다음 특징이 있어요.

  • 선택 사항이에요. 쓰지 않아도 모든 API 를 쓸 수 있어요.
  • C++ 전용이에요. 순수 C 프로젝트에서 include 하면 컴파일 오류가 나요.
  • 헤더만으로 동작해요. 추가로 링크할 라이브러리가 없어요.
  • 우산 헤더 stove_api.h 와 별개의 헤더라서, 쓰려면 #include "base_guard.h" 를 따로 추가해요.
도우미역할
StoveMakeParam<T>()파라미터 객체를 만들어요. T 는 IStoveInitializeParam 처럼 만들 인터페이스예요. 종류 값을 직접 넘기거나 형 변환할 필요가 없어요. SDK 가 만들지 못하면 비어 있는 StoveGuard 를 돌려줘요.
StoveGuard<T>객체를 들고 있다가 범위를 벗어나면 ShouldDestroy() 를 확인하고 Destroy() 해요. out 파라미터를 받을 때는 Put() 으로 주소를 넘겨요. IsValid() 로 비어 있는지 확인하고, Get() 으로 원시 포인터를 꺼내고, -> 로 메서드를 바로 호출해요.
StoveResultGuard동기 함수가 반환한 IStoveResult* 를 들고 있다가 범위를 벗어나면 해제해요. if (result) 는 호출이 성공했는지를 뜻하고, 결과 객체가 없는 경우도 실패로 처리해요. GetResultCode() 로 결과 코드를 읽어요.

StoveGuard 는 SDK 소유 객체를 잘못 감싸도 ShouldDestroy() 가 false 이면 아무것도 하지 않아서, 이중 해제가 일어나지 않아요.

Brick Smash 는 이 도우미를 써요. 다음은 src/stove/StoveSession.cpp 의 Begin() 에서 파라미터를 만들고 호출하는 부분이에요.

cpp
auto param = StoveMakeParam<IStoveRestartAppIfNecessaryParam>();
if (!param.IsValid())
{
    Fail("Stove_CreateParam(RestartAppIfNecessaryParam) 실패");
    return;
}
param->SetEnvironment(cfg.environment.c_str()); // L"SANDBOX" 또는 L"LIVE"
param->SetGameId(cfg.game_id.c_str());
param->SetAppKey(cfg.app_key.c_str());
param->SetWaitTimeMilliSec(60000);  // 런처 응답을 기다리는 시간
param->SetLaunchStoveLauncher(true); // 런처가 꺼져 있으면 실행한다

// 결과는 게임 루프의 Stove_RunCallback() 에서 콜백으로 온다.
Stove_RestartAppIfNecessary(param.Get(), OnRestartAppIfNecessaryFinished, this);
// param 은 StoveGuard 가 범위를 벗어날 때 Destroy 한다.

out 파라미터와 동기 함수의 결과도 같은 방식으로 다뤄요. 다음은 같은 파일의 Initialize() 에서 사용자 정보를 읽는 부분이에요.

cpp
// 로그인 사용자 정보. out 객체는 성공 여부와 무관하게 StoveGuard 가 해제한다.
StoveGuard<IStoveUser> user;
StoveResultGuard userResult(Stove_GetUser(user.Put()));
if (userResult && user.IsValid())
    nickname_ = WideToUtf8(user->GetNickName());

도우미를 쓰면 Destroy() 호출이 소스에서 사라져요. 이 가이드의 이후 예제도 모두 이 방식이에요.

결과 확인

모든 함수는 결과를 IStoveResult 로 알려 줘요. 동기 함수는 반환값으로, 비동기 함수는 콜백의 callbackResult->GetResult() 로 받아요. 성공 여부는 항상 IsSuccessful() 분기 하나로 판단하고, try-catch 는 쓰지 않아요.

메서드반환형설명
IsSuccessful()bool성공이면 true 예요.
GetResultCode()uint32_t결과 코드예요. 성공이면 0 이고, 실패하면 원인을 나타내는 값이 들어 있어요.
GetMethodCode()uint32_t어느 함수가 만든 결과인지 나타내는 값이에요. 1000 단위로 모듈이 나뉘어요(예: 4000 번대는 Ownership). 로그를 남길 때 함께 기록하면 원인을 찾기 쉬워요.

비동기 콜백의 IStoveCallbackResult 는 실패 원인을 더 자세히 알려 줘요.

메서드반환형설명
GetResult()IStoveResult*결과 객체예요. 콜백이 끝나면 무효가 되고, Destroy() 하지 않아요.
GetErrorMessage()const wchar_t*오류가 난 이유를 설명하는 메시지예요.
GetExternalError()int32_t외부 오류 값(HTTP 오류 코드 또는 서버 API 결과 코드)이에요.
GetUserData()void*비동기 함수를 호출할 때 넘긴 userData 예요.

결과 코드는 base_misc.h 의 열거형 2개에 모여 있어요. 0 ~ 299 는 모든 모듈이 함께 쓰는 공통 코드(EStoveCommonResultCode)이고, 300 이상은 기능별 코드(EStoveResultCode)예요. 연동하면서 자주 만나는 코드는 다음과 같아요.

코드이름뜻
0k_EStoveCommonResultCode_Success성공이에요.
1k_EStoveCommonResultCode_Fail일반 실패예요.
5k_EStoveCommonResultCode_InvalidParam파라미터가 잘못되었어요. 버퍼가 작을 때도 이 코드가 와요.
16k_EStoveCommonResultCode_BaseNotInitializedSDK 가 초기화되지 않은 상태에서 호출했어요.
18k_EStoveCommonResultCode_AlreadyInitialized이미 초기화된 상태에서 Stove_Initialize 를 다시 호출했어요.
29k_EStoveCommonResultCode_AsyncOperationInProgress같은 비동기 작업이 아직 진행 중이에요.
31k_EStoveCommonResultCode_NotSupportedCountry사용자 국가에서 지원하지 않는 기능이에요.
249k_EStoveCommonResultCode_NetworkTransportError네트워크 전송 오류예요. GetExternalError() 에 통신 계층의 오류 코드가 담겨요.
304k_EStoveResultCode_NeedStoveLauncher스토브 런처가 필요한데 실행 중이 아니에요.
307k_EStoveResultCode_IpcConnectFailed런처와 통신하지 못했어요.
308k_EStoveResultCode_IpcAesKeyNotReceived런처와 통신하지 못했어요.
309k_EStoveResultCode_IpcTimeout런처와 통신하지 못했어요.

Brick Smash 는 실패한 콜백의 원인을 사람이 읽을 수 있게 만드는 함수를 하나 두고, 모든 콜백이 이 함수를 같이 써요. 다음은 src/StoveState.h 의 DescribeFailure() 예요. 결과 코드와 오류 메시지를 한 줄로 합쳐요.

cpp
inline std::string DescribeFailure(const IStoveCallbackResult* r)
{
    std::string s = "code=" + std::to_string(r->GetResult()->GetResultCode());
    std::string msg = WideToUtf8(r->GetErrorMessage());
    if (!msg.empty())
        s += " " + msg;
    return s;
}

비동기 함수와 콜백

헤더에서 반환형이 void 이고 콜백을 인자로 받는 함수는 비동기 함수예요. 결과는 반환값이 아니라 콜백으로 전달돼요. 비동기 함수는 공통으로 다음 형태예요.

cpp
void Stove_FetchOwnerships(const IStoveTypeBase* param, OnOwnershipListCallback onFinished, void* userData);

콜백은 __cdecl 함수 포인터이고, 인자는 2개예요. 첫 번째는 IStoveCallbackResult*, 두 번째는 기능별 결과 객체예요. 호출할 때 넘긴 userData 는 콜백 인자로 따로 오지 않고 callbackResult->GetUserData() 로 꺼내요.

콜백 자리에는 일반 함수나 캡처하지 않는 람다만 넘길 수 있어요. 함수 포인터라서 무언가를 캡처하는 람다([&], [this])는 넘길 수 없어요. 게임 쪽 객체가 필요하면 userData 로 넘기고 콜백에서 GetUserData() 로 꺼내요. Brick Smash 는 이렇게 해요. 다음은 src/stove/StoveSession.cpp 의 콜백 연결부예요. Begin() 에서 this 를 userData 로 넘기고, 콜백은 이를 꺼내 세션 객체의 멤버 함수로 넘겨요.

cpp
namespace
{
    StoveSession* Self(const IStoveCallbackResult* r)
    {
        return static_cast<StoveSession*>(r->GetUserData());
    }

    void __cdecl OnFetchOwnershipsFinished(const IStoveCallbackResult* r, const IStoveOwnershipList* list)
    {
        Self(r)->OnOwnerships(r, list);
    }
}

userData 로 지역 변수의 주소를 넘기면 안 돼요. 콜백은 함수가 반환된 뒤 나중 프레임에 실행되므로, 그때는 지역 변수가 이미 사라져 있어요. userData 가 가리키는 객체는 콜백이 실행될 때까지 살아 있어야 해요. Brick Smash 는 main() 이 끝날 때까지 살아 있는 StoveSession 과 AppState 를 넘겨요.

콜백 인자는 콜백 안에서만 유효해요

콜백 인자(IStoveCallbackResult* 와 두 번째 인자, 그 안에서 꺼낸 객체와 문자열)는 콜백이 실행되는 동안에만 유효해요. 콜백이 끝나면 포인터가 가리키는 객체가 사라지므로, 콜백 밖에서 써야 하는 값은 콜백 안에서 복사해 두어요. 문자열은 std::string 이나 std::wstring 같은 게임 쪽 저장소에 옮겨 담아요.

Brick Smash 는 이 규칙을 src/StoveState.h 의 상태 구조체로 일관되게 지켜요. 구조체마다 AsyncStatus 를 하나 두고, 화면과 콜백이 이 값으로 서로 신호를 주고받아요.

cpp
enum class AsyncStatus
{
    Idle,
    Loading,
    Done,
    Error,
};

// 스탯 조회 (Stove_FetchStat)
struct StatState
{
    AsyncStatus status = AsyncStatus::Idle;
    std::string error;
    int currentValue = 0;
};
  • 화면(요청하는 쪽)은 status 가 Idle 일 때 SDK 호출을 한 번만 시작하고, status 를 Loading 으로 바꿔요.
  • 콜백은 GetUserData() 로 상태 구조체의 포인터를 꺼내, 필요한 값을 바로 복사한 뒤 status 를 Done 이나 Error 로 바꿔요.
  • 콜백이 받은 IStove* 객체의 포인터는 따로 보관하지 않아요.

다음은 src/stove/StoveGameSupport.cpp 의 OnFetchStatFinished() 예요. 실패하면 DescribeFailure() 로 원인을 저장하고, 성공하면 값을 복사해요.

cpp
void __cdecl OnFetchStatFinished(const IStoveCallbackResult* r, const IStoveStat* stat)
{
    auto* st = Self<StatState>(r);
    if (!r->GetResult()->IsSuccessful())
    {
        st->status = AsyncStatus::Error;
        st->error = DescribeFailure(r);
        return;
    }
    st->currentValue = stat->GetCurrentValue();
    st->status = AsyncStatus::Done;
}

Stove_RunCallback 호출 규칙

콜백은 Stove_RunCallback() 을 호출할 때 그 스레드에서 실행돼요.

  1. 게임 루프에서 매 프레임 Stove_RunCallback() 을 호출해요.
  2. 메인(UI) 스레드에서 호출해요. 헤더에 메인 스레드에서 호출해야 한다고 명시되어 있어요.
  3. 첫 비동기 함수(Stove_RestartAppIfNecessary)를 호출한 직후부터 Stove_Uninitialize() 를 호출하기 전까지 계속 호출해요.
  4. while (true) { Stove_RunCallback(); } 처럼 이 함수만 도는 별도 루프를 만들지 않아요. 게임 루프의 한 단계로 넣어요.

Brick Smash 는 StoveSession::Pump() 안에서 Stove_RunCallback() 을 부르고, main() 의 게임 루프가 매 프레임 Pump() 를 호출해요. 자세한 코드는 2장의 게임 루프와 종료에 있어요.

한 프레임에서 콜백 처리 시간이 길어질까 걱정되면 Stove_RunCallbackWithTimeout(timeoutMillisec) 을 대신 써요. 지정한 시간(밀리초)까지만 콜백을 처리하고, 남은 콜백은 다음 호출에서 이어서 처리해요. 두 함수 중 하나만 골라 쓰면 돼요.

cpp
Stove_RunCallbackWithTimeout(10); // 콜백 처리에 최대 10ms 를 써요.

문자열과 버퍼

  • SDK 와 주고받는 문자열은 모두 wchar_t 기반(UTF-16)이에요. 입력은 const wchar_t* 로 넘기고, 리터럴은 L"문자열" 로 써요.
  • SDK 가 돌려주는 const wchar_t* 는 그 문자열을 담은 객체가 살아 있는 동안만 유효해요. 객체를 Destroy() 했거나 콜백이 끝났다면 다시 읽지 않아요.

Brick Smash 의 UI 라이브러리(Dear ImGui)는 UTF-8 char* 를 쓰기 때문에, 두 표현을 바꾸는 WideToUtf8() 와 Utf8ToWide() 를 src/StringUtil.h 에 두었어요. 설정 값은 SDK 에 바로 넘길 수 있게 src/AppConfig.h 에서 std::wstring 으로 보관해요.

cpp
// SDK 는 모든 문자열을 wchar_t*(UTF-16) 로, ImGui 는 char*(UTF-8) 로 다룬다.
// 두 표현 사이를 변환하는 유틸리티.
std::string WideToUtf8(const wchar_t* src);
std::wstring Utf8ToWide(const std::string& src);

문자열을 버퍼로 돌려받는 함수는 wchar_t* out, uint32_t length 형태예요. 이 가이드에서는 Stove_GetVersion 과 Stove_GetCloudSavingPath 가 여기에 해당해요.

규칙내용
length 의 단위바이트가 아니라 wchar_t 개수예요. 끝의 널 문자까지 들어갈 수 있는 버퍼 크기를 넣어요.
버퍼가 nullptr 이거나 length 가 0k_EStoveCommonResultCode_InvalidParam(5) 로 실패해요.
버퍼가 작을 때잘린 문자열을 돌려주지 않아요. 버퍼를 빈 문자열로 비우고 k_EStoveCommonResultCode_InvalidParam(5) 로 실패해요.

다음은 src/stove/StoveSession.cpp 의 Initialize() 에서 SDK 버전을 읽는 부분이에요.

cpp
// SDK 버전. 기술지원 문의 때 함께 알려 주면 좋다.
wchar_t version[64] = { 0 };
StoveResultGuard versionResult(Stove_GetVersion(version, 64));
if (versionResult)
    sdkVersion_ = WideToUtf8(version);

호출 형식 2가지

헤더는 같은 기능을 2가지 형식으로 제공해요.

형식예쓰는 환경
인터페이스 호출 형식result->IsSuccessful(), param->SetGameId(L"..."), result->Destroy()C++ 컴파일러로 빌드하는 프로젝트
펼친 함수 형식(*_flat_api.h)Stove_IStoveResult_IsSuccessful(result), Stove_IStoveRestartAppIfNecessaryParam_SetGameId(param, L"...")순수 C 컴파일러, 또는 가상 함수를 호출할 수 없는 언어 바인딩

이 가이드의 예제는 모두 인터페이스 호출 형식이에요. C++ 로 빌드할 수 있으면 이 형식이 코드가 짧고 형 변환도 적어요.

펼친 함수(flat API)는 Steamworks SDK 에서 가져온 개념이에요. 인터페이스의 가상 함수 호출(obj->Method())을 쓸 수 없는 상황, 즉 순수 C 컴파일러로 빌드하거나 C++ 문법을 지원하지 않는 언어와 엔진에서 DLL 함수를 직접 불러 쓸 때 사용해요. 인터페이스의 메서드 하나하나를 같은 이름의 C 함수로 펼쳐 놓은 것이라, 첫 번째 인자로 대상 객체를 넘기면 돼요. 펼친 함수의 이름은 다음 규칙을 따라요.

text
Stove_<인터페이스 이름>_<메서드 이름>(self, 나머지 인자...)
  • result->IsSuccessful() → Stove_IStoveResult_IsSuccessful(result)
  • callbackResult->GetResult() → Stove_IStoveCallbackResult_GetResult(callbackResult)
  • user->GetNickName() → Stove_IStoveUser_GetNickName(user)
  • param->SetGameId(L"...") → Stove_IStoveRestartAppIfNecessaryParam_SetGameId(param, L"...")

해제만 예외예요. Destroy 는 모든 객체의 공통 부모인 IStoveTypeBase 에만 펼친 함수가 있어서, Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)obj) 처럼 형 변환해서 호출해요. ShouldDestroy 도 마찬가지로 Stove_IStoveTypeBase_ShouldDestroy 를 써요.

같은 코드를 펼친 함수 형식으로 쓰면 다음과 같아요. 순수 C 에서는 base_guard.h 를 쓸 수 없으니 해제도 직접 해요.

c
#include <stdbool.h> /* 순수 C 에서는 stove_api.h 보다 먼저 include 해요. */
#include "stove_api.h"

IStoveRestartAppIfNecessaryParam* param = (IStoveRestartAppIfNecessaryParam*)
    Stove_CreateParam(k_EStoveBaseTypeKind_RestartAppIfNecessaryParam);
Stove_IStoveRestartAppIfNecessaryParam_SetGameId(param, L"YOUR_GAME_ID");
Stove_RestartAppIfNecessary(param, OnRestartAppIfNecessaryFinished, NULL);
if (param != NULL && Stove_IStoveTypeBase_ShouldDestroy((IStoveTypeBase*)param)) Stove_IStoveTypeBase_Destroy((IStoveTypeBase*)param);

헤더는 bool 을 쓰지만 <stdbool.h> 를 직접 include 하지 않아요. C++ 에서는 문제가 없고, 순수 C 로 빌드할 때만 stove_api.h 보다 먼저 <stdbool.h> 를 include 해 주세요.

정리

규칙한 줄 요약
파라미터Stove_CreateParam() 으로 만들고, 호출이 반환되면 해제해요. StoveMakeParam<T>() 를 쓰면 자동으로 해제돼요.
해제게임이 받은 객체는 게임이 Destroy() 하고, 콜백 인자는 해제하지 않아요.
결과항상 IsSuccessful() 로 판단해요.
콜백인자는 2개예요. userData 는 GetUserData() 로 꺼내고, 값은 콜백 안에서 복사해요.
콜백 실행매 프레임 메인 스레드에서 Stove_RunCallback() 을 호출해야 해요.
문자열wchar_t 기반이고, 버퍼 길이는 wchar_t 개수예요.

2. 초기화 · 종료 · 소유권

게임이 스토브 런처를 거쳐 실행되었는지 확인하고, SDK 를 초기화하고, 사용자가 게임을 구매했는지 확인한 뒤, 게임이 끝날 때 SDK 를 종료하는 단계예요. 모든 기능의 전제가 되므로 가장 먼저 연동해요. 판매하는 게임이면 소유권 확인은 첫 연동에 반드시 포함해요.

이 장의 코드는 Brick Smash 의 src/stove/StoveSession.h, src/stove/StoveSession.cpp, src/main.cpp 에서 가져왔어요. SDK 의 수명 주기를 StoveSession 클래스 하나가 맡고, 게임 루프는 이 클래스의 Pump() 만 호출해요. 각 함수가 하는 일을 따라가며 읽으면 전체 흐름을 이해할 수 있어요.

사전 준비

STOVE Studio 에서 다음 값을 확인해 두세요. 게임 ID 와 앱 키는 STOVE Studio 의 빌드관리 메뉴 오른쪽 위에 있는 상품키 에서 확인할 수 있어요.

값넣는 Setter설명
환경IStoveRestartAppIfNecessaryParam::SetEnvironment개발과 테스트 중에는 L"SANDBOX", 출시 빌드에서는 L"LIVE" 를 넣어요. 대소문자는 구분하지 않아요.
게임 IDIStoveRestartAppIfNecessaryParam::SetGameIdSTOVE Studio 에서 발급한 게임 ID 예요.
앱 키IStoveRestartAppIfNecessaryParam::SetAppKeySTOVE Studio 에서 발급한 앱 키예요.
샵 키IStoveInitializeParam::SetShopKey결제(6장)를 쓰는 게임만 필요해요. STOVE Studio 에서 인게임 상점을 등록하면 발급돼요.

Brick Smash 는 이 값들을 소스에 적지 않고 실행 파일 옆의 config/stove_config.ini 에 둬요. 저장소에는 템플릿인 config/stove_config.example.ini 만 들어 있으니, 이 파일을 stove_config.ini 로 복사해서 발급받은 값으로 채워요.

ini
[stove]
; 환경: 개발·테스트는 SANDBOX, 출시 빌드는 LIVE
environment = SANDBOX
; STOVE Studio 에서 발급받은 값
game_id = YOUR_GAME_ID
app_key = YOUR_APP_KEY
; 인게임 상점 ShopKey. 비워 두면 결제 기능을 초기화하지 않는다.
shop_key = YOUR_SHOP_KEY

[ownership]
; 판매 중인 DLC 의 게임 ID. 소유하면 게임에서 넓은 패들을 쓴다. DLC 가 없으면 비워 둔다.
dlc_game_id = YOUR_DLC_GAME_ID

설정 파일을 읽은 값은 src/AppConfig.h 의 AppConfig 구조체에 담겨요. SDK 가 wchar_t* 를 요구하므로 문자열은 std::wstring 으로 보관해요.

cpp
struct AppConfig
{
    // [stove]
    std::wstring environment = L"SANDBOX"; // SANDBOX / LIVE
    std::wstring game_id;
    std::wstring app_key;
    std::wstring shop_key;                 // 비워 두면 결제 기능이 초기화되지 않는다

    // [ownership]
    std::wstring dlc_game_id;              // 판매 중인 DLC 의 게임 ID. 없으면 비워 둔다
    // ...
};

환경 값은 정해진 값만 써요. 정해지지 않은 값을 넣으면 오류 없이 샌드박스 환경으로 동작하므로, 출시 빌드에서 L"LIVE" 를 넣었는지 꼭 확인해 주세요.

호출 순서

  1. Stove_CreateParam(k_EStoveBaseTypeKind_RestartAppIfNecessaryParam) 으로 런처 실행 확인 파라미터를 만들고 환경 · 게임 ID · 앱 키를 넣어요.
  2. Stove_RestartAppIfNecessary() 를 호출해요. 비동기 함수라 결과는 콜백으로 와요. 호출이 반환되면 파라미터를 해제해요.
  3. 게임 루프를 시작하고 매 프레임 Stove_RunCallback() 을 호출해요. 이 호출이 있어야 2번의 콜백이 실행돼요.
  4. 콜백에서 결과를 확인해요.
    • 실패했으면 사용자에게 안내하고 게임을 종료해요.
    • outcome->IsRestartRequired() 가 true 이면 런처가 게임을 다시 실행하므로 현재 프로세스를 바로 종료해요.
    • false 이면 다음 단계로 넘어가요.
  5. Stove_CreateParam(k_EStoveBaseTypeKind_InitializeParam) 으로 초기화 파라미터를 만들고, 결제를 쓰면 샵 키와 창 핸들을 넣어요.
  6. Stove_Initialize() 를 호출해요. 동기 함수라 반환된 IStoveResult* 로 바로 성공 여부를 확인해요.
  7. 초기화가 성공하면 Stove_GetUser() 로 사용자 정보를, Stove_GetVersion() 으로 SDK 버전을 읽어요.
  8. Stove_FetchOwnerships() 로 소유권을 조회하고, 콜백에서 구매 여부를 판정해요.
  9. 셧다운과 과몰입 알림 콜백을 등록해요. 자세한 내용은 4장에서 설명해요.
  10. 게임 루프를 돌려요.
  11. 게임이 끝날 때 Stove_Uninitialize() 를 호출하고, 그 뒤로는 Stove_RunCallback() 을 호출하지 않아요.

환경 · 게임 ID · 앱 키는 1번에서 한 번만 넣어요. Stove_Initialize() 는 런처 실행 확인 때 넣은 값을 그대로 이어서 쓰므로, 초기화 파라미터에는 이 값들을 다시 넣지 않아요. 그래서 런처 실행 확인과 초기화는 반드시 한 흐름으로 이어져야 해요.

StoveSession 의 상태 흐름

Brick Smash 는 위 순서를 StoveSession 클래스의 Phase 값으로 관리해요. 다음은 src/stove/StoveSession.h 의 발췌예요.

cpp
// SDK 수명주기 전체를 관리한다.
//
//   1) Begin(cfg, hwnd)   : Stove_RestartAppIfNecessary (비동기) 시작
//   2) 매 프레임 Pump()   : Stove_RunCallback + 남은 노출 시간 갱신
//      콜백 → Stove_Initialize → GetUser/GetVersion → FetchOwnerships → 규제 알림 등록
//   3) 종료 시 Shutdown() : Stove_Uninitialize
class StoveSession
{
public:
    enum class Phase
    {
        Idle,
        RestartCheckPending, // RestartAppIfNecessary 콜백 대기
        OwnershipPending,    // 초기화 완료, 소유권 조회 콜백 대기
        Ready,               // 모든 준비 완료
        RestartRequired,     // 런처가 게임을 다시 실행한다. 즉시 종료.
        Failed,
    };

    void Begin(const AppConfig& cfg, void* hwnd);
    void Pump(float dt);
    void Shutdown();

    bool ready() const { return phase_ == Phase::Ready; }
    bool shouldQuit() const { return phase_ == Phase::RestartRequired; }
    // ...
};
Phase뜻다음으로 넘어가는 조건
Idle아직 시작 전이거나 종료한 뒤예요.Begin() 을 호출하면 RestartCheckPending 이 돼요.
RestartCheckPendingStove_RestartAppIfNecessary() 의 콜백을 기다려요.콜백에서 IsRestartRequired() 가 false 이고 초기화에 성공하면 OwnershipPending, true 이면 RestartRequired, 실패하면 Failed 가 돼요.
OwnershipPending초기화를 마치고 소유권 조회 콜백을 기다려요.기본 게임을 소유하면 Ready, 아니면 Failed 가 돼요.
Ready모든 준비가 끝났어요. 게임 화면을 그려요.
RestartRequired런처가 게임을 다시 실행해요. 바로 종료해야 해요.
Failed어느 단계에서든 실패했어요. error() 에 원인이 담겨요.

게임 화면은 ready() 가 true 일 때만 그려요. 그 전에는 "STOVE SDK 초기화 중..." 을, Failed 이면 실패 원인을 보여 줘요.

런처 실행 확인

StoveSession::Begin() 은 창을 만든 뒤 호출해요. 런처 실행 확인 파라미터를 만들고 Stove_RestartAppIfNecessary() 를 호출해요. 이 함수는 비동기라서 반환 직후에는 결과를 알 수 없어요. 결과는 게임 루프의 Stove_RunCallback() 에서 콜백으로 도착해요.

cpp
void StoveSession::Begin(const AppConfig& cfg, void* hwnd)
{
    cfg_ = &cfg;
    hwnd_ = hwnd;
    phase_ = Phase::RestartCheckPending;

    auto param = StoveMakeParam<IStoveRestartAppIfNecessaryParam>();
    if (!param.IsValid())
    {
        Fail("Stove_CreateParam(RestartAppIfNecessaryParam) 실패");
        return;
    }
    param->SetEnvironment(cfg.environment.c_str()); // L"SANDBOX" 또는 L"LIVE"
    param->SetGameId(cfg.game_id.c_str());
    param->SetAppKey(cfg.app_key.c_str());
    param->SetWaitTimeMilliSec(60000);  // 런처 응답을 기다리는 시간
    param->SetLaunchStoveLauncher(true); // 런처가 꺼져 있으면 실행한다

    // 결과는 게임 루프의 Stove_RunCallback() 에서 콜백으로 온다.
    Stove_RestartAppIfNecessary(param.Get(), OnRestartAppIfNecessaryFinished, this);
    // param 은 StoveGuard 가 범위를 벗어날 때 Destroy 한다.
}

IStoveRestartAppIfNecessaryParam 의 Setter 는 다음과 같아요.

Setter형식설명
SetEnvironmentconst wchar_t*환경 값이에요. L"SANDBOX" 또는 L"LIVE" 를 넣어요.
SetGameIdconst wchar_t*게임 ID 예요.
SetAppKeyconst wchar_t*앱 키예요.
SetWaitTimeMilliSecuint32_t런처에서 실행되었는지 확인할 때 기다리는 시간(밀리초)이에요. 만든 직후의 값은 0 이에요.
SetLaunchStoveLauncherbool런처가 실행 중이 아닐 때 런처를 실행할지 정해요. 만든 직후의 값은 false 예요.
SetPlatformNameconst wchar_t*연동 플랫폼 이름이에요(예: L"Stove", L"Steam"). 스토브에서만 판매하는 게임은 설정하지 않아요.

콜백은 OnRestartAppIfNecessaryCallback 형식이고, 두 번째 인자 IStoveRestartAppIfNecessaryOutcome 은 메서드 1개를 가져요.

메서드반환형설명
IsRestartRequired()booltrue 이면 런처를 통해 다시 실행해야 하므로 현재 프로세스를 종료해야 해요. false 이면 계속 진행해도 돼요.

콜백이 도착하면 OnRestartChecked() 가 결과를 판단하고, 초기화와 소유권 조회를 이어서 호출해요.

cpp
void StoveSession::OnRestartChecked(const IStoveCallbackResult* r, const IStoveRestartAppIfNecessaryOutcome* outcome)
{
    if (!r->GetResult()->IsSuccessful())
    {
        Fail("런처 실행 확인 실패: " + DescribeFailure(r));
        return;
    }
    if (outcome->IsRestartRequired())
    {
        // 런처가 게임을 다시 실행한다. 아직 초기화 전이므로 Uninitialize 는 부르지 않는다.
        phase_ = Phase::RestartRequired;
        return;
    }
    if (!Initialize())
        return;

    // 2) 소유권 조회 (기본 게임 + DLC). 파라미터 자리는 SDK 가 쓰지 않으므로 nullptr.
    phase_ = Phase::OwnershipPending;
    Stove_FetchOwnerships(nullptr, OnFetchOwnershipsFinished, this);
}

세 갈래로 나뉘는 점을 눈여겨봐요. 실패하면 Failed, 다시 실행해야 하면 RestartRequired, 계속 진행해도 되면 초기화로 넘어가요. RestartRequired 는 아직 초기화하기 전이라서 Stove_Uninitialize() 를 호출하지 않아요.

초기화

StoveSession::Initialize() 는 Stove_Initialize() 를 호출하고, 사용자 정보와 SDK 버전을 읽고, 규제 알림 콜백을 등록해요.

IStoveInitializeParam 의 Setter 는 2개예요.

Setter형식설명
SetShopKeyconst wchar_t*샵 키예요. 값이 있으면 Stove_Initialize() 가 결제 기능도 함께 초기화해요. 비워 두면 결제 기능을 초기화하지 않아요.
SetMainWndHandleconst void*게임 메인 창의 핸들(HWND)이에요. 창이 만들어진 뒤의 핸들만 유효해요. SDK 가 결제 창을 띄울 때 이 창을 기준으로 해요.
  • 결제를 쓰는 게임은 SetShopKey 와 SetMainWndHandle 을 둘 다 넣어요. 샵 키가 없으면 결제 기능이 초기화되지 않아 6장의 함수가 동작하지 않아요.
  • 결제를 쓰지 않는 게임은 파라미터 없이 Stove_Initialize(nullptr) 로 호출해도 돼요. 헤더에 initParam 을 nullptr 로 넘길 수 있다고 명시되어 있어요. 이때도 소유권 · 업적 · 스탯 · 리더보드 · 로그 · 규제 알림은 모두 동작해요.

Brick Smash 는 결제를 쓰기 때문에 둘 다 넣어요.

cpp
bool StoveSession::Initialize()
{
    auto param = StoveMakeParam<IStoveInitializeParam>();
    if (!param.IsValid())
    {
        Fail("Stove_CreateParam(InitializeParam) 실패");
        return false;
    }
    // 결제를 쓰므로 샵 키와 메인 창 핸들을 둘 다 넣는다. 결제가 없으면 Stove_Initialize(nullptr) 로 충분하다.
    param->SetShopKey(cfg_->shop_key.c_str());
    param->SetMainWndHandle(hwnd_);

    StoveResultGuard result(Stove_Initialize(param.Get()));
    if (!result)
    {
        // 일부 모듈만 초기화된 상태일 수 있으니 정리한 뒤 실패 처리한다.
        StoveResultGuard uninit(Stove_Uninitialize());
        Fail("Stove_Initialize 실패: code=" + std::to_string(result.GetResultCode()));
        return false;
    }
    initialized_ = true;

    // 로그인 사용자 정보. out 객체는 성공 여부와 무관하게 StoveGuard 가 해제한다.
    StoveGuard<IStoveUser> user;
    StoveResultGuard userResult(Stove_GetUser(user.Put()));
    if (userResult && user.IsValid())
        nickname_ = WideToUtf8(user->GetNickName());

    // SDK 버전. 기술지원 문의 때 함께 알려 주면 좋다.
    wchar_t version[64] = { 0 };
    StoveResultGuard versionResult(Stove_GetVersion(version, 64));
    if (versionResult)
        sdkVersion_ = WideToUtf8(version);

    // 3) 규제 알림 콜백 등록. 한 번만 등록하면 SDK 가 필요할 때마다 콜백을 보낸다.
    Stove_ShutdownNotification(nullptr, OnShutdownNotificationFinished, this);
    Stove_OverImmersionNotification(nullptr, OnOverImmersionNotificationFinished, this);
    // ... 베트남 알림 등록은 추가 연동 문서의 7장을 참고하세요 ...
    return true;
}

코드에서 짚어 둘 점은 다음과 같아요.

  • Stove_Initialize() 가 반환한 IStoveResult* 는 StoveResultGuard 가 받아서, if (!result) 로 성공 여부를 판단해요. 도우미가 범위를 벗어날 때 결과 객체를 해제해요.
  • 초기화에 실패하면 Stove_Uninitialize() 를 먼저 호출한 뒤 실패로 처리해요. 실패한 초기화는 일부 기능만 초기화된 채로 남을 수 있어서 정리가 필요해요. 다시 시도하려면 이 정리를 거친 뒤 Stove_Initialize() 를 다시 호출해요.
  • Stove_GetUser() 의 out 파라미터는 StoveGuard<IStoveUser> 의 Put() 으로 받아요. 호출이 성공했든 실패했든 객체는 도우미가 해제해요. 닉네임은 콜백이 아니라 동기 함수로 얻는 값이지만, 문자열을 복사해서 nickname_ 에 보관하는 점은 같아요.
  • Stove_GetVersion() 의 length 인자에는 바이트 수가 아니라 wchar_t 개수 64 를 넘겨요.
  • 규제 알림 등록 함수는 반환값이 없는 비동기 함수라서 한 번만 호출하면 돼요. 알림은 4장에서 설명해요.

소유권 확인

로그인한 사용자가 지금 실행 중인 게임의 기본 게임 · 데모 · DLC 를 실제로 보유하고 있는지 확인하는 기능이에요. 스토어인디 게임은 판매가 기본이라 첫 연동에 포함해요. DLC 를 판매하는 게임이면 DLC 콘텐츠를 열기 전에도 소유권을 확인해서, 구매하지 않은 사용자에게 DLC 콘텐츠가 노출되지 않게 해요.

STOVE Studio 에 따로 설정할 것은 없어요. 확인 대상이 되는 기본 게임 · 데모 · DLC 항목은 게임을 스토어에 등록하고 판매를 준비하는 과정에서 이미 등록돼 있어요.

호출 순서

  1. Stove_Initialize() 가 성공한 뒤 Stove_FetchOwnerships(nullptr, 콜백, userData) 를 호출해요. 파라미터 자리는 SDK 가 쓰지 않는 인자라 nullptr 을 넘겨요.
  2. 게임 루프의 Stove_RunCallback() 에서 콜백이 실행돼요.
  3. 콜백에서 IStoveOwnershipList 를 GetCount() · GetAt(i) 로 순회해요.
  4. 항목마다 게임 ID · 상품 분류 · 소유 상태를 함께 확인해요.
  5. 기본 게임의 소유가 확인되지 않으면 게임 정책에 따라 처리해요.

결과 객체

콜백은 OnOwnershipListCallback 형식이에요.

cpp
typedef void(__cdecl* OnOwnershipListCallback)(const IStoveCallbackResult* callbackResult, const IStoveOwnershipList* ownerships);

IStoveOwnershipList 는 소유권 항목의 목록이에요.

메서드반환형설명
GetCount()uint32_t항목 개수예요.
GetAt(uint32_t index)const IStoveOwnership*index 번째 항목이에요. 범위를 벗어나면 nullptr 이에요.

IStoveOwnership 항목 하나는 다음 값을 가져요.

메서드반환형설명
GetGameId()const wchar_t*이 항목에 연결된 STOVE 게임 ID 예요.
GetGameCode()int32_t상품 분류예요. EStoveOwnershipGameCode 값이에요.
GetOwnershipCode()int32_t소유 상태예요. EStoveOwnershipCode 값이에요.
GetPurchaseDate()uint64_t구매 시각이에요. UTC 기준 Unix epoch 밀리초예요.

소유 상태(EStoveOwnershipCode)는 다음과 같아요. 소유 중으로 처리하는 값은 Acquire 하나뿐이에요.

값이름뜻
0k_EStoveOwnershipCode_None기록된 소유 상태가 없어요. 소유하지 않은 것으로 처리해요.
1k_EStoveOwnershipCode_Acquire지금 소유하고 있어요.
2k_EStoveOwnershipCode_Lose소유권을 잃었어요(예: 환불). 소유하지 않은 것으로 처리해요.

상품 분류(EStoveOwnershipGameCode)는 다음과 같아요. 값 1 과 2 는 폐기된 번호라 오지 않아요.

값이름뜻
0k_EStoveOwnershipGameCode_None상품 항목이 아니거나 분류가 지정되지 않았어요.
3k_EStoveOwnershipGameCode_Basic기본 게임이에요.
4k_EStoveOwnershipGameCode_Demo데모 빌드예요.
5k_EStoveOwnershipGameCode_Dlc기본 게임에 딸린 DLC 예요.

콜백에서 구매 여부 판정

다음은 StoveSession::OnOwnerships() 예요. 목록을 순회하면서 소유 중인 항목만 보고, 게임 ID 와 상품 분류를 함께 확인해서 기본 게임과 DLC 의 소유 여부를 멤버 변수에 복사해요.

cpp
void StoveSession::OnOwnerships(const IStoveCallbackResult* r, const IStoveOwnershipList* list)
{
    if (!r->GetResult()->IsSuccessful())
    {
        Fail("소유권 조회 실패: " + DescribeFailure(r));
        return;
    }

    ownsBaseGame_ = false;
    ownsDlc_ = false;
    for (uint32_t i = 0; i < list->GetCount(); ++i)
    {
        const IStoveOwnership* o = list->GetAt(i);
        if (o == nullptr || o->GetOwnershipCode() != k_EStoveOwnershipCode_Acquire)
            continue; // None · Lose 는 소유하지 않은 상태

        const wchar_t* gameId = o->GetGameId();
        if (o->GetGameCode() == k_EStoveOwnershipGameCode_Basic && wcscmp(gameId, cfg_->game_id.c_str()) == 0)
            ownsBaseGame_ = true;
        else if (o->GetGameCode() == k_EStoveOwnershipGameCode_Dlc && wcscmp(gameId, cfg_->dlc_game_id.c_str()) == 0)
            ownsDlc_ = true;
    }

    if (!ownsBaseGame_)
    {
        Fail("게임을 구매한 계정으로 실행해 주세요.");
        return;
    }
    phase_ = Phase::Ready;
}

이 코드가 지키는 규칙은 다음과 같아요.

  • 소유 상태가 Acquire 인 항목만 봐요. None 과 Lose(환불 등)는 소유하지 않은 것으로 처리해요.
  • 게임 ID 와 상품 분류를 함께 확인해요. 기본 게임은 Basic 이면서 설정 파일의 game_id 와 같은 항목이고, DLC 는 Dlc 이면서 dlc_game_id 와 같은 항목이에요.
  • 조회 자체가 실패한 경우(IsSuccessful() 이 false)는 소유하지 않은 것과 구분해서 처리해요. Brick Smash 는 둘 다 Failed 로 두지만 원인 문구가 달라요.
  • 판정 결과를 ownsBaseGame_ 와 ownsDlc_ 에 복사하고, IStoveOwnership* 포인터는 보관하지 않아요. 콜백이 끝나면 목록과 항목이 무효가 되기 때문이에요.

DLC 검색과 활용

DLC 는 기본 게임과 별도의 소유권 항목으로 조회돼요. 그래서 DLC 를 확인하려면 DLC 의 게임 ID 를 알아야 해요. Brick Smash 는 설정 파일의 dlc_game_id 를 cfg.dlc_game_id 로 읽어 두고, 목록에서 k_EStoveOwnershipGameCode_Dlc 이면서 게임 ID 가 같은 항목을 찾아요. 그 항목이 Acquire 이면 ownsDlc_ 가 true 가 돼요.

DLC 를 소유하면 게임이 어떻게 달라지는지는 게임이 정해요. Brick Smash 는 DLC 를 가진 사용자에게 넓은 패들을 줘요. 다음은 src/ui/GameScreen.cpp 의 발췌예요. 라운드를 시작할 때 ownsDlc() 값에 따라 패들 너비를 고르고, 메뉴 화면(src/ui/MenuScreen.cpp)에는 "DLC: 와이드 패들 적용 중" 을 표시해요.

cpp
// DLC 보유 시 넓은 패들(180)을 쓴다.
game.Start(field.x, field.y, field.w, field.h,
           ctx.session->ownsDlc() ? 180.0f : 110.0f);

DLC 를 팔지 않는 게임이면 dlc_game_id 를 비워 두면 돼요. 빈 문자열과 같은 게임 ID 는 없으므로 ownsDlc_ 는 계속 false 예요.

미소유 시 처리

  • 기본 게임을 소유하지 않은 경우: 구매가 필요하다는 안내를 띄운 뒤 게임을 종료하는 방식이 일반적이에요. Brick Smash 는 Failed 상태로 두고 "게임을 구매한 계정으로 실행해 주세요." 를 보여 줘요. 안내 문구와 종료 방식은 게임 정책으로 정해요.
  • 데모 빌드인 경우: 데모로 배포한 빌드라면 k_EStoveOwnershipGameCode_Demo 항목을 확인 대상으로 써요.
  • DLC 를 소유하지 않은 경우: 게임은 그대로 진행하고 DLC 콘텐츠만 잠가요. Brick Smash 는 기본 크기의 패들을 줘요. 구매 안내를 띄울지는 게임 정책으로 정해요.
  • 조회 자체가 실패한 경우: 소유하지 않은 것과 구분해서 처리해요. 네트워크 문제일 수 있으니 안내한 뒤 다시 조회하거나 게임을 종료해요.

목록에는 지금 실행 중인 게임의 항목(기본 게임 · DLC · 데모)이 내려와요.

게임 루프와 종료

게임 루프는 매 프레임 StoveSession::Pump() 를 호출해요. Pump() 는 Stove_RunCallback() 을 불러서 쌓여 있는 콜백을 실행해요. 앞에서 본 OnRestartChecked() 와 OnOwnerships() 도 이 호출 안에서 실행돼요.

cpp
void StoveSession::Pump(float dt)
{
    // 모든 비동기 콜백은 이 호출 안에서, 이 스레드에서 실행된다.
    Stove_RunCallback();

    if (notice_.secondsLeft > 0.0f && !notice_.blocksGame)
        notice_.secondsLeft -= dt;
    if (overimmersion_.visible && (overimmersion_.secondsLeft -= dt) <= 0.0f)
        overimmersion_.visible = false;
}

Pump() 아래쪽의 notice_ 와 overimmersion_ 처리는 규제 알림 배너의 남은 노출 시간을 줄이는 코드예요. 4장에서 설명해요.

다음은 src/main.cpp 의 발췌예요. 창을 만든 뒤 session.Begin() 을 호출하고, 루프 안에서 Pump() 로 콜백을 처리하고, 준비가 끝났을 때만 게임 화면을 그리고, 루프가 끝나면 Shutdown() 을 호출해요.

cpp
// 창을 만든 뒤 호출한다. 이후 콜백은 매 프레임 Pump() 의 Stove_RunCallback 에서 도착한다.
StoveSession session;
session.Begin(cfg, hwnd);

// ...

while (!quit)
{
    SDL_Event e;
    while (SDL_PollEvent(&e))
    {
        ImGui_ImplSDL3_ProcessEvent(&e);
        if (e.type == SDL_EVENT_QUIT)
            quit = true;
    }

    session.Pump(io.DeltaTime); // 내부에서 Stove_RunCallback 호출
    if (session.shouldQuit())   // 런처가 게임을 다시 실행하는 경우
        break;

    // ... 화면 그리기 ...
    if (!session.ready())
    {
        if (session.phase() == StoveSession::Phase::Failed)
        {
            ImGui::TextColored(ImVec4(1, 0.4f, 0.4f, 1), "SDK 초기화 실패");
            ImGui::TextWrapped("%s", session.error().c_str());
            ImGui::TextDisabled("STOVE 런처로 실행했는지, config/stove_config.ini 설정이 올바른지 확인해 주세요.");
        }
        else
        {
            ImGui::TextUnformatted("STOVE SDK 초기화 중...");
        }
    }
    else
    {
        // ... 메뉴, 게임, 업적, 랭킹, 스탯, 상점, 보관함 화면 ...
    }
}

session.Shutdown();
  • 초기화가 끝나기 전에도 게임 루프는 돌아가요. 루프가 돌아야 Pump() 가 콜백을 처리하기 때문이에요. 이 루프 안에서 초기화가 진행되는 동안에는 "초기화 중" 문구만 보여 줘요.
  • session.shouldQuit() 가 true 이면 런처가 게임을 다시 실행하는 중이에요. 루프를 바로 끝내요.
  • 창을 닫는 등 게임이 끝나면 루프를 빠져나와 session.Shutdown() 을 호출해요.

종료는 Stove_Uninitialize() 를 호출해요. StoveSession::Shutdown() 이 이를 맡아요.

cpp
void StoveSession::Shutdown()
{
    if (initialized_)
    {
        // 이용시간 보고를 끝내느라 최대 3초까지 걸릴 수 있다. 이후로는 Stove_RunCallback() 을 부르지 않는다.
        StoveResultGuard result(Stove_Uninitialize());
        initialized_ = false;
    }
    phase_ = Phase::Idle;
}

Stove_Uninitialize() 는 동기 함수예요. 신규 API 에는 모듈별 종료 함수가 없어서 이 호출 하나로 모든 기능이 종료돼요.

  • 게임이 끝날 때 한 번만 호출해요. 실행 도중 초기화와 종료를 반복하지 않아요.
  • initialized_ 가 true 일 때만 호출해요. 초기화에 성공하지 못했거나 RestartRequired 로 끝난 경우에는 호출하지 않아요.
  • 호출한 뒤에는 SDK 함수를 쓰지 않고, Stove_RunCallback() 호출도 멈춰요.
  • 반환된 IStoveResult* 도 해제해요. 예제에서는 StoveResultGuard 가 해제해요.
  • 3.5.3 부터 Stove_Uninitialize() 는 이용시간을 서버에 보고하느라 최대 3초까지 걸릴 수 있어요. 게임을 닫는 시점에 호출하고, 그 시간 동안 화면이 멈춰 보일 수 있으니 종료 화면을 먼저 보여 주는 등 게임 사정에 맞게 처리해요.

실패 처리

상황결과권장 처리
런처 실행 확인 콜백이 실패로 옴대표적으로 IpcConnectFailed(307) · IpcAesKeyNotReceived(308) · IpcTimeout(309)런처를 거치지 않고 실행했거나 런처와 통신하지 못한 경우예요. 이후 SDK 기능이 동작하지 않으니 사용자에게 안내하고 게임을 종료해요. 원인은 GetResultCode() 와 GetErrorMessage() 로 확인해요. Brick Smash 는 DescribeFailure() 로 원인을 화면에 보여 줘요.
IsRestartRequired() 가 true성공런처가 게임을 다시 실행해요. 현재 프로세스는 바로 종료해요. 아직 초기화 전이므로 Stove_Uninitialize() 는 호출하지 않아요.
런처 실행 확인 없이 Stove_Initialize() 를 호출함NeedStoveLauncher(304) 등반드시 런처 실행 확인 콜백에서 초기화를 이어서 호출해요.
Stove_Initialize() 실패실패 코드일부 기능만 초기화된 상태로 남을 수 있어요. 다시 시도하려면 Stove_Uninitialize() 를 먼저 호출한 뒤 Stove_Initialize() 를 호출해요.
종료하지 않고 Stove_Initialize() 를 다시 호출함AlreadyInitialized(18)실패했던 기능의 초기화를 다시 하지 않아요. 위와 같이 Stove_Uninitialize() 를 먼저 호출해요.
소유권 조회가 실패로 옴네트워크 오류 등소유하지 않은 것과 구분해서 안내해요. 다시 조회하거나 게임을 종료해요.
기본 게임을 소유하지 않음조회는 성공구매가 필요하다는 안내를 띄우고 게임을 종료해요.

주의할 점

Stove_RestartAppIfNecessary() 를 호출한 직후부터 게임 루프에서 Stove_RunCallback() 이 돌고 있어야 해요. 루프를 시작하기 전에 콜백을 기다리며 멈춰 있으면 콜백이 영영 실행되지 않아 초기화로 넘어가지 못해요.

Stove_Initialize() 가 성공하기 전에는 다른 기능 함수를 호출하지 않아요. 초기화 전에 호출하면 BaseNotInitialized(16) 같은 실패가 와요. Brick Smash 는 ready() 가 true 가 되기 전에는 기능 화면을 그리지 않는 방식으로 이를 막아요.

환경 값은 SANDBOX 와 LIVE 만 써요. 출시 빌드에서 L"LIVE" 를 넣었는지 확인해 주세요.

Stove_Initialize() 가 실패하면 Stove_Uninitialize() 로 정리한 뒤에 다시 시도해요. 정리 없이 다시 호출하면 AlreadyInitialized(18) 가 와요.

콜백으로 받은 목록과 항목은 콜백이 끝나면 무효가 돼요. 판정 결과는 멤버 변수에 복사하고 IStoveOwnership* 포인터를 보관하지 않아요.

3. Signature Verifier

Stove Signature Verifier 는 PC SDK DLL 을 바꿔치기하는 변조 공격에 대응하는 정적 라이브러리예요. 판매하는 게임이면 반드시 적용해 주세요. 이 장에서는 라이브러리가 무엇을 검사하는지, 어떤 파일을 골라 프로젝트에 넣는지, 코드 어디에서 호출하는지를 Brick Smash 의 실제 설정과 함께 설명해요.

Signature Verifier 란

  • PC SDK 본체와 따로 배포되는 라이브러리예요. PC SDK 2.x 와 3.x 를 모두 지원하므로, 신규 C API 로 연동하는 게임도 그대로 적용해요.
  • 호출할 함수는 StartStoveVerify() 하나예요. 헤더 StoveSignatureVerifier.h 에 선언되어 있어요.
  • 이 함수는 PC SDK 가 쓰는 DLL 이 올바르게 코드사이닝(디지털 서명)되어 있는지 검사해요. 코드사이닝은 DLL 이 신뢰할 수 있는 제작자에게서 변경되지 않은 채 배포되었음을 증명하는 디지털 서명이에요. 서명이 없는 DLL 을 찾으면 보안을 위해 게임을 바로 종료해요.

다음은 패키지에 들어 있는 StoveSignatureVerifier.h 의 선언이에요.

cpp
#ifdef __cplusplus
extern "C" {
#endif

// StoveSignatureVerifier 라이브러리 함수들
void StartStoveVerify();

#ifdef __cplusplus
}
#endif

무엇을 검사하나요

검사 대상은 STOVE 가 배포한 PC SDK 의 DLL 로 한정돼요. 게임 실행 파일이 있는 폴더와 그 하위 폴더를 탐색해서, 게임에 포함된 PC SDK 의 DLL 을 찾아 검사해요. 신규 C API 로 연동한 게임에서는 BaseSDK.dll 이 검사 대상이에요.

  • 게임 실행 파일, 게임이 직접 만든 DLL, 엔진이나 프레임워크의 런타임 DLL 은 검사 대상이 아니에요. 따라서 이 라이브러리를 적용하려고 게임 쪽 바이너리에 따로 코드사이닝을 할 필요는 없어요.
  • 검증은 게임이 실행되는 동안 주기적으로 반복돼요. 실행 중에 DLL 이 교체되어도 감지해요.

PC SDK 의 DLL 을 찾지 못하면 변조된 것과 똑같이 처리되어 게임이 종료돼요. 게임 패키징 결과물에서 BaseSDK.dll 이 실행 파일 폴더 또는 그 하위 폴더에 실제 파일로 있는지 반드시 확인해 주세요.

배포 패키지 구성

PCSDK 다운로드 페이지, 또는 다음 링크에서 최신 패키지를 내려받아요.

StoveSignatureVerifier_v1.0.5_x86_x64.zip

Visual Studio 2015 ~ 2026 툴셋별 · 런타임 라이브러리별 라이브러리를 모두 담고 있어요. 패키지 하나에 32비트(Win32)와 64비트(x64) 라이브러리가 모두 들어 있어요. 압축을 풀면 다음 구조예요.

text
Deploy
├ Include
│ └ StoveSignatureVerifier.h
└ Lib
  ├ Win32
  │ └ Release
  │   ├ MD
  │   │ ├ StoveSignatureVerifier_vs2015.lib
  │   │ ├ StoveSignatureVerifier_vs2017.lib
  │   │ ├ StoveSignatureVerifier_vs2019.lib
  │   │ ├ StoveSignatureVerifier_vs2022.lib
  │   │ └ StoveSignatureVerifier_vs2026.lib
  │   └ MT
  │     └ (MD와 동일한 파일 구성)
  └ x64
    └ Release
      ├ MD
      │ └ (Win32와 동일한 파일 구성)
      └ MT
        └ (Win32와 동일한 파일 구성)
  • Deploy/Include/StoveSignatureVerifier.h: 소스 코드에 include 하는 헤더 파일이에요.
  • Lib/{아키텍처}/Release/{런타임}/StoveSignatureVerifier_{툴셋}.lib: 정적 라이브러리 파일이에요.

라이브러리는 3가지 기준으로 골라요.

기준값고르는 방법
아키텍처Win32, x64게임의 대상 아키텍처와 같은 것
런타임MD, MT게임의 런타임 라이브러리 설정과 같은 것
툴셋vs2015(v140), vs2017(v141), vs2019(v142), vs2022(v143), vs2026(v145)게임 프로젝트의 플랫폼 도구 집합과 같은 것

툴셋이 일치하는 파일이 없으면 게임 프로젝트의 플랫폼 도구 집합보다 낮은 버전의 라이브러리를 골라 주세요. 링커는 자신과 같거나 더 오래된 버전으로 만든 라이브러리만 링크할 수 있어서, 더 높은 버전을 고르면 링크 오류(LNK2019, LNK1120)가 날 수 있어요.

신규 C API 를 연동하는 이 가이드는 x64 만 다루므로 Lib/x64/Release/ 아래에서 골라요. Brick Smash 는 Visual Studio 2022 로 빌드하는 x64 예제라서 vs2022 라이브러리를 골랐어요.

프로젝트 설정

Visual Studio 프로젝트에서는 다음 순서로 설정해요.

  1. 솔루션 디렉터리에 StoveSignatureVerifier 디렉터리를 만들고, 패키지의 Deploy 아래 Include 와 Lib 디렉터리를 이 안에 복사해요.
  2. 구성 속성 > C/C++ > 일반 > 추가 포함 디렉터리 에 헤더 경로를 넣어요.
    text
    $(SolutionDir)StoveSignatureVerifier\Deploy\Include
    
  3. 구성 속성 > 링커 > 일반 > 추가 라이브러리 디렉터리 에 라이브러리 경로를 넣어요. 아래는 런타임 라이브러리를 MD 로 설정한 프로젝트의 예예요. MT 로 설정했으면 경로 끝을 MT 로 바꿔요. 경로가 ...\Release 에서 끝나지 않고 런타임 폴더까지 들어가야 해요.
    text
    $(SolutionDir)StoveSignatureVerifier\Deploy\Lib\$(Platform)\Release\MD
    
  4. 구성 속성 > 링커 > 입력 > 추가 종속성 에 플랫폼 도구 집합에 맞는 파일 이름을 넣어요. 아래는 Visual Studio 2022(v143)의 예예요. BaseSDK.lib 와 함께 둘 다 추가 종속성에 넣어요.
    text
    StoveSignatureVerifier_vs2022.lib
    
  5. 구성 속성 > C/C++ > 코드 생성 > 런타임 라이브러리 설정이 3번에서 고른 MD · MT 와 같은지 확인해요. 다르면 링크 단계에서 LNK2038 오류가 나요.

개발 빌드에 넣지 않으려면 위 설정을 Release 구성에만 적용해요. 구성 선택 상자에서 Release 를 고른 상태로 입력하면 돼요.

Brick Smash 의 설정

Brick Smash 는 Visual Studio 솔루션의 Release 구성과 CMake 프로젝트에 같은 설정을 해 두었어요. 다음은 CMakeLists.txt 의 발췌예요. 서명 검증 라이브러리는 Release 구성에서만 링크해요. 개발용 Debug 빌드에는 들어가지 않아요.

cmake
set(STOVE_VERIFIER_DIR ${CMAKE_SOURCE_DIR}/third_party/StoveSignatureVerifier)

target_include_directories(BrickSmash PRIVATE
    ${CMAKE_SOURCE_DIR}/src
    ${STOVE_SDK_DIR}/Include
    ${STOVE_VERIFIER_DIR}/Include
)

target_link_libraries(BrickSmash PRIVATE
    SDL3::SDL3
    imgui::imgui
    ${STOVE_SDK_DIR}/lib/x64/BaseSDK.lib
    # 서명 검증 라이브러리는 릴리즈 구성에서만 링크한다.
    $<$<CONFIG:Release>:${STOVE_VERIFIER_DIR}/Lib/StoveSignatureVerifier_vs2022.lib>
)
  • 포함 디렉터리에는 구성 구분 없이 헤더 경로를 넣어요. 헤더를 include 해도 라이브러리가 링크되지 않으면 아무 일도 일어나지 않아요.
  • $<$<CONFIG:Release>:...> 는 CMake 의 생성기 표현식이에요. 빌드 구성이 Release 일 때만 안쪽 파일을 링크 목록에 넣어요.
  • Brick Smash 는 패키지에서 StoveSignatureVerifier_vs2022.lib 하나만 골라 third_party/StoveSignatureVerifier/Lib 에 두었어요. 이 방식은 경로를 간단하게 하려는 예제의 선택이에요. 패키지 구조를 그대로 두고 쓰려면 위 표와 같이 Lib/x64/Release/MD 경로를 가리켜요.

호출 위치

StartStoveVerify() 는 게임이 시작되자마자, PC SDK 의 어떤 함수보다도 먼저 호출해요. 그리고 릴리즈 빌드에서만 호출되도록 전처리기 조건으로 감싸요. 다음은 src/main.cpp 의 main() 첫 부분이에요.

cpp
#if defined(NDEBUG) || defined(_NDEBUG)
#include "StoveSignatureVerifier.h"
#endif

int main(int, char**)
{
#if defined(NDEBUG) || defined(_NDEBUG)
    // 서명 검증은 PC SDK 의 어떤 함수보다 먼저, 릴리즈 빌드에서만 호출한다.
    StartStoveVerify();
#endif

    AppConfig cfg;
    cfg.Load("config/stove_config.ini");

    // ... 창 생성 ...
    // 창을 만든 뒤 호출한다. 이후 콜백은 매 프레임 Pump() 의 Stove_RunCallback 에서 도착한다.
    StoveSession session;
    session.Begin(cfg, hwnd);
  • 헤더 include 와 함수 호출을 같은 조건(NDEBUG 또는 _NDEBUG)으로 감싸요. CMake 의 Release 구성은 NDEBUG 를 정의하므로, 라이브러리를 링크하는 구성과 호출하는 구성이 일치해요. 일치하지 않으면 링크 오류가 날 수 있어요.
  • StartStoveVerify() 는 2장의 session.Begin(), 즉 Stove_RestartAppIfNecessary() 를 호출하기 전에 있어요. main() 의 첫 줄이에요.
  • 게임 실행 파일의 진입점에서 호출하는 것이 가장 안전해요.

주의할 점

개발 중인 빌드에서는 절대 쓰면 안 돼요. 정식 배포하는 릴리즈 빌드에만 적용해 주세요.

PC SDK 의 DLL 을 찾지 못하면 변조된 것과 똑같이 처리되어 게임이 종료돼요. 릴리즈 빌드를 패키징한 폴더에 BaseSDK.dll 이 실제 파일로 들어 있는지 확인해 주세요.

런타임 라이브러리 설정이 다르면 링크 단계에서 LNK2038 오류가 나요. 배포 패키지에는 MT(정적 CRT)와 MD(동적 CRT) 2가지 런타임용 라이브러리가 모두 들어 있으니, 게임 프로젝트의 구성 속성 > C/C++ > 코드 생성 > 런타임 라이브러리 와 같은 종류를 골라요.

툴셋 이름이 같은 파일이 없으면 프로젝트의 플랫폼 도구 집합보다 낮은 버전의 라이브러리를 골라요. 더 높은 버전을 고르면 링크 오류가 날 수 있어요.

자주 묻는 질문

게임 실행 파일이나 게임에서 만든 DLL 에도 코드사이닝이 필요한가요

필요하지 않아요. 검사 대상은 STOVE 가 배포한 PC SDK 의 DLL 뿐이며, 게임 실행 파일과 게임이 직접 만든 DLL, 엔진이나 프레임워크의 런타임 DLL 은 검사하지 않아요. 자세한 대상은 위의 무엇을 검사하나요 항목을 참고해 주세요.

게임 실행 파일이 아닌 DLL 에서 StartStoveVerify() 를 호출해도 되나요

호출할 수 있어요. 검사 기준이 되는 폴더는 호출한 모듈의 위치가 아니라 실행 중인 프로세스의 실행 파일이 있는 폴더 이므로, 라이브러리를 링크한 DLL 이 어느 경로에 있든 검사 대상은 똑같이 찾아요.

다만 다음 2가지를 지켜 주세요.

  • DllMain 에서 호출하면 안 돼요. StartStoveVerify() 는 내부에서 검증용 스레드를 만들고 파일 시스템을 탐색해요. DllMain 은 로더 락이 걸린 상태에서 실행되므로, 이 안에서 호출하면 교착 상태가 일어날 수 있어요. DLL 이 로드된 뒤 호출되는 초기화 함수에서 호출해 주세요.
  • 가능하면 게임 실행 파일의 진입점에서 호출해 주세요. 검증 코드가 별도 모듈에 있으면 그 모듈을 로드하지 않는 방식으로 우회할 여지가 생겨요. 실행 파일을 직접 빌드할 수 있는 구조라면 진입점에서 호출하는 편이 안전해요.

MT 와 MD 중 무엇을 선택해야 하나요

게임 프로젝트의 구성 속성 > C/C++ > 코드 생성 > 런타임 라이브러리 설정과 같은 것을 선택해요. 다르게 선택하면 링크 단계에서 LNK2038 오류가 나요.

4. 셧다운 · 게임시간 제한

서비스 국가의 법령에 따라 사용자에게 안내를 띄워야 하는 기능이에요. 이 장에서는 게임시간선택제(셧다운) 알림과 한국의 과몰입 방지 알림을 연동해요. 베트남의 연령등급과 과몰입 알림은 7장에서 다뤄요.

이 장의 코드는 Brick Smash 의 src/stove/StoveSession.cpp, src/stove/StoveSession.h, src/ui/RegulationOverlay.cpp 에서 가져왔어요.

두 함수의 차이

함수대상콜백이 오는 때콜백 정보
Stove_ShutdownNotification게임시간선택제(셧다운)가 적용된 계정종료 시각이 다가올 때마다, 그리고 종료 시각에IStoveShutdownInfo
Stove_OverImmersionNotification한국의 과몰입 방지 대상 사용자매시간IStoveOverImmersionInfo
  • 한국 내 서비스는 과몰입 방지를 반드시 연동해요. 게임시간선택제는 19세 미만 청소년이 이용하는 게임이면 반드시 연동해요.
  • 두 함수 모두 알림을 받을 콜백을 등록하는 함수예요. 한 번만 호출해 두면 SDK 가 대상 사용자에게 필요한 때마다 콜백을 여러 번 보내요. 대상이 아닌 사용자에게는 콜백이 오지 않거나 실패 결과가 와요.
  • 첫 번째 인자는 SDK 가 쓰지 않는 인자라 nullptr 을 넘겨요. 파라미터 객체를 만들지 않아도 돼요.

호출 순서

  1. Stove_Initialize() 가 성공한 뒤 Stove_ShutdownNotification() 과 Stove_OverImmersionNotification() 을 한 번씩 호출해 콜백을 등록해요.
  2. 게임 루프의 Stove_RunCallback() 에서 콜백이 올 때마다 전달된 정보로 화면에 안내를 띄워요.
  3. 콜백 정보는 콜백 안에서만 유효하므로, 화면에 띄우는 데 필요한 값은 게임 쪽 변수로 복사해요.

Brick Smash 는 2장의 StoveSession::Initialize() 안에서 이 두 함수를 등록해요. 초기화에 성공한 직후이고, 사용자 정보와 버전을 읽은 뒤예요. 다음은 그 2줄이에요.

cpp
// 3) 규제 알림 콜백 등록. 한 번만 등록하면 SDK 가 필요할 때마다 콜백을 보낸다.
Stove_ShutdownNotification(nullptr, OnShutdownNotificationFinished, this);
Stove_OverImmersionNotification(nullptr, OnOverImmersionNotificationFinished, this);

userData 로 this 를 넘기고, 콜백은 GetUserData() 로 StoveSession 을 꺼내 멤버 함수로 넘겨요. 다음은 src/stove/StoveSession.cpp 의 콜백 연결부예요.

cpp
void __cdecl OnShutdownNotificationFinished(const IStoveCallbackResult* r, const IStoveShutdownInfo* info)
{
    Self(r)->OnShutdown(r, info);
}
void __cdecl OnOverImmersionNotificationFinished(const IStoveCallbackResult* r, const IStoveOverImmersionInfo* info)
{
    Self(r)->OnOverImmersion(r, info);
}

화면에 띄울 값 담아 두기

콜백은 Stove_RunCallback() 안에서 실행되지만 화면은 별도로 그려요. 그래서 콜백이 받은 정보를 화면이 읽을 수 있는 구조체에 복사해 둬요. Brick Smash 는 src/stove/StoveSession.h 에 NoticeState 를 두었어요. 셧다운과 한국 과몰입 알림이 같은 배너를 쓰기 때문에 구조체 하나를 같이 써요.

cpp
// 규제 알림(셧다운 · 한국 과몰입)을 화면에 띄우기 위한 값.
struct NoticeState
{
    std::string message;      // SDK 가 내려준 문구. 게임이 바꾸지 않는다.
    float secondsLeft = 0.0f; // 남은 노출 시간(초). 0 이하면 숨긴다.
    bool blocksGame = false;  // true 면 사용자가 확인한 뒤 게임을 종료해야 한다(셧다운 시각 도달).
};
필드채우는 값쓰임
message콜백의 GetMsg() 를 UTF-8 로 바꿔 복사한 문구배너에 그대로 그려요.
secondsLeftGetExposureTime()배너를 보여 줄 남은 시간이에요. 매 프레임 줄이고, 0 이하가 되면 숨겨요.
blocksGame셧다운 시각에 도달했는지true 이면 배너에 확인 버튼을 보여 주고, 확인하면 게임을 종료해요.

셧다운 알림 (Stove_ShutdownNotification)

게임시간선택제가 적용된 계정에 종료 시각이 다가오면 안내를 보내는 기능이에요.

cpp
void Stove_ShutdownNotification(const IStoveTypeBase* param, OnShutdownNotificationCallback onFinished, void* userData);
typedef void(__cdecl* OnShutdownNotificationCallback)(const IStoveCallbackResult* callbackResult, const IStoveShutdownInfo* shutdown);

콜백의 두 번째 인자 IStoveShutdownInfo 는 다음 메서드를 가져요.

메서드반환형설명
GetMsg()const wchar_t*셧다운 안내 메시지예요.
GetExposureTime()int32_t메시지 노출 시간이에요. 초 단위예요.
GetInadvanceMinutes()int32_t셧다운까지 남은 시간이에요. 분 단위예요.
  • GetInadvanceMinutes() 가 0보다 크면 몇 분 뒤 이용이 제한된다는 안내를 띄워요.
  • GetInadvanceMinutes() 가 0이면 이용 가능 시간을 모두 쓴 상태예요. 안내를 띄우고, 사용자가 확인하면 바로 게임을 종료해요.
  • 안내 문구는 GetMsg() 로 받은 값을 그대로 써요. 게임이 문구를 따로 만들지 않아요.

다음은 StoveSession::OnShutdown() 이에요.

cpp
void StoveSession::OnShutdown(const IStoveCallbackResult* r, const IStoveShutdownInfo* info)
{
    if (!r->GetResult()->IsSuccessful())
        return; // 셧다운 대상이 아닌 계정이면 실패 결과가 올 수 있다. 정상 동작.

    notice_.message = WideToUtf8(info->GetMsg());
    notice_.secondsLeft = static_cast<float>(info->GetExposureTime());
    // 남은 시간이 0 이면 이용 가능 시간을 모두 쓴 것. 사용자가 확인하면 게임을 종료한다.
    notice_.blocksGame = (info->GetInadvanceMinutes() <= 0);
}
  • 결과가 실패이면 아무것도 하지 않고 돌아가요. 셧다운 대상이 아닌 계정에는 실패 결과가 올 수 있고, 이는 정상 동작이에요.
  • 성공하면 문구와 노출 시간을 notice_ 에 복사해요. 문구는 SDK 가 내려준 값을 그대로 써요.
  • 남은 시간이 0 이하이면 blocksGame 을 true 로 둬요. 이용 시간을 모두 쓴 것이라 사용자가 확인한 뒤 게임을 종료해야 해요.

Stove_ShutdownNotification 은 한국 전용 함수가 아니에요. 게임시간선택제가 적용된 계정이면 해외에서 접속해도 똑같이 동작해요. 또 함수를 연동하는 것만으로는 콜백이 오지 않고, 게임시간선택제 대상 게임으로 먼저 등록되어 있어야 해요. 등록은 기술지원으로 문의해 주세요.

한국 과몰입 알림 (Stove_OverImmersionNotification)

한국의 과몰입 방지 대상 사용자에게 매시간 경고 메시지를 보내는 기능이에요.

cpp
void Stove_OverImmersionNotification(const IStoveTypeBase* param, OnOverImmersionNotificationCallback onFinished, void* userData);
typedef void(__cdecl* OnOverImmersionNotificationCallback)(const IStoveCallbackResult* callbackResult, const IStoveOverImmersionInfo* overImmersion);

헤더에 한국 전용 함수(Korea-only API) 라고 표기되어 있어요. 접속 IP 로 판별한 국가(Stove_GetGds 의 GetNation 값)가 한국이 아니면 NotSupportedCountry(31) 로 실패해요. 이 실패는 정상적인 결과이니 오류로 안내하지 않아요.

콜백의 두 번째 인자 IStoveOverImmersionInfo 는 다음 메서드를 가져요.

메서드반환형설명
GetMsg()const wchar_t*과몰입 경고 메시지예요.
GetElapsedHours()int32_t게임을 이용한 시간이에요. 시간 단위예요.
GetExposureTime()int32_t메시지 노출 시간이에요. 초 단위예요.

다음은 StoveSession::OnOverImmersion() 이에요.

cpp
void StoveSession::OnOverImmersion(const IStoveCallbackResult* r, const IStoveOverImmersionInfo* info)
{
    // 한국 전용. 다른 국가 사용자는 NotSupportedCountry(31) 로 실패하며 이는 정상이다.
    if (!r->GetResult()->IsSuccessful())
        return;

    notice_.message = WideToUtf8(info->GetMsg());
    notice_.secondsLeft = static_cast<float>(info->GetExposureTime());
    notice_.blocksGame = false;
}

셧다운과 다른 점은 blocksGame 을 항상 false 로 두는 것뿐이에요. 과몰입 경고는 안내만 하고, 게임을 종료시키지 않아요.

과몰입 경고 메시지는 게임 화면에서 사용자가 알아볼 수 있는 위치에 띄워야 해요. 화면 구석에 작게 표시하거나 다른 UI 에 가려지지 않게 해 주세요. 문구는 GetMsg() 값을 그대로 써요.

노출 시간 줄이기

배너를 보여 주는 시간은 콜백이 알려 준 GetExposureTime() 초예요. 콜백은 시간이 지나는 것을 알려 주지 않으니, 게임이 프레임마다 남은 시간을 줄여요. Brick Smash 는 StoveSession::Pump() 에서 해요.

cpp
void StoveSession::Pump(float dt)
{
    // 모든 비동기 콜백은 이 호출 안에서, 이 스레드에서 실행된다.
    Stove_RunCallback();

    if (notice_.secondsLeft > 0.0f && !notice_.blocksGame)
        notice_.secondsLeft -= dt;
    // ... 베트남 과몰입 오버레이의 남은 시간 처리는 추가 연동 문서의 7장을 참고하세요 ...
}
  • dt 는 이전 프레임 이후 지난 시간(초)이에요.
  • blocksGame 이 true 이면 시간을 줄이지 않아요. 셧다운 시각에 도달한 안내는 사용자가 확인 버튼을 누를 때까지 계속 보여 줘야 하기 때문이에요.
  • 새 콜백이 오면 OnShutdown() 과 OnOverImmersion() 이 secondsLeft 를 다시 채워서 배너가 다시 나타나요.

배너 그리기와 게임 종료

화면을 그리는 쪽은 src/ui/RegulationOverlay.cpp 의 DrawRegulationOverlays() 예요. main() 이 매 프레임 호출해요. 셧다운과 과몰입 배너 부분은 다음과 같아요.

cpp
void DrawRegulationOverlays(StoveSession& session, bool* requestQuit)
{
    // 셧다운·과몰입 알림 배너. 문구는 SDK 가 내려준 그대로 쓴다.
    const NoticeState& n = session.notice();
    if (n.secondsLeft > 0.0f || n.blocksGame)
    {
        ImGuiViewport* vp = ImGui::GetMainViewport();
        ImGui::SetNextWindowPos(ImVec2(vp->Size.x * 0.5f, 20.0f), ImGuiCond_Always, ImVec2(0.5f, 0.0f));
        ImGui::SetNextWindowSize(ImVec2(vp->Size.x * 0.8f, 0.0f));
        ImGui::PushStyleColor(ImGuiCol_WindowBg, ImVec4(0.7f, 0.1f, 0.1f, 0.95f));
        ImGui::Begin("##notice", nullptr,
                     ImGuiWindowFlags_NoTitleBar | ImGuiWindowFlags_NoResize | ImGuiWindowFlags_NoMove |
                     ImGuiWindowFlags_NoSavedSettings | ImGuiWindowFlags_AlwaysAutoResize);
        ImGui::TextWrapped("%s", n.message.c_str());
        if (n.blocksGame && ImGui::Button("확인"))
            *requestQuit = true;
        ImGui::End();
        ImGui::PopStyleColor();
    }
    // ... 베트남 오버레이 그리기는 추가 연동 문서의 7장을 참고하세요 ...
}
  • 남은 노출 시간이 있거나 blocksGame 이 true 이면 화면 위쪽 가운데에 배너를 그려요. 배경을 붉은색으로 해서 눈에 띄게 하고, 가로를 화면의 80% 로 넓게 잡았어요.
  • 문구는 n.message 를 그대로 출력해요. SDK 가 내려준 값을 게임이 고치지 않아요.
  • blocksGame 이 true 일 때만 확인 버튼을 그려요. 버튼을 누르면 *requestQuit = true 로 두고, main() 은 이 값을 quit 으로 받아서 게임 루프를 끝내요. 루프가 끝나면 2장의 게임 루프와 종료에서 본 session.Shutdown() 이 Stove_Uninitialize() 를 호출해요.

셧다운 시각에 도달하면 이렇게 흘러가요.

  1. 이용 시간이 끝나는 시각이 되면 SDK 가 GetInadvanceMinutes() 가 0 인 콜백을 보내요.
  2. OnShutdown() 이 blocksGame 을 true 로 두고 문구를 복사해요.
  3. 배너가 계속 보이고 확인 버튼이 나타나요.
  4. 사용자가 확인을 누르면 게임이 종료돼요.

정리

항목내용
등록 시점Stove_Initialize() 가 성공한 뒤 한 번만 호출해요.
첫 번째 인자nullptr 이에요.
콜백 횟수한 번 등록하면 SDK 가 필요할 때마다 여러 번 보내요.
셧다운게임시간선택제 대상 게임으로 먼저 등록해야 해요. 한국 전용이 아니에요. GetInadvanceMinutes() 가 0 이면 안내 후 종료해요.
한국 과몰입한국 전용이에요. 다른 국가는 NotSupportedCountry(31) 로 실패하며 정상이에요. 매시간 와요.
문구SDK 가 내려준 GetMsg() 를 그대로 써요.
콜백 정보콜백 안에서만 유효하니 값을 복사해요.

베트남 사용자를 대상으로 서비스하는 게임은 연령등급과 과몰입 알림도 연동해야 해요. 이는 7장에서 설명해요.

여기까지가 기본 연동이에요. 게임에 필요한 기능은 추가 연동 문서의 5장부터 골라 붙여요.

연동 중에 막히는 부분이 있으면 기술지원으로 문의해 주세요.

메일문의 : store.support@smilegate.com