Skip to content

Item Fields

This document describes all configurable ITEM fields in the codebase. Use these to customize item behavior, appearance, interactions, and metadata.

Unspecified fields will use sensible defaults.


Overview

The global ITEM table defines per-item settings such as sounds, inventory dimensions, restrictions, stats, and hooks. Unspecified fields will use sensible defaults.


Field Summary

Field Type Default Description
BagSound table nil Sound played when moving items to/from the bag.
DropOnDeath boolean false Deletes the item upon player death.
noDrop boolean false Prevents dropping or giving the item.
FactionWhitelist table nil Allowed faction indices for vendor interaction.
RequiredSkillLevels table nil Skill requirements needed to use the item.
SteamIDWhitelist table nil Allowed Steam IDs for vendor interaction.
UsergroupWhitelist table nil Allowed user groups for vendor interaction.
VIPWhitelist boolean false Restricts usage to VIP players.
ammo string "" Ammo type provided.
armor number 0 Armor value granted when equipped.
attribBoosts table {} Attribute boosts applied when equipped.
base string "" Base item this item derives from.
canSplit boolean true Whether the item stack can be divided.
category string "Miscellaneous" Inventory grouping category.
class string "" Weapon entity class.
contents string "" HTML contents of a readable book.
desc string "No Description" Short description shown to players.
entityid string "" Entity class spawned by the item.
equipSound string "" Sound played when equipping.
useSound string "" Sound played when using the item.
flag string "" Flag required to purchase the item.
forceRender boolean false Always regenerate the spawn icon.
functions table DefaultFunctions Table of interaction functions.
health number 0 Amount of health restored when used.
height number 1 Height in inventory grid.
id any 0 Database identifier.
iconCam table nil Custom spawn icon camera settings.
invHeight number 0 Internal bag inventory height.
invWidth number 0 Internal bag inventory width.
isBag boolean false Marks the item as a bag providing extra inventory.
isBase boolean false Indicates the table is a base item.
isOutfit boolean false Marks the item as an outfit.
isStackable boolean false Allows stacking multiple quantities.
isWeapon boolean false Marks the item as a weapon.
maxQuantity number 1 Maximum stack size.
model string "" 3D model path for the item.
name string "INVALID NAME" Displayed name of the item.
newSkin number 0 Skin index applied to the player model.
outfitCategory string "" Slot or category for the outfit.
pacData table {} PAC3 customization information.
bodyGroups table nil Bodygroup values applied when equipped.
hooks table {} Table of hook callbacks.
postHooks table {} Table of post-hook callbacks.
price number 0 Item cost for trading or selling.
quantity number 1 Current amount in the item stack.
rarity string "" Rarity level affecting vendor color.
replacements string "" Model replacements when equipped.
unequipSound string "" Sound played when unequipping.
uniqueID string "undefined" Overrides the automatically generated unique identifier.
url string "" Web address opened when using the item.
weaponCategory string "" Slot category for the weapon.
width number 1 Width in inventory grid.

Field Details

Audio & Interaction

BagSound

Type:

table

Description:

Sound played when moving items to/from the bag; specified as {path, volume}.

Example Usage:

ITEM.BagSound = {"physics/cardboard/cardboard_box_impact_soft2.wav", 50}

equipSound

Type:

string

Description:

Sound played when equipping the item.

Example Usage:

ITEM.equipSound = "items/ammo_pickup.wav"

unequipSound

Type:

string

Description:

Sound played when unequipping the item.

Example Usage:

ITEM.unequipSound = "items/ammo_pickup.wav"

useSound

Type:

string

Description:

Sound played when using the item.

Example Usage:

ITEM.useSound = "items/ammo_pickup.wav"

Restrictions & Whitelists

DropOnDeath

Type:

boolean

Description:

Deletes the item upon player death.

Example Usage:

ITEM.DropOnDeath = true

noDrop

Type:

boolean

Description:

Prevents the item from being dropped or given to another player.

Example Usage:

ITEM.noDrop = true

FactionWhitelist

Type:

table

Description:

Allowed faction indices for vendor interaction.

Example Usage:

ITEM.FactionWhitelist = {FACTION_CITIZEN}

RequiredSkillLevels

Type:

table

Description:

Skill requirements needed to use the item.

Example Usage:

ITEM.RequiredSkillLevels = {Strength = 5}

SteamIDWhitelist

Type:

table

Description:

Allowed Steam IDs for vendor interaction.

Example Usage:

ITEM.SteamIDWhitelist = {"STEAM_0:1:123"}

UsergroupWhitelist

Type:

table

Description:

Allowed user groups for vendor interaction.

Example Usage:

ITEM.UsergroupWhitelist = {"admin"}

VIPWhitelist

Type:

boolean

Description:

Restricts usage to VIP players.

Example Usage:

ITEM.VIPWhitelist = true

Inventory & Stacking

isBag

Type:

boolean

Description:

Marks the item as a bag providing extra inventory.

Example Usage:

ITEM.isBag = true

invWidth

Type:

number

Description:

Internal bag inventory width.

Example Usage:

ITEM.invWidth = 2

invHeight

Type:

number

Description:

Internal bag inventory height.

Example Usage:

ITEM.invHeight = 2

width

Type:

number

Description:

Width in the external inventory grid.

Example Usage:

ITEM.width = 2

height

Type:

number

Description:

Height in the external inventory grid.

Example Usage:

ITEM.height = 1

canSplit

Type:

boolean

Description:

Whether the item stack can be divided.

Example Usage:

ITEM.canSplit = true

isStackable

Type:

boolean

Description:

Allows stacking multiple quantities.

Example Usage:

ITEM.isStackable = false

maxQuantity

Type:

number

Description:

Maximum stack size.

Example Usage:

ITEM.maxQuantity = 10

quantity

Type:

number

Description:

Current amount in the item stack.

Example Usage:

print(item:getQuantity())

Categorization & Metadata

base

Type:

string

Description:

Base item this item derives from.

Example Usage:

ITEM.base = "base_weapons"

When loading items from a folder such as items/weapons/, the framework

automatically sets ITEM.base to match that folder (e.g. base_weapons).

Ideally you should organize item files under directories named after the base

they inherit from so this assignment happens automatically.


isBase

Type:

boolean

Description:

Indicates the table is a base item.

Example Usage:

ITEM.isBase = true

category

Type:

string

Description:

Inventory grouping category.

Example Usage:

ITEM.category = "Storage"

name

Type:

string

Description:

Displayed name of the item.

Example Usage:

ITEM.name = "Example Item"

desc

Type:

string

Description:

Short description shown to players.

Example Usage:

ITEM.desc = "An example item"

uniqueID

Type:

string

Description:

String identifier used to register the item. When omitted it is derived

from the file path, but you may override it to provide a custom ID.

Example Usage:

ITEM.uniqueID = "custom_unique_id"

id

Type:

any

Description:

Unique numeric identifier assigned by the inventory system. Instances

use this to reference the item in the database and it should not be

manually set.

Example Usage:

print(item.id)

Equipment & Stats

armor

Type:

number

Description:

Armor value granted when equipped.

Example Usage:

ITEM.armor = 50

health

Type:

number

Description:

Amount of health restored when used.

Example Usage:

ITEM.health = 50

attribBoosts

Type:

table

Description:

Attribute boosts applied on equip.

Example Usage:

ITEM.attribBoosts = {strength = 5}

isOutfit

Type:

boolean

Description:

Marks the item as an outfit.

Example Usage:

ITEM.isOutfit = true

newSkin

Type:

number

Description:

Skin index applied to the player model.

Example Usage:

ITEM.newSkin = 1

outfitCategory

Type:

string

Description:

Slot or category for the outfit.

Example Usage:

ITEM.outfitCategory = "body"

pacData

Type:

table

Description:

PAC3 customization information.

Example Usage:

-- This attaches an HGIBS gib model to the player’s eyes bone
ITEM.pacData = {
    [1] = {
        ["children"] = {
            [1] = {
                ["children"] = {
                },
                ["self"] = {
                    ["Angles"] = Angle(12.919322967529, 6.5696062847564e-006, -1.0949343050015e-005),
                    ["Position"] = Vector(-2.099609375, 0.019973754882813, 1.0180969238281),
                    ["UniqueID"] = "4249811628",
                    ["Size"] = 1.25,
                    ["Bone"] = "eyes",
                    ["Model"] = "models/Gibs/HGIBS.mdl",
                    ["ClassName"] = "model",
                },
            },
        },
        ["self"] = {
            ["ClassName"] = "group",
            ["UniqueID"] = "907159817",
            ["EditorExpand"] = true,
        },
    },
}

bodyGroups

Type:

table

Description:

Bodygroup values applied when the outfit is equipped.

Example Usage:

ITEM.bodyGroups = { head = 1, torso = 2 }

replacements

Type:

string

Description:

Model replacements when equipped.

Example Usage:

-- This will change a certain part of the model.
ITEM.replacements = {"group01", "group02"}
-- This will change the player's model completely.
ITEM.replacements = "models/manhack.mdl"
-- This will have multiple replacements.
ITEM.replacements = {
    {"male", "female"},
    {"group01", "group02"}
}```

---

### Combat & Ammo

#### `class`

**Type:**

`string`

**Description:**

Weapon entity class. Also used by grenade items to determine the weapon entity spawned.

**Example Usage:**

```lua

ITEM.class = "weapon_pistol"

isWeapon

Type:

boolean

Description:

Marks the item as a weapon.

Example Usage:

ITEM.isWeapon = true

ammo

Type:

string

Description:

Ammo type provided.

Example Usage:

ITEM.ammo = "pistol"

weaponCategory

Type:

string

Description:

Slot category for the weapon.

Example Usage:

ITEM.weaponCategory = "sidearm"

Visuals & Models

model

Type:

string

Description:

3D model path for the item.

Example Usage:

ITEM.model = "models/props_c17/oildrum001.mdl"

iconCam

Type:

table

Description:

Custom camera parameters used when rendering the item's spawn icon. Contains pos, ang, and fov keys.

Example Usage:

ITEM.iconCam = {

    pos = Vector(0, 0, 32),

    ang = Angle(0, 180, 0),

    fov = 45

}

forceRender

Type:

boolean

Description:

When true, forces the spawn icon to regenerate even if an icon for the model already exists.

Example Usage:

ITEM.forceRender = true

Entity & Content

entityid

Type:

string

Description:

Entity class spawned by the item.

Example Usage:

ITEM.entityid = "item_suit"

contents

Type:

string

Description:

HTML contents of a readable book.

Example Usage:

ITEM.contents = "<h1>Book</h1>"

Economic & Pricing

price

Type:

number

Description:

Item cost for trading or selling.

Example Usage:

ITEM.price = 100

flag

Type:

string

Description:

Flag required to purchase the item.

Example Usage:

ITEM.flag = "Y"

rarity

Type:

string

Description:

Rarity level affecting vendor color.

Example Usage:

ITEM.rarity = "Legendary"

url

Type:

string

Description:

Web address opened when using the item.

Example Usage:

ITEM.url = "https://example.com"

Behavior & Hooks

functions

Type:

table

Description:

Table mapping action names to definitions. Each function entry controls button text, icons and behavior when the action is triggered.

The name and tip fields for each action are automatically passed through the L() localization helper when an item is registered. Provide translation keys instead of raw strings.

Example Usage:

ITEM.functions = {}

hooks

Type:

table

Description:

Callbacks triggered on specific item events. Use ITEM:hook("event", func) to attach them.

Example Usage:

ITEM:hook("drop", function(itm)

    print(itm.name .. " was dropped")

end)

postHooks

Type:

table

Description:

Table of post-hook callbacks.

Example Usage:

-- Defined in base_weapons

function ITEM.postHooks:drop(result)

    local ply = self.player

    if ply:HasWeapon(self.class) then

        ply:StripWeapon(self.class)

    end

end

Additional post hooks can be registered dynamically using ITEM:postHook:

ITEM:postHook("drop", function(itm, res)

    print("Post drop result: " .. tostring(res))

end)

Item Type Examples

Minimal definitions for each built-in item type are shown below.

Weapon

ITEM.name = "Sub Machine Gun"

ITEM.model = "models/weapons/w_smg1.mdl"

ITEM.class = "weapon_smg1"

ITEM.weaponCategory = "primary"

ITEM.isWeapon = true

Ammo

ITEM.name = "Pistol Ammo"

ITEM.model = "models/items/357ammo.mdl"

ITEM.ammo = "pistol"

ITEM.maxQuantity = 30

Outfit

ITEM.name = "Combine Armor"

ITEM.model = "models/props_c17/BriefCase001a.mdl"

ITEM.outfitCategory = "body"

ITEM.replacements = "models/player/combine_soldier.mdl"

ITEM.newSkin = 1

PAC Outfit

ITEM.name = "Skull Mask"

ITEM.outfitCategory = "hat"

ITEM.pacData = { ... }

Aid Item

ITEM.name = "Bandages"

ITEM.model = "models/weapons/w_package.mdl"

ITEM.health = 50

Book

ITEM.name = "Example"

ITEM.contents = "<h1>An Example</h1>"

URL Item

ITEM.name = "Hi Barbie"

ITEM.url = "https://www.youtube.com/watch?v=9ezbBugUQiQ"

Entity Spawner

ITEM.name = "Item Suit"

ITEM.entityid = "item_suit"

Grenade

ITEM.name = "Grenade"

ITEM.class = "weapon_frag"

ITEM.DropOnDeath = true

Bag

ITEM.name = "Small Bag"

ITEM.isBag = true

ITEM.invWidth = 2

ITEM.invHeight = 2

ITEM.BagSound = {"physics/cardboard/cardboard_box_impact_soft2.wav", 50}