# nova\_inventory

NOVA Framework inventory system with drag & drop, usable items, and weight-based limits.

## Features

* **Drag & Drop** — Move items between slots via NUI
* **Usable Items** — Food, drinks, medkit, bandage, repair kit, weapons, armor, ammo
* **Hotbar** — Use items in slots 1–5 with number keys
* **Drop & Pickup** — Drop items on ground, pick up with E
* **Weight System** — Configurable max weight (default 120kg)
* **Ground Items** — Dropped items persist for 5 minutes (configurable)

## Configuration

### nova\_inventory/config.lua

```lua
InvConfig = {
    MaxSlots = 40,           -- Total inventory slots
    MaxWeight = 120000,      -- Max weight in grams (120 kg)
    HotbarSlots = 5,         -- Slots 1-5 are hotbar
    DropDistance = 3.0,      -- Max drop distance
    PickupDistance = 2.0,    -- Distance to pick up ground items
    GroundItemExpiry = 300,  -- Seconds before ground items despawn (5 min)
}
```

### Item Configuration: nova\_core/config/items.lua

Items are registered in the core, not the inventory script:

```lua
NovaItems.Register('bread', {
    label = 'Pão',
    weight = 200,              -- grams
    type = 'food',             -- item, weapon, food, drink, misc, ammo
    useable = true,
    unique = false,            -- Can stack?
    shouldClose = true,        -- Close inventory after use?
    description = 'Um pão fresquinho.',
    image = 'bread.png',
})
```

### Item Properties

| Property      | Type    | Description                                       |
| ------------- | ------- | ------------------------------------------------- |
| `label`       | string  | Display name                                      |
| `weight`      | number  | Weight in grams                                   |
| `type`        | string  | `item`, `weapon`, `food`, `drink`, `misc`, `ammo` |
| `useable`     | boolean | Can the item be used?                             |
| `unique`      | boolean | If true, cannot stack; if false, stacks           |
| `shouldClose` | boolean | Close inventory after use                         |
| `description` | string  | Item description                                  |
| `image`       | string  | Image filename (default: `name.png`)              |

## Adding Custom Usable Items

Edit `client/useitems.lua` to add item effects:

```lua
-- 1. Add the item to nova_core/config/items.lua with useable = true
NovaItems.Register('my_item', {
    label = 'My Custom Item',
    weight = 100,
    type = 'item',
    useable = true,
    shouldClose = true,
})

-- 2. Add the effect in client/useitems.lua
ItemEffects['my_item'] = function(itemData)
    local success = ProgressBar('Using item...', 3000, {
        animation = { dict = 'mp_common', clip = 'givetake1_a', flag = 49 },
        canCancel = true,
    })
    if success then
        Notify('You used the item!', 'success')
        -- Your custom logic here
    end
end
```

### Built-in Item Effects (useitems.lua)

| Item                                          | Effect                        |
| --------------------------------------------- | ----------------------------- |
| `bread`, `sandwich`, `burger`                 | Restore hunger                |
| `water`, `coffee`, `energy_drink`             | Restore thirst                |
| `medikit`                                     | Full health                   |
| `bandage`                                     | +50 health                    |
| `armor`                                       | Full armor                    |
| `repairkit`                                   | Repair nearby vehicle         |
| `jerrycan`                                    | Refuel nearby vehicle         |
| `weapon_*`                                    | Equip/unequip weapon          |
| `ammo_*`                                      | Add ammo to compatible weapon |
| `id_card`, `driver_license`, `weapon_license` | Show (no consume)             |

## Weight System

* Each item has a `weight` in grams
* Total inventory weight = sum of (item weight × amount) for all slots
* Cannot pick up or receive items if it would exceed `MaxWeight`
* Current weight is displayed in the NUI

## Exports

| Export                  | Parameters                                           | Returns | Description                       |
| ----------------------- | ---------------------------------------------------- | ------- | --------------------------------- |
| `AddItem`               | `source`, `itemName`, `amount`, `slot?`, `metadata?` | boolean | Add item to player (server)       |
| `RemoveItem`            | `source`, `itemName`, `amount`                       | boolean | Remove item (server)              |
| `HasItem`               | `source`, `itemName`, `amount?`                      | boolean | Check if player has item (server) |
| `GetItemCount`          | `source`, `itemName`                                 | number  | Count of item (server)            |
| `GetPlayerInventory`    | `source`                                             | table   | Full inventory slots (server)     |
| `SetInventoryMaxWeight` | `source`, `weight`                                   | —       | Set max weight (server)           |
| `OpenInventory`         | —                                                    | —       | Open inventory UI (client)        |
| `CloseInventory`        | —                                                    | —       | Close inventory UI (client)       |
| `IsOpen`                | —                                                    | boolean | Is inventory open? (client)       |

## Usage Examples

### Give item (server)

```lua
exports['nova_inventory']:AddItem(source, 'bread', 5)
```

### Check and remove item (server)

```lua
if exports['nova_inventory']:HasItem(source, 'lockpick', 1) then
    exports['nova_inventory']:RemoveItem(source, 'lockpick', 1)
    -- Proceed with lockpicking
end
```

### Open inventory from another script (client)

```lua
exports['nova_inventory']:OpenInventory()
```

### Listen for item use

Item use events are handled through `useitems.lua` — register your custom item effects there using the built-in ItemEffects system.

## Notes

* Inventory opens with **Tab** (control 37)
* Items are stored in the database via nova\_core
* A server event is triggered when any item is used (for other scripts to hook)
* Progress bar uses `nova_hud:ProgressBar`; notifications use `nova_notify`

## Security

* All operations are validated server-side
* Internal event names are not disclosed in this documentation for security purposes