# Player

Before using any **player inventory methods** (`add_item`, `has_item`, `get_item`, etc.), you **must first retrieve the player inventory object** using the provided export:

```lua
local player = exports.list_inventory:get_player(source)
```

This returns the full player inventory object, with all public methods attached.\
Then you can use the methods below like so: 

```lua
RegisterCommand("give_bread", function(source)
    local player = exports.list_inventory:get_player(source)
    if not player then 
        print("Inventory not found") 
        return 
    end

    player:add_item("bread", 1)
end)
```

***

## create\_player\_inventory

Create a player inventory object and attach methods/data.

#### Params

* `source` (number): The player source

#### Returns

* Player inventory object or `false`

```lua
local player = exports.list_inventory:create_player_inventory(source)
```

***

## get\_player

Returns the inventory object for the given player.

#### Params

* `source` (number): The player source

#### Returns

* Player inventory object or `nil`

```lua
local inv = exports.list_inventory:get_player(source)
```

***

## add\_item

Adds an item to the inventory, optionally with metadata.

#### Params

* `id` (string): Item ID
* `amount` (number): Quantity
* `item_data` (table, optional): Item metadata (e.g., quality, serial)

#### Returns

* `true` on success, or `false, reason` on failure

```lua
player:add_item("water", 2, { quality = 100 })
```

***

## remove\_item

Removes item(s) by slot, ID, or metadata.

#### Params

* `lookup` (number|string|table): Slot number, item ID, or metadata table
* `amount` (number): Amount to remove

#### Returns

* `true` on success, `false` otherwise

```lua
player:remove_item(1, 1) -- slot
player:remove_item("bread", 1) -- ID
player:remove_item({ quality = 50 }, 1) -- metadata
```

***

## has\_item

Checks if inventory contains item by slot, ID, or metadata.

#### Params

* `lookup` (number|string|table): Slot number, item ID, or metadata table
* `amount` (number): Amount required (default: 1)

#### Returns

* `true` if found, otherwise `false`

```lua
player:has_item("water", 2)
```

***

## get\_item

Returns the first matching item by slot, ID, or metadata.

#### Params

* `lookup` (number|string|table): Slot number, item ID, or metadata table

#### Returns

* Item object or `nil`

```lua
local item = player:get_item("water")
```

***

## get\_items

Returns a table of all items in the inventory.

#### Returns

* `table`: All items indexed by slot

```lua
local items = player:get_items()
```

***

## set\_data

Sets a custom data field on the inventory.

#### Params

* `key` (string): Field name
* `value` (any): Value to store

#### Returns

* `true`

```lua
player:set_data("weight", 500)
```

***

## get\_data

Gets a specific or all data values from the inventory.

#### Params

* `key` (string, optional): Field name

#### Returns

* Value of the field or full data table

```lua
local weight = player:get_data("weight")
```

***

## has\_data

Checks whether a custom data key exists.

#### Params

* `key` (string): Field name

#### Returns

* `true` if exists, `false` otherwise

```lua
if player:has_data("slots") then ... end
```

***

## update\_item\_data

Updates the metadata for a specific slot.

#### Params

* `slot` (number|string): Slot number
* `new_data` (table): New metadata to merge in

#### Returns

* `true` on success, `false` on failure

```lua
player:update_item_data(1, { durability = 80 })
```

***

## split\_item

Splits a stack in one slot into a new one.

#### Params

* `slot` (number|string): Source slot
* `amount` (number): Amount to split

#### Returns

* `true` on success, `false` otherwise

```lua
player:split_item(1, 3)
```

***

## clear\_items

Removes all items from the inventory.

#### Returns

* `true`

```lua
player:clear_items()
```

***

## save

Saves the current inventory state to the database.

#### Returns

* `true` on success, `false` on failure

```lua
player:save()
```

***

## sync

Syncs the inventory with the client.

```lua
player:sync()
```