> For the complete documentation index, see [llms.txt](/llms.txt)

# GS2-Grade API 레퍼런스

그레이드·희귀도 기능




캐릭터나 장비의 그레이드(희귀도)를 관리하고, 그레이드업을 통해 GS2-Experience의 랭크 캡을 끌어올리는 구조를 제공합니다.

캐릭터나 장비의 육성에서는 경험치를 쌓아 레벨업하지만, 레벨에는 상한이 있습니다.<br>
GS2-Grade에서 그레이드를 올리면 그 상한인 랭크 캡이 끌어올려져, 더 높은 레벨까지 육성할 수 있게 됩니다.<br>
이른바 한계 돌파나 진화에 해당하는 성장 요소를 구현하기 위한 서비스입니다.

그레이드는 캐릭터나 장비 같은 대상을 고유하게 가리키는 `propertyId`별로 `Status`로 관리되며, 0부터 시작하는 정수인 `gradeValue`로 현재 그레이드를 보관합니다.<br>
그레이드 모델에는 `gradeEntries`로서, 그레이드별로 GS2-Experience의 랭크 캡에 설정할 값(`rankCapValue`)을 정의합니다.<br>
그레이드가 변화했을 때의 랭크 캡 동기화는 자동으로 이루어지지만, 그레이드 모델 자체를 갱신한 경우에는 `ApplyRankCap`을 호출하여 기존 스테이터스에 반영할 수 있습니다.

프로퍼티 ID가 정규 표현식에 일치하는지에 따라 초기 그레이드 값을 설정할 수 있습니다.<br>
예를 들어, GS2-Inventory의 ItemModel 이름이 SSR로 시작하는 경우에는 그레이드 3, SR로 시작하는 경우에는 그레이드 2로 시작하도록 설정함으로써<br>
ItemModel의 종류에 따라 초기 랭크 캡을 다르게 설정할 수 있습니다.

그레이드업 방법 중 "같은 종류의 캐릭터나 장비를 합성하는" 경우에, 소재로 사용하려는 리소스가 "같은 종류의 캐릭터나 장비"인지를 판정하는 처리를 지원하는 기능이 마련되어 있습니다.<br>
`propertyIdRegex`로 그레이드의 프로퍼티 ID에서 사용자 ID나 ItemModel 이름 등의 파라미터를 추출하고, 이를 `gradeUpPropertyIdRegex`에 삽입하여 정규 표현식을 구성한 뒤, 소재로 사용하려는 리소스의 프로퍼티 ID가 이에 일치하는지를 판정함으로써 구현합니다.

그레이드 모델에는 `acquireActionRates`를 설정할 수 있으며, 그레이드에 따라 입수 액션의 보상량을 조정할 수 있습니다.<br>
이를 활용하면 "고그레이드 캐릭터는 퀘스트 보상 획득량이 늘어난다", "그레이드별로 경험치 배율이 달라진다"와 같은 성장 요소를 구현할 수 있습니다.

트랜잭션의 입수 액션에 `Gs2Grade:MultiplyAcquireActionsByUserId`를 포함시키면, 지정한 그레이드의 배율을 적용한 입수 액션 목록으로 변환할 수 있습니다.

[마이크로서비스 소개 / GS2-Grade](../../microservices/grade)



- [GS2-Grade Deploy/CDK 레퍼런스](/ko/api_reference/grade/deploy/)
  
- [GS2-Grade SDK API 레퍼런스](/ko/api_reference/grade/sdk/)
  
- [GS2-Grade SDK for Game Engine API 레퍼런스](/ko/api_reference/grade/game_engine/)
  
- [GS2-Grade 마스터 데이터 레퍼런스](/ko/api_reference/grade/master_data/)
  
- [GS2-Grade 스크립트 트리거 레퍼런스](/ko/api_reference/grade/script/)
  
- [GS2-Grade 트랜잭션 액션](/ko/api_reference/grade/stamp_sheet/)