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 의 활성 버프 효과를 반영)이 사용됩니다.
수량 지정 가능한 액션: 예
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||||||||||||||||
| userId | string | ✓ | ~ 128자 | 사용자ID#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다. | ||||||||||||||||
| inventoryName | string | ✓ | ~ 128자 | 인벤토리 모델 이름 이 인벤토리의 구조와 용량 설정을 정의하는 인벤토리 모델의 이름입니다. 사용자의 인벤토리 인스턴스를 모델 정의에 연결하여 사용 가능한 아이템의 종류와 용량 제한을 결정합니다. | ||||||||||||||||
| verifyType | 문자열 열거형 enum { “less”, “lessEqual”, “greater”, “greaterEqual”, “equal”, “notEqual” } | ✓ | 검증 종류
| |||||||||||||||||
| currentInventoryMaxCapacity | int | ✓ | 0 ~ 2147483646 | 현재 인벤토리의 최대 용량 | ||||||||||||||||
| multiplyValueSpecifyingQuantity | bool | true | 수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부 | |||||||||||||||||
| timeOffsetToken | string | ~ 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.
수량 지정 가능한 액션: 예
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||||||||||||||||
| userId | string | ✓ | ~ 128자 | 사용자ID#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다. | ||||||||||||||||
| inventoryName | string | ✓ | ~ 128자 | 인벤토리 모델 이름 인벤토리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. | ||||||||||||||||
| itemName | string | ✓ | ~ 128자 | 아이템 모델명 이 세트에 저장된 아이템의 종류를 정의하는 아이템 모델의 이름입니다. inventoryName과 조합하여 이 아이템 세트의 스택 상한과 다중 스택 동작을 결정합니다. | ||||||||||||||||
| verifyType | 문자열 열거형 enum { “less”, “lessEqual”, “greater”, “greaterEqual”, “equal”, “notEqual” } | ✓ | 검증 종류
| |||||||||||||||||
| itemSetName | string | ~ 36자 | 아이템 세트를 식별하는 이름 | |||||||||||||||||
| count | long | ✓ | 0 ~ 9223372036854775805 | 소지 수량 | ||||||||||||||||
| multiplyValueSpecifyingQuantity | bool | true | 수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부 | |||||||||||||||||
| timeOffsetToken | string | ~ 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개 이상 존재).
조건이 충족되지 않으면 오류가 반환됩니다.
수량 지정 가능한 액션: 예
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||||||||||||
| inventoryName | string | ✓ | ~ 128자 | 인벤토리 모델명 이 아이템 세트를 포함하는 인벤토리 모델의 이름입니다. itemName과 함께 사용되어 이 소지품이 어떤 인벤토리와 아이템 종류에 속하는지를 식별하는 데 사용됩니다. | ||||||||||||
| userId | string | ✓ | ~ 128자 | 사용자ID#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다. | ||||||||||||
| itemName | string | ✓ | ~ 128자 | 아이템 모델명 이 세트에 저장된 아이템의 종류를 정의하는 아이템 모델의 이름입니다. inventoryName과 조합하여 이 아이템 세트의 스택 상한과 다중 스택 동작을 결정합니다. | ||||||||||||
| itemSetName | string | ✓ | UUID | ~ 36자 | 아이템 세트를 식별하는 이름 아이템 세트의 고유한 이름을 보유합니다. 이름은 UUID(Universally Unique Identifier) 형식으로 자동 생성되며, 각 아이템 세트를 식별하는 데 사용됩니다. | |||||||||||
| referenceOf | string | ✓ | ~ 1024자 | 참조원 장비 슬롯이나 편성 바인드 등, 이 아이템 세트에 대한 외부 참조를 나타내는 문자열 식별자입니다. 인벤토리 모델에서 protectReferencedItem이 활성화된 경우, 참조원을 가진 아이템 세트는 소비하거나 삭제할 수 없습니다. | ||||||||||||
| verifyType | 문자열 열거형 enum { “not_entry”, “already_entry”, “empty”, “not_empty” } | ✓ | 검증 종류
| |||||||||||||
| timeOffsetToken | string | ~ 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.
수량 지정 가능한 액션: 예
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||||||||||||||||
| userId | string | ✓ | ~ 128자 | 사용자ID#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다. | ||||||||||||||||
| inventoryName | string | ✓ | ~ 128자 | 심플 인벤토리 모델 이름 심플 인벤토리 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||||||||||||||||
| itemName | string | ✓ | ~ 128자 | 심플 아이템 모델 이름 이 레코드에 저장된 아이템의 종류를 정의하는 심플 아이템 모델의 이름입니다. 이 소지품이 어떤 아이템 정의에 대응하는지 식별하는 데 사용됩니다. | ||||||||||||||||
| verifyType | 문자열 열거형 enum { “less”, “lessEqual”, “greater”, “greaterEqual”, “equal”, “notEqual” } | ✓ | 검증 종류
| |||||||||||||||||
| count | long | ✓ | 0 ~ 9223372036854775805 | 소지 수량 | ||||||||||||||||
| multiplyValueSpecifyingQuantity | bool | true | 수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부 | |||||||||||||||||
| timeOffsetToken | string | ~ 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.
비교는 문자열 기반 수량에 대해 임의 정밀도 연산으로 수행됩니다.
조건이 충족되지 않으면 오류가 반환되고, 충족되면 요청이 성공합니다.
수량 지정 가능한 액션: 예
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||||||||||||||||
| userId | string | ✓ | ~ 128자 | 사용자ID#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다. | ||||||||||||||||
| inventoryName | string | ✓ | ~ 128자 | 거대 인벤토리 모델 이름 거대 인벤토리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. | ||||||||||||||||
| itemName | string | ✓ | ~ 128자 | 거대 아이템 모델 이름 이 레코드에 저장된 아이템의 종류를 정의하는 거대 아이템 모델의 이름입니다. 이 거대 아이템 소지품이 어떤 아이템 정의에 대응하는지 식별하는 데 사용됩니다. | ||||||||||||||||
| verifyType | 문자열 열거형 enum { “less”, “lessEqual”, “greater”, “greaterEqual”, “equal”, “notEqual” } | ✓ | 검증 종류
| |||||||||||||||||
| count | string | ✓ | ~ 1024자 | 소지 수량 최대 1024자리까지의 정수값 문자열 | ||||||||||||||||
| multiplyValueSpecifyingQuantity | bool | true | 수량을 지정했을 때, 검증에 사용하는 값도 곱할지 여부 | |||||||||||||||||
| timeOffsetToken | string | ~ 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 에러가 반환됩니다.
수량 지정 가능한 액션: 예
반전 가능한 액션: 예
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| inventoryName | string | ✓ | ~ 128자 | 인벤토리 모델명 이 아이템 세트를 포함하는 인벤토리 모델의 이름입니다. itemName과 함께 사용되어 이 소지품이 어떤 인벤토리와 아이템 종류에 속하는지를 식별하는 데 사용됩니다. | ||
| userId | string | ✓ | ~ 128자 | 사용자ID#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다. | ||
| itemName | string | ✓ | ~ 128자 | 아이템 모델명 이 세트에 저장된 아이템의 종류를 정의하는 아이템 모델의 이름입니다. inventoryName과 조합하여 이 아이템 세트의 스택 상한과 다중 스택 동작을 결정합니다. | ||
| consumeCount | long | ✓ | 1 ~ 9223372036854775805 | 소비 수량 | ||
| itemSetName | string | ~ 36자 | 아이템 세트를 식별하는 이름 | |||
| timeOffsetToken | string | ~ 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를 지정하여 심플 아이템 소비
소비 수량의 배치를 사용하여 지정된 사용자의 심플 인벤토리 내 아이템 수량을 감소시킵니다.
단일 원자적 작업으로 여러 아이템을 소비할 수 있습니다. 어느 하나의 아이템 수량이라도 부족한 경우, 작업 전체가 실패합니다.
수량 지정 가능한 액션: 아니오
반전 가능한 액션: 예
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| inventoryName | string | ✓ | ~ 128자 | 심플 인벤토리 모델 이름 심플 인벤토리 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| userId | string | ✓ | ~ 128자 | 사용자ID#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다. | ||
| consumeCounts | List<ConsumeCount> | ✓ | 1 ~ 100 items | 심플 아이템의 소비 수량 리스트 | ||
| timeOffsetToken | string | ~ 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를 설정할 수 있습니다.
수량 지정 가능한 액션: 예
반전 가능한 액션: 예
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| inventoryName | string | ✓ | ~ 128자 | 거대 인벤토리 모델 이름 거대 인벤토리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. | ||
| userId | string | ✓ | ~ 128자 | 사용자ID#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다. | ||
| itemName | string | ✓ | ~ 128자 | 거대 아이템 모델 이름 거대 아이템 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. | ||
| consumeCount | string | ✓ | ~ 1024자 | 거대 아이템의 소비 수량 최대 1024자리까지의 정수값 문자열 | ||
| timeOffsetToken | string | ~ 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 로 자동 생성된 후 지정된 값이 가산됩니다.
수량 지정 가능한 액션: 예
반전 가능한 액션: 아니오
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| inventoryName | string | ✓ | ~ 128자 | 인벤토리 모델 이름 이 인벤토리의 구조와 용량 설정을 정의하는 인벤토리 모델의 이름입니다. 사용자의 인벤토리 인스턴스를 모델 정의에 연결하여 사용 가능한 아이템의 종류와 용량 제한을 결정합니다. | ||
| userId | string | ✓ | ~ 128자 | 사용자ID#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다. | ||
| addCapacityValue | int | ✓ | 1 ~ 2147483646 | 가산할 용량 크기 | ||
| timeOffsetToken | string | ~ 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 를 초과할 수 없습니다.
수량 지정 가능한 액션: 예
반전 가능한 액션: 아니오
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| inventoryName | string | ✓ | ~ 128자 | 인벤토리 모델 이름 이 인벤토리의 구조와 용량 설정을 정의하는 인벤토리 모델의 이름입니다. 사용자의 인벤토리 인스턴스를 모델 정의에 연결하여 사용 가능한 아이템의 종류와 용량 제한을 결정합니다. | ||
| userId | string | ✓ | ~ 128자 | 사용자ID#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다. | ||
| newCapacityValue | int | ✓ | 1 ~ 2147483646 | 인벤토리의 새로운 최대 용량 | ||
| timeOffsetToken | string | ~ 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로 전송될 수 있습니다.
수량 지정 가능한 액션: 예
반전 가능한 액션: 예
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| inventoryName | string | ✓ | ~ 128자 | 인벤토리 모델 이름 인벤토리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. | ||
| itemName | string | ✓ | ~ 128자 | 아이템 모델명 이 세트에 저장된 아이템의 종류를 정의하는 아이템 모델의 이름입니다. inventoryName과 조합하여 이 아이템 세트의 스택 상한과 다중 스택 동작을 결정합니다. | ||
| userId | string | ✓ | ~ 128자 | 사용자ID#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다. | ||
| acquireCount | long | ✓ | 1 ~ 9223372036854775805 | 입수하는 양 | ||
| expiresAt | long | 0 | 유효기간 UNIX 시간·밀리초 | |||
| createNewItemSet | bool | false | 기존 아이템 세트에 여유가 있더라도 새로운 아이템 세트를 생성할지 여부 | |||
| itemSetName | string | ~ 36자 | 아이템 세트를 식별하는 이름 | |||
| timeOffsetToken | string | ~ 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를 통해 그레이드가 설정됩니다.
수량 지정 가능한 액션: 아니오
반전 가능한 액션: 아니오
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| inventoryName | string | ✓ | ~ 128자 | 인벤토리 모델 이름 인벤토리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. | ||
| itemName | string | ✓ | ~ 128자 | 아이템 모델명 이 세트에 저장된 아이템의 종류를 정의하는 아이템 모델의 이름입니다. inventoryName과 조합하여 이 아이템 세트의 스택 상한과 다중 스택 동작을 결정합니다. | ||
| userId | string | ✓ | ~ 128자 | 사용자ID#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다. | ||
| gradeModelId | string | ✓ | ~ 1024자 | 그레이드 모델 GRN | ||
| gradeValue | long | ✓ | 1 ~ 9223372036854775805 | 설정할 그레이드 값 | ||
| timeOffsetToken | string | ~ 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 이 활성화된 경우, 참조원을 가진 아이템은 소비·삭제할 수 없게 되어, 장비 중인 아이템이 실수로 소비되는 것을 방지할 수 있습니다.
수량 지정 가능한 액션: 아니오
반전 가능한 액션: 아니오
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| inventoryName | string | ✓ | ~ 128자 | 인벤토리 모델명 이 아이템 세트를 포함하는 인벤토리 모델의 이름입니다. itemName과 함께 사용되어 이 소지품이 어떤 인벤토리와 아이템 종류에 속하는지를 식별하는 데 사용됩니다. | ||
| userId | string | ✓ | ~ 128자 | 사용자ID#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다. | ||
| itemName | string | ✓ | ~ 128자 | 아이템 모델명 이 세트에 저장된 아이템의 종류를 정의하는 아이템 모델의 이름입니다. inventoryName과 조합하여 이 아이템 세트의 스택 상한과 다중 스택 동작을 결정합니다. | ||
| itemSetName | string | ✓ | UUID | ~ 36자 | 아이템 세트를 식별하는 이름 아이템 세트의 고유한 이름을 보유합니다. 이름은 UUID(Universally Unique Identifier) 형식으로 자동 생성되며, 각 아이템 세트를 식별하는 데 사용됩니다. | |
| referenceOf | string | ✓ | ~ 1024자 | 참조원 장비 슬롯이나 편성 바인드 등, 이 아이템 세트에 대한 외부 참조를 나타내는 문자열 식별자입니다. 인벤토리 모델에서 protectReferencedItem이 활성화된 경우, 참조원을 가진 아이템 세트는 소비하거나 삭제할 수 없습니다. | ||
| timeOffsetToken | string | ~ 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 이 활성화되어 있고 다른 참조원이 남아있지 않은 경우, 아이템은 다시 소비·삭제가 가능해집니다.
수량 지정 가능한 액션: 아니오
반전 가능한 액션: 아니오
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| inventoryName | string | ✓ | ~ 128자 | 인벤토리 모델명 이 아이템 세트를 포함하는 인벤토리 모델의 이름입니다. itemName과 함께 사용되어 이 소지품이 어떤 인벤토리와 아이템 종류에 속하는지를 식별하는 데 사용됩니다. | ||
| userId | string | ✓ | ~ 128자 | 사용자ID#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다. | ||
| itemName | string | ✓ | ~ 128자 | 아이템 모델명 이 세트에 저장된 아이템의 종류를 정의하는 아이템 모델의 이름입니다. inventoryName과 조합하여 이 아이템 세트의 스택 상한과 다중 스택 동작을 결정합니다. | ||
| itemSetName | string | ✓ | UUID | ~ 36자 | 아이템 세트를 식별하는 이름 아이템 세트의 고유한 이름을 보유합니다. 이름은 UUID(Universally Unique Identifier) 형식으로 자동 생성되며, 각 아이템 세트를 식별하는 데 사용됩니다. | |
| referenceOf | string | ✓ | ~ 1024자 | 참조원 장비 슬롯이나 편성 바인드 등, 이 아이템 세트에 대한 외부 참조를 나타내는 문자열 식별자입니다. 인벤토리 모델에서 protectReferencedItem이 활성화된 경우, 참조원을 가진 아이템 세트는 소비하거나 삭제할 수 없습니다. | ||
| timeOffsetToken | string | ~ 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 배열로 각 아이템의 이름과 수량을 지정합니다.
일반적인 아이템 세트와 달리, 심플 아이템에는 용량 제한, 스택 제한, 유효기간이 없습니다.
수량 지정 가능한 액션: 아니오
반전 가능한 액션: 예
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| inventoryName | string | ✓ | ~ 128자 | 심플 인벤토리 모델 이름 심플 인벤토리 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| userId | string | ✓ | ~ 128자 | 사용자ID#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다. | ||
| acquireCounts | List<AcquireCount> | ✓ | 1 ~ 100 items | 심플 아이템의 입수 수량 리스트 | ||
| timeOffsetToken | string | ~ 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 배열로 각 아이템의 이름과 목표 수량을 지정합니다.
입수/소비가 상대적 연산인 것과 달리, 이 경우 현재 수량을 완전히 덮어씁니다.
수량 지정 가능한 액션: 아니오
반전 가능한 액션: 아니오
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| inventoryName | string | ✓ | ~ 128자 | 심플 인벤토리 모델 이름 심플 인벤토리 모델 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| userId | string | ✓ | ~ 128자 | 사용자ID#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다. | ||
| counts | List<HeldCount> | ✓ | 1 ~ 100 items | 심플 아이템의 소지 수량 목록 | ||
| timeOffsetToken | string | ~ 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를 설정할 수 있습니다.
수량 지정 가능한 액션: 예
반전 가능한 액션: 예
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| inventoryName | string | ✓ | ~ 128자 | 거대 인벤토리 모델 이름 거대 인벤토리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. | ||
| userId | string | ✓ | ~ 128자 | 사용자ID#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다. | ||
| itemName | string | ✓ | ~ 128자 | 거대 아이템 모델 이름 거대 아이템 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. | ||
| acquireCount | string | ✓ | ~ 1024자 | 거대 아이템의 입수 수량 최대 1024자리까지의 정수값 문자열 | ||
| timeOffsetToken | string | ~ 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자리의 유효한 정수 문자열이어야 합니다.
아이템이 아직 존재하지 않는 경우 자동으로 생성됩니다.
입수·소비와 같은 상대적 연산과 달리, 정확한 값을 직접 설정합니다.
수량 지정 가능한 액션: 예
반전 가능한 액션: 아니오
| 타입 | 활성화 조건 | 필수 | 기본값 | 값 제한 | 설명 | |
|---|---|---|---|---|---|---|
| namespaceName | string | ✓ | ~ 128자 | 네임스페이스 이름 네임스페이스 고유의 이름입니다. 영숫자 및 -(하이픈) _(언더스코어) .(마침표)로 지정합니다. | ||
| inventoryName | string | ✓ | ~ 128자 | 거대 인벤토리 모델 이름 거대 인벤토리 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. | ||
| userId | string | ✓ | ~ 128자 | 사용자ID#{userId}로 설정하면 로그인 중인 사용자ID로 치환됩니다. | ||
| itemName | string | ✓ | ~ 128자 | 거대 아이템 모델 이름 거대 아이템 모델 고유 이름입니다. 영숫자 및 -(하이픈), _(언더스코어), .(마침표)로 지정합니다. | ||
| count | string | ✓ | ~ 1024자 | 거대 아이템의 수량 최대 1024자리까지의 정수값 문자열 | ||
| timeOffsetToken | string | ~ 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]타임 오프셋 토큰",
})