Packs

All information you would need regarding 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

• Enabling Packs on an Item

• Registering Pack Items in Your Inventory

• Spawning a Pack (Command)

• Spawning a Pack (Export)

• Packs in Shops

• Placing Packs on the Ground

• Interacting with Placed Packs

• Showcase Display Modes

• Configuration Reference

• Pack Item Settings Reference

• Generating Pack Items Automatically

• 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

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

qb-core

["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:

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:

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.

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.