GS2-Idle SDK for Game Engine API 레퍼런스
모델
EzStatus
스테이터스
처음으로 GetIdleStatus 를 호출했을 때 생성되며, 그 시점부터 방치 시간의 카운트가 시작됩니다.
방치 시간의 카운트는 보상을 받으면 리셋됩니다.
GS2-Schedule 의 이벤트가 연관되어 있는 경우, 이벤트 개최 전에는 Category 에 액세스할 수 없으며, 스테이터스를 생성할 수도 없습니다.
이벤트가 연관되어 있는 경우, 스테이터스는 이벤트의 반복 횟수를 보유합니다.
현재 이벤트ID와 스테이터스 생성 시의 이벤트ID가 일치하지 않는 경우, 현재 이벤트의 반복 횟수와 스테이터스가 보유한 반복 횟수가 일치하지 않는 경우, 또는 이벤트의 시작 시각보다 앞서 스테이터스가 생성된 경우, 대기 시간은 리셋됩니다.
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| categoryName | string | ✓ | ~ 128자 | 카테고리 모델 이름 이 스테이터스가 속한 카테고리 모델의 이름입니다. 방치 보상 계산에 사용되는 보상 간격, 최대 방치 시간, 입수 액션, 스케줄 설정을 포함하는 카테고리 모델 정의를 참조합니다. | ||
| randomSeed | long | 0 | 0 ~ 9223372036854775805 | 난수 시드 방치 보상 계산 시 결정론적 난수 생성에 사용되는 시드 값입니다. 보상 계산이 재현 가능하고 일관성이 있음을 보장하여 서버가 보상 결과를 검증할 수 있도록 합니다. 보상을 받을 때마다 갱신됩니다. | ||
| idleMinutes | int | ✓ | 0 ~ 2147483646 | 방치 시간(분) 마지막 보상 수취 또는 스테이터스 생성 이후의 누적 방치 시간(분)입니다. 이 값은 idleStartedAt 으로부터의 경과 시간으로 계산되며, maximumIdleMinutes 로 상한이 설정됩니다. 이용 가능한 보상 수는 이 값을 카테고리 모델의 rewardIntervalMinutes 로 나누어 결정됩니다. | ||
| maximumIdleMinutes | int | 0 | 0 ~ 2147483646 | 최대 방치 시간(분) 이 스테이터스가 축적할 수 있는 최대 방치 시간(분)입니다. 스테이터스 생성 시 카테고리 모델의 defaultMaximumIdleMinutes 로 초기화됩니다. 입수 액션을 통해 사용자별로 늘릴 수 있으며, 프리미엄 사용자나 이벤트 참가자가 더 많은 방치 보상을 축적할 수 있도록 합니다. |
EzCategoryModel
카테고리 모델
카테고리 모델이란, 방치 보상을 얻을 수 있는 대기 카테고리를 설정하는 엔티티입니다.
설정에는 대기 시간별 보상이나 최대 대기 시간 등의 정보가 포함됩니다.
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128자 | 카테고리 모델 이름 카테고리 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| metadata | string | ~ 2048자 | 메타데이터 메타데이터에는 임의의 값을 설정할 수 있습니다. 이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. | |||
| rewardIntervalMinutes | int | ✓ | 0 ~ 2147483646 | 보상 간격(분) 각 방치 보상 사이의 시간 간격(분)입니다. 예를 들어 60으로 설정하면, 사용자는 방치 시간 60분마다 보상 1유닛을 획득합니다. 보상의 총 개수는 (경과 방치 분수) / rewardIntervalMinutes로 계산되며, acquireActions 배열을 순환합니다. | ||
| defaultMaximumIdleMinutes | int | ✓ | 0 ~ 2147483646 | 기본 최대 방치 시간(분) 이 카테고리의 새로운 스테이터스에 대한 기본 최대 방치 시간(분)입니다. 이 제한을 초과하는 방치 시간은 추가 보상을 축적하지 않습니다. 이 값은 스테이터스 생성 시 각 스테이터스의 maximumIdleMinutes 에 복사되며, 입수 액션을 통해 사용자별로 확장할 수 있습니다. | ||
| acquireActions | List<EzAcquireActionList> | [] | 1 ~ 100 items | 대기 시간마다 얻을 수 있는 입수 액션 리스트 대기 시간을 “X분"이라고 가정하면 “X / rewardIntervalMinutes"가 보상을 받을 수 있는 횟수가 되지만, 여기서 지정한 배열의 요소를 반복함으로써 대기 시간마다 다른 보상을 부여할 수 있습니다. | ||
| idlePeriodScheduleId | string | ~ 1024자 | 방치 기간 스케줄ID 방치 시간이 축적되는 기간을 정의하는 GS2-Schedule 이벤트의 GRN입니다. 설정하면 이벤트가 활성 상태인 동안에만 방치 시간이 카운트됩니다. 이벤트가 반복되는 경우, 스테이터스는 반복 횟수를 추적하고 새로운 사이클이 시작될 때 방치 시간을 리셋하여 이벤트 기간마다 보상이 계산되도록 합니다. | |||
| receivePeriodScheduleId | string | ~ 1024자 | 수취 기간 스케줄ID 사용자가 축적된 방치 보상을 받을 수 있는 시간대를 정의하는 GS2-Schedule 이벤트의 GRN입니다. 설정하면 이벤트가 활성 상태인 동안에만 보상 수취가 허용됩니다. 이를 통해 방치 축적 기간과는 별도의 기간 한정 보상 수취 기간을 설정할 수 있습니다. |
EzConfig
컨피그 설정
트랜잭션의 변수에 적용하는 설정 값
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| key | string | ✓ | ~ 64자 | 이름 | ||
| value | string | ~ 51200자 | 값 |
EzAcquireAction
입수 액션
방치 보상으로 사용되는 단일 입수 액션을 나타냅니다. 액션 타입(예: 아이템 추가, 통화 증가)과 그 요청 파라미터로 구성됩니다. 방치 보상을 수령하면 이러한 액션들이 트랜잭션으로 조합되어 실행되며, 사용자에게 보상이 지급됩니다.
EzAcquireActionList
입수 액션 리스트
하나의 보상 간격에서 함께 지급되는 여러 입수 액션을 그룹화하는 래퍼입니다. 각 AcquireActionList는 카테고리 모델의 acquireActions 배열 내 하나의 보상 주기에 대응하며, 각 간격마다 서로 다른 보상 조합을 설정할 수 있습니다.
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| acquireActions | List<EzAcquireAction> | [] | 0 ~ 100 items | 입수 액션 리스트 이 보상 간격이 트리거될 때 함께 실행되는 입수 액션의 집합입니다. 여러 액션을 조합하여 하나의 방치 보상 주기에서 서로 다른 종류의 보상을 동시에 지급할 수 있습니다. 리스트당 최대 100개의 액션입니다. |
EzVerifyActionResult
검증 액션 실행 결과
EzConsumeActionResult
소비 액션 실행 결과
EzAcquireActionResult
획득 액션 실행 결과
EzTransactionResult
트랜잭션 실행 결과
서버 사이드에서 트랜잭션 자동 실행 기능을 이용하여 실행된 트랜잭션의 실행 결과
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| transactionId | string | ✓ | 36 ~ 36자 | 트랜잭션 ID | ||
| verifyResults | List<EzVerifyActionResult> | 0 ~ 10 items | 검증 액션의 실행 결과 목록 | |||
| consumeResults | List<EzConsumeActionResult> | [] | 0 ~ 10 items | 소비 액션의 실행 결과 목록 | ||
| acquireResults | List<EzAcquireActionResult> | [] | 0 ~ 100 items | 획득 액션 실행 결과 리스트 |
메서드
getCategoryModel
이름을 지정하여 방치 보상 카테고리 정의 조회
이름을 지정하여 방치 보상 카테고리 모델을 1건 조회합니다.
조회되는 정보에는 보상 간격(몇 분마다 보상이 누적되는지), 최대 방치 시간의 상한, 지급되는 보상 내용, 스케줄 설정이 포함됩니다.
특정 방치 보상 유형의 상세 정보를 표시하는 데 사용합니다. 예를 들어 “금광 — 30분마다 골드 10개 — 최대 누적: 8시간 — 현재: 160골드 수령 가능"과 같은 표시에 유용합니다.
Request
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| categoryName | string | ✓ | ~ 128자 | 카테고리 모델 이름 카테고리 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
Result
| 타입 | 설명 | |
|---|---|---|
| item | EzCategoryModel | 카테고리 모델 |
구현 예제
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).CategoryModel(
categoryName: "category-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).CategoryModel(
categoryName: "category-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Idle->Namespace(
"namespace-0001" // namespaceName
)->CategoryModel(
"category-0001" // categoryName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}var domain = ez.idle.namespace_(
"namespace-0001"
).category_model(
"category-0001"
)
var async_result = await domain.model()
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result값 변경 이벤트 핸들링
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).CategoryModel(
categoryName: "category-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId); var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).CategoryModel(
categoryName: "category-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Idle->Namespace(
"namespace-0001" // namespaceName
)->CategoryModel(
"category-0001" // categoryName
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Idle::Model::FCategoryModel> value) {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
Domain->Unsubscribe(CallbackId);var domain = ez.idle.namespace_(
"namespace-0001"
).category_model(
"category-0001"
)
# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
# 값이 변화했을 때 호출됨
# value에는 변경 후의 값이 전달됩니다
pass
)
# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
listCategoryModels
방치 보상 카테고리 정의 목록 조회
이 네임스페이스에 등록된 모든 방치 보상 카테고리를 조회합니다.
카테고리 모델은 AFK(방치) 보상의 동작 방식을 정의합니다. 보상이 누적되는 간격(예: 10분마다), 최대 방치 시간(예: 최대 8시간), 플레이어가 받는 보상 내용, 수령 후 타이머를 리셋할지 여부 등입니다.
또한 카테고리를 스케줄에 연결하여 방치 보상이 활성화되는 기간을 제어할 수도 있습니다(예: 평일 이벤트 중에만 유효).
플레이어에게 어떤 종류의 방치 보상이 있는지 표시하는 데 사용합니다. 예를 들어 “금광(30분마다 골드 10개, 최대 8시간)”, “수련장(1시간마다 XP 50, 최대 24시간)“과 같은 표시에 유용합니다.
Request
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
Result
| 타입 | 설명 | |
|---|---|---|
| items | List<EzCategoryModel> | 카테고리 모델 리스트 |
구현 예제
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.CategoryModelsAsync(
).ToListAsync(); var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.CategoryModels(
);
List<EzCategoryModel> items = new List<EzCategoryModel>();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
} const auto Domain = Gs2->Idle->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->CategoryModels(
);
TArray<Gs2::UE5::Idle::Model::FEzCategoryModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}값 변경 이벤트 핸들링
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeCategoryModels(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeCategoryModels(callbackId); var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeCategoryModels(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeCategoryModels(callbackId); const auto Domain = Gs2->Idle->Namespace(
"namespace-0001" // namespaceName
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->SubscribeCategoryModels(
[]() {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
Domain->UnsubscribeCategoryModels(CallbackId);이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
getStatus
특정 카테고리의 방치 보상 상태 조회
특정 카테고리에서 플레이어의 방치 보상 상태를 조회합니다.
상태에는 방치 타이머 시작 시각과 현재 최대 방치 시간이 포함됩니다. 상태가 아직 존재하지 않는 경우, 현재 시각을 시작 시각으로 하여 자동으로 생성됩니다.
특정 방치 보상의 진행 상황을 표시하는 데 사용합니다. 예를 들어 “금광 — 방치 중 4시간 30분 / 최대 8시간 — 90골드 수령 가능"과 같은 표시에 유용합니다.
Request
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| categoryName | string | ✓ | ~ 128자 | 카테고리 모델 이름 이 스테이터스가 속한 카테고리 모델의 이름입니다. 방치 보상 계산에 사용되는 보상 간격, 최대 방치 시간, 입수 액션, 스케줄 설정을 포함하는 카테고리 모델 정의를 참조합니다. | ||
| gameSession | GameSession | ✓ | GameSession |
Result
| 타입 | 설명 | |
|---|---|---|
| item | EzStatus | 상태 |
구현 예제
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
categoryName: "category-0001"
);
var item = await domain.ModelAsync(); var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
categoryName: "category-0001"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Idle->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Status(
"category-0001" // categoryName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}var domain = ez.idle.namespace_(
"namespace-0001"
).me(game_session).status(
"category-0001"
)
var async_result = await domain.model()
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result값 변경 이벤트 핸들링
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
categoryName: "category-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId); var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
categoryName: "category-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Idle->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Status(
"category-0001" // categoryName
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Idle::Model::FStatus> value) {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
Domain->Unsubscribe(CallbackId);var domain = ez.idle.namespace_(
"namespace-0001"
).me(game_session).status(
"category-0001"
)
# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
# 값이 변화했을 때 호출됨
# value에는 변경 후의 값이 전달됩니다
pass
)
# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
listStatuses
플레이어의 방치 보상 상태 목록 조회
모든 카테고리에 걸친 플레이어의 방치 보상 상태를 모두 조회합니다.
각 상태에는 플레이어가 언제부터 방치를 시작했는지(마지막으로 보상을 수령한 시각 또는 타이머 시작 시각)와 현재 최대 방치 시간이 포함됩니다.
“방치 보상” 개요 화면을 구성하는 데 사용합니다. 예를 들어 “금광: 4시간 30분 누적, 수련장: 1시간 15분 누적"처럼 각 카테고리에 “수령” 버튼을 붙여 표시하는 화면에 유용합니다.
Request
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| gameSession | GameSession | ✓ | GameSession | |||
| pageToken | string | ~ 1024자 | 데이터 취득을 시작할 위치를 지정하는 토큰 | |||
| limit | int | 30 | 1 ~ 1000 | 취득할 데이터 건수 |
Result
| 타입 | 설명 | |
|---|---|---|
| items | List<EzStatus> | 상태 목록 |
| nextPageToken | string | 목록의 나머지를 취득하기 위한 페이지 토큰 |
구현 예제
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var items = await domain.StatusesAsync(
).ToListAsync(); var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
var it = domain.Statuses(
);
List<EzStatus> items = new List<EzStatus>();
while (it.HasNext())
{
yield return it.Next();
if (it.Error != null)
{
onError.Invoke(it.Error, null);
break;
}
if (it.Current != null)
{
items.Add(it.Current);
}
else
{
break;
}
} const auto Domain = Gs2->Idle->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
const auto It = Domain->Statuses(
);
TArray<Gs2::UE5::Idle::Model::FEzStatusPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}값 변경 이벤트 핸들링
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeStatuses(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeStatuses(callbackId); var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeStatuses(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeStatuses(callbackId); const auto Domain = Gs2->Idle->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->SubscribeStatuses(
[]() {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
Domain->UnsubscribeStatuses(CallbackId);이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
prediction
지금 수령할 수 있는 방치 보상을 미리보기
플레이어가 지금 수령할 경우 받게 될 보상을 계산하여 반환합니다. 실제로 수령하지는 않습니다.
보상량은 플레이어가 방치한 시간을 보상 간격으로 나눈 값을 기준으로 하며, 최대 방치 시간으로 상한이 설정됩니다.
타이머 리셋이나 보상 지급은 이루어지지 않습니다. 읽기 전용 미리보기입니다.
플레이어가 “수령” 버튼을 누르기 전에 무엇을 받게 될지 표시하는 데 사용합니다. 예를 들어 “수령 예정: 골드 90개, 젬 5개"와 같은 표시에 유용합니다.
Request
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| categoryName | string | ✓ | ~ 128자 | 카테고리 모델 이름 이 스테이터스가 속한 카테고리 모델의 이름입니다. 방치 보상 계산에 사용되는 보상 간격, 최대 방치 시간, 입수 액션, 스케줄 설정을 포함하는 카테고리 모델 정의를 참조합니다. | ||
| gameSession | GameSession | ✓ | GameSession |
Result
| 타입 | 설명 | |
|---|---|---|
| items | List<EzAcquireAction> | 보상 |
| status | EzStatus | 상태 |
구현 예제
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
categoryName: "category-0001"
);
var result = await domain.PredictionAsync(
);
var item = await result.ModelAsync(); var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
categoryName: "category-0001"
);
var future = domain.PredictionFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
var future2 = future.Result.ModelFuture();
yield return future2;
if (future2.Error != null)
{
onError.Invoke(future2.Error, null);
yield break;
}
var result = future2.Result; const auto Domain = Gs2->Idle->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Status(
"category-0001" // categoryName
);
const auto Future = Domain->Prediction(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
// 변경된 값 / 결과 값을 취득
const auto Future2 = Future->GetTask().Result()->Model();
Future2->StartSynchronousTask();
if (Future2->GetTask().IsError())
{
return Future2->GetTask().Error();
}
const auto Result = Future2->GetTask().Result();var domain = ez.idle.namespace_(
"namespace-0001"
).me(game_session).status(
"category-0001"
)
var async_result = await domain.prediction(
)
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.resultreceive
누적된 방치 보상을 수령
지정한 카테고리에서 플레이어의 방치 시간을 기준으로 누적된 보상을 수령합니다.
보상량은 플레이어가 방치한 시간을 보상 간격으로 나눈 값에서 계산되며, 최대 방치 시간으로 상한이 설정됩니다.
수령 후, 방치 타이머는 리셋되고 0부터 다시 누적이 시작됩니다.
방치 보상 화면의 “보상 수령” 또는 “회수” 버튼에 사용합니다. 예를 들어 플레이어가 “회수"를 탭하면 자리를 비운 동안 누적된 “골드 90개, 젬 5개"를 수령하는 동작입니다.
Request
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| categoryName | string | ✓ | ~ 128자 | 카테고리 모델 이름 이 스테이터스가 속한 카테고리 모델의 이름입니다. 방치 보상 계산에 사용되는 보상 간격, 최대 방치 시간, 입수 액션, 스케줄 설정을 포함하는 카테고리 모델 정의를 참조합니다. | ||
| gameSession | GameSession | ✓ | GameSession |
Result
| 타입 | 설명 | |
|---|---|---|
| items | List<EzAcquireAction> | 보상 |
| status | EzStatus | 갱신한 스테이터스 |
| transactionId | string | 발행된 트랜잭션 ID |
| stampSheet | string | 퀘스트 시작 처리 실행에 사용하는 스탬프 시트 |
| stampSheetEncryptionKeyId | string | 스탬프 시트의 서명 계산에 사용한 암호화 키 GRN |
| autoRunStampSheet | bool | 트랜잭션 자동 실행이 활성화되어 있는지 여부 |
| atomicCommit | bool | 트랜잭션을 원자적으로 커밋할지 여부 |
| transaction | string | 발행된 트랜잭션 |
| transactionResult | EzTransactionResult | 트랜잭션 실행 결과 |
구현 예제
var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
categoryName: "category-0001"
);
var result = await domain.ReceiveAsync(
);
// New Experience에서는 스탬프 시트가 SDK 레벨에서 자동으로 실행됩니다.
// 에러가 발생하면 TransactionException이 발생합니다.
// TransactionException::Retry()로 재시도할 수 있습니다. var domain = gs2.Idle.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Status(
categoryName: "category-0001"
);
var future = domain.ReceiveFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
// New Experience에서는 스탬프 시트가 SDK 레벨에서 자동으로 실행됩니다.
// 에러가 발생하면 TransactionException이 발생합니다.
// TransactionException::Retry()로 재시도할 수 있습니다. const auto Domain = Gs2->Idle->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Status(
"category-0001" // categoryName
);
const auto Future = Domain->Receive(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}var domain = ez.idle.namespace_(
"namespace-0001"
).me(game_session).status(
"category-0001"
)
var async_result = await domain.receive(
)
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result