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:
equipSound
Type:
string
Description:
Sound played when equipping the item.
Example Usage:
unequipSound
Type:
string
Description:
Sound played when unequipping the item.
Example Usage:
useSound
Type:
string
Description:
Sound played when using the item.
Example Usage:
Restrictions & Whitelists
DropOnDeath
Type:
boolean
Description:
Deletes the item upon player death.
Example Usage:
noDrop
Type:
boolean
Description:
Prevents the item from being dropped or given to another player.
Example Usage:
FactionWhitelist
Type:
table
Description:
Allowed faction indices for vendor interaction.
Example Usage:
RequiredSkillLevels
Type:
table
Description:
Skill requirements needed to use the item.
Example Usage:
SteamIDWhitelist
Type:
table
Description:
Allowed Steam IDs for vendor interaction.
Example Usage:
UsergroupWhitelist
Type:
table
Description:
Allowed user groups for vendor interaction.
Example Usage:
VIPWhitelist
Type:
boolean
Description:
Restricts usage to VIP players.
Example Usage:
Inventory & Stacking
isBag
Type:
boolean
Description:
Marks the item as a bag providing extra inventory.
Example Usage:
invWidth
Type:
number
Description:
Internal bag inventory width.
Example Usage:
invHeight
Type:
number
Description:
Internal bag inventory height.
Example Usage:
width
Type:
number
Description:
Width in the external inventory grid.
Example Usage:
height
Type:
number
Description:
Height in the external inventory grid.
Example Usage:
canSplit
Type:
boolean
Description:
Whether the item stack can be divided.
Example Usage:
isStackable
Type:
boolean
Description:
Allows stacking multiple quantities.
Example Usage:
maxQuantity
Type:
number
Description:
Maximum stack size.
Example Usage:
quantity
Type:
number
Description:
Current amount in the item stack.
Example Usage:
Categorization & Metadata
base
Type:
string
Description:
Base item this item derives from.
Example Usage:
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:
category
Type:
string
Description:
Inventory grouping category.
Example Usage:
name
Type:
string
Description:
Displayed name of the item.
Example Usage:
desc
Type:
string
Description:
Short description shown to players.
Example Usage:
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:
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:
Equipment & Stats
armor
Type:
number
Description:
Armor value granted when equipped.
Example Usage:
health
Type:
number
Description:
Amount of health restored when used.
Example Usage:
attribBoosts
Type:
table
Description:
Attribute boosts applied on equip.
Example Usage:
isOutfit
Type:
boolean
Description:
Marks the item as an outfit.
Example Usage:
newSkin
Type:
number
Description:
Skin index applied to the player model.
Example Usage:
outfitCategory
Type:
string
Description:
Slot or category for the outfit.
Example Usage:
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:
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:
ammo
Type:
string
Description:
Ammo type provided.
Example Usage:
weaponCategory
Type:
string
Description:
Slot category for the weapon.
Example Usage:
Visuals & Models
model
Type:
string
Description:
3D model path for the item.
Example Usage:
iconCam
Type:
table
Description:
Custom camera parameters used when rendering the item's spawn icon. Contains pos
, ang
, and fov
keys.
Example Usage:
forceRender
Type:
boolean
Description:
When true
, forces the spawn icon to regenerate even if an icon for the model already exists.
Example Usage:
Entity & Content
entityid
Type:
string
Description:
Entity class spawned by the item.
Example Usage:
contents
Type:
string
Description:
HTML contents of a readable book.
Example Usage:
Economic & Pricing
price
Type:
number
Description:
Item cost for trading or selling.
Example Usage:
flag
Type:
string
Description:
Flag required to purchase the item.
Example Usage:
rarity
Type:
string
Description:
Rarity level affecting vendor color.
Example Usage:
url
Type:
string
Description:
Web address opened when using the item.
Example Usage:
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:
hooks
Type:
table
Description:
Callbacks triggered on specific item events. Use ITEM:hook("event", func)
to attach them.
Example Usage:
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 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