> For the complete documentation index, see [llms.txt](https://docs.menanak47.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.menanak47.com/multi-framework/ak47_inventory/exports/client.md).

# Client

### 💻 Core Client Operations

These functions are used to check the core state of the client-side inventory or handle primary interactions.

#### Ready

Checks if the player's inventory system has fully loaded and is ready to be used. It's recommended to check this before performing other client-side inventory operations during script initialization.

```lua
exports['ak47_inventory']:Ready()
```

Return: `boolean`

* `true` if ready, `false` otherwise

### 🗃️ UI & Inventory Management

Functions for managing the inventory user interface and its state.

#### OpenInventory

Opens the inventory user interface. It can open a specific inventory (like a stash), a dynamically created one, or another player's inventory.

```lua
exports['ak47_inventory']:OpenInventory(data)
```

* data: `table`, `string`, or `number`
  * `string:` target inventory identifier (e.g., 'stash:1234')
  * `number:` target player server ID to open their inventory
  * `table:` Configuration data for creating and opening a temporary/dynamic inventory
    * `identifier` (unique inventory identifier)
    * `label` (display label)
    * `type` (inventory type: stash, backpack, glovebox, trunk)
    * `maxWeight` (maximum weight capacity)
    * `slots` (total number of slots)

Example:

{% tabs %}
{% tab title="Existing Stash" %}

```lua
exports['ak47_inventory']:OpenInventory('stash:1234')
```

{% endtab %}

{% tab title="New/Housing Stash" %}

```lua
exports['ak47_inventory']:OpenInventory({
	identifier = 'stash:1234',
	label = 'Housing Stash',
	type = 'stash',
	maxWeight = 120000,
	slots = 50,
})
```

{% endtab %}

{% tab title="Player Inventory" %}

```lua
--player server id
exports['ak47_inventory']:OpenInventory(5)
```

{% endtab %}
{% endtabs %}

#### OpenNearbyInventory

Attempts to open the inventory of the nearest player to the client.

```lua
exports['ak47_inventory']:OpenNearbyInventory()
```

#### CloseInventory

Forces the inventory UI to close for the local player.

```lua
exports['ak47_inventory']:CloseInventory()
```

#### SetInventoryBusy

Sets the inventory's busy state, preventing or allowing the player to interact with their inventory UI. Useful when locking the inventory during an animation or progress bar.

```lua
exports['ak47_inventory']:SetInventoryBusy(busy)
```

* busy: `boolean` (true to lock, false to unlock)

Use Case:

```lua
local invBusy = LocalPlayer.state.invBusy
 
if invBusy then
    -- Do stuff when busy
else
    -- Do stuff when not busy
end
```

### 🔍 Data Retrieval & Getters

Functions for reading the client's inventory state, fetching item information, and searching for items.

#### Items

Retrieves the shared item configuration from the client. You can use this to fetch the definition of every item or a specific item's details (label, weight, etc.).

{% tabs %}
{% tab title="All Items" %}

```lua
exports['ak47_inventory']:Items()
```

{% endtab %}

{% tab title="Single Item" %}

```lua
exports['ak47_inventory']:Items('water')
```

{% endtab %}
{% endtabs %}

#### GetItem

Retrieves a consolidated object containing data about a specific item in the player's inventory.

```lua
exports['ak47_inventory']:GetItem(name, info, strict)
```

* name: `string`
  * item name
* info: `table` (optional)
  * filter by specific metadata
* strict: `boolean` (optional)
  * if true, strictly matches info properties; otherwise uses partial matching

Return: `table`

* item table with total item amount & properties

#### GetFirstItem

Finds and returns the data of the **first occurrence** of an item found in the inventory, regardless of how many stacks exist.

```lua
exports['ak47_inventory']:GetFirstItem(item)
```

* item: `string`
  * item name

Return: `table`

* first found item table

#### GetItemLabel

Returns the friendly display label of a specific item name.

```lua
exports['ak47_inventory']:GetItemLabel(name)
```

* name: `string`
  * item name

Return: `string`

* item label

#### HasItems

Verifies if the player's inventory contains a list of specific items in the required quantities.

```lua
exports['ak47_inventory']:HasItems(items)
```

* items: `table`
  * Key-value table of items: `{[item_name] = amount}`

Return: `boolean`, `table`

* hasAll (true if all items are present)
* missingItems (table of missing items and the amounts still needed)

Example:

```lua
exports['ak47_inventory']:HasItems({
    water = 5,
    bread = 3
})
```

#### Search

A versatile search function to find item counts or full slot data in the local player's inventory.

```lua
exports['ak47_inventory']:Search(searchType, item, info)
```

* searchType: `string`
  * `'slots'` (returns a table of slots where the item was found at)
  * `'amount'` (returns the amount of the specified item in the player's inventory. If searching for multiple items, returns key-value pairs of `itemName = amount`)
* item: `table` or `string`
  * Can be a single item name or an array of item names
* info: `table` or `string` (optional)
  * If info is provided as a string, it will search the item's `info.type` property

**Amount**

{% tabs %}
{% tab title="Single Item" %}

```lua
local amount = exports['ak47_inventory']:Search('amount', 'water')
print('You have ' .. amount .. ' water')
```

{% endtab %}

{% tab title="Multiple Items" %}

```lua
local inventory = exports['ak47_inventory']:Search('amount', {'meat', 'skin'}, {grade="1"})
 
if inventory then
    for name, amount in pairs(inventory) do
        print('You have ' .. amount .. ' ' .. name)
    end
end
```

{% endtab %}
{% endtabs %}

**Slots**

{% tabs %}
{% tab title="Single Item" %}

```lua
local water = exports['ak47_inventory']:Search('slots', 'water')
local amount = 0
 
for _, v in pairs(water) do
    print(v.slot .. ' contains ' .. v.amount .. ' water ' .. json.encode(v.info))
    amount = amount + v.amount
end
 
print('You have ' .. amount .. ' water')
```

{% endtab %}

{% tab title="Multiple Items" %}

```lua
local items = exports['ak47_inventory']:Search('slots', {'meat', 'skin'}, 'deer')
 
if items then
    for name, data in pairs(items) do
        local amount = 0
 
        for _, v in pairs(data) do
            if v.slot then
                print(v.slot .. ' contains ' .. v.amount .. ' ' .. name .. ' ' .. json.encode(v.info))
                amount = amount + v.amount
            end
        end
 
        print('You have ' .. amount .. ' ' .. name)
    end
end
```

{% endtab %}
{% endtabs %}

#### GetAmount

Returns the total numeric count of a specific item in the player's inventory. It sums up all stacks of that item.

```lua
exports['ak47_inventory']:GetAmount(itemName, info, strict)
```

* itemName: `string`
* info: `table` (optional)
* strict: `boolean` (optional)
  * Strictly match info properties, otherwise use partial matching

Return: `number`

* total amount of the item

#### GetPlayerItems

Retrieves the list (table) of items currently in the local player's inventory.

```lua
exports['ak47_inventory']:GetPlayerItems()
```

Return: `table`

* table of player items

#### GetPlayerWeight

Retrieves the current total weight of the items in the local player's inventory.

```lua
exports['ak47_inventory']:GetPlayerWeight()
```

Return: `number`

* current inventory weight

#### GetPlayerMaxWeight

Retrieves the maximum weight capacity of the local player's inventory.

```lua
exports['ak47_inventory']:GetPlayerMaxWeight()
```

Return: `number`

* maximum inventory weight

### 📍 Slot Operations

Functions for interacting with specific slots in the local player's inventory.

#### GetSlotWithItem

Retrieves the data of the **first slot found** containing the specific item.

```lua
exports['ak47_inventory']:GetSlotWithItem(itemName, info, strict)
```

* itemName: `string`
* info: `table` (optional)
* strict: `boolean` (optional)

Return: `table` or `nil`

* slot data table, if found

#### GetSlotIdWithItem

Retrieves the slot index (ID) of the **first slot found** containing the specific item.

```lua
exports['ak47_inventory']:GetSlotIdWithItem(itemName, info, strict)
```

* itemName: `string`
* info: `table` (optional)
* strict: `boolean` (optional)

Return: `number` or `nil`

* slot ID, if found

#### GetSlotsWithItem

Retrieves a list of **all slot data tables** that contain the specific item.

```lua
exports['ak47_inventory']:GetSlotsWithItem(itemName, info, strict)
```

* itemName: `string`
* info: `table` (optional)
* strict: `boolean` (optional)

Return: `table` or `nil`

* array of slot data tables

#### GetSlotIdsWithItem

Retrieves a list of **all slot IDs** containing the specific item.

```lua
exports['ak47_inventory']:GetSlotIdsWithItem(itemName, info, strict)
```

* itemName: `string`
* info: `table` (optional)
* strict: `boolean` (optional)

Return: `table` or `nil`

* array of slot IDs

#### GetSlot

Retrieves the item data stored at a specific slot index in the player's inventory. Returns `nil` if the slot is empty.

```lua
exports['ak47_inventory']:GetSlot(slotId)
```

* slotId: `number`
  * the slot index to query

Return: `table` or `nil`

* the item data table at that slot

#### UseSlot

Triggers the use action for the item currently occupying a specific slot.

```lua
exports['ak47_inventory']:UseSlot(slotId)
```

* slotId: `number`
  * the slot index to use

### ⚔️ Weapons

Functions for managing equipped weapons on the client side.

#### UnEquipeWeapon

Unequips the currently equipped weapon from the local player's hands.

```lua
exports['ak47_inventory']:UnEquipeWeapon()
```