GS2-Enhance SDK for Game Engine API 레퍼런스

게임 엔진용 GS2-Enhance SDK의 모델 사양과 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 형식으로 기록됩니다.
여기서는 메타데이터의 어느 계층에 경험치 값이 저장되어 있는지를 기재해야 합니다.

강화 시 일정 확률로 대성공과 같은 형태로 입수할 수 있는 경험치량에 보정값을 적용할 수 있습니다.
그 추첨 확률도 이 엔티티에서 정의합니다.

targetInventoryModelId 에는 강화 대상이 되는 아이템을 보유하는 인벤토리 모델을, materialInventoryModelId 에는 소재로 사용할 수 있는 아이템을 보유하는 인벤토리 모델을 지정합니다.
양쪽은 서로 다른 인벤토리 모델로 할 수 있으므로, 캐릭터를 강화 대상으로 하고 강화 전용 아이템을 소재로 하는 구성이 가능합니다.

각 소재가 제공하는 경험치는 소재 아이템의 아이템 모델 메타데이터에 기술하며, 그 JSON의 어디에 값이 들어 있는지를 acquireExperienceHierarchy 로 지정합니다.
{ "aaa": { "bbb": { "experienceValue": 100 } } } 와 같은 구조라면 [ "aaa", "bbb", "experienceValue" ] 와 같이 지정합니다. 계층은 최대 10단계까지 지정할 수 있습니다.

획득한 경험치는 experienceModelId 로 지정한 GS2-Experience 의 경험치 모델에 가산됩니다.
가산 대상 프로퍼티 ID는 강화 대상 아이템의 프로퍼티 ID에 acquireExperienceSuffix 를 부여한 것이 됩니다. 이를 통해 하나의 아이템에 캐릭터 레벨의 level 과 호감도의 like 같은 여러 종류의 경험치를 가지게 할 수 있습니다.

bonusRates 에는 획득 경험치에 적용할 배율의 가중치 추첨을 정의합니다.
각 항목은 배율(1.5 라면 150%)과 배출 가중치를 가지며, 강화를 실행할 때마다 가중치 추첨으로 하나가 선택됩니다. 항목은 최대 1,000건까지 등록할 수 있습니다.

타입 활성화 조건 필수 기본값 값 제한 설명
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-Grade 에서 관리하는 그레이드를 끌어올리는 강화 처리입니다.
그레이드가 올라가면 GS2-Experience 측의 랭크 캡이 상향되어, 대상을 더 높은 레벨까지 육성할 수 있게 됩니다.

targetInventoryModelId 에는 한계돌파 대상이 되는 아이템을 보유하는 GS2-Inventory 의 인벤토리 모델을 지정합니다.
한계돌파하는 아이템과 소재로 소비하는 동일 종류 아이템 모두 이 인벤토리 모델에 속해 있어야 합니다.
gradeModelId 에는 대상 아이템의 그레이드를 추적하는 GS2-Grade 의 그레이드 모델을 지정합니다. 한계돌파에 성공하면 해당 그레이드가 1 상향됩니다.

gradeEntries 에는 각 그레이드에 도달하기 위해 소비하는 동일 종류 아이템의 수를 그레이드별로 정의합니다. 엔트리는 1건 이상 1,000건까지 등록할 수 있습니다.
예를 들어 그레이드 1은 1개, 그레이드 2는 3개와 같이 설정함으로써 한계돌파 단계마다 비용을 개별적으로 제어할 수 있습니다.

소재로 소비한 리소스는 그 리소스가 보유하고 있던 내용과 함께 사라집니다.
소재가 경험치 등의 리소스를 가지고 있더라도 대상에게 인계되지 않으므로, 인계가 필요한 경우에는 사전에 인계용 리소스로 변환해 두어야 합니다.

타입 활성화 조건 필수 기본값 값 제한 설명
name string
✓
~ 128자 한계돌파 레이트 모델명
한계돌파 레이트 모델 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
metadata string ~ 2048자 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다.
targetInventoryModelId string
✓
~ 1024자 한계돌파 대상에 사용할 수 있는 GS2-Inventory 인벤토리 모델 GRN
한계돌파 대상이 되는 아이템을 보유하는 GS2-Inventory의 인벤토리 모델을 지정합니다. 한계돌파하는 아이템과 소재로 소비되는 동일 종류 아이템 모두 이 인벤토리 모델에 속해 있어야 합니다.
gradeModelId string
✓
~ 1024자 그레이드 모델 GRN
대상 아이템의 한계돌파 레벨을 추적하는 GS2-Grade의 그레이드 모델을 지정합니다. 한계돌파가 성공하면, 이 그레이드 모델 내에서 아이템의 그레이드가 가산됩니다.
groupKeyHierarchy List<string> [] 0 ~ 10 items ItemModel의 메타데이터에 저장할, 그룹 키를 정의하는 JSON 데이터의 계층 구조
그룹 키는 장비의 부위처럼 아이템 모델을 분류하는 값으로, 레시피가 소재와 한계돌파 대상을 비교할 때 사용합니다.
{ “unleash”: { “group”: “weapon” } }와 같은 구조의 메타데이터라면 [ “unleash”, “group” ]으로 지정합니다.
값은 문자열이어야 합니다. 레시피에서 “같은 그룹"이나 targetGroupKeys를 사용하는 경우에는 필수입니다.
gradeEntries List<EzUnleashRateEntryModel>
✓
1 ~ 1000 items 그레이드 엔트리 목록
한계돌파의 각 그레이드 레벨에 대한 소재 비용을 정의합니다. 각 엔트리는 그레이드 값과, 해당 그레이드에 도달하기 위해 소비해야 하는 동일 종류 아이템 수를 매핑합니다. 예를 들어, 그레이드 1은 복제품 1개, 그레이드 2는 복제품 3개와 같이 설정할 수 있습니다.

EzUnleashRateEntryModel

한계돌파 레이트 엔트리 모델

한계돌파 진행에서 단일 그레이드 레벨의 소재 비용을 정의합니다. 각 엔트리는 대상이 되는 그레이드 값과, 해당 그레이드를 달성하기 위해 소비해야 하는 동일 종류 아이템의 수를 지정합니다.

타입 활성화 조건 필수 기본값 값 제한 설명
gradeValue long
✓
1 ~ 1000 대상 그레이드
이 엔트리가 비용을 정의하는 그레이드 값입니다. 이 그레이드 레벨로의 한계돌파를 실행할 때, needCount로 지정된 수의 아이템이 소비됩니다.
type 문자열 열거형
enum {
  “simple”,
  “recipe”
}
“simple” 소재 조건의 종류
“심플(simple)“은 한계돌파 대상과 같은 아이템 모델의 복제를 needCount개 소비합니다. 기존의 동작입니다.
“레시피(recipe)“는 플레이어가 레시피를 하나 선택하고, 선택한 레시피에 정의된 소재를 소비합니다.
정의설명
simple심플
recipe레시피
needCount int {type} == “simple”
✓※
1 ~ 1000 동일 종류의 아이템을 몇 개 소비할지
대상 그레이드로의 한계돌파를 실행하기 위해 소비해야 하는 동일 종류 아이템의 수입니다. 이 아이템들은 한계돌파되는 아이템과 동일한 아이템 모델의 것입니다.

※ type이(가) “simple” 이면 필수
recipes List<EzUnleashRecipe> {type} == “recipe”
✓※
1 ~ 10 items 레시피 목록
type이 “레시피"일 때 사용합니다. 한계돌파 실행 시, 플레이어는 이 중에서 레시피를 하나 선택합니다.

※ type이(가) “recipe” 이면 필수

EzUnleashRecipe

한계돌파 레시피

그레이드를 1단계 올리는 방법 중 하나입니다. 그레이드 엔트리에 여러 레시피가 있는 경우, 플레이어는 그중 하나를 선택하며, 선택한 레시피의 소재는 모두 필요합니다.

타입 활성화 조건 필수 기본값 값 제한 설명
name string
✓
~ 128자 레시피 이름
그레이드 엔트리 안에서 고유한 이름입니다. 한계돌파 실행 시, 플레이어는 이 이름으로 레시피를 지정합니다.
metadata string ~ 2048자 메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다.
targetGroupKeys List<string> [] 0 ~ 10 items 이 레시피를 사용할 수 있는 한계돌파 대상의 그룹 키
비어 있는 경우, 어떤 한계돌파 대상에도 사용할 수 있습니다.
값이 있는 경우, 한계돌파 대상 아이템 모델의 그룹 키가 포함될 때만 사용할 수 있습니다. 그룹 키는 한계돌파 레이트 모델의 groupKeyHierarchy를 사용하여 아이템 모델의 메타데이터에서 읽습니다.
materials List<EzUnleashMaterial>
✓
1 ~ 10 items 이 레시피가 필요로 하는 소재
이 레시피를 사용하면 모든 소재가 소비됩니다.

EzUnleashMaterial

한계돌파 소재

레시피가 필요로 하는 소재의 1종류를 정의합니다.
“개체(individual)“는 장비의 복제처럼, 플레이어가 선택한 아이템 세트를 소비합니다.
“수량(quantity)“은 범용 강화 소재처럼, 설정으로 정해지는 아이템을 수량으로 소비합니다.

타입 활성화 조건 필수 기본값 값 제한 설명
name string
✓
~ 128자 소재 이름
레시피 안에서 고유한 이름입니다. 한계돌파 실행 시, 플레이어는 개체 소재마다 이 이름으로 아이템 세트를 지정합니다.
materialType 문자열 열거형
enum {
  “individual”,
  “quantity”
}
✓
소재의 종류
“개체(individual)“는 플레이어가 선택한 아이템 세트를 소비합니다.
“수량(quantity)“은 설정으로 정해지는 아이템을 수량으로 소비합니다.
정의설명
individual개체
quantity수량
individualSetting EzUnleashIndividualMaterialSetting {materialType} == “individual”
✓※
개체 소재 설정
materialType이 “개체"일 때 사용합니다.

※ materialType이(가) “individual” 이면 필수
quantitySetting EzUnleashQuantityMaterialSetting {materialType} == “quantity”
✓※
수량 소재 설정
materialType이 “수량"일 때 사용합니다.

※ materialType이(가) “quantity” 이면 필수

EzUnleashIndividualMaterialSetting

개체 소재 설정

장비의 복제처럼, 아이템 세트를 개체로서 소비하는 소재를 정의합니다.
어떤 아이템 세트를 소비할지는 플레이어가 선택하며, 선택된 아이템 세트는 한계돌파 대상 아이템과 같은 인벤토리 모델에 속해 있어야 합니다.
개체마다 GS2-Grade의 그레이드를 가질 수 있으므로, 소재의 그레이드를 조건으로 할 수도 있습니다.

타입 활성화 조건 필수 기본값 값 제한 설명
matchType 문자열 열거형
enum {
  “sameItem”,
  “sameGroup”
}
✓
소재와 한계돌파 대상의 일치 조건
“같은 아이템(sameItem)“은 한계돌파 대상과 같은 아이템 모델의 아이템 세트만 받습니다.
“같은 그룹(sameGroup)“은 아이템 모델의 그룹 키가 한계돌파 대상의 아이템 모델과 같은 아이템 세트를 받습니다. 그룹 키는 한계돌파 레이트 모델의 groupKeyHierarchy를 사용하여 아이템 모델의 메타데이터에서 읽습니다.
정의설명
sameItem같은 아이템
sameGroup같은 그룹
gradeCondition 문자열 열거형
enum {
  “any”,
  “sameAsTarget”,
  “equal”
}
“any” 소재의 그레이드 조건
“상관없음(any)“은 소재의 그레이드를 확인하지 않습니다.
“한계돌파 대상과 같음(sameAsTarget)“은 소재의 그레이드가 한계돌파 대상의 현재 그레이드와 같을 것을 요구합니다.
“지정값과 일치(equal)“는 소재의 그레이드가 gradeValue로 지정한 값일 것을 요구합니다.
그레이드는 한계돌파 레이트 모델의 그레이드 모델을 사용하여, 트랜잭션 안에서 GS2-Grade에 의해 검증됩니다.
정의설명
any상관없음
sameAsTarget한계돌파 대상과 같음
equal지정값과 일치
gradeValue long {gradeCondition} == “equal”
✓※
0 ~ 1000 소재에 요구하는 그레이드
gradeCondition이 “지정값과 일치"일 때 사용합니다.

※ gradeCondition이(가) “equal” 이면 필수
count int
✓
1 ~ 1000 소비할 아이템 세트의 수
이 소재로서 플레이어가 지정해야 하는 아이템 세트의 수입니다. 각 아이템 세트는 1개씩 소비됩니다.

EzUnleashQuantityMaterialSetting

수량 소재 설정

범용 강화 소재처럼, 수량으로 소비하는 소재를 정의합니다.
플레이어는 아이템을 선택하지 않으며, 소비할 아이템 모델은 이 설정으로 정해지고, 지정한 수량이 소비됩니다.
GS2-Inventory의 일반 인벤토리와 심플 인벤토리 모두 사용할 수 있습니다.

타입 활성화 조건 필수 기본값 값 제한 설명
matchType 문자열 열거형
enum {
  “sameGroup”,
  “specified”
}
✓
소비할 아이템 모델을 정하는 방법
“같은 그룹(sameGroup)“은 materialInventoryModelId의 인벤토리 안에서, 그룹 키가 한계돌파 대상의 아이템 모델과 같은 아이템 모델을 소비합니다. 해당하는 아이템 모델은 정확히 1개여야 합니다.
“지정(specified)“은 itemModelId로 지정한 아이템 모델을 소비합니다.
정의설명
sameGroup같은 그룹
specified지정
materialInventoryModelId string {matchType} == “sameGroup”
✓※
~ 1024자 소재를 찾을 GS2-Inventory 인벤토리 모델 GRN
matchType이 “같은 그룹"일 때 사용합니다. 심플 인벤토리 모델의 GRN도 지정할 수 있습니다.

※ matchType이(가) “sameGroup” 이면 필수
itemModelId string {matchType} == “specified”
✓※
~ 1024자 소비할 GS2-Inventory 아이템 모델 GRN
matchType이 “지정"일 때 사용합니다. 심플 아이템 모델의 GRN도 지정할 수 있습니다.

※ matchType이(가) “specified” 이면 필수
count int
✓
1 ~ 2147483645 소비할 수량

EzConfig

컨피그 설정

트랜잭션의 변수에 적용하는 설정 값

타입 활성화 조건 필수 기본값 값 제한 설명
key string
✓
~ 64자 이름
value string ~ 51200자 값

EzMaterial

강화 소재

강화 조작 중에 소비되는 소재 아이템을 나타냅니다. 각 소재는 특정 GS2-Inventory 아이템 세트를 참조하며, 소비할 수량을 지정합니다. 소재가 제공하는 경험치는 아이템 모델의 메타데이터로부터 결정됩니다.

타입 활성화 조건 필수 기본값 값 제한 설명
materialItemSetId string
✓
~ 1024자 강화 소재가 되는 아이템 세트의 GRN
강화 소재로 소비되는 특정 GS2-Inventory 아이템 세트를 참조합니다. 아이템은 강화 레이트 모델에서 지정된 소재 인벤토리 모델에 속해 있어야 합니다.
count int 1 0 ~ 2147483645 소비 수량
이 소재 아이템의 소비 수량입니다. 이 소재로부터 얻는 합계 경험치는, 아이템 1개당 경험치(아이템 모델의 메타데이터에서 취득)에 이 수량을 곱하여 계산됩니다.

EzVerifyActionResult

검증 액션 실행 결과

타입 활성화 조건 필수 기본값 값 제한 설명
action 문자열 열거형
enum {
"Gs2Dictionary:VerifyEntryByUserId",
"Gs2Distributor:IfExpressionByUserId",
"Gs2Distributor:AndExpressionByUserId",
"Gs2Distributor:OrExpressionByUserId",
"Gs2Enchant:VerifyRarityParameterStatusByUserId",
"Gs2Experience:VerifyRankByUserId",
"Gs2Experience:VerifyRankCapByUserId",
"Gs2Grade:VerifyGradeByUserId",
"Gs2Grade:VerifyGradeUpMaterialByUserId",
"Gs2Guild:VerifyCurrentMaximumMemberCountByGuildName",
"Gs2Guild:VerifyIncludeMemberByUserId",
"Gs2Inventory:VerifyInventoryCurrentMaxCapacityByUserId",
"Gs2Inventory:VerifyItemSetByUserId",
"Gs2Inventory:VerifyReferenceOfByUserId",
"Gs2Inventory:VerifySimpleItemByUserId",
"Gs2Inventory:VerifyBigItemByUserId",
"Gs2Limit:VerifyCounterByUserId",
"Gs2Matchmaking:VerifyIncludeParticipantByUserId",
"Gs2Mission:VerifyCompleteByUserId",
"Gs2Mission:VerifyCounterValueByUserId",
"Gs2Ranking2:VerifyGlobalRankingScoreByUserId",
"Gs2Ranking2:VerifyClusterRankingScoreByUserId",
"Gs2Ranking2:VerifySubscribeRankingScoreByUserId",
"Gs2Schedule:VerifyTriggerByUserId",
"Gs2Schedule:VerifyEventByUserId",
"Gs2SerialKey:VerifyCodeByUserId",
"Gs2Stamina:VerifyStaminaValueByUserId",
"Gs2Stamina:VerifyStaminaMaxValueByUserId",
"Gs2Stamina:VerifyStaminaRecoverIntervalMinutesByUserId",
"Gs2Stamina:VerifyStaminaRecoverValueByUserId",
"Gs2Stamina:VerifyStaminaOverflowValueByUserId",
}
✓
검증 액션에서 실행할 액션의 종류
verifyRequest string
✓
~ 524288자 액션 실행 시 사용되는 요청의 JSON 문자열
statusCode int 0 ~ 999 상태 코드
verifyResult string ~ 1048576자 결과 내용

EzConsumeActionResult

소비 액션 실행 결과

타입 활성화 조건 필수 기본값 값 제한 설명
action 문자열 열거형
enum {
"Gs2AdReward:ConsumePointByUserId",
"Gs2Dictionary:DeleteEntriesByUserId",
"Gs2Enhance:DeleteProgressByUserId",
"Gs2Exchange:DeleteAwaitByUserId",
"Gs2Experience:SubExperienceByUserId",
"Gs2Experience:SubRankCapByUserId",
"Gs2Formation:SubMoldCapacityByUserId",
"Gs2Grade:SubGradeByUserId",
"Gs2Guild:DecreaseMaximumCurrentMaximumMemberCountByGuildName",
"Gs2Idle:DecreaseMaximumIdleMinutesByUserId",
"Gs2Inbox:OpenMessageByUserId",
"Gs2Inbox:DeleteMessageByUserId",
"Gs2Inventory:ConsumeItemSetByUserId",
"Gs2Inventory:ConsumeSimpleItemsByUserId",
"Gs2Inventory:ConsumeBigItemByUserId",
"Gs2JobQueue:DeleteJobByUserId",
"Gs2Limit:CountUpByUserId",
"Gs2LoginReward:MarkReceivedByUserId",
"Gs2Mission:ReceiveByUserId",
"Gs2Mission:BatchReceiveByUserId",
"Gs2Mission:DecreaseCounterByUserId",
"Gs2Mission:ResetCounterByUserId",
"Gs2Money:WithdrawByUserId",
"Gs2Money:RecordReceipt",
"Gs2Money2:WithdrawByUserId",
"Gs2Money2:VerifyReceiptByUserId",
"Gs2Quest:DeleteProgressByUserId",
"Gs2Ranking2:CreateGlobalRankingReceivedRewardByUserId",
"Gs2Ranking2:CreateClusterRankingReceivedRewardByUserId",
"Gs2Schedule:DeleteTriggerByUserId",
"Gs2SerialKey:UseByUserId",
"Gs2Showcase:IncrementPurchaseCountByUserId",
"Gs2SkillTree:MarkRestrainByUserId",
"Gs2Stamina:DecreaseMaxValueByUserId",
"Gs2Stamina:ConsumeStaminaByUserId",
}
✓
소비 액션에서 실행할 액션의 종류
consumeRequest string
✓
~ 524288자 액션 실행 시 사용되는 요청의 JSON 문자열
statusCode int 0 ~ 999 상태 코드
consumeResult string ~ 1048576자 결과 내용

EzAcquireActionResult

획득 액션 실행 결과

타입 활성화 조건 필수 기본값 값 제한 설명
action 문자열 열거형
enum {
"Gs2AdReward:AcquirePointByUserId",
"Gs2Dictionary:AddEntriesByUserId",
"Gs2Enchant:ReDrawBalanceParameterStatusByUserId",
"Gs2Enchant:SetBalanceParameterStatusByUserId",
"Gs2Enchant:ReDrawRarityParameterStatusByUserId",
"Gs2Enchant:AddRarityParameterStatusByUserId",
"Gs2Enchant:SetRarityParameterStatusByUserId",
"Gs2Enhance:DirectEnhanceByUserId",
"Gs2Enhance:UnleashByUserId",
"Gs2Enhance:CreateProgressByUserId",
"Gs2Exchange:ExchangeByUserId",
"Gs2Exchange:IncrementalExchangeByUserId",
"Gs2Exchange:CreateAwaitByUserId",
"Gs2Exchange:AcquireForceByUserId",
"Gs2Exchange:SkipByUserId",
"Gs2Experience:AddExperienceByUserId",
"Gs2Experience:SetExperienceByUserId",
"Gs2Experience:AddRankCapByUserId",
"Gs2Experience:SetRankCapByUserId",
"Gs2Experience:MultiplyAcquireActionsByUserId",
"Gs2Formation:AddMoldCapacityByUserId",
"Gs2Formation:SetMoldCapacityByUserId",
"Gs2Formation:AcquireActionsToFormProperties",
"Gs2Formation:SetFormByUserId",
"Gs2Formation:AcquireActionsToPropertyFormProperties",
"Gs2Friend:UpdateProfileByUserId",
"Gs2Grade:AddGradeByUserId",
"Gs2Grade:ApplyRankCapByUserId",
"Gs2Grade:MultiplyAcquireActionsByUserId",
"Gs2Guild:IncreaseMaximumCurrentMaximumMemberCountByGuildName",
"Gs2Guild:SetMaximumCurrentMaximumMemberCountByGuildName",
"Gs2Idle:IncreaseMaximumIdleMinutesByUserId",
"Gs2Idle:SetMaximumIdleMinutesByUserId",
"Gs2Idle:ReceiveByUserId",
"Gs2Inbox:SendMessageByUserId",
"Gs2Inventory:AddCapacityByUserId",
"Gs2Inventory:SetCapacityByUserId",
"Gs2Inventory:AcquireItemSetByUserId",
"Gs2Inventory:AcquireItemSetWithGradeByUserId",
"Gs2Inventory:AddReferenceOfByUserId",
"Gs2Inventory:DeleteReferenceOfByUserId",
"Gs2Inventory:AcquireSimpleItemsByUserId",
"Gs2Inventory:SetSimpleItemsByUserId",
"Gs2Inventory:AcquireBigItemByUserId",
"Gs2Inventory:SetBigItemByUserId",
"Gs2JobQueue:PushByUserId",
"Gs2Limit:CountDownByUserId",
"Gs2Limit:DeleteCounterByUserId",
"Gs2LoginReward:DeleteReceiveStatusByUserId",
"Gs2LoginReward:UnmarkReceivedByUserId",
"Gs2Lottery:DrawByUserId",
"Gs2Lottery:ResetBoxByUserId",
"Gs2Mission:RevertReceiveByUserId",
"Gs2Mission:IncreaseCounterByUserId",
"Gs2Mission:SetCounterByUserId",
"Gs2Money:DepositByUserId",
"Gs2Money:RevertRecordReceipt",
"Gs2Money2:DepositByUserId",
"Gs2Quest:CreateProgressByUserId",
"Gs2Schedule:TriggerByUserId",
"Gs2Schedule:ExtendTriggerByUserId",
"Gs2Script:InvokeScript",
"Gs2SerialKey:RevertUseByUserId",
"Gs2SerialKey:IssueOnce",
"Gs2Showcase:DecrementPurchaseCountByUserId",
"Gs2Showcase:ForceReDrawByUserId",
"Gs2SkillTree:MarkReleaseByUserId",
"Gs2Stamina:RecoverStaminaByUserId",
"Gs2Stamina:RaiseMaxValueByUserId",
"Gs2Stamina:SetMaxValueByUserId",
"Gs2Stamina:SetRecoverIntervalByUserId",
"Gs2Stamina:SetRecoverValueByUserId",
"Gs2StateMachine:StartStateMachineByUserId",
}
✓
입수 액션에서 실행할 액션의 종류
acquireRequest string
✓
~ 524288자 액션 실행 시 사용되는 요청의 JSON 문자열
statusCode int 0 ~ 999 상태 코드
acquireResult string ~ 1048576자 결과 내용

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)

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);

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)

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);

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.result

end

강화를 완료한다 (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.result

getProgress

현재 강화의 진행 정보를 취득한다

플레이어의 진행 중인 강화 진행 정보를 취득합니다.
진행 정보에는 레이트 모델 이름, 대상 아이템, 사용한 소재, 사전 계산된 경험치, 추첨된 보너스 레이트가 포함됩니다.
플레이어가 이탈했다가 돌아왔을 때 강화 확인 화면을 복원하는 데 사용합니다. 예를 들어 “+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)

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.result

enhance

아이템을 강화한다

지정한 소재를 소비하여 대상 아이템에 경험치를 부여합니다(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