Documentation index for AI agents

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

게임 엔진용 GS2-Grade SDK의 모델 사양과 API 레퍼런스

모델

EzStatus

스테이터스

스테이터스란 프로퍼티 ID마다 존재하는 엔티티로,
현재 그레이드의 값을 보유합니다.

프로퍼티 ID란 스테이터스 고유의 ID로, 개발자가 임의의 값을 설정할 수 있습니다.
연동되는 GS2-Experience의 프로퍼티 ID와 완전히 일치하는 값을 사용할 것을 강력히 권장합니다.

타입활성화 조건필수기본값값 제한설명
gradeNamestring
~ 128자그레이드 모델 이름
이 스테이터스가 속한 그레이드 모델의 이름입니다. 그레이드 엔트리의 매핑, 연동된 경험치 모델, 보상 가산 테이블을 포함하는 그레이드 모델 정의를 참조합니다.
propertyIdstring
~ 1024자프로퍼티 ID
이 그레이드 스테이터스의 개발자 정의 식별자로, 사용자와 그레이드 모델 내에서 고유합니다. 그레이드 값과 랭크 캡의 올바른 동기화를 보장하기 위해, 연동되는 GS2-Experience 스테이터스의 프로퍼티 ID와 동일한 값을 사용하는 것을 강력히 권장합니다.
gradeValuelong11 ~ 9223372036854775805현재 그레이드
이 스테이터스의 현재 그레이드 값입니다. 연동되는 GS2-Experience 모델의 랭크 캡을 결정하기 위해 그레이드 모델의 그레이드 엔트리 배열의 인덱스로 사용됩니다. 이 값이 변경되면 관련된 경험치 스테이터스의 랭크 캡이 해당 그레이드 엔트리에서 정의된 값으로 자동 갱신됩니다.

EzGradeModel

그레이드 모델

그레이드 모델이란 캐릭터나 장비의 랭크를 나타내는 엔티티로, 그레이드에 따라 GS2-Experience의 랭크 캡을 설정할 수 있습니다.

타입활성화 조건필수기본값값 제한설명
namestring
~ 128자그레이드 모델 이름
그레이드 모델 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
metadatastring~ 2048자메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다.
experienceModelIdstring
~ 1024자GS2-Experience 경험치 모델 GRN
이 그레이드 모델과 연동시킬 GS2-Experience의 경험치 모델의 GRN입니다. 그레이드 값이 변경되면, 그레이드 엔트리의 매핑에 기반하여 연동된 경험치 모델의 랭크 캡이 자동으로 업데이트됩니다. 이를 통해 높은 그레이드가 더 높은 랭크 캡을 해제하는 그레이드 기반 성장을 구현할 수 있습니다.
gradeEntriesList<EzGradeEntryModel>
1 ~ 100 items그레이드 엔트리 모델 리스트
각 그레이드 값을 연동된 GS2-Experience 모델의 랭크 캡에 매핑하는 그레이드 엔트리의 순서가 있는 리스트입니다. 배열의 인덱스가 그레이드 값에 대응하므로, 첫 번째 항목(인덱스 0)이 그레이드 0의 랭크 캡을, 두 번째 항목이 그레이드 1의 랭크 캡을 정의합니다.
acquireActionRatesList<EzAcquireActionRate>0 ~ 100 items보상 가산 테이블 리스트
그레이드를 기반으로 보상량을 스케일링하기 위한 이름이 지정된 배율 테이블의 컬렉션입니다. 여러 테이블을 정의하여 서로 다른 종류의 보상(예: 경험치, 통화, 아이템)에 다른 스케일링 규칙을 적용할 수 있습니다.

EzGradeEntryModel

그레이드 엔트리 모델

그레이드 값과 연동되는 GS2-Experience 모델의 랭크 캡 매핑을 정의합니다.

타입활성화 조건필수기본값값 제한설명
metadatastring~ 2048자메타데이터
메타데이터에는 임의의 값을 설정할 수 있습니다.
이 값들은 GS2의 동작에는 영향을 주지 않으므로, 게임 내에서 사용하는 정보를 저장하는 용도로 사용할 수 있습니다.
rankCapValuelong
0 ~ 9223372036854775805랭크 캡 값
이 그레이드가 적용되었을 때 연동된 GS2-Experience 모델에 설정할 랭크 캡 값입니다. 플레이어의 그레이드가 이 항목에 대응하는 값으로 변경되면, 관련된 경험치 스테이터스의 랭크 캡이 이 값으로 자동 업데이트되어 도달 가능한 최대 랭크가 제어됩니다.

EzAcquireAction

입수 액션

타입활성화 조건필수기본값값 제한설명
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",
}
입수 액션에서 실행할 액션의 종류
requeststring
~ 524288자액션 실행 시 사용되는 요청의 JSON 문자열

EzAcquireActionRate

보상 가산 테이블

현재 그레이드 값을 기준으로 보상량을 조정하는 이름이 지정된 배율 테이블을 정의합니다. 각 그레이드 값은 트랜잭션의 입수 액션에 적용되는 배율에 매핑되며, 그레이드가 높은 캐릭터나 장비일수록 더 많은 보상을 받을 수 있습니다. 표준적인 배정밀도 부동소수점수 모드와, 매우 큰 값에 대응하는 빅 넘버 모드를 모두 지원합니다.

타입활성화 조건필수기본값값 제한설명
namestring
~ 128자보상 가산 테이블 이름
그레이드 모델 내에서 이 배율 테이블을 고유하게 식별하는 이름입니다. 트랜잭션의 특정 입수 액션에 그레이드 기반 보상 스케일링을 적용할 때 참조됩니다.
mode문자열 열거형
enum {
  “double”,
  “big”
}
“double”보상 가산 테이블 종류
배율 값의 수치 정밀도 모드를 선택합니다. “double” 모드는 대부분의 경우에 적합한 표준 부동소수점수를 사용합니다. “big” 모드는 최대 1024자리까지의 문자열 표현 숫자를 사용하여, 매우 큰 값 계산이 필요한 게임에 대응합니다.
정의설명
double2^48 미만의 부동소수점 수
big문자열 표기로 1024자리 미만의 부동소수점 수
ratesList<double>{mode} == “double”
✓※
1 ~ 1000 items그레이드별 배율 리스트 (double 모드)
그레이드 값으로 인덱싱된 보상 배율의 배열로, 배정밀도 부동소수점수를 사용합니다. 인덱스 0의 항목이 그레이드 0의 배율, 인덱스 1이 그레이드 1의 배율이 됩니다. mode가 “double"로 설정된 경우에 사용됩니다.

※ mode이(가) “double” 이면 필수
bigRatesList<string>{mode} == “big”
✓※
1 ~ 1000 items그레이드별 배율 리스트 (big 모드)
그레이드 값으로 인덱싱된 보상 배율의 배열로, 확장된 정밀도를 위해 문자열 표현 숫자를 사용합니다. 인덱스 0의 항목이 그레이드 0의 배율, 인덱스 1이 그레이드 1의 배율이 됩니다. 매우 큰 수치 계산이 필요한 게임을 위해 mode가 “big"으로 설정된 경우에 사용됩니다.

※ mode이(가) “big” 이면 필수

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",
}
검증 액션에서 실행할 액션의 종류
verifyRequeststring
~ 524288자액션 실행 시 사용되는 요청의 JSON 문자열
statusCodeint0 ~ 999상태 코드
verifyResultstring~ 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",
}
소비 액션에서 실행할 액션의 종류
consumeRequeststring
~ 524288자액션 실행 시 사용되는 요청의 JSON 문자열
statusCodeint0 ~ 999상태 코드
consumeResultstring~ 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",
}
입수 액션에서 실행할 액션의 종류
acquireRequeststring
~ 524288자액션 실행 시 사용되는 요청의 JSON 문자열
statusCodeint0 ~ 999상태 코드
acquireResultstring~ 1048576자결과 내용

EzTransactionResult

트랜잭션 실행 결과

서버 사이드에서 트랜잭션 자동 실행 기능을 이용하여 실행된 트랜잭션의 실행 결과

타입활성화 조건필수기본값값 제한설명
transactionIdstring
36 ~ 36자트랜잭션 ID
verifyResultsList<EzVerifyActionResult>0 ~ 10 items검증 액션의 실행 결과 목록
consumeResultsList<EzConsumeActionResult>[]0 ~ 10 items소비 액션의 실행 결과 목록
acquireResultsList<EzAcquireActionResult>[]0 ~ 100 items획득 액션 실행 결과 리스트

메서드

getGradeModel

이름을 지정하여 한계돌파·각성 모델 가져오기

이름을 지정하여 그레이드 모델을 1건 가져옵니다.
가져올 수 있는 정보에는 그레이드 엔트리(각 그레이드에서 최대 레벨이 어떻게 변하는지의 정의), 기본 초기 그레이드, 보상 배율 레이트가 포함됩니다.
특정 한계돌파 시스템의 상세 정보를 표시할 때 사용합니다. 예를 들어 「철의 검: 그레이드 2 → 최대 Lv 70, 그레이드 3 → 최대 Lv 80」이나 「현재 보상 보너스: x1.5」와 같은 표시에 유용합니다.

Request

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
gradeNamestring
~ 128자그레이드 모델 이름
그레이드 모델 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.

Result

타입설명
itemEzGradeModel그레이드 모델

구현 예제

    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).GradeModel(
        gradeName: "grade-0001"
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).GradeModel(
        gradeName: "grade-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Grade->Namespace(
        "namespace-0001" // namespaceName
    )->GradeModel(
        "grade-0001" // gradeName
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
var domain = ez.grade.namespace_(
        "namespace-0001"
    ).grade_model(
        "grade-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.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).GradeModel(
        gradeName: "grade-0001"
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);
    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).GradeModel(
        gradeName: "grade-0001"
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);
    const auto Domain = Gs2->Grade->Namespace(
        "namespace-0001" // namespaceName
    )->GradeModel(
        "grade-0001" // gradeName
    );

    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Grade::Model::FGradeModel> value) {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->Unsubscribe(CallbackId);
var domain = ez.grade.namespace_(
        "namespace-0001"
    ).grade_model(
        "grade-0001"
    )

# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
    # 값이 변화했을 때 호출됨
    # value에는 변경 후의 값이 전달됩니다
    pass
)

# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)

listGradeModels

한계돌파·각성 모델 목록 가져오기

이 네임스페이스에 등록된 모든 그레이드 모델을 가져옵니다.
그레이드 모델은 「한계돌파」나 「각성」의 구조를 정의합니다. 플레이어가 그레이드를 올림으로써 아이템이나 캐릭터의 최대 레벨(랭크 캡)이 얼마나 올라가는지를 제어합니다.
예를 들어, 그레이드 0의 무기는 최대 레벨이 50이지만, 한계돌파하여 그레이드 1이 되면 최대 레벨이 60으로, 그레이드 2에서 70으로… 이렇게 올라갑니다.
보상 배율 레이트도 정의할 수 있어, 그레이드 레벨에 따라 보상량을 늘릴 수 있습니다(예: 그레이드 3의 캐릭터는 골드 획득량 1.5배).
한계돌파·각성 UI를 구축하는 데 사용합니다. 예를 들어 「그레이드 2/5 — 최대 Lv: 70 — 다음: 동일 캐릭터 3체 필요」와 같은 표시에 유용합니다.

Request

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.

Result

타입설명
itemsList<EzGradeModel>그레이드 모델 목록

구현 예제

    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    );
    var items = await domain.GradeModelsAsync(
    ).ToListAsync();
    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    );
    var it = domain.GradeModels(
    );
    List<EzGradeModel> items = new List<EzGradeModel>();
    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->Grade->Namespace(
        "namespace-0001" // namespaceName
    );
    const auto It = Domain->GradeModels(
    );
    TArray<Gs2::UE5::Grade::Model::FEzGradeModelPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }
값 변경 이벤트 핸들링
    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeGradeModels(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeGradeModels(callbackId);
    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeGradeModels(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeGradeModels(callbackId);
    const auto Domain = Gs2->Grade->Namespace(
        "namespace-0001" // namespaceName
    );

    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->SubscribeGradeModels(
        []() {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->UnsubscribeGradeModels(CallbackId);

applyRankCap

현재 한계돌파 그레이드에 맞춰 최대 레벨을 동기화하기

GS2-Experience의 최대 레벨(랭크 캡)을 현재 그레이드(한계돌파 레벨)에 맞춰 업데이트합니다.
예를 들어, 캐릭터가 그레이드 2(최대 Lv 70)에서 그레이드 3(최대 Lv 80)으로 한계돌파된 경우, 이를 호출하면 Experience 시스템에 새로운 최대 레벨이 80이라는 것이 반영됩니다.
그레이드가 외부에서 변경되어 Experience의 최대 레벨과 동기화할 필요가 있을 때 유용합니다.
일반적으로 그레이드 변경 시 최대 레벨은 자동으로 업데이트되지만, 데이터가 어긋난 경우 수동으로 호출할 수도 있습니다.

Request

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
gradeNamestring
~ 128자그레이드 모델 이름
이 스테이터스가 속한 그레이드 모델의 이름입니다. 그레이드 엔트리의 매핑, 연동된 경험치 모델, 보상 가산 테이블을 포함하는 그레이드 모델 정의를 참조합니다.
gameSessionGameSession
GameSession
propertyIdstring
~ 1024자프로퍼티 ID
이 그레이드 스테이터스의 개발자 정의 식별자로, 사용자와 그레이드 모델 내에서 고유합니다. 그레이드 값과 랭크 캡의 올바른 동기화를 보장하기 위해, 연동되는 GS2-Experience 스테이터스의 프로퍼티 ID와 동일한 값을 사용하는 것을 강력히 권장합니다.

Result

타입설명
itemEzStatus상태
experienceNamespaceNamestringGS2-Experience 네임스페이스 이름
experienceStatusEzStatus랭크 캡 갱신 후의 GS2-Experience 상태

구현 예제

    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        gradeName: "grade-0001",
        propertyId: "property-0001"
    );
    var result = await domain.ApplyRankCapAsync(
    );
    var item = await result.ModelAsync();
    var experienceNamespaceName = result.ExperienceNamespaceName;
    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        gradeName: "grade-0001",
        propertyId: "property-0001"
    );
    var future = domain.ApplyRankCapFuture(
    );
    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;
    var experienceNamespaceName = future.Result.ExperienceNamespaceName;
    const auto Domain = Gs2->Grade->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Status(
        "grade-0001", // gradeName
        "property-0001" // propertyId
    );
    const auto Future = Domain->ApplyRankCap(
    );
    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();
    const auto ExperienceNamespaceName = Result->ExperienceNamespaceName;
var domain = ez.grade.namespace_(
        "namespace-0001"
    ).me(game_session).status(
        "grade-0001",
        "property-0001"
    )

var async_result = await domain.apply_rank_cap(
)
if async_result.error != null:
    push_error(str(async_result.error))
    return

var result = async_result.result

getStatus

특정 아이템이나 캐릭터의 한계돌파·각성 상태 가져오기

플레이어가 보유한 특정 프로퍼티의 현재 그레이드(한계돌파 레벨)를 가져옵니다.
프로퍼티는 그레이드 모델 이름(어떤 한계돌파 시스템을 사용할지)과 프로퍼티 ID(어떤 아이템이나 캐릭터인지)로 식별합니다.
한계돌파 상세 화면을 표시할 때 사용합니다. 예를 들어 “철의 검 — 그레이드: ★3 — 최대 Lv: 80 — 다음 한계돌파에는 2개 더 필요"와 같은 표시에 유용합니다.

Request

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
gradeNamestring
~ 128자그레이드 모델 이름
이 스테이터스가 속한 그레이드 모델의 이름입니다. 그레이드 엔트리의 매핑, 연동된 경험치 모델, 보상 가산 테이블을 포함하는 그레이드 모델 정의를 참조합니다.
gameSessionGameSession
GameSession
propertyIdstring
~ 1024자프로퍼티 ID
이 그레이드 스테이터스의 개발자 정의 식별자로, 사용자와 그레이드 모델 내에서 고유합니다. 그레이드 값과 랭크 캡의 올바른 동기화를 보장하기 위해, 연동되는 GS2-Experience 스테이터스의 프로퍼티 ID와 동일한 값을 사용하는 것을 강력히 권장합니다.

Result

타입설명
itemEzStatus상태

구현 예제

    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        gradeName: "grade-0001",
        propertyId: "property-0001"
    );
    var item = await domain.ModelAsync();
    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        gradeName: "grade-0001",
        propertyId: "property-0001"
    );
    var future = domain.ModelFuture();
    yield return future;
    var item = future.Result;
    const auto Domain = Gs2->Grade->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Status(
        "grade-0001", // gradeName
        "property-0001" // propertyId
    );
    const auto Future = Domain->Model();
    Future->StartSynchronousTask();
    if (Future->GetTask().IsError())
    {
        return false;
    }
var domain = ez.grade.namespace_(
        "namespace-0001"
    ).me(game_session).status(
        "grade-0001",
        "property-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.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        gradeName: "grade-0001",
        propertyId: "property-0001"
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);
    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    ).Status(
        gradeName: "grade-0001",
        propertyId: "property-0001"
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.Subscribe(
        value => {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    domain.Unsubscribe(callbackId);
    const auto Domain = Gs2->Grade->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    )->Status(
        "grade-0001", // gradeName
        "property-0001" // propertyId
    );

    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->Subscribe(
        [](TSharedPtr<Gs2::Grade::Model::FStatus> value) {
            // 값이 변화했을 때 호출됨
            // value에는 변경 후의 값이 전달됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->Unsubscribe(CallbackId);
var domain = ez.grade.namespace_(
        "namespace-0001"
    ).me(game_session).status(
        "grade-0001",
        "property-0001"
    )

# 이벤트 핸들링 시작
var callback_id = domain.subscribe_model(func(value):
    # 값이 변화했을 때 호출됨
    # value에는 변경 후의 값이 전달됩니다
    pass
)

# 이벤트 핸들링 정지
domain.unsubscribe_model(callback_id)

listStatuses

플레이어의 한계돌파·각성 상태 목록 가져오기

플레이어가 보유한 아이템이나 캐릭터의 현재 그레이드(한계돌파 레벨)를 가져옵니다.
그레이드 모델 이름으로 필터링할 수도 있습니다. 생략하면 모든 그레이드 타입의 상태가 반환됩니다.
각 상태에는 현재 그레이드 값과 그것이 어느 프로퍼티(아이템이나 캐릭터)에 속하는지가 포함됩니다.
한계돌파를 완료한 아이템의 목록을 표시하는 데 사용합니다. 예를 들어 “철의 검 ★3, 불의 지팡이 ★1, 용의 갑옷 ★5"와 같은 표시에 유용합니다.

Request

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
gradeNamestring~ 128자그레이드 모델명
gameSessionGameSession
GameSession
pageTokenstring~ 1024자데이터 취득을 시작할 위치를 지정하는 토큰
limitint301 ~ 1000취득할 데이터 건수

Result

타입설명
itemsList<EzStatus>상태 목록
nextPageTokenstring목록의 나머지를 취득하기 위한 페이지 토큰

구현 예제

    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var items = await domain.StatusesAsync(
        gradeName: "grade-0001"
    ).ToListAsync();
    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );
    var it = domain.Statuses(
        gradeName: "grade-0001"
    );
    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->Grade->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );
    const auto It = Domain->Statuses(
        "grade-0001" // gradeName
    );
    TArray<Gs2::UE5::Grade::Model::FEzStatusPtr> Result;
    for (auto Item : *It)
    {
        if (Item.IsError())
        {
            return false;
        }
        Result.Add(Item.Current());
    }
값 변경 이벤트 핸들링
    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeStatuses(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeStatuses(callbackId);
    var domain = gs2.Grade.Namespace(
        namespaceName: "namespace-0001"
    ).Me(
        gameSession: GameSession
    );

    // 이벤트 핸들링 시작
    var callbackId = domain.SubscribeStatuses(
        () => {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    domain.UnsubscribeStatuses(callbackId);
    const auto Domain = Gs2->Grade->Namespace(
        "namespace-0001" // namespaceName
    )->Me(
        GameSession
    );

    // 이벤트 핸들링 시작
    const auto CallbackId = Domain->SubscribeStatuses(
        []() {
            // 리스트의 요소가 변화했을 때 호출됨
        }
    );

    // 이벤트 핸들링 정지
    Domain->UnsubscribeStatuses(CallbackId);