item library

Records the entity an item instance has been spawned as.

Parameters

• entity Entity The item entity
• itemTable Item The item instance

Creates a new instance of an item with a copy of another instance's data.

Parameters

• itemTable Item The instance to copy

Returns

• Item The new instance

Creates an instance of an item, or returns the existing instance with that item ID.

The instance is a copy of the definition stored in item.GetInstances. Data and custom fields are merged into it, and its OnInstantiated callback is called. Instances only exist in the realm they are created in; give them to players to network them.

When the item ID already belongs to an instance of another item, the server gives the new instance an ID of its own, so check the returned instance's itemID; the client replaces its instance, as the server decides which item an ID stands for.

local itemTable = item.CreateInstance('ration', nil, { Opened = true })

Parameters

• uniqueID Any Unique ID, index or name of the item, as accepted by item.FindByID
• itemID Number optional, defaults to nil Item ID of the instance; a new one is generated when nil
• data Map optional, defaults to nil Data fields to merge into the instance's data
• customData Map optional, defaults to nil Fields to merge into the instance itself

Returns

• Item The instance, or nil when the item does not exist

Makes a player destroy an item from their inventory.

Calls the item's OnDestroy (return false to cancel), takes the item, plays the destroySound and fires PlayerDestroyItem.

Parameters

• player Player The player destroying the item
• itemTable Item The item instance
• bNoSound Boolean optional, defaults to nil Do not play the destroy sound

Returns

• Boolean true when destroyed, false when cancelled, nil when the item cannot be destroyed

Makes a player drop an item, spawning it as an entity.

Calls the item's OnDrop (return false to cancel), takes the item and creates the entity with OnCreateDropEntity or cw.entity:CreateItem. When no position is given, the item is dropped where the player is looking, flush to the ground. Plays the dropSound and fires PlayerDropItem.

Parameters

• player Player The player dropping the item
• itemTable Item The item instance
• position Vector optional, defaults to nil Where to drop the item
• bNoSound Boolean optional, defaults to nil Do not play the drop sound
• bNoTake Boolean optional, defaults to nil Do not require or take the item from the player's inventory

Returns

• Boolean true when dropped, false when OnDrop cancelled it, nil when the item cannot be dropped

Finds an item definition by index, unique ID, weapon class or name.

When there is no exact match, the shortest item whose name contains the identifier (case insensitive, as plain text) is returned, falling back to a match on PrintName.

local itemTable = item.FindByID('ration')

Parameters

• identifier Any The index (Number), unique ID, weapon class or part of the name (String)
• bShouldValidate Boolean optional, defaults to nil Return a merged copy of the definition, as item.Validate does

Returns

• Item The item definition, or nil when none matches

Returns the entity an item instance has been spawned as.

Parameters

• itemTable Item The item instance

Returns

• Entity The item entity, or nil when it does not exist

Returns the item instance with an item ID.

Parameters

• itemID Number The item ID, or a string containing it

Returns

• Item The instance, or nil when it does not exist

Generates a new item ID from the current time and an increasing counter.

IDs of instances that already exist in this realm are skipped.

Returns

• Number The new item ID

Returns every registered item definition, indexed by unique ID.

Returns

• Map<Item> Item definitions indexed by unique ID

See also

• item.GetStored

Returns every registered item definition, indexed by its numeric index.

The index is the short CRC of the unique ID that items are networked by.

Returns

• Map<Item> Item definitions indexed by numeric index

Returns the item instance a weapon entity was created from.

The instance is found through the weapon's ItemID networked string.

Parameters

• weapon Weapon The weapon

Returns

• Item The item instance, or nil when the weapon is invalid or not from an item

Returns a minimal table describing an item instance, used to network it.

Parameters

• itemTable Item The instance
• bNetworkData Boolean optional, defaults to nil Include the values of the networked data fields

Returns

• Map The definition with itemID, index and data

Returns the model and skin to draw an item's icon with.

Uses iconModel/iconSkin, then model/skin, overridden by the item's GetClientSideModel/GetClientSideSkin, falling back to an oil drum model.

Parameters

• itemTable Item The item

Returns

• String The model path
• Number The skin

Returns every item instance that exists in this realm, indexed by item ID.

Returns

• Map<Item> Item instances indexed by item ID

Builds an item's markup tooltip with its name, weight, space, description and category.

The item's GetClientSideName, GetClientSideInfo and GetClientSideDescription override the defaults. The callback can change the shown values before the markup is built.

local toolTip = item.GetMarkupToolTip(itemTable, false, function(display)
  display.weight = 'Weightless'
end)

Parameters

• itemTable Item The item
• bBusinessStyle Boolean optional, defaults to nil Show the batch size and the price, coloured by whether the player can afford it
• Callback Function optional, defaults to nil Called with the display info Map (name, weight, space, toolTip and itemTitle, which replaces the title when set)

Returns

• String The markup text

Returns a table that identifies an item instance.

Parameters

• itemTable Item The instance

Returns

• Map A table with the item's uniqueID and itemID

Returns every registered item definition, indexed by unique ID.

Returns

• Map<Item> Item definitions indexed by unique ID

See also

• item.GetAll

Returns the weapon item definitions, indexed by weapon class.

Filled by item.Initialize with every item based on weapon_base, keyed by its weaponClass or, when it has none, its unique ID.

Returns

• Map<Item> Weapon item definitions indexed by weapon class

Returns whether an item's data equals the data stored on the item library table.

Declared with . on the library instead of as a CItem method, so it compares against item.data rather than another item.

Parameters

• itemTable Item The item to compare

Returns

• Boolean Whether the data tables are equal

Loads every item file in a directory.

Each file is run with a new item as ITEM, named after the file without its realm prefix, and registered afterwards.

Parameters

• directory String Lua path of the directory

Merges every item with its base, sets up weapon items and fires the item initialization hooks.

Items whose base item does not exist are removed. Calls each item's OnSetup, fires ClockworkItemInitialized for every item and ClockworkPostItemsInitialized once at the end.

Returns whether an item is based on weapon_base.

Parameters

• itemTable Item The item

Returns

• Boolean Whether the item is a weapon

Merges an item over a copy of its base item, resolving the base's own bases first.

Unless temporary, the result is registered in place of the item with baseClass set to the base.

Parameters

• itemTable Item The item definition
• baseItem String Unique ID of the base item
• bTemporary Boolean optional, defaults to nil Return the merged table without registering it

Returns

• Item The merged item, or nil when the base does not exist or is the item itself

Creates a new, unregistered item definition.

Item files get one as ITEM from item.IncludeItems; call it directly to build items in code and register them with CItem:Register.

local ITEM = item.New('gold_bar')
ITEM.name = 'Gold Bar'
ITEM.weight = 2
ITEM:Register()

Parameters

• uniqueID String Unique ID of the item

Returns

• Item The new item definition

Registers an item definition so it can be found and instantiated.

The unique ID is lowercased and stripped of ' and ., falling back to the name with spaces replaced by underscores. Sets index and PrintName, and on the server adds the item's models to the client downloads during the initial load.

Parameters

• itemTable Item The item definition

Forgets the item entity of an instance, called when the entity is removed.

Does nothing when the entity has no item, or when the instance has since been spawned as another entity.

Parameters

• entity Entity The item entity

Sends an item instance and its networked data to a player over the ItemData Cable message.

The client creates the instance without adding it to an inventory.

Parameters

• player Player The player to send to
• itemTable Item The item instance; nothing is sent when nil

Sends changed item data to the item's observers over the InvNetwork Cable message.

The observers are collected with the ItemGetNetworkObservers hook, which fills info.observers; returning true from it or setting info.sendToAll sends the update to every player.

Parameters

• itemTable Item The item instance
• data Map The changed data fields

Returns

• List<Player> The observers the update was sent to, or nil when sent to everyone

Makes a player use an item from their inventory.

Calls the item's OnUse: a nil return takes the item from the player, false cancels the use and any other value keeps the item. Plays the item's useSound and fires PlayerUseItem.

Parameters

• player Player The player using the item
• itemTable Item The item instance
• bNoSound Boolean optional, defaults to nil Do not play the use sound

Returns

• Boolean true when used, false when OnUse cancelled it, nil when the player does not have the item or it cannot be used

Restores the CItem metatable and methods on an item table, such as one received or copied.

Does nothing to tables that already have the methods.

Parameters

• itemTable Item The item table; anything that is not a table is ignored
• bShouldMerge Boolean optional, defaults to nil Return a copy of the registered definition with the table's fields merged into it

Returns

• Item The item table or the merged copy, or nil when itemTable is not a table