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

# GS2-Inventory Script Trigger Reference

Reference for event triggers that call extended scripts



## Trigger

### acquire

Item acquisition

**Related methods:**
acquireItemSetByUserId - Acquire Item Sets by specifying the user ID
acquireItemSetWithGradeByUserId - Acquire one Item Set while setting the grade to GS2-Grade by specifying the user ID


#### Synchronous Execution Script

The script is executed synchronously before the item acquisition process.

##### Request

| | Type | Description |
| --- | --- | --- |
| namespace | [Namespace](../sdk/#namespace) | Namespace |
| inventory | [Inventory](../sdk/#inventory) | Inventory |
| itemSets | [ItemSet[]](../sdk/#itemset) | List of Item Sets |
| acquireItemName | string | Name of Item Model acquired |
| userId | string | User ID |
| acquireCount | long | Quantity acquired |
| expiresAt | long | Expiration time<br>Unix time, milliseconds |

##### Result

|  | Type | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- |
| permit | bool | ✓ |  |  | Whether to allow item acquisition |
| overrideAcquireCount | int |  |  | 0 ~ 2147483645 | Actual amount obtained to be applied |

##### Implementation Example


**Lua**
```lua

-- Request
local namespace = args.namespace
local inventory = args.inventory
local itemSets = args.itemSets
local acquireItemName = args.acquireItemName
local userId = args.userId
local acquireCount = args.acquireCount
local expiresAt = args.expiresAt

-- Business logic:
local permit = true
local overrideAcquireCount = 0

-- Result
result = {
  permit=permit,
  overrideAcquireCount=overrideAcquireCount
}
```


#### Asynchronous Execution Script

The script is executed asynchronously after the item acquisition process.

##### Request

| | Type | Description |
| --- | --- | --- |
| namespace | [Namespace](../sdk/#namespace) | Namespace |
| oldInventory | [Inventory](../sdk/#inventory) | Inventory before update |
| oldItemSets | [ItemSet[]](../sdk/#itemset) | List of Item Sets before renewal |
| newInventory | [Inventory](../sdk/#inventory) | Inventory after update |
| newItemSets | [ItemSet[]](../sdk/#itemset) | List of updated Item Sets |
| acquireItemName | string | Name of Item Model acquired |
| userId | string | User ID |
| acquireCount | long | Quantity acquired |
| overflowValue | long | Amount of overflow |
| expiresAt | long | Expiration time<br>Unix time, milliseconds |


##### Implementation Example


**Lua**
```lua

-- Request
local namespace = args.namespace
local oldInventory = args.oldInventory
local oldItemSets = args.oldItemSets
local newInventory = args.newInventory
local newItemSets = args.newItemSets
local acquireItemName = args.acquireItemName
local userId = args.userId
local acquireCount = args.acquireCount
local overflowValue = args.overflowValue
local expiresAt = args.expiresAt

-- Asynchronous scripts typically do not affect the API response.
-- These scripts are typically used for logging, analytics, external notifications, and similar purposes.

result = {
}
```


---
  
### overflowDone

process for notifying the quantity that could not be acquired after the acquisition limit is reached

**Related methods:**
acquireItemSetByUserId - Acquire Item Sets by specifying the user ID
acquireItemSetWithGradeByUserId - Acquire one Item Set while setting the grade to GS2-Grade by specifying the user ID


#### Synchronous Execution Script

The script is executed synchronously before the process for notifying the quantity that could not be acquired after the acquisition limit is reached.

##### Request

| | Type | Description |
| --- | --- | --- |
| namespace | [Namespace](../sdk/#namespace) | Namespace |
| inventory | [Inventory](../sdk/#inventory) | Inventory |
| itemModel | [ItemModel](../sdk/#itemmodel) | Item Model |
| userId | string | User ID |
| overflowValue | long | Amount of overflow |


##### Implementation Example


**Lua**
```lua

-- Request
local namespace = args.namespace
local inventory = args.inventory
local itemModel = args.itemModel
local userId = args.userId
local overflowValue = args.overflowValue

-- Business logic:

-- Result
result = {
}
```


---
  
### consume

item consumption

**Related methods:**
consumeItemSet - Consume Item Sets
consumeItemSetByUserId - Consume Item Sets by specifying the user ID


#### Synchronous Execution Script

The script is executed synchronously before the item consumption process.

##### Request

| | Type | Description |
| --- | --- | --- |
| namespace | [Namespace](../sdk/#namespace) | Namespace |
| inventory | [Inventory](../sdk/#inventory) | Inventory |
| itemSets | [ItemSet[]](../sdk/#itemset) | List of Item Sets |
| consumeItemName | string | Name of Item Model consumed |
| userId | string | User ID |
| consumeCount | long | Quantity consumed |

##### Result

|  | Type | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- |
| permit | bool | ✓ |  |  | Whether to allow item consumption |
| overrideConsumeCount | int |  |  | 0 ~ 2147483645 | Actual consumption to be applied |

##### Implementation Example


**Lua**
```lua

-- Request
local namespace = args.namespace
local inventory = args.inventory
local itemSets = args.itemSets
local consumeItemName = args.consumeItemName
local userId = args.userId
local consumeCount = args.consumeCount

-- Business logic:
local permit = true
local overrideConsumeCount = 0

-- Result
result = {
  permit=permit,
  overrideConsumeCount=overrideConsumeCount
}
```


#### Asynchronous Execution Script

The script is executed asynchronously after the item consumption process.

##### Request

| | Type | Description |
| --- | --- | --- |
| namespace | [Namespace](../sdk/#namespace) | Namespace |
| oldInventory | [Inventory](../sdk/#inventory) | Inventory before consumption |
| oldItemSets | [ItemSet[]](../sdk/#itemset) | List of Item Sets before consumption |
| newInventory | [Inventory](../sdk/#inventory) | Inventory after consumption |
| newItemSets | [ItemSet[]](../sdk/#itemset) | List of Item Sets after consumption |
| consumeItemName | string | Name of Item Model consumed |
| userId | string | User ID |
| consumeCount | long | Quantity consumed |


##### Implementation Example


**Lua**
```lua

-- Request
local namespace = args.namespace
local oldInventory = args.oldInventory
local oldItemSets = args.oldItemSets
local newInventory = args.newInventory
local newItemSets = args.newItemSets
local consumeItemName = args.consumeItemName
local userId = args.userId
local consumeCount = args.consumeCount

-- Asynchronous scripts typically do not affect the API response.
-- These scripts are typically used for logging, analytics, external notifications, and similar purposes.

result = {
}
```


---
  
### simpleItemAcquire

Simple Item acquisition

**Related methods:**
acquireSimpleItemsByUserId - Acquire Simple Items by User ID


#### Synchronous Execution Script

The script is executed synchronously before the simple item acquisition process.

##### Request

| | Type | Description |
| --- | --- | --- |
| namespace | [Namespace](../sdk/#namespace) | Namespace |
| inventoryName | string | Simple Inventory Model Name<br>The name of the simple inventory model that defines the item types for this inventory. Links the user's simple inventory instance to its model definition. |
| simpleItems | [SimpleItem[]](../sdk/#simpleitem) | List of Simple Items |
| userId | string | User ID |
| acquireCounts | [AcquireCount[]](../sdk/#acquirecount) | List of acquisition quantities for Simple Items |

##### Result

|  | Type | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- |
| permit | bool | ✓ |  |  | Whether to allow Simple Item acquisition |
| overrideAcquireCounts | AcquireCount[] |  |  | 0 ~ 100 items | List of acquisition quantities for Simple Items |

##### Implementation Example


**Lua**
```lua

-- Request
local namespace = args.namespace
local inventoryName = args.inventoryName
local simpleItems = args.simpleItems
local userId = args.userId
local acquireCounts = args.acquireCounts

-- Business logic:
local permit = true
local overrideAcquireCounts = {}

-- Result
result = {
  permit=permit,
  overrideAcquireCounts=overrideAcquireCounts
}
```


#### Asynchronous Execution Script

The script is executed asynchronously after the simple item acquisition process.

##### Request

| | Type | Description |
| --- | --- | --- |
| namespace | [Namespace](../sdk/#namespace) | Namespace |
| inventoryName | string | Simple Inventory Model Name<br>The name of the simple inventory model that defines the item types for this inventory. Links the user's simple inventory instance to its model definition. |
| oldSimpleItems | [SimpleItem[]](../sdk/#simpleitem) | List of Simple Items before update |
| newSimpleItems | [SimpleItem[]](../sdk/#simpleitem) | List of Simple Items after Update |
| userId | string | User ID |
| acquireCounts | [AcquireCount[]](../sdk/#acquirecount) | List of Simple Items |


##### Implementation Example


**Lua**
```lua

-- Request
local namespace = args.namespace
local inventoryName = args.inventoryName
local oldSimpleItems = args.oldSimpleItems
local newSimpleItems = args.newSimpleItems
local userId = args.userId
local acquireCounts = args.acquireCounts

-- Asynchronous scripts typically do not affect the API response.
-- These scripts are typically used for logging, analytics, external notifications, and similar purposes.

result = {
}
```


---
  
### simpleItemConsume

Simple Item consumption

**Related methods:**
consumeSimpleItems - Consume Simple Items
consumeSimpleItemsByUserId - Consume Simple Items by User ID


#### Synchronous Execution Script

The script is executed synchronously before the simple item consumption process.

##### Request

| | Type | Description |
| --- | --- | --- |
| namespace | [Namespace](../sdk/#namespace) | Namespace |
| inventoryName | string | Simple Inventory Model Name<br>The name of the simple inventory model that defines the item types for this inventory. Links the user's simple inventory instance to its model definition. |
| simpleItems | [SimpleItem[]](../sdk/#simpleitem) | List of Simple Item |
| userId | string | User ID |
| consumeCounts | [ConsumeCount[]](../sdk/#consumecount) | List of consumption quantities of Simple Items |

##### Result

|  | Type | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- |
| permit | bool | ✓ |  |  | Whether to allow Simple Item consumption |
| overrideConsumeCounts | ConsumeCount[] |  |  | 0 ~ 100 items | List of Simple Items |

##### Implementation Example


**Lua**
```lua

-- Request
local namespace = args.namespace
local inventoryName = args.inventoryName
local simpleItems = args.simpleItems
local userId = args.userId
local consumeCounts = args.consumeCounts

-- Business logic:
local permit = true
local overrideConsumeCounts = {}

-- Result
result = {
  permit=permit,
  overrideConsumeCounts=overrideConsumeCounts
}
```


#### Asynchronous Execution Script

The script is executed asynchronously after the simple item consumption process.

##### Request

| | Type | Description |
| --- | --- | --- |
| namespace | [Namespace](../sdk/#namespace) | Namespace |
| inventoryName | string | Simple Inventory Model Name<br>The name of the simple inventory model that defines the item types for this inventory. Links the user's simple inventory instance to its model definition. |
| oldSimpleItems | [SimpleItem[]](../sdk/#simpleitem) | List of Before update Simple Items |
| newSimpleItems | [SimpleItem[]](../sdk/#simpleitem) | List of After update Simple Items |
| userId | string | User ID |
| consumeCounts | [ConsumeCount[]](../sdk/#consumecount) | List of consumption quantities of Simple Items |


##### Implementation Example


**Lua**
```lua

-- Request
local namespace = args.namespace
local inventoryName = args.inventoryName
local oldSimpleItems = args.oldSimpleItems
local newSimpleItems = args.newSimpleItems
local userId = args.userId
local consumeCounts = args.consumeCounts

-- Asynchronous scripts typically do not affect the API response.
-- These scripts are typically used for logging, analytics, external notifications, and similar purposes.

result = {
}
```


---
  
### bigItemAcquire

Big Item acquisition

**Related methods:**
acquireBigItemByUserId - Acquire Big Item by User ID


#### Synchronous Execution Script

The script is executed synchronously before the big item acquisition process.

##### Request

| | Type | Description |
| --- | --- | --- |
| namespace | [Namespace](../sdk/#namespace) | Namespace |
| inventoryName | string | Big Inventory Model Name<br>The name of the big inventory model that defines the item types for this inventory. Links the user's big inventory instance to its model definition. |
| itemName | string | Big Item Model Name<br>The name of the big item model that defines the type of item stored in this record. Used to identify which item definition this big item possession corresponds to. |
| item | [BigItem](../sdk/#bigitem) | Big Item |
| userId | string | User ID |
| acquireCount | string | Acquisition quantity for a Big Item<br>Integer value strings up to 1024 digits |

##### Result

|  | Type | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- |
| permit | bool | ✓ |  |  | Whether to allow Big Item acquisition |
| rate | float |  | 1.0 | 0 ~ 1000 | Reward quantity multiplier |

##### Implementation Example


**Lua**
```lua

-- Request
local namespace = args.namespace
local inventoryName = args.inventoryName
local itemName = args.itemName
local item = args.item
local userId = args.userId
local acquireCount = args.acquireCount

-- Business logic:
local permit = true
local rate = 1.0

-- Result
result = {
  permit=permit,
  rate=rate
}
```


#### Asynchronous Execution Script

The script is executed asynchronously after the big item acquisition process.

##### Request

| | Type | Description |
| --- | --- | --- |
| namespace | [Namespace](../sdk/#namespace) | Namespace |
| inventoryName | string | Big Inventory Model Name<br>The name of the big inventory model that defines the item types for this inventory. Links the user's big inventory instance to its model definition. |
| itemName | string | Big Item Model Name<br>The name of the big item model that defines the type of item stored in this record. Used to identify which item definition this big item possession corresponds to. |
| oldItem | [BigItem](../sdk/#bigitem) | Before update Big Item |
| newItem | [BigItem](../sdk/#bigitem) | After update Big Item |
| userId | string | User ID |
| acquireCount | string | Acquisition quantity for a Big Item<br>Integer value strings up to 1024 digits |


##### Implementation Example


**Lua**
```lua

-- Request
local namespace = args.namespace
local inventoryName = args.inventoryName
local itemName = args.itemName
local oldItem = args.oldItem
local newItem = args.newItem
local userId = args.userId
local acquireCount = args.acquireCount

-- Asynchronous scripts typically do not affect the API response.
-- These scripts are typically used for logging, analytics, external notifications, and similar purposes.

result = {
}
```


---
  
### bigItemConsume

big item consumption

**Related methods:**
consumeBigItem - Consume Big Items
consumeBigItemByUserId - Consume Big Items by User ID


#### Synchronous Execution Script

The script is executed synchronously before the big item consumption process.

##### Request

| | Type | Description |
| --- | --- | --- |
| namespace | [Namespace](../sdk/#namespace) | Namespace |
| inventoryName | string | Big Inventory Model Name<br>The name of the big inventory model that defines the item types for this inventory. Links the user's big inventory instance to its model definition. |
| itemName | string | Big Item Model Name<br>The name of the big item model that defines the type of item stored in this record. Used to identify which item definition this big item possession corresponds to. |
| item | [BigItem](../sdk/#bigitem) | Big Item |
| userId | string | User ID |
| consumeCount | string | Consumption quantity of a Big Item<br>Integer value strings up to 1024 digits |

##### Result

|  | Type | Required | Default | Value Limits | Description |
| --- | --- | --- | --- | --- | --- |
| permit | bool | ✓ |  |  | Whether to allow Big Item consumption |
| rate | float |  | 1.0 | 0 ~ 1000 | Consume quantity rate |

##### Implementation Example


**Lua**
```lua

-- Request
local namespace = args.namespace
local inventoryName = args.inventoryName
local itemName = args.itemName
local item = args.item
local userId = args.userId
local consumeCount = args.consumeCount

-- Business logic:
local permit = true
local rate = 1.0

-- Result
result = {
  permit=permit,
  rate=rate
}
```


#### Asynchronous Execution Script

The script is executed asynchronously after the big item consumption process.

##### Request

| | Type | Description |
| --- | --- | --- |
| namespace | [Namespace](../sdk/#namespace) | Namespace |
| inventoryName | string | Big Inventory Model Name<br>The name of the big inventory model that defines the item types for this inventory. Links the user's big inventory instance to its model definition. |
| itemName | string | Big Item Model Name<br>The name of the big item model that defines the type of item stored in this record. Used to identify which item definition this big item possession corresponds to. |
| oldItem | [BigItem](../sdk/#bigitem) | Before update Big Item |
| newItem | [BigItem](../sdk/#bigitem) | After update Big Item |
| userId | string | User ID |
| consumeCount | string | Consumption quantity of a Big Item<br>Integer value strings up to 1024 digits |


##### Implementation Example


**Lua**
```lua

-- Request
local namespace = args.namespace
local inventoryName = args.inventoryName
local itemName = args.itemName
local oldItem = args.oldItem
local newItem = args.newItem
local userId = args.userId
local consumeCount = args.consumeCount

-- Asynchronous scripts typically do not affect the API response.
-- These scripts are typically used for logging, analytics, external notifications, and similar purposes.

result = {
}
```


---