Documentation index for AI agents

GS2-Inventory 트랜잭션 액션

검증/소비/입수 각 트랜잭션 액션의 사양

액션의 조합과 동시 실행

모든 서비스에 공통되는 전제는 트랜잭션 액션의 조합에 정리되어 있습니다. 먼저 그쪽을 읽어 주십시오. 이 절의 나머지는 GS2-Inventory 고유의 내용입니다.

GS2-Inventory의 트랜잭션 액션은 4종류의 대상을 다룹니다.

  • 아이템 : 네임스페이스·사용자·인벤토리·아이템 모델의 조합으로 결정됩니다. 그 아이템의 스택과 스택에 붙은 참조를 함께 보관합니다. 스택은 아이템 세트 이름으로 구별되는 한 덩어리로, 유효 기간을 나누고 싶은 경우 등에 하나의 아이템이 여러 스택을 가질 수 있습니다.
  • 빅 아이템 : 같은 조합으로 결정됩니다. 일반 아이템보다 큰 수를 다룰 수 있는 보유 수를 하나 보관합니다. 아이템과는 이름이 같아도 다른 대상입니다.
  • 심플 인벤토리 : 네임스페이스·사용자·인벤토리의 조합으로 결정됩니다. 하나 안에 모든 심플 아이템의 보유 수를 보관하지만, 기록은 아이템 이름별로 나뉩니다.
  • 인벤토리의 용량 : 네임스페이스·사용자·인벤토리의 조합으로 결정됩니다. 최대 용량과 사용량을 별도로 보관합니다.
조작같은 행을 겹쳤을 때중첩 너머다른 대상이 되는 경계
아이템의 획득
AcquireItemSetByUserId
같은 스택이면 통합되어 개수가 합산된다. 다른 스택에 대한 획득을 나열하면 실패한다실패한다인벤토리·아이템 모델 (아이템)
아이템의 획득 (그레이드 지정)
AcquireItemSetWithGradeByUserId
스택을 하나 만든다. 개수는 합산되지 않는다실패한다인벤토리·아이템 모델 (아이템)
아이템의 소비
ConsumeItemSetByUserId
통합되어 개수가 합산된다실패한다인벤토리·아이템 모델 (아이템)
참조의 추가
AddReferenceOfByUserId
스택과 참조 대상이 모두 같으면 통합된다. 한쪽이라도 다르면 실패한다실패한다인벤토리·아이템 모델 (아이템)
참조의 삭제
DeleteReferenceOfByUserId
스택과 참조 대상이 모두 같으면 통합된다. 한쪽이라도 다르면 실패한다실패한다인벤토리·아이템 모델 (아이템)
빅 아이템의 획득
AcquireBigItemByUserId
통합되어 개수가 합산된다실패한다인벤토리·아이템 모델 (빅 아이템)
빅 아이템의 소비
ConsumeBigItemByUserId
통합되어 개수가 합산된다실패한다인벤토리·아이템 모델 (빅 아이템)
빅 아이템의 설정
SetBigItemByUserId
같은 값이면 통합. 값이 다르면 발행 시에 오류실패한다인벤토리·아이템 모델 (빅 아이템)
심플 아이템의 획득·소비
AcquireSimpleItemsByUserId ConsumeSimpleItemsByUserId
혼재해도 된다. 아이템별로 통합되어 개수가 합산된다합산된다인벤토리·아이템 이름
심플 아이템의 설정
SetSimpleItemsByUserId
같은 값이면 통합. 값이 다르면 발행 시에 오류실패한다인벤토리·아이템 이름
용량의 가산
AddCapacityByUserId
통합되어 합산된다합산된다인벤토리·최대 용량
용량의 설정
SetCapacityByUserId
같은 값이면 통합. 값이 다르면 발행 시에 오류실패한다인벤토리·최대 용량
검증 액션 전반 (참조의 검증 제외)임계값이 합산된다읽기만 하므로 충돌하지 않는다인벤토리·아이템 모델·검증 타입
참조의 검증
VerifyReferenceOfByUserId
먼저 지정한 쪽이 남음. 임계값을 갖지 않으므로읽기만 하므로 충돌하지 않는다아이템·검증 타입·참조 대상

참조의 추가·삭제는 하나의 액션으로 여러 참조 대상을 지정하는 API가 없습니다. 같은 아이템에 두 개의 참조를 붙이고 싶은 경우에는 트랜잭션을 나누어 주십시오.

같은 개수의 획득이 안쪽과 바깥쪽에서 도착한 경우에는 실패하지 않고 1건으로 묶입니다. 추첨 두 개가 모두 같은 아이템을 1개 배분하면 들어오는 것은 1개뿐이며 오류는 발생하지 않습니다. 개수가 다르면 실패하므로, 조용히 맞지 않는 것은 개수가 일치했을 때뿐입니다. 소비도 마찬가지입니다.

아이템과 빅 아이템은 행이 나뉘어 있어도 경계가 같습니다. 같은 아이템을 건드리는 두 행을 하나의 트랜잭션에 넣으면 실패합니다. 획득과 소비, 획득과 참조의 추가 같은 조합이 여기에 해당합니다.

아이템의 획득·소비는 용량의 사용량도 업데이트하지만, 이쪽은 최대 용량과는 다른 속성이므로 용량의 가산·설정과 충돌하는 일은 없습니다.

스택 상한이나 용량을 초과한 획득은 오류가 되지 않습니다. 담기지 않은 만큼은 오버플로로 취급되어, 네임스페이스에 설정이 있으면 GS2-Inbox 등으로 전달되고 설정이 없으면 사라집니다. 통합되어 개수가 합산되면 단독으로는 담겼을 획득이 상한에 닿을 수 있으므로, 오버플로를 받을 곳을 준비하지 않은 경우에는 주의해 주십시오.

중단되는 조건은 세 가지입니다. 스택 상한까지 채운 뒤 새 스택을 만들 수 없을 때, 즉 복수 스택이 허용되지 않거나 인벤토리 용량에 여유가 없을 때, 그리고 하나의 아이템의 스택 수가 상한에 도달했을 때입니다. 아이템 세트 이름을 명시한 획득은 그 스택에 담기지 않은 만큼이 그대로 오버플로가 됩니다.

심플 아이템은 아이템 이름별로 기록이 나뉘므로, 다른 아이템이라면 몇 개를 나열해도 충돌하지 않습니다. 통합 후의 합계가 보유 수를 초과하는 소비는 충돌(409)로 거부되며 아무것도 소비되지 않습니다.

검증 액션은 트랜잭션 시작 시점의 상태를 봅니다. 같은 트랜잭션에서 도달하는 보유 수나 용량을 검증할 수는 없습니다.

중첩된 트랜잭션에 주의

심플 아이템과 용량은 중첩 너머에서도 안전합니다. 값별로 기록하므로 어느 경로로 도착하든 한 번의 업데이트로 묶입니다.

아이템과 빅 아이템은 다릅니다. 같은 아이템을 안쪽과 바깥쪽 양쪽에서 업데이트하면, 행이 같아도 트랜잭션이 실패합니다. 보상이나 추첨이 배분하는 아이템을 바깥쪽에서도 건드리고 있지 않은지 확인해 주십시오.

제한을 회피하고 싶은 경우

아이템의 획득, 참조의 추가·삭제, 용량과 심플 아이템과 빅 아이템의 설정은 획득 액션, 아이템의 소비는 소비 액션입니다. 획득 액션끼리의 충돌은 acquireActionUseJobQueue를 활성화하면 해소되지만, 획득과 소비의 공존은 enableAtomicCommit을 비활성화하지 않으면 해소되지 않습니다.

동시 실행과 재시도

심플 아이템의 획득·소비와 용량의 가산은 동시 실행 요청이 몇 개 겹쳐도 충돌하지 않습니다. 심플 아이템의 예외는 동시에 실행된 소비의 합계가 보유 수를 초과한 경우로, 이때는 충돌(409)이 됩니다. 재시도하면 그 시점에 보유 수가 충분하면 성공합니다.

아이템, 빅 아이템, 용량의 설정, 관리 콘솔이나 서버 API에서의 변경은 리비전 대조를 수반하는 기록이므로, 같은 대상에 대한 다른 업데이트와 겹치면 충돌(409)이 반환될 수 있습니다. 특히 용량의 설정은 인벤토리 전체의 리비전을 보므로, 같은 인벤토리에 대한 아이템의 출입과 겹치기만 해도 일어납니다. 요청 내용에 문제가 있는 것은 아니므로, 재시도하면 성공합니다.


Verify Action

검증 액션

Gs2Inventory:VerifyInventoryCurrentMaxCapacityByUserId

사용자 ID를 지정하여 인벤토리의 최대 용량을 검증

지정된 사용자의 현재 최대 인벤토리 용량이 지정된 조건을 만족하는지 검증합니다.
6개의 비교 연산자를 지원합니다: less, lessEqual, greater, greaterEqual, equal, notEqual.
검증에는 버프 적용 후의 용량 값(GS2-Buff 의 활성 버프 효과를 반영)이 사용됩니다.

수량 지정 가능한 액션: 예

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
inventoryNamestring
~ 128자인벤토리 모델 이름
이 인벤토리의 구조와 용량 설정을 정의하는 인벤토리 모델의 이름입니다. 사용자의 인벤토리 인스턴스를 모델 정의에 연결하여 사용 가능한 아이템의 종류와 용량 제한을 결정합니다.
verifyType문자열 열거형
enum {
  “less”,
  “lessEqual”,
  “greater”,
  “greaterEqual”,
  “equal”,
  “notEqual”
}
검증 종류
정의설명
less현재 인벤토리의 최대 용량이 지정 값 미만일 것
lessEqual현재 인벤토리의 최대 용량이 지정 값 이하일 것
greater현재 인벤토리의 최대 용량이 지정 값 초과일 것
greaterEqual현재 인벤토리의 최대 용량이 지정 값 이상일 것
equal현재 인벤토리의 최대 용량이 지정 값과 일치할 것
notEqual현재 인벤토리의 최대 용량이 지정 값과 일치하지 않을 것
currentInventoryMaxCapacityint
0 ~ 2147483646현재 인벤토리의 최대 용량
multiplyValueSpecifyingQuantitybooltrue수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Inventory:VerifyInventoryCurrentMaxCapacityByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "inventoryName": "[string]인벤토리 모델 이름",
        "verifyType": "[string]검증 종류",
        "currentInventoryMaxCapacity": "[int]현재 인벤토리의 최대 용량",
        "multiplyValueSpecifyingQuantity": "[bool]수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Inventory:VerifyInventoryCurrentMaxCapacityByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  inventoryName: "[string]인벤토리 모델 이름"
  verifyType: "[string]검증 종류"
  currentInventoryMaxCapacity: "[int]현재 인벤토리의 최대 용량"
  multiplyValueSpecifyingQuantity: "[bool]수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("inventory").verify.verify_inventory_current_max_capacity_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    inventoryName="[string]인벤토리 모델 이름",
    verifyType="[string]검증 종류",
    currentInventoryMaxCapacity="[int]현재 인벤토리의 최대 용량",
    multiplyValueSpecifyingQuantity="[bool]수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부",
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Gs2Inventory:VerifyItemSetByUserId

사용자 ID를 지정하여 아이템 세트의 소지 수량 검증

지정된 사용자의 합계 아이템 수량이 지정된 조건을 만족하는지 검증합니다.
수량은 지정된 아이템 타입의 모든 아이템 세트를 합산하여 계산됩니다.
6가지 비교 연산자를 지원합니다: less, lessEqual, greater, greaterEqual, equal, notEqual.

수량 지정 가능한 액션: 예

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
inventoryNamestring
~ 128자인벤토리 모델 이름
인벤토리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다.
itemNamestring
~ 128자아이템 모델명
이 세트에 저장된 아이템의 종류를 정의하는 아이템 모델의 이름입니다. inventoryName과 조합하여 이 아이템 세트의 스택 상한과 다중 스택 동작을 결정합니다.
verifyType문자열 열거형
enum {
  “less”,
  “lessEqual”,
  “greater”,
  “greaterEqual”,
  “equal”,
  “notEqual”
}
검증 종류
정의설명
less소지 수량이 지정 값 미만일 것
lessEqual소지 수량이 지정 값 이하일 것
greater소지 수량이 지정 값 초과일 것
greaterEqual소지 수량이 지정 값 이상일 것
equal소지 수량이 지정 값과 일치할 것
notEqual소지 수량이 지정 값과 일치하지 않을 것
itemSetNamestring~ 36자아이템 세트를 식별하는 이름
countlong
0 ~ 9223372036854775805소지 수량
multiplyValueSpecifyingQuantitybooltrue수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Inventory:VerifyItemSetByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "inventoryName": "[string]인벤토리 모델 이름",
        "itemName": "[string]아이템 모델명",
        "verifyType": "[string]검증 종류",
        "itemSetName": "[string]아이템 세트를 식별하는 이름",
        "count": "[long]소지 수량",
        "multiplyValueSpecifyingQuantity": "[bool]수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Inventory:VerifyItemSetByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  inventoryName: "[string]인벤토리 모델 이름"
  itemName: "[string]아이템 모델명"
  verifyType: "[string]검증 종류"
  itemSetName: "[string]아이템 세트를 식별하는 이름"
  count: "[long]소지 수량"
  multiplyValueSpecifyingQuantity: "[bool]수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("inventory").verify.verify_item_set_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    inventoryName="[string]인벤토리 모델 이름",
    itemName="[string]아이템 모델명",
    verifyType="[string]검증 종류",
    itemSetName="[string]아이템 세트를 식별하는 이름",
    count="[long]소지 수량",
    multiplyValueSpecifyingQuantity="[bool]수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부",
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Gs2Inventory:VerifyReferenceOfByUserId

사용자 ID를 지정하여 아이템의 참조원을 검증

지정된 사용자의 아이템 세트 상의 참조원 상태를 검증합니다.
4개의 검증 타입을 지원: not_entry(참조원이 미등록), already_entry(참조원이 등록됨), empty(참조원이 0개), not_empty(참조원이 1개 이상 존재).
조건이 충족되지 않으면 오류가 반환됩니다.

수량 지정 가능한 액션: 예

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
inventoryNamestring
~ 128자인벤토리 모델명
이 아이템 세트를 포함하는 인벤토리 모델의 이름입니다. itemName과 함께 사용되어 이 소지품이 어떤 인벤토리와 아이템 종류에 속하는지를 식별하는 데 사용됩니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
itemNamestring
~ 128자아이템 모델명
이 세트에 저장된 아이템의 종류를 정의하는 아이템 모델의 이름입니다. inventoryName과 조합하여 이 아이템 세트의 스택 상한과 다중 스택 동작을 결정합니다.
itemSetNamestring
UUID~ 36자아이템 세트를 식별하는 이름
아이템 세트의 고유한 이름을 보유합니다.
이름은 UUID(Universally Unique Identifier) 형식으로 자동 생성되며, 각 아이템 세트를 식별하는 데 사용됩니다.
referenceOfstring
~ 1024자참조원
장비 슬롯이나 편성 바인드 등, 이 아이템 세트에 대한 외부 참조를 나타내는 문자열 식별자입니다. 인벤토리 모델에서 protectReferencedItem이 활성화된 경우, 참조원을 가진 아이템 세트는 소비하거나 삭제할 수 없습니다.
verifyType문자열 열거형
enum {
  “not_entry”,
  “already_entry”,
  “empty”,
  “not_empty”
}
검증 종류
정의설명
not_entry지정한 참조원이 아직 등록되어 있지 않을 것
already_entry지정한 참조원이 이미 등록되어 있을 것
empty참조원으로 등록되어 있는 요소가 0개일 것
not_empty참조원으로 등록되어 있는 요소가 1개 이상일 것
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Inventory:VerifyReferenceOfByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "inventoryName": "[string]인벤토리 모델명",
        "userId": "[string]사용자ID",
        "itemName": "[string]아이템 모델명",
        "itemSetName": "[string]아이템 세트를 식별하는 이름",
        "referenceOf": "[string]참조원",
        "verifyType": "[string]검증 종류",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Inventory:VerifyReferenceOfByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  inventoryName: "[string]인벤토리 모델명"
  userId: "[string]사용자ID"
  itemName: "[string]아이템 모델명"
  itemSetName: "[string]아이템 세트를 식별하는 이름"
  referenceOf: "[string]참조원"
  verifyType: "[string]검증 종류"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("inventory").verify.verify_reference_of_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    inventoryName="[string]인벤토리 모델명",
    userId="[string]사용자ID",
    itemName="[string]아이템 모델명",
    itemSetName="[string]아이템 세트를 식별하는 이름",
    referenceOf="[string]참조원",
    verifyType="[string]검증 종류",
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Gs2Inventory:VerifySimpleItemByUserId

사용자 ID를 지정하여 심플 아이템 소지 수량 검증

지정된 사용자의 심플 아이템 수량이 지정된 조건을 만족하는지 검증합니다.
6가지 비교 연산자를 지원합니다: less, lessEqual, greater, greaterEqual, equal, notEqual.

수량 지정 가능한 액션: 예

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
inventoryNamestring
~ 128자심플 인벤토리 모델 이름
심플 인벤토리 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
itemNamestring
~ 128자심플 아이템 모델 이름
이 레코드에 저장된 아이템의 종류를 정의하는 심플 아이템 모델의 이름입니다. 이 소지품이 어떤 아이템 정의에 대응하는지 식별하는 데 사용됩니다.
verifyType문자열 열거형
enum {
  “less”,
  “lessEqual”,
  “greater”,
  “greaterEqual”,
  “equal”,
  “notEqual”
}
검증 종류
정의설명
less소지 수량이 지정 값 미만일 것
lessEqual소지 수량이 지정 값 이하일 것
greater소지 수량이 지정 값 초과일 것
greaterEqual소지 수량이 지정 값 이상일 것
equal소지 수량이 지정 값과 일치할 것
notEqual소지 수량이 지정 값과 일치하지 않을 것
countlong
0 ~ 9223372036854775805소지 수량
multiplyValueSpecifyingQuantitybooltrue수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Inventory:VerifySimpleItemByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "inventoryName": "[string]심플 인벤토리 모델 이름",
        "itemName": "[string]심플 아이템 모델 이름",
        "verifyType": "[string]검증 종류",
        "count": "[long]소지 수량",
        "multiplyValueSpecifyingQuantity": "[bool]수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Inventory:VerifySimpleItemByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  inventoryName: "[string]심플 인벤토리 모델 이름"
  itemName: "[string]심플 아이템 모델 이름"
  verifyType: "[string]검증 종류"
  count: "[long]소지 수량"
  multiplyValueSpecifyingQuantity: "[bool]수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("inventory").verify.verify_simple_item_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    inventoryName="[string]심플 인벤토리 모델 이름",
    itemName="[string]심플 아이템 모델 이름",
    verifyType="[string]검증 종류",
    count="[long]소지 수량",
    multiplyValueSpecifyingQuantity="[bool]수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부",
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Gs2Inventory:VerifyBigItemByUserId

사용자 ID를 지정하여 거대 아이템의 소지 수량 검증

지정 사용자의 거대 아이템 수량이 지정된 조건을 충족하는지 검증합니다.
6가지 비교 연산자를 지원합니다: less, lessEqual, greater, greaterEqual, equal, notEqual.
비교는 문자열 기반 수량에 대해 임의 정밀도 연산으로 수행됩니다.
조건이 충족되지 않으면 오류가 반환되고, 충족되면 요청이 성공합니다.

수량 지정 가능한 액션: 예

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
inventoryNamestring
~ 128자거대 인벤토리 모델 이름
거대 인벤토리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다.
itemNamestring
~ 128자거대 아이템 모델 이름
이 레코드에 저장된 아이템의 종류를 정의하는 거대 아이템 모델의 이름입니다. 이 거대 아이템 소지품이 어떤 아이템 정의에 대응하는지 식별하는 데 사용됩니다.
verifyType문자열 열거형
enum {
  “less”,
  “lessEqual”,
  “greater”,
  “greaterEqual”,
  “equal”,
  “notEqual”
}
검증 종류
정의설명
less소지 수량이 지정 값 미만일 것
lessEqual소지 수량이 지정 값 이하일 것
greater소지 수량이 지정 값 초과일 것
greaterEqual소지 수량이 지정 값 이상일 것
equal소지 수량이 지정 값과 일치할 것
notEqual소지 수량이 지정 값과 일치하지 않을 것
countstring
~ 1024자소지 수량
최대 1024자리까지의 정수값 문자열
multiplyValueSpecifyingQuantitybooltrue수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Inventory:VerifyBigItemByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "userId": "[string]사용자ID",
        "inventoryName": "[string]거대 인벤토리 모델 이름",
        "itemName": "[string]거대 아이템 모델 이름",
        "verifyType": "[string]검증 종류",
        "count": "[string]소지 수량",
        "multiplyValueSpecifyingQuantity": "[bool]수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Inventory:VerifyBigItemByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  userId: "[string]사용자ID"
  inventoryName: "[string]거대 인벤토리 모델 이름"
  itemName: "[string]거대 아이템 모델 이름"
  verifyType: "[string]검증 종류"
  count: "[string]소지 수량"
  multiplyValueSpecifyingQuantity: "[bool]수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("inventory").verify.verify_big_item_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    userId="[string]사용자ID",
    inventoryName="[string]거대 인벤토리 모델 이름",
    itemName="[string]거대 아이템 모델 이름",
    verifyType="[string]검증 종류",
    count="[string]소지 수량",
    multiplyValueSpecifyingQuantity="[bool]수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부",
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Consume Action

소비 액션

Gs2Inventory:ConsumeItemSetByUserId

사용자 ID를 지정하여 아이템 세트를 소비

지정된 사용자의 인벤토리 내 특정 아이템의 수량을 감소시킵니다.
itemSetName을 지정하면 해당 특정 스택만 소비 대상이 됩니다. 지정하지 않으면 해당 아이템 타입의 모든 스택에서 소비됩니다.
아이템 세트의 수량이 0이 되면 자동으로 삭제됩니다.
충분한 아이템이 없는 경우 Insufficient 에러가 반환됩니다.

수량 지정 가능한 액션: 예

반전 가능한 액션: 예

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
inventoryNamestring
~ 128자인벤토리 모델명
이 아이템 세트를 포함하는 인벤토리 모델의 이름입니다. itemName과 함께 사용되어 이 소지품이 어떤 인벤토리와 아이템 종류에 속하는지를 식별하는 데 사용됩니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
itemNamestring
~ 128자아이템 모델명
이 세트에 저장된 아이템의 종류를 정의하는 아이템 모델의 이름입니다. inventoryName과 조합하여 이 아이템 세트의 스택 상한과 다중 스택 동작을 결정합니다.
consumeCountlong
1 ~ 9223372036854775805소비 수량
itemSetNamestring~ 36자아이템 세트를 식별하는 이름
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Inventory:ConsumeItemSetByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "inventoryName": "[string]인벤토리 모델명",
        "userId": "[string]사용자ID",
        "itemName": "[string]아이템 모델명",
        "consumeCount": "[long]소비 수량",
        "itemSetName": "[string]아이템 세트를 식별하는 이름",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Inventory:ConsumeItemSetByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  inventoryName: "[string]인벤토리 모델명"
  userId: "[string]사용자ID"
  itemName: "[string]아이템 모델명"
  consumeCount: "[long]소비 수량"
  itemSetName: "[string]아이템 세트를 식별하는 이름"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("inventory").consume.consume_item_set_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    inventoryName="[string]인벤토리 모델명",
    userId="[string]사용자ID",
    itemName="[string]아이템 모델명",
    consumeCount="[long]소비 수량",
    itemSetName="[string]아이템 세트를 식별하는 이름",
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Gs2Inventory:ConsumeSimpleItemsByUserId

사용자 ID를 지정하여 심플 아이템 소비

소비 수량의 배치를 사용하여 지정된 사용자의 심플 인벤토리 내 아이템 수량을 감소시킵니다.
단일 원자적 작업으로 여러 아이템을 소비할 수 있습니다. 어느 하나의 아이템 수량이라도 부족한 경우, 작업 전체가 실패합니다.

수량 지정 가능한 액션: 아니오

반전 가능한 액션: 예

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
inventoryNamestring
~ 128자심플 인벤토리 모델 이름
심플 인벤토리 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
consumeCountsList<ConsumeCount>
1 ~ 100 items심플 아이템의 소비 수량 리스트
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Inventory:ConsumeSimpleItemsByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "inventoryName": "[string]심플 인벤토리 모델 이름",
        "userId": "[string]사용자ID",
        "consumeCounts": [
            {
                "itemName": "[string]심플 아이템 모델 이름",
                "count": "[long]소비 수량"
            }
        ],
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Inventory:ConsumeSimpleItemsByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  inventoryName: "[string]심플 인벤토리 모델 이름"
  userId: "[string]사용자ID"
  consumeCounts: 
    - itemName: "[string]심플 아이템 모델 이름"
      count: "[long]소비 수량"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("inventory").consume.consume_simple_items_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    inventoryName="[string]심플 인벤토리 모델 이름",
    userId="[string]사용자ID",
    consumeCounts={
        {
            itemName="[string]심플 아이템 모델 이름",
            count="[long]소비 수량"
        }
    },
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Gs2Inventory:ConsumeBigItemByUserId

사용자 ID를 지정하여 거대 아이템 소비

임의 정밀도 연산을 사용하여 지정 사용자의 거대 아이템 수량에서 지정된 수량을 감산합니다.
consumeCount는 최대 1024자리의 유효한 정수 문자열이어야 합니다.
현재 수량이 부족한 경우 Insufficient 오류가 반환되며, 감산은 이루어지지 않습니다.
네임스페이스 설정을 통해 거대 아이템 소비 시 커스텀 로직을 실행하는 GS2-Script를 설정할 수 있습니다.

수량 지정 가능한 액션: 예

반전 가능한 액션: 예

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
inventoryNamestring
~ 128자거대 인벤토리 모델 이름
거대 인벤토리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
itemNamestring
~ 128자거대 아이템 모델 이름
거대 아이템 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다.
consumeCountstring
~ 1024자거대 아이템의 소비 수량
최대 1024자리까지의 정수값 문자열
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Inventory:ConsumeBigItemByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "inventoryName": "[string]거대 인벤토리 모델 이름",
        "userId": "[string]사용자ID",
        "itemName": "[string]거대 아이템 모델 이름",
        "consumeCount": "[string]거대 아이템의 소비 수량",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Inventory:ConsumeBigItemByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  inventoryName: "[string]거대 인벤토리 모델 이름"
  userId: "[string]사용자ID"
  itemName: "[string]거대 아이템 모델 이름"
  consumeCount: "[string]거대 아이템의 소비 수량"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("inventory").consume.consume_big_item_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    inventoryName="[string]거대 인벤토리 모델 이름",
    userId="[string]사용자ID",
    itemName="[string]거대 아이템 모델 이름",
    consumeCount="[string]거대 아이템의 소비 수량",
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Acquire Action

입수 액션

Gs2Inventory:AddCapacityByUserId

사용자 ID를 지정하여 인벤토리의 용량 크기를 가산

지정된 양만큼 사용자의 인벤토리 용량을 증가시킵니다.
결과 용량은 인벤토리 모델의 maxCapacity 를 초과할 수 없습니다.
인벤토리가 아직 존재하지 않는 경우, initialCapacity 로 자동 생성된 후 지정된 값이 가산됩니다.

수량 지정 가능한 액션: 예

반전 가능한 액션: 아니오

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
inventoryNamestring
~ 128자인벤토리 모델 이름
이 인벤토리의 구조와 용량 설정을 정의하는 인벤토리 모델의 이름입니다. 사용자의 인벤토리 인스턴스를 모델 정의에 연결하여 사용 가능한 아이템의 종류와 용량 제한을 결정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
addCapacityValueint
1 ~ 2147483646가산할 용량 크기
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Inventory:AddCapacityByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "inventoryName": "[string]인벤토리 모델 이름",
        "userId": "[string]사용자ID",
        "addCapacityValue": "[int]가산할 용량 크기",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Inventory:AddCapacityByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  inventoryName: "[string]인벤토리 모델 이름"
  userId: "[string]사용자ID"
  addCapacityValue: "[int]가산할 용량 크기"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("inventory").acquire.add_capacity_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    inventoryName="[string]인벤토리 모델 이름",
    userId="[string]사용자ID",
    addCapacityValue="[int]가산할 용량 크기",
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Gs2Inventory:SetCapacityByUserId

사용자 ID를 지정하여 인벤토리의 용량 크기를 설정

사용자의 인벤토리 용량을 지정된 절대값으로 설정합니다.
갱신 전후의 인벤토리 상태를 모두 반환하므로, 신구 용량 값을 비교할 수 있습니다.
새로운 용량 값은 인벤토리 모델의 maxCapacity 를 초과할 수 없습니다.

수량 지정 가능한 액션: 예

반전 가능한 액션: 아니오

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
inventoryNamestring
~ 128자인벤토리 모델 이름
이 인벤토리의 구조와 용량 설정을 정의하는 인벤토리 모델의 이름입니다. 사용자의 인벤토리 인스턴스를 모델 정의에 연결하여 사용 가능한 아이템의 종류와 용량 제한을 결정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
newCapacityValueint
1 ~ 2147483646인벤토리의 새로운 최대 용량
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Inventory:SetCapacityByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "inventoryName": "[string]인벤토리 모델 이름",
        "userId": "[string]사용자ID",
        "newCapacityValue": "[int]인벤토리의 새로운 최대 용량",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Inventory:SetCapacityByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  inventoryName: "[string]인벤토리 모델 이름"
  userId: "[string]사용자ID"
  newCapacityValue: "[int]인벤토리의 새로운 최대 용량"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("inventory").acquire.set_capacity_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    inventoryName="[string]인벤토리 모델 이름",
    userId="[string]사용자ID",
    newCapacityValue="[int]인벤토리의 새로운 최대 용량",
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Gs2Inventory:AcquireItemSetByUserId

사용자 ID를 지정하여 아이템 세트 입수

사용자의 인벤토리에 아이템을 추가합니다. 기존 아이템 세트에 여유(스택 제한 미만)가 있는 경우 그곳에 추가되며, 그렇지 않은 경우 복수 스택이 허용되어 있으면 새로운 아이템 세트가 생성됩니다.
선택적으로 expiresAt을 지정하여 새로 생성되는 아이템 세트의 유효기간을 설정할 수 있습니다. 유효기간이 이미 지난 아이템은 빈 것으로 취급됩니다.
createNewItemSet이 true인 경우, 기존 세트에 여유가 있어도 항상 새로운 아이템 세트가 생성됩니다.
합계 수량이 인벤토리 용량을 초과하는 경우 오버플로우 수량이 반환되며, 네임스페이스 설정에 따라 오버플로우분이 GS2-Inbox로 전송될 수 있습니다.

수량 지정 가능한 액션: 예

반전 가능한 액션: 예

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
inventoryNamestring
~ 128자인벤토리 모델 이름
인벤토리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다.
itemNamestring
~ 128자아이템 모델명
이 세트에 저장된 아이템의 종류를 정의하는 아이템 모델의 이름입니다. inventoryName과 조합하여 이 아이템 세트의 스택 상한과 다중 스택 동작을 결정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
acquireCountlong
1 ~ 9223372036854775805입수하는 양
expiresAtlong0유효기간
UNIX 시간·밀리초
createNewItemSetboolfalse기존 아이템 세트에 여유가 있더라도 새로운 아이템 세트를 생성할지 여부
itemSetNamestring~ 36자아이템 세트를 식별하는 이름
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Inventory:AcquireItemSetByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "inventoryName": "[string]인벤토리 모델 이름",
        "itemName": "[string]아이템 모델명",
        "userId": "[string]사용자ID",
        "acquireCount": "[long]입수하는 양",
        "expiresAt": "[long]유효기간",
        "createNewItemSet": "[bool]기존 아이템 세트에 여유가 있더라도 새로운 아이템 세트를 생성할지 여부",
        "itemSetName": "[string]아이템 세트를 식별하는 이름",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Inventory:AcquireItemSetByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  inventoryName: "[string]인벤토리 모델 이름"
  itemName: "[string]아이템 모델명"
  userId: "[string]사용자ID"
  acquireCount: "[long]입수하는 양"
  expiresAt: "[long]유효기간"
  createNewItemSet: "[bool]기존 아이템 세트에 여유가 있더라도 새로운 아이템 세트를 생성할지 여부"
  itemSetName: "[string]아이템 세트를 식별하는 이름"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("inventory").acquire.acquire_item_set_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    inventoryName="[string]인벤토리 모델 이름",
    itemName="[string]아이템 모델명",
    userId="[string]사용자ID",
    acquireCount="[long]입수하는 양",
    expiresAt="[long]유효기간",
    createNewItemSet="[bool]기존 아이템 세트에 여유가 있더라도 새로운 아이템 세트를 생성할지 여부",
    itemSetName="[string]아이템 세트를 식별하는 이름",
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Gs2Inventory:AcquireItemSetWithGradeByUserId

사용자 ID를 지정하여 GS2-Grade에 그레이드를 설정하면서 아이템 세트를 1개 입수

아이템을 1개 입수함과 동시에 GS2-Grade를 통해 그레이드 값을 설정합니다.
각 아이템이 서로 다른 그레이드 값을 가지는 품질/랭크 시스템(예: 스탯이 다른 장비)을 가진 아이템에 사용됩니다.
항상 새로운 아이템 세트가 생성되며(createNewItemSet의 동작), 아이템 입수 후 GS2-Grade의 SetGradeByUserId를 통해 그레이드가 설정됩니다.

수량 지정 가능한 액션: 아니오

반전 가능한 액션: 아니오

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
inventoryNamestring
~ 128자인벤토리 모델 이름
인벤토리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다.
itemNamestring
~ 128자아이템 모델명
이 세트에 저장된 아이템의 종류를 정의하는 아이템 모델의 이름입니다. inventoryName과 조합하여 이 아이템 세트의 스택 상한과 다중 스택 동작을 결정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
gradeModelIdstring
~ 1024자그레이드 모델 GRN
gradeValuelong
1 ~ 9223372036854775805설정할 그레이드 값
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Inventory:AcquireItemSetWithGradeByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "inventoryName": "[string]인벤토리 모델 이름",
        "itemName": "[string]아이템 모델명",
        "userId": "[string]사용자ID",
        "gradeModelId": "[string]그레이드 모델 GRN",
        "gradeValue": "[long]설정할 그레이드 값",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Inventory:AcquireItemSetWithGradeByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  inventoryName: "[string]인벤토리 모델 이름"
  itemName: "[string]아이템 모델명"
  userId: "[string]사용자ID"
  gradeModelId: "[string]그레이드 모델 GRN"
  gradeValue: "[long]설정할 그레이드 값"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("inventory").acquire.acquire_item_set_with_grade_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    inventoryName="[string]인벤토리 모델 이름",
    itemName="[string]아이템 모델명",
    userId="[string]사용자ID",
    gradeModelId="[string]그레이드 모델 GRN",
    gradeValue="[long]설정할 그레이드 값",
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Gs2Inventory:AddReferenceOfByUserId

사용자 ID를 지정하여 아이템에 참조원을 추가

지정된 사용자의 지정된 아이템 세트에 참조원 문자열을 등록합니다.
참조원은 아이템 세트를 외부 엔티티(장비 슬롯이나 캐릭터 등)에 연관 짓습니다.
인벤토리 모델에서 protectReferencedItem 이 활성화된 경우, 참조원을 가진 아이템은 소비·삭제할 수 없게 되어, 장비 중인 아이템이 실수로 소비되는 것을 방지할 수 있습니다.

수량 지정 가능한 액션: 아니오

반전 가능한 액션: 아니오

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
inventoryNamestring
~ 128자인벤토리 모델명
이 아이템 세트를 포함하는 인벤토리 모델의 이름입니다. itemName과 함께 사용되어 이 소지품이 어떤 인벤토리와 아이템 종류에 속하는지를 식별하는 데 사용됩니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
itemNamestring
~ 128자아이템 모델명
이 세트에 저장된 아이템의 종류를 정의하는 아이템 모델의 이름입니다. inventoryName과 조합하여 이 아이템 세트의 스택 상한과 다중 스택 동작을 결정합니다.
itemSetNamestring
UUID~ 36자아이템 세트를 식별하는 이름
아이템 세트의 고유한 이름을 보유합니다.
이름은 UUID(Universally Unique Identifier) 형식으로 자동 생성되며, 각 아이템 세트를 식별하는 데 사용됩니다.
referenceOfstring
~ 1024자참조원
장비 슬롯이나 편성 바인드 등, 이 아이템 세트에 대한 외부 참조를 나타내는 문자열 식별자입니다. 인벤토리 모델에서 protectReferencedItem이 활성화된 경우, 참조원을 가진 아이템 세트는 소비하거나 삭제할 수 없습니다.
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Inventory:AddReferenceOfByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "inventoryName": "[string]인벤토리 모델명",
        "userId": "[string]사용자ID",
        "itemName": "[string]아이템 모델명",
        "itemSetName": "[string]아이템 세트를 식별하는 이름",
        "referenceOf": "[string]참조원",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Inventory:AddReferenceOfByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  inventoryName: "[string]인벤토리 모델명"
  userId: "[string]사용자ID"
  itemName: "[string]아이템 모델명"
  itemSetName: "[string]아이템 세트를 식별하는 이름"
  referenceOf: "[string]참조원"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("inventory").acquire.add_reference_of_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    inventoryName="[string]인벤토리 모델명",
    userId="[string]사용자ID",
    itemName="[string]아이템 모델명",
    itemSetName="[string]아이템 세트를 식별하는 이름",
    referenceOf="[string]참조원",
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Gs2Inventory:DeleteReferenceOfByUserId

사용자 ID를 지정하여 아이템의 참조원을 삭제

지정된 사용자의 지정된 아이템 세트에서 특정 참조원 문자열을 삭제합니다.
삭제 후, protectReferencedItem 이 활성화되어 있고 다른 참조원이 남아있지 않은 경우, 아이템은 다시 소비·삭제가 가능해집니다.

수량 지정 가능한 액션: 아니오

반전 가능한 액션: 아니오

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
inventoryNamestring
~ 128자인벤토리 모델명
이 아이템 세트를 포함하는 인벤토리 모델의 이름입니다. itemName과 함께 사용되어 이 소지품이 어떤 인벤토리와 아이템 종류에 속하는지를 식별하는 데 사용됩니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
itemNamestring
~ 128자아이템 모델명
이 세트에 저장된 아이템의 종류를 정의하는 아이템 모델의 이름입니다. inventoryName과 조합하여 이 아이템 세트의 스택 상한과 다중 스택 동작을 결정합니다.
itemSetNamestring
UUID~ 36자아이템 세트를 식별하는 이름
아이템 세트의 고유한 이름을 보유합니다.
이름은 UUID(Universally Unique Identifier) 형식으로 자동 생성되며, 각 아이템 세트를 식별하는 데 사용됩니다.
referenceOfstring
~ 1024자참조원
장비 슬롯이나 편성 바인드 등, 이 아이템 세트에 대한 외부 참조를 나타내는 문자열 식별자입니다. 인벤토리 모델에서 protectReferencedItem이 활성화된 경우, 참조원을 가진 아이템 세트는 소비하거나 삭제할 수 없습니다.
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Inventory:DeleteReferenceOfByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "inventoryName": "[string]인벤토리 모델명",
        "userId": "[string]사용자ID",
        "itemName": "[string]아이템 모델명",
        "itemSetName": "[string]아이템 세트를 식별하는 이름",
        "referenceOf": "[string]참조원",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Inventory:DeleteReferenceOfByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  inventoryName: "[string]인벤토리 모델명"
  userId: "[string]사용자ID"
  itemName: "[string]아이템 모델명"
  itemSetName: "[string]아이템 세트를 식별하는 이름"
  referenceOf: "[string]참조원"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("inventory").acquire.delete_reference_of_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    inventoryName="[string]인벤토리 모델명",
    userId="[string]사용자ID",
    itemName="[string]아이템 모델명",
    itemSetName="[string]아이템 세트를 식별하는 이름",
    referenceOf="[string]참조원",
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Gs2Inventory:AcquireSimpleItemsByUserId

사용자 ID를 지정하여 심플 아이템 입수

입수 수량의 배치를 사용하여 사용자의 심플 인벤토리에 아이템을 추가합니다.
단일 원자적 작업으로 여러 아이템을 입수할 수 있습니다. acquireCounts 배열로 각 아이템의 이름과 수량을 지정합니다.
일반적인 아이템 세트와 달리, 심플 아이템에는 용량 제한, 스택 제한, 유효기간이 없습니다.

수량 지정 가능한 액션: 아니오

반전 가능한 액션: 예

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
inventoryNamestring
~ 128자심플 인벤토리 모델 이름
심플 인벤토리 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
acquireCountsList<AcquireCount>
1 ~ 100 items심플 아이템의 입수 수량 리스트
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Inventory:AcquireSimpleItemsByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "inventoryName": "[string]심플 인벤토리 모델 이름",
        "userId": "[string]사용자ID",
        "acquireCounts": [
            {
                "itemName": "[string]심플 아이템 모델 이름",
                "count": "[long]입수하는 양"
            }
        ],
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Inventory:AcquireSimpleItemsByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  inventoryName: "[string]심플 인벤토리 모델 이름"
  userId: "[string]사용자ID"
  acquireCounts: 
    - itemName: "[string]심플 아이템 모델 이름"
      count: "[long]입수하는 양"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("inventory").acquire.acquire_simple_items_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    inventoryName="[string]심플 인벤토리 모델 이름",
    userId="[string]사용자ID",
    acquireCounts={
        {
            itemName="[string]심플 아이템 모델 이름",
            count="[long]입수하는 양"
        }
    },
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Gs2Inventory:SetSimpleItemsByUserId

사용자 ID를 지정하여 심플 아이템 설정

단일 원자적 작업으로 여러 심플 아이템의 절대 수량을 설정합니다.
counts 배열로 각 아이템의 이름과 목표 수량을 지정합니다.
입수/소비가 상대적 연산인 것과 달리, 이 경우 현재 수량을 완전히 덮어씁니다.

수량 지정 가능한 액션: 아니오

반전 가능한 액션: 아니오

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
inventoryNamestring
~ 128자심플 인벤토리 모델 이름
심플 인벤토리 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
countsList<HeldCount>
1 ~ 100 items심플 아이템의 소지 수량 목록
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Inventory:SetSimpleItemsByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "inventoryName": "[string]심플 인벤토리 모델 이름",
        "userId": "[string]사용자ID",
        "counts": [
            {
                "itemName": "[string]심플 아이템 모델 이름",
                "count": "[long]소지 수량"
            }
        ],
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Inventory:SetSimpleItemsByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  inventoryName: "[string]심플 인벤토리 모델 이름"
  userId: "[string]사용자ID"
  counts: 
    - itemName: "[string]심플 아이템 모델 이름"
      count: "[long]소지 수량"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("inventory").acquire.set_simple_items_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    inventoryName="[string]심플 인벤토리 모델 이름",
    userId="[string]사용자ID",
    counts={
        {
            itemName="[string]심플 아이템 모델 이름",
            count="[long]소지 수량"
        }
    },
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Gs2Inventory:AcquireBigItemByUserId

사용자 ID를 지정하여 거대 아이템 입수

임의 정밀도 연산을 사용하여 사용자의 거대 아이템 수량에 지정된 수량을 가산합니다.
acquireCount는 최대 1024자리의 유효한 정수 문자열이어야 하며, 형식이 올바르지 않으면 오류가 발생합니다.
아이템이 아직 존재하지 않는 경우 자동으로 생성됩니다.
네임스페이스 설정을 통해 거대 아이템 입수 시 커스텀 로직을 실행하는 GS2-Script를 설정할 수 있습니다.

수량 지정 가능한 액션: 예

반전 가능한 액션: 예

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
inventoryNamestring
~ 128자거대 인벤토리 모델 이름
거대 인벤토리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
itemNamestring
~ 128자거대 아이템 모델 이름
거대 아이템 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다.
acquireCountstring
~ 1024자거대 아이템의 입수 수량
최대 1024자리까지의 정수값 문자열
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Inventory:AcquireBigItemByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "inventoryName": "[string]거대 인벤토리 모델 이름",
        "userId": "[string]사용자ID",
        "itemName": "[string]거대 아이템 모델 이름",
        "acquireCount": "[string]거대 아이템의 입수 수량",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Inventory:AcquireBigItemByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  inventoryName: "[string]거대 인벤토리 모델 이름"
  userId: "[string]사용자ID"
  itemName: "[string]거대 아이템 모델 이름"
  acquireCount: "[string]거대 아이템의 입수 수량"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("inventory").acquire.acquire_big_item_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    inventoryName="[string]거대 인벤토리 모델 이름",
    userId="[string]사용자ID",
    itemName="[string]거대 아이템 모델 이름",
    acquireCount="[string]거대 아이템의 입수 수량",
    timeOffsetToken="[string]타임 오프셋 토큰",
})

Gs2Inventory:SetBigItemByUserId

사용자 ID를 지정하여 거대 아이템 설정

거대 아이템의 수량을 지정된 절대값으로 설정하여 현재 수량을 완전히 대체합니다.
수량은 최대 1024자리의 유효한 정수 문자열이어야 합니다.
아이템이 아직 존재하지 않는 경우 자동으로 생성됩니다.
입수·소비와 같은 상대적 연산과 달리, 정확한 값을 직접 설정합니다.

수량 지정 가능한 액션: 예

반전 가능한 액션: 아니오

타입활성화 조건필수기본값값 제한설명
namespaceNamestring
~ 128자네임스페이스 이름
네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다.
inventoryNamestring
~ 128자거대 인벤토리 모델 이름
거대 인벤토리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다.
userIdstring
~ 128자사용자ID
#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다.
itemNamestring
~ 128자거대 아이템 모델 이름
거대 아이템 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다.
countstring
~ 1024자거대 아이템의 수량
최대 1024자리까지의 정수값 문자열
timeOffsetTokenstring~ 1024자타임 오프셋 토큰
{
    "action": "Gs2Inventory:SetBigItemByUserId",
    "request": {
        "namespaceName": "[string]네임스페이스 이름",
        "inventoryName": "[string]거대 인벤토리 모델 이름",
        "userId": "[string]사용자ID",
        "itemName": "[string]거대 아이템 모델 이름",
        "count": "[string]거대 아이템의 수량",
        "timeOffsetToken": "[string]타임 오프셋 토큰"
    }
}
action: Gs2Inventory:SetBigItemByUserId
request:
  namespaceName: "[string]네임스페이스 이름"
  inventoryName: "[string]거대 인벤토리 모델 이름"
  userId: "[string]사용자ID"
  itemName: "[string]거대 아이템 모델 이름"
  count: "[string]거대 아이템의 수량"
  timeOffsetToken: "[string]타임 오프셋 토큰"
transaction.service("inventory").acquire.set_big_item_by_user_id({
    namespaceName="[string]네임스페이스 이름",
    inventoryName="[string]거대 인벤토리 모델 이름",
    userId="[string]사용자ID",
    itemName="[string]거대 아이템 모델 이름",
    count="[string]거대 아이템의 수량",
    timeOffsetToken="[string]타임 오프셋 토큰",
})