# Packs

## Packs

Packs allow you to bundle multiple servings of a consumable item into a single inventory item. Instead of giving a player 6 individual donuts, you give them one "Pack of Donut" containing 6 servings. Players can use items directly from the pack in their inventory, or optionally place the pack on the ground for other players to take from.

***

### Table of Contents

* [How Packs Work](#how-packs-work)
* [Enabling Packs on an Item](#enabling-packs-on-an-item)
* [Registering Pack Items in Your Inventory](#registering-pack-items-in-your-inventory)
* [Spawning a Pack (Command)](#spawning-a-pack-command)
* [Spawning a Pack (Export)](#spawning-a-pack-export)
* [Packs in Shops](#packs-in-shops)
* [Placing Packs on the Ground](#placing-packs-on-the-ground)
* [Interacting with Placed Packs](#interacting-with-placed-packs)
* [Showcase Display Modes](#showcase-display-modes)
* [Configuration Reference](#configuration-reference)
* [Pack Item Settings Reference](#pack-item-settings-reference)
* [Generating Pack Items Automatically](#generating-pack-items-automatically)
* [FAQ](#faq)

***

### How Packs Work

1. **An item has packs enabled** via the creator menu (the `pack` field on the item settings).
2. **A pack item** is registered in your inventor, named `pack_<itemName>` (ex. `pack_donut`).
3. **Using a pack from inventory** removes one serving from the pack and gives the player one individual consumable item. When the pack is empty, it is removed.
4. **Placing a pack on the ground** (if `canPlace` is enabled) creates a physical prop in the world that other players can interact with via the target system (ox\_target, qb-target, etc).

***

### Enabling Packs on an Item

In the **Creator Menu**, you can enable packs for any item. The pack configuration is stored as part of the item settings. The relevant fields are:

| Field               | Type       | Description                                                                                                            |
| ------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------- |
| `enabled`           | `boolean`  | Whether the pack is active for this item                                                                               |
| `amount`            | `number`   | Number of servings in the pack                                                                                         |
| `canPlace`          | `boolean`  | Whether the pack can be placed on the ground                                                                           |
| `prop`              | `string?`  | Custom prop model for the placed pack (defaults to `v_serv_abox_02`, which is just a box)                              |
| `placementRequired` | `boolean?` | If `true`, the pack **must** be placed on the ground before it can be used — it cannot be used directly from inventory |

***

### Registering Pack Items in Your Inventory

Each pack-enabled consumable needs a corresponding pack item in your inventory resource. The naming convention is `pack_<itemName>`.

#### ox\_inventory

```lua
["pack_donut"] = {
    label = "Pack of Donut",
    weight = 0,
    stack = false,
},
```

#### qb-core

```lua
["pack_donut"] = {["name"] = "pack_donut", ["label"] = "Pack of Donut", ["weight"] = 0, ["unique"] = true, ["image"] = "pack_donut.png", ["type"] = "item"},
```

> A `pack_box.png` image is included in `extras/items/images/` that you can use as a default pack image.

***

### Spawning a Pack (Command)

Use the spawn command to give a player a pack in-game:

```
/spawn_pack <itemName>
```

* `<itemName>` is the **base consumable name**, not the pack name (ex. `donut`, not `pack_donut`)
* Requires the permission configured in `Config.Settings.packs.permission` (default: `"command"`)
* The command name is configurable via `Config.Settings.packs.spawnCommand`

**Example:**

```
/spawn_pack donut
```

***

### Spawning a Pack (Export)

You can give a player a pack from another script using the server export:

```lua
exports["zyke_consumables"]:SpawnPack(playerId, "donut")
```

* `playerId` — The server ID of the player
* Second argument is the **base item name** (not the pack name)

***

### Packs in Shops

Since this is just a normal item in your inventory, you can add the packs into any shop script.

***

### Placing Packs on the Ground

If `canPlace` is enabled for the item's pack settings:

1. The player uses the pack item from their inventory
2. A placement preview appears (the pack prop)
3. The player confirms the placement position
4. The pack is removed from inventory and placed in the world
5. A physical prop appears that other players can interact with

#### Limits

* Each player can have a maximum number of placed packs, configured by `Config.Settings.packs.maxPlacedPerPlayer` (default: `10`)
* Placed packs are automatically cleaned up after a configurable inactivity period — `Config.Settings.packs.cleanupInterval` (default: `43200` seconds / 12 hours)

***

### Interacting with Placed Packs

When a placed pack is in range, players can interact via the target system. Two options appear:

| Option     | Description                                                                                                                                      |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Use**    | Takes one serving from the pack and gives the player the consumable item. The pack's remaining count decreases. When empty, the pack is removed. |
| **Pickup** | Picks up the entire pack and puts it back in the player's inventory with its current amount.                                                     |

If the player has the `adminDebugPermission`, an additional **Admin Debug** option appears that prints the pack data to the F8 console.

***

### Showcase Display Modes

Players can choose how placed packs appear via the **Personal Settings** menu (`/consum:settings`). The `packShowcase` setting controls the display prop on top of placed packs:

| Mode       | Description                                                                  |
| ---------- | ---------------------------------------------------------------------------- |
| `basic`    | No prop on top of the pack, just the box                                     |
| `static`   | A static (non-moving) ghost prop of the item is displayed on top of the pack |
| `advanced` | A slowly rotating ghost prop of the item is displayed on top of the pack     |

Default: `static`

The ghost prop uses the item's first prop model and appears semi-transparent (40% opacity).

***

### Configuration Reference

All pack-related settings in `Config.Settings.packs`:

```lua
packs = {
    spawnCommand = {"spawn_pack"},     -- Command(s) to spawn a pack
    permission = "command",            -- Permission required to use the spawn command
    maxPlacedPerPlayer = 10,           -- Max packs a player can place in the world
    cleanupInterval = 43200,           -- Seconds before an unused placed pack is removed (12h)
    adminDebugPermission = "command",  -- Permission for the admin debug target option
}
```

***

### Pack Item Settings Reference

The `pack` field on an item's settings (set via item creator menu). This is just a flattened visual reference of the UI configuration.

```lua
pack = {
    enabled = true,            -- Toggle packs for this item
    amount = 6,                -- Number of servings in each pack
    canPlace = true,           -- Allow placing in the world
    prop = "v_serv_abox_02",   -- Custom prop model (optional, defaults to v_serv_abox_02)
    placementRequired = false, -- Force placement before use (optional)
}
```

***

### Generating Pack Items Automatically

Use the `consum:gen_packs` server console command to automatically generate a `packs.lua` file containing inventory definitions for all pack-enabled items. This file can be copy-pasted directly into your inventory resource.

There's different modes of generating the items, so that you can decide what the template for the pack image name will be. Functionality of this may vary based on inventory.

| Command                                      | Description                                                                                           |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `/consum:gen_packs` or `/consum:gen_packs 1` | Generates `packs.lua` with image set to `pack_<itemName>.png`                                         |
| `/consum:gen_packs 2`                        | Image set to the base item's image (`<itemName>.png`) — useful if you don't have separate pack images |
| `/consum:gen_packs 3`                        | Image set to `pack_box.png` for all packs — a generic box image included in `extras/items/images/`    |

The generated file is saved to the root of the `zyke_consumables` resource folder.

***

### FAQ

**Q: Do I need to register pack items in my inventory?** Yes. Each pack-enabled item needs a `pack_<itemName>` entry in your inventory resource.

**Q: What happens when a pack runs out of servings?** The pack is removed, from inventory if used from inventory, or from the world if used from a placed pack.

**Q: What prop is used for placing packs?** By default `v_serv_abox_02` (a small cardboard box). You can override it per-item via the `prop` field in the pack settings.

**Q: Can other players take from my placed pack?** Yes. Any player within range can interact with a placed pack to either use a serving or pick up the entire pack.

**Q: How do I change the spawn command?** Modify `Config.Settings.packs.spawnCommand`. It accepts an array, you can add multiple commands.