GS2-Enhance SDK for Game Engine API 레퍼런스
모델
EzProgress
강화 진행 상황
강화 시작 시 생성되며, 종료 시 삭제됩니다.
강화 도중에 앱을 종료한 경우에는 이 데이터가 남은 상태가 되며
엔티티가 보유한 진행 중인 강화 정보로부터 게임을 재개할 수 있습니다.
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| name | string | ✓ | UUID | ~ 36자 | 강화 진행 상황 ID 강화 진행 상황의 고유 ID를 보유합니다. ID는 UUID(Universally Unique Identifier) 형식으로 자동 생성되며, 강화 진행 상황을 식별하는 데 사용됩니다. | |
| rateName | string | ✓ | ~ 128자 | 강화 레이트 모델 이름 이 강화 조작의 파라미터를 정의하는 강화 레이트 모델의 이름입니다. 대상 인벤토리, 소재 인벤토리, 경험치 계층, 보너스 레이트를 지정하는 모델을 참조합니다. | ||
| propertyId | string | ✓ | ~ 1024자 | 강화 대상의 프로퍼티 ID 강화되는 GS2-Inventory 아이템의 프로퍼티 ID입니다. 강화 완료 시 경험치를 받는 특정 아이템 인스턴스를 식별합니다. | ||
| experienceValue | long | ✓ | 0 ~ 9223372036854775805 | 획득할 수 있는 경험치 소비한 소재로부터 산출된 기본 경험치입니다. 이 값은 각 소재의 메타데이터에 정의된 경험치에 소재 수량을 곱한 값의 합계로 결정됩니다. | ||
| rate | float | ✓ | 0 ~ 100.0 | 경험치 배율 기본 경험치에 적용되는 보너스 배율입니다. 강화 레이트 모델의 보너스 레이트에서 가중치 추첨으로 결정됩니다. 1.0은 보너스 없음을, 1.0보다 큰 값은 “대성공” 보너스를 나타냅니다(예: 1.5로 경험치 150%). |
EzRateModel
강화 레이트 모델
강화 레이트는 강화에 사용하는 소재와 강화 대상을 정의한 데이터입니다.
소재 데이터와 강화 대상 데이터는 모두 GS2-Inventory에서 관리되고 있어야 합니다.
강화로 얻는 경험치는 GS2-Inventory의 메타데이터에 JSON 형식으로 기록됩니다.
여기서는 메타데이터의 어느 계층에 경험치 값이 저장되어 있는지를 기재해야 합니다.
강화 시 일정 확률로 대성공과 같은 형태로 입수할 수 있는 경험치량에 보정값을 적용할 수 있습니다.
그 추첨 확률도 이 엔티티에서 정의합니다.
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128자 | 강화 레이트 모델 이름 강화 레이트 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(밑줄) .(마침표)로 지정합니다. | ||
| metadata | string | ~ 2048자 | 메타데이터 메타데이터에는 임의의 값을 설정할 수 있습니다. 이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. | |||
| targetInventoryModelId | string | ✓ | ~ 1024자 | 강화 대상으로 사용할 수 있는 GS2-Inventory 인벤토리 모델의 GRN
강화 대상이 되는 아이템을 보유하는 GS2-Inventory의 인벤토리 모델을 지정합니다. 강화되는 아이템은 이 인벤토리 모델에 속해 있어야 합니다. | ||
| acquireExperienceSuffix | string | ✓ | ~ 1024자 | GS2-Experience에서 획득한 경험치를 저장하는 프로퍼티 ID에 부여하는 서픽스 아이템의 프로퍼티 ID 끝에 추가되어, 경험치가 저장되는 GS2-Experience의 프로퍼티 ID를 구성하는 문자열입니다. 같은 아이템에 여러 경험치 종류를 부여할 수 있습니다(예: 캐릭터 레벨의 “level”, 호감도의 “like”). | ||
| materialInventoryModelId | string | ✓ | ~ 1024자 | 강화 소재로 사용할 수 있는 GS2-Inventory 인벤토리 모델 GRN
강화 소재로 사용할 수 있는 아이템을 보유하는 GS2-Inventory의 인벤토리 모델을 지정합니다. 각 소재가 제공하는 경험치는 acquireExperienceHierarchy로 지정된 JSON 계층을 사용하여 아이템 모델의 메타데이터에 정의됩니다. | ||
| acquireExperienceHierarchy | List<string> | 0 ~ 10 items | ItemModel의 메타데이터에 저장할, 획득 경험치를 정의하는 JSON 데이터의 계층 구조 정의 GS2-Enhance에는 GS2-Inventory와 연동하여 강화를 수행하는 기능이 있으며, ItemModel의 메타데이터에 JSON 형식으로 강화 소재로 사용했을 때의 경험치량을 설정합니다. 예를 들어, { “aaa”: { “bbb”: { “experienceValue”: 100 } } }와 같은 구조의 데이터 정의로 메타데이터에 설정하고 싶은 경우에는 [ “aaa”, “bbb”, “experienceValue” ]와 같이 지정합니다. 자세한 내용은 마이크로서비스 소개 / GS2-Enhance 항목에서 설명합니다. | |||
| experienceModelId | string | ✓ | ~ 1024자 | 강화 결과로 얻는 GS2-Experience 경험치 모델 GRN
강화로 얻은 경험치가 기록되는 GS2-Experience의 경험치 모델을 지정합니다. 경험치는 대상 아이템의 프로퍼티 ID와 acquireExperienceSuffix를 조합하여 식별되는 프로퍼티에 가산됩니다. |
EzUnleashRateModel
한계돌파 레이트 모델
아이템의 한계돌파(해방) 조건을 정의합니다. GS2-Inventory에서 관리되는 아이템과 GS2-Grade의 그레이드 모델을 연결하여 그레이드 진행을 가능하게 합니다. 각 그레이드 레벨에서 소비하는 동일 종류 아이템의 수를 개별적으로 설정할 수 있어, 각 한계돌파 단계의 비용을 세밀하게 제어할 수 있습니다.
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| name | string | ✓ | ~ 128자 | 한계돌파 레이트 모델명 한계돌파 레이트 모델 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| metadata | string | ~ 2048자 | 메타데이터 메타데이터에는 임의의 값을 설정할 수 있습니다. 이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다. | |||
| targetInventoryModelId | string | ✓ | ~ 1024자 | 한계돌파 대상에 사용할 수 있는 GS2-Inventory 인벤토리 모델 GRN
한계돌파 대상이 되는 아이템을 보유하는 GS2-Inventory의 인벤토리 모델을 지정합니다. 한계돌파하는 아이템과 소재로 소비되는 동일 종류 아이템 모두 이 인벤토리 모델에 속해 있어야 합니다. | ||
| gradeModelId | string | ✓ | ~ 1024자 | 그레이드 모델 GRN
대상 아이템의 한계돌파 레벨을 추적하는 GS2-Grade의 그레이드 모델을 지정합니다. 한계돌파가 성공하면, 이 그레이드 모델 내에서 아이템의 그레이드가 가산됩니다. | ||
| gradeEntries | List<EzUnleashRateEntryModel> | ✓ | 1 ~ 1000 items | 그레이드 엔트리 목록 한계돌파의 각 그레이드 레벨에 대한 소재 비용을 정의합니다. 각 엔트리는 그레이드 값과, 해당 그레이드에 도달하기 위해 소비해야 하는 동일 종류 아이템 수를 매핑합니다. 예를 들어, 그레이드 1은 복제품 1개, 그레이드 2는 복제품 3개와 같이 설정할 수 있습니다. |
EzUnleashRateEntryModel
한계돌파 레이트 엔트리 모델
한계돌파 진행에서 단일 그레이드 레벨의 소재 비용을 정의합니다. 각 엔트리는 대상이 되는 그레이드 값과, 해당 그레이드를 달성하기 위해 소비해야 하는 동일 종류 아이템의 수를 지정합니다.
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| gradeValue | long | ✓ | 1 ~ 1000 | 대상 그레이드 이 엔트리가 비용을 정의하는 그레이드 값입니다. 이 그레이드 레벨로의 한계돌파를 실행할 때, needCount로 지정된 수의 아이템이 소비됩니다. | ||
| needCount | int | ✓ | 1 ~ 1000 | 동일 종류의 아이템을 몇 개 소비할지 대상 그레이드로의 한계돌파를 실행하기 위해 소비해야 하는 동일 종류 아이템의 수입니다. 이 아이템들은 한계돌파되는 아이템과 동일한 아이템 모델의 것입니다. |
EzConfig
컨피그 설정
트랜잭션의 변수에 적용하는 설정 값
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| key | string | ✓ | ~ 64자 | 이름 | ||
| value | string | ~ 51200자 | 값 |
EzMaterial
강화 소재
강화 조작 중에 소비되는 소재 아이템을 나타냅니다. 각 소재는 특정 GS2-Inventory 아이템 세트를 참조하며, 소비할 수량을 지정합니다. 소재가 제공하는 경험치는 아이템 모델의 메타데이터로부터 결정됩니다.
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| materialItemSetId | string | ✓ | ~ 1024자 | 강화 소재가 되는 아이템 세트의 GRN
강화 소재로 소비되는 특정 GS2-Inventory 아이템 세트를 참조합니다. 아이템은 강화 레이트 모델에서 지정된 소재 인벤토리 모델에 속해 있어야 합니다. | ||
| count | int | 1 | 0 ~ 2147483645 | 소비 수량 이 소재 아이템의 소비 수량입니다. 이 소재로부터 얻는 합계 경험치는, 아이템 1개당 경험치(아이템 모델의 메타데이터에서 취득)에 이 수량을 곱하여 계산됩니다. |
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 | 획득 액션 실행 결과 리스트 |
메서드
getRateModel
이름을 지정하여 강화 레이트 모델을 취득한다
이름을 지정하여 강화 레이트 모델을 1건 취득합니다.
취득할 수 있는 정보에는 강화 대상 아이템이 속한 인벤토리, 소재가 속한 인벤토리, 소재로부터의 경험치 계산 방법, 보너스 레이트 확률 테이블이 포함됩니다.
특정 강화 레시피의 상세 정보를 표시할 때 사용합니다. 예를 들어 무기 강화 화면에서 필요한 소재나 보너스 레이트 확률을 표시하는 데 유용합니다.
Request
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| rateName | string | ✓ | ~ 128자 | 강화 레이트 모델 이름 강화 레이트 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(밑줄) .(마침표)로 지정합니다. |
Result
| 타입 | 설명 | |
|---|---|---|
| item | EzRateModel | 강화 레이트 모델 |
구현 예제
var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
).RateModel(
rateName: "character-level"
);
var item = await domain.ModelAsync(); var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
).RateModel(
rateName: "character-level"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Enhance->Namespace(
"namespace-0001" // namespaceName
)->RateModel(
"character-level" // rateName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}var domain = ez.enhance.namespace_(
"namespace-0001"
).rate_model(
"character-level"
)
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.Enhance.Namespace(
namespaceName: "namespace-0001"
).RateModel(
rateName: "character-level"
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId); var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
).RateModel(
rateName: "character-level"
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Enhance->Namespace(
"namespace-0001" // namespaceName
)->RateModel(
"character-level" // rateName
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Enhance::Model::FRateModel> value) {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
Domain->Unsubscribe(CallbackId);var domain = ez.enhance.namespace_(
"namespace-0001"
).rate_model(
"character-level"
)
# 이벤트 핸들링 시작
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의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
listRateModels
강화 레이트 모델 목록을 취득한다
이 네임스페이스에 등록되어 있는 모든 강화 레이트 모델을 취득합니다.
레이트 모델은 강화 레시피를 정의합니다. 어떤 아이템을 소재로 사용할 수 있는지, 각 소재가 얼마의 경험치를 주는지, 보너스 배율 추첨이 있는지 등을 설정합니다.
강화 UI를 구축할 때 사용합니다. 예를 들어 어떤 무기를 강화할 수 있고 어떤 소재를 받는지 표시하는 데 유용합니다.
Request
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
Result
| 타입 | 설명 | |
|---|---|---|
| items | List<EzRateModel> | 강화 레이트 모델 목록 |
구현 예제
var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.RateModelsAsync(
).ToListAsync(); var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.RateModels(
);
List<EzRateModel> items = new List<EzRateModel>();
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->Enhance->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->RateModels(
);
TArray<Gs2::UE5::Enhance::Model::FEzRateModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}값 변경 이벤트 핸들링
var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeRateModels(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeRateModels(callbackId); var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeRateModels(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeRateModels(callbackId); const auto Domain = Gs2->Enhance->Namespace(
"namespace-0001" // namespaceName
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->SubscribeRateModels(
[]() {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
Domain->UnsubscribeRateModels(CallbackId);이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
getUnleashRateModel
이름을 지정하여 한계돌파 레이트 모델을 취득한다
이름을 지정하여 한계돌파(해방) 레이트 모델을 1건 취득합니다.
취득할 수 있는 정보에는 대상 인벤토리, 아이템의 그레이드를 관리하는 그레이드 모델, 각 그레이드 레벨의 소재 요건을 정의하는 그레이드 엔트리 목록이 포함됩니다.
특정 한계돌파 레시피의 상세 정보를 표시할 때 사용합니다. 예를 들어 아이템 상세 화면에서 “그레이드 1→2: 동일 아이템 1개 필요”, “그레이드 2→3: 동일 아이템 2개 필요"와 같이 표시하는 데 유용합니다.
Request
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| rateName | string | ✓ | ~ 128자 | 한계돌파 레이트 모델명 한계돌파 레이트 모델 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
Result
| 타입 | 설명 | |
|---|---|---|
| item | EzUnleashRateModel | 한계돌파 레이트 모델 |
구현 예제
var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
).UnleashRateModel(
rateName: "character-level"
);
var item = await domain.ModelAsync(); var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
).UnleashRateModel(
rateName: "character-level"
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Enhance->Namespace(
"namespace-0001" // namespaceName
)->UnleashRateModel(
"character-level" // rateName
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}var domain = ez.enhance.namespace_(
"namespace-0001"
).unleash_rate_model(
"character-level"
)
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.Enhance.Namespace(
namespaceName: "namespace-0001"
).UnleashRateModel(
rateName: "character-level"
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId); var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
).UnleashRateModel(
rateName: "character-level"
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Enhance->Namespace(
"namespace-0001" // namespaceName
)->UnleashRateModel(
"character-level" // rateName
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Enhance::Model::FUnleashRateModel> value) {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
Domain->Unsubscribe(CallbackId);var domain = ez.enhance.namespace_(
"namespace-0001"
).unleash_rate_model(
"character-level"
)
# 이벤트 핸들링 시작
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의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
listUnleashRateModels
한계돌파 레이트 모델 목록을 취득한다
이 네임스페이스에 등록되어 있는 모든 한계돌파(해방) 레이트 모델을 취득합니다.
한계돌파 레이트 모델은 아이템의 그레이드(레벨 상한)를 올리는 방법을 정의합니다. 예를 들어 같은 무기의 복제품을 소비하여 레벨 상한을 올리는 방식입니다.
각 모델은 그레이드별로 필요한 소재를 지정할 수 있어, 아이템이 강해질수록 비용을 높일 수도 있습니다.
한계돌파 UI 구축에 사용합니다. 어떤 아이템을 한계돌파할 수 있고 어떤 소재가 필요한지 플레이어에게 표시하는 데 유용합니다.
Request
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. |
Result
| 타입 | 설명 | |
|---|---|---|
| items | List<EzUnleashRateModel> | 한계돌파 레이트 모델 목록 |
구현 예제
var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
);
var items = await domain.UnleashRateModelsAsync(
).ToListAsync(); var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
);
var it = domain.UnleashRateModels(
);
List<EzUnleashRateModel> items = new List<EzUnleashRateModel>();
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->Enhance->Namespace(
"namespace-0001" // namespaceName
);
const auto It = Domain->UnleashRateModels(
);
TArray<Gs2::UE5::Enhance::Model::FEzUnleashRateModelPtr> Result;
for (auto Item : *It)
{
if (Item.IsError())
{
return false;
}
Result.Add(Item.Current());
}값 변경 이벤트 핸들링
var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeUnleashRateModels(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeUnleashRateModels(callbackId); var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
);
// 이벤트 핸들링 시작
var callbackId = domain.SubscribeUnleashRateModels(
() => {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
domain.UnsubscribeUnleashRateModels(callbackId); const auto Domain = Gs2->Enhance->Namespace(
"namespace-0001" // namespaceName
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->SubscribeUnleashRateModels(
[]() {
// 리스트의 요소가 변화했을 때 호출됨
}
);
// 이벤트 핸들링 정지
Domain->UnsubscribeUnleashRateModels(CallbackId);이 이벤트는 SDK가 가진 로컬 캐시의 값이 변경되었을 때 호출됩니다.
로컬 캐시는 SDK가 가진 API의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-Distributor를 통한 스탬프 시트의 실행, 또는 GS2-Gateway의 알림을 활성화한 GS2-JobQueue의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
deleteProgress
진행 중인 강화를 취소한다
플레이어의 진행 중인 강화의 진행 정보를 삭제하여 강화를 취소합니다.
Start에서 소비된 소재는 반환되지 않습니다. 보류 중인 경험치 부여만 취소됩니다.
플레이어가 강화를 취소하고 싶은 경우나, 다른 강화를 시작하기 전에 정리하고 싶은 경우에 사용합니다.
또는 Start 호출 시 force를 true로 설정하면 기존 진행 정보를 자동으로 폐기할 수도 있습니다.
Request
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| gameSession | GameSession | ✓ | GameSession |
Result
| 타입 | 설명 | |
|---|---|---|
| item | EzProgress | 강화의 진행 정보 |
구현 예제
var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Progress(
);
var result = await domain.DeleteProgressAsync(
); var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Progress(
);
var future = domain.DeleteProgressFuture(
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
} const auto Domain = Gs2->Enhance->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Progress(
);
const auto Future = Domain->DeleteProgress(
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}
const auto Result = Future->GetTask().Result();var domain = ez.enhance.namespace_(
"namespace-0001"
).me(game_session).progress(
)
var async_result = await domain.delete_progress(
)
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.resultend
강화를 완료한다 (2단계 흐름)
Start API로 시작한 강화 처리를 완료합니다.
Start 시에 사전 계산된 경험치와 보너스 레이트를 대상 아이템에 반영합니다.
완료 후 진행 정보는 자동으로 삭제됩니다.
결과에는 획득 경험치와 보너스 레이트가 포함되므로, “강화 완료! +1200 EXP"와 같은 최종 결과 화면을 표시할 수 있습니다.
Request
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| gameSession | GameSession | ✓ | GameSession | |||
| config | List<EzConfig> | [] | 0 ~ 32 items | 트랜잭션 변수에 적용할 설정값 |
Result
| 타입 | 설명 | |
|---|---|---|
| item | EzProgress | 강화의 진행 정보 |
| transactionId | string | 발행된 트랜잭션 ID |
| stampSheet | string | 보상 지급 처리 실행에 사용하는 스탬프 시트 |
| stampSheetEncryptionKeyId | string | 스탬프 시트의 서명 계산에 사용한 암호화 키 GRN |
| autoRunStampSheet | bool | 트랜잭션 자동 실행이 활성화되어 있는지 여부 |
| atomicCommit | bool | 트랜잭션을 원자적으로 커밋할지 여부 |
| transaction | string | 발행된 트랜잭션 |
| transactionResult | EzTransactionResult | 트랜잭션 실행 결과 |
| acquireExperience | long | 획득 경험치량 |
| bonusRate | float | 경험치 보너스 배율(1.0=보너스 없음) |
구현 예제
var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Progress(
);
var result = await domain.EndAsync(
config: null
);
// New Experience에서는 스탬프 시트가 SDK 레벨에서 자동으로 실행됩니다.
// 에러가 발생하면 TransactionException이 발생합니다.
// TransactionException::Retry()로 재시도할 수 있습니다. var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Progress(
);
var future = domain.EndFuture(
config: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
// New Experience에서는 스탬프 시트가 SDK 레벨에서 자동으로 실행됩니다.
// 에러가 발생하면 TransactionException이 발생합니다.
// TransactionException::Retry()로 재시도할 수 있습니다. const auto Domain = Gs2->Enhance->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Progress(
);
const auto Future = Domain->End(
// config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}var domain = ez.enhance.namespace_(
"namespace-0001"
).me(game_session).progress(
)
var async_result = await domain.end(
null # config
)
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.resultgetProgress
현재 강화의 진행 정보를 취득한다
플레이어의 진행 중인 강화 진행 정보를 취득합니다.
진행 정보에는 레이트 모델 이름, 대상 아이템, 사용한 소재, 사전 계산된 경험치, 추첨된 보너스 레이트가 포함됩니다.
플레이어가 이탈했다가 돌아왔을 때 강화 확인 화면을 복원하는 데 사용합니다. 예를 들어 “+1200 EXP 획득 예정(대성공 x1.5)“을 다시 표시할 때 유용합니다.
Request
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| gameSession | GameSession | ✓ | GameSession |
Result
| 타입 | 설명 | |
|---|---|---|
| item | EzProgress | 실행 중인 강화의 진행 정보 |
구현 예제
var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Progress(
);
var item = await domain.ModelAsync(); var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Progress(
);
var future = domain.ModelFuture();
yield return future;
var item = future.Result; const auto Domain = Gs2->Enhance->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Progress(
);
const auto Future = Domain->Model();
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}var domain = ez.enhance.namespace_(
"namespace-0001"
).me(game_session).progress(
)
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.Enhance.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Progress(
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId); var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Progress(
);
// 이벤트 핸들링 시작
var callbackId = domain.Subscribe(
value => {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
domain.Unsubscribe(callbackId); const auto Domain = Gs2->Enhance->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Progress(
);
// 이벤트 핸들링 시작
const auto CallbackId = Domain->Subscribe(
[](TSharedPtr<Gs2::Enhance::Model::FProgress> value) {
// 값이 변화했을 때 호출됨
// value에는 변경 후의 값이 전달됨
}
);
// 이벤트 핸들링 정지
Domain->Unsubscribe(CallbackId);var domain = ez.enhance.namespace_(
"namespace-0001"
).me(game_session).progress(
)
# 이벤트 핸들링 시작
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의 실행에 의해 변화한 것만이 대상이 됩니다.
따라서 이 방법 이외로 값이 변경된 경우 콜백은 호출되지 않습니다.
start
강화를 시작한다 (2단계 흐름)
소재를 소비하여 경험치와 보너스 레이트를 계산하지만, 경험치는 아직 반영하지 않습니다.
계산 결과는 진행 정보로 저장되므로, 플레이어에게 확인 화면을 표시할 수 있습니다. 예를 들어 “+1200 EXP 획득 예정(대성공 x1.5)“과 같은 미리보기를 보여줄 수 있습니다.
플레이어가 확인하면 End를 호출하여 실제로 대상 아이템에 경험치를 반영합니다.
이미 진행 중인 강화가 있는 경우, force를 true로 설정하면 이를 폐기하고 새로운 강화를 시작할 수 있습니다.
Request
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| rateName | string | ✓ | ~ 128자 | 강화 레이트 모델 이름 이 강화 조작의 파라미터를 정의하는 강화 레이트 모델의 이름입니다. 대상 인벤토리, 소재 인벤토리, 경험치 계층, 보너스 레이트를 지정하는 모델을 참조합니다. | ||
| targetItemSetId | string | ✓ | ~ 1024자 | 강화 대상 아이템 세트의 GRN | ||
| materials | List<EzMaterial> | 0 ~ 10 items | 강화 소재 목록 | |||
| gameSession | GameSession | ✓ | GameSession | |||
| force | bool | false | 이미 시작된 강화가 있는 경우 이를 폐기하고 시작할지 | |||
| config | List<EzConfig> | [] | 0 ~ 32 items | 트랜잭션 변수에 적용할 설정값 |
Result
| 타입 | 설명 | |
|---|---|---|
| transactionId | string | 발행된 트랜잭션 ID |
| stampSheet | string | 강화 시작 처리 실행에 사용하는 스탬프 시트 |
| stampSheetEncryptionKeyId | string | 스탬프 시트의 서명 계산에 사용한 암호화 키 GRN |
| autoRunStampSheet | bool | 트랜잭션 자동 실행이 활성화되어 있는지 여부 |
| atomicCommit | bool | 트랜잭션을 원자적으로 커밋할지 여부 |
| transaction | string | 발행된 트랜잭션 |
| transactionResult | EzTransactionResult | 트랜잭션 실행 결과 |
구현 예제
var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Progress(
);
var result = await domain.StartAsync(
rateName: "character-level",
targetItemSetId: "item-set-0001",
materials: new List<Gs2.Unity.Gs2Enhance.Model.EzMaterial> {
new Gs2.Unity.Gs2Enhance.Model.EzMaterial() {
MaterialItemSetId = "material-0001",
Count = 1,
},
},
force: null,
config: null
);
// New Experience에서는 스탬프 시트가 SDK 레벨에서 자동으로 실행됩니다.
// 에러가 발생하면 TransactionException이 발생합니다.
// TransactionException::Retry()로 재시도할 수 있습니다. var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Progress(
);
var future = domain.StartFuture(
rateName: "character-level",
targetItemSetId: "item-set-0001",
materials: new List<Gs2.Unity.Gs2Enhance.Model.EzMaterial> {
new Gs2.Unity.Gs2Enhance.Model.EzMaterial() {
MaterialItemSetId = "material-0001",
Count = 1,
},
},
force: null,
config: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
// New Experience에서는 스탬프 시트가 SDK 레벨에서 자동으로 실행됩니다.
// 에러가 발생하면 TransactionException이 발생합니다.
// TransactionException::Retry()로 재시도할 수 있습니다. const auto Domain = Gs2->Enhance->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Progress(
);
const auto Future = Domain->Start(
"character-level", // rateName
"item-set-0001", // targetItemSetId
[]
{
auto v = MakeShared<TArray<TSharedPtr<Gs2::UE5::Enhance::Model::FEzMaterial>>>();
v->Add(
MakeShared<Gs2::UE5::Enhance::Model::FEzMaterial>()
->WithMaterialItemSetId(TOptional<FString>("material-0001"))
->WithCount(TOptional<int32>(1))
);
return v;
}() // materials
// force
// config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}var domain = ez.enhance.namespace_(
"namespace-0001"
).me(game_session).progress(
)
var async_result = await domain.start(
"character-level", # rate_name
"item-set-0001", # target_item_set_id
[
Gs2EnhanceEzMaterial.new()
.with_material_item_set_id("material-0001")
.with_count(1),
], # materials
null, # force
null # config
)
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.resultenhance
아이템을 강화한다
지정한 소재를 소비하여 대상 아이템에 경험치를 부여합니다(1단계로 완료).
획득 경험치는 강화 레이트 모델을 기반으로 계산되며, 보너스 레이트 확률 테이블에서 배율이 추첨되는 경우가 있습니다. 예를 들어 “대성공"으로 경험치가 1.5배가 되는 방식입니다.
결과에는 획득한 경험치량과 적용된 보너스 레이트가 포함되므로, “무기가 레벨업! +1200 EXP(대성공 x1.5)“와 같은 결과 화면을 표시할 수 있습니다.
이는 가장 간단한 강화 방법입니다. 플레이어에게 결과를 보여준 후 확정하고 싶은 경우에는 Start/End 흐름을 사용해 주세요.
Request
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| rateName | string | ✓ | ~ 128자 | 강화 레이트 모델 이름 강화 레이트 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(밑줄) .(마침표)로 지정합니다. | ||
| gameSession | GameSession | ✓ | GameSession | |||
| targetItemSetId | string | ✓ | ~ 1024자 | 강화 대상 아이템 세트의 GRN | ||
| materials | List<EzMaterial> | ✓ | 1 ~ 10 items | 강화 소재 목록 | ||
| config | List<EzConfig> | [] | 0 ~ 32 items | 트랜잭션 변수에 적용할 설정값 |
Result
| 타입 | 설명 | |
|---|---|---|
| item | EzRateModel | 강화 레이트 모델 |
| transactionId | string | 발행된 트랜잭션 ID |
| stampSheet | string | 강화 처리 실행에 사용하는 스탬프 시트 |
| stampSheetEncryptionKeyId | string | 스탬프 시트의 서명 계산에 사용한 암호화 키 GRN |
| autoRunStampSheet | bool | 트랜잭션 자동 실행이 활성화되어 있는지 여부 |
| atomicCommit | bool | 트랜잭션을 원자적으로 커밋할지 여부 |
| transaction | string | 발행된 트랜잭션 |
| transactionResult | EzTransactionResult | 트랜잭션 실행 결과 |
| acquireExperience | long | 획득 경험치량 |
| bonusRate | float | 경험치 보너스 배율(1.0=보너스 없음) |
구현 예제
var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Enhance(
);
var result = await domain.EnhanceAsync(
rateName: "rate-0001",
targetItemSetId: "item-set-0001",
materials: new List<Gs2.Unity.Gs2Enhance.Model.EzMaterial> {
new Gs2.Unity.Gs2Enhance.Model.EzMaterial() {
MaterialItemSetId = "material-0001",
Count = 1,
},
},
config: null
);
// New Experience에서는 스탬프 시트가 SDK 레벨에서 자동으로 실행됩니다.
// 에러가 발생하면 TransactionException이 발생합니다.
// TransactionException::Retry()로 재시도할 수 있습니다. var domain = gs2.Enhance.Namespace(
namespaceName: "namespace-0001"
).Me(
gameSession: GameSession
).Enhance(
);
var future = domain.EnhanceFuture(
rateName: "rate-0001",
targetItemSetId: "item-set-0001",
materials: new List<Gs2.Unity.Gs2Enhance.Model.EzMaterial> {
new Gs2.Unity.Gs2Enhance.Model.EzMaterial() {
MaterialItemSetId = "material-0001",
Count = 1,
},
},
config: null
);
yield return future;
if (future.Error != null)
{
onError.Invoke(future.Error, null);
yield break;
}
// New Experience에서는 스탬프 시트가 SDK 레벨에서 자동으로 실행됩니다.
// 에러가 발생하면 TransactionException이 발생합니다.
// TransactionException::Retry()로 재시도할 수 있습니다. const auto Domain = Gs2->Enhance->Namespace(
"namespace-0001" // namespaceName
)->Me(
GameSession
)->Enhance(
);
const auto Future = Domain->Enhance(
"rate-0001", // rateName
"item-set-0001", // targetItemSetId
[]
{
auto v = MakeShared<TArray<TSharedPtr<Gs2::UE5::Enhance::Model::FEzMaterial>>>();
v->Add(
MakeShared<Gs2::UE5::Enhance::Model::FEzMaterial>()
->WithMaterialItemSetId(TOptional<FString>("material-0001"))
->WithCount(TOptional<int32>(1))
);
return v;
}() // materials
// config
);
Future->StartSynchronousTask();
if (Future->GetTask().IsError())
{
return false;
}var domain = ez.enhance.namespace_(
"namespace-0001"
).me(game_session).enhance(
)
var async_result = await domain.enhance(
"rate-0001", # rate_name
"item-set-0001", # target_item_set_id
[
Gs2EnhanceEzMaterial.new()
.with_material_item_set_id("material-0001")
.with_count(1),
], # materials
null # config
)
if async_result.error != null:
push_error(str(async_result.error))
return
var result = async_result.result