Item

Interactable entities that can be held in inventories.

Items are objects that are contained inside of an Inventory, or as standalone entities if they are dropped in the world. They usually have functionality that provides more gameplay aspects to the schema. For example, the zipties in the HL2 RP schema allow a player to tie up and search a player.

For an item to have an actual presence, they need to be instanced (usually with ix.item.Instance). Items describe the properties, while instances are a clone of these properties that can have their own unique data (e.g an ID card will have the same name but different numerical IDs). You can think of items as the class, while instances are objects of the Item class.

Creating item classes (ItemStructure)

Item classes are defined in their own file inside of your schema or plugin's items/ folder. In these item class files you specify how instances of the item behave. This includes default values for basic things like the item's name and description, to more advanced things by overriding extra methods from an item base. See ItemStructure for information on how to define a basic item class.

Item classes in this folder are automatically loaded by Helix when the server starts up.

Item bases

If many items share the same functionality (i.e a can of soda and a bottle of water can both be consumed), then you might want to consider using an item base to reduce the amount of duplication for these items. Item bases are defined the same way as regular item classes, but they are placed in the items/base/ folder in your schema or plugin. For example, a consumables base would be in items/base/sh_consumables.lua.

Any items that you want to use this base must be placed in a subfolder that has the name of the base you want that item to use. For example, for a bottled water item to use the consumable base, it must be placed in items/consumables/sh_bottled_water.lua. This also means that you cannot place items into subfolders as you wish, since the framework will try to use an item base that doesn't exist.

The default item bases that come with Helix are:

  • ammo - provides ammo to any items with the weapons base
  • bags - holds an inventory that other items can be stored inside of
  • outfit - changes the appearance of the player that wears it
  • pacoutfit - changes the appearance of the player that wears it using PAC3
  • weapons - makes any SWEP into an item that can be equipped

These item bases usually come with extra values and methods that you can define/override in order to change their functionality. You should take a look at the source code for these bases to see their capabilities.

Item functions (ItemFunctionStructure)

Requiring players to interact with items in order for them to do something is quite common. As such, there is already a built-in mechanism to allow players to right-click items and show a list of available options. Item functions are defined in your item class file in the ITEM.functions table. See ItemFunctionStructure on how to define them.

Helix comes with drop, take, and combine item functions by default that allows items to be dropped from a player's inventory, picked up from the world, and combining items together. These can be overridden by defining an item function in your item class file with the same name. See the bags base for example usage of the combine item function.

Item icons (ItemIconStructure)

Icons for items sometimes don't line up quite right, in which case you can modify an item's iconCam value and line up the rendered model as needed. See ItemIconStructure for more details.

Functions

Item:Call(method, client, entity, ...)

 View source »

Calls one of the item's methods.

Parameters

  • method string

    The method to be called

  • client Player

    The client to pass when calling the method, if applicable

  • entity Entity

    The eneity to pass when calling the method, if applicable

  • ...

    Arguments to pass to the method

Returns

  • any

    The values returned by the method

Item:GetCharacterID()

 View source »

Returns the ID of the owning character, if one exists.

Returns

  • number

    The owning character's ID

Item:GetData(key, default)

 View source »

Returns the value stored on a key within the item's data.

Parameters

  • key string

    The key in which the value is stored

  • default default: nil

    The value to return in case there is no value stored in the key

Returns

  • any

    The value stored within the key

Item:GetDescription()

 View source »

Returns the description of the item.

Returns

  • string

    The description of the item

Item:GetEntity()

 View source »

Returns the item's entity.

Returns

  • entity

    The entity of the item

Item:GetID()

 View source »

Returns this item's database ID. This is guaranteed to be unique.

Returns

  • number

    Unique ID of item

Item:GetModel()

 View source »

Returns the model of the item.

Returns

  • string

    The model of the item

Item:GetName()

 View source »

Returns the name of the item.

Returns

Item:GetOwner()

 View source »

Returns the player that owns this item.

Returns

  • player

    Player owning this item

Item:GetPlayerID()

 View source »

Returns the SteamID64 of the owning player, if one exists.

Returns

  • number

    The owning player's SteamID64

Item:GetSkin()

 View source »

Returns the skin of the item.

Returns

  • number

    The skin of the item

Item:Hook(name, func)

 View source »

Changes the function called on specific events for the item.

Parameters

  • name string

    The name of the hook

  • func function

    The function to call once the event occurs

Item:PostHook(name, func)

 View source »

Changes the function called after hooks for specific events for the item.

Parameters

  • name string

    The name of the hook

  • func function

    The function to call after the original hook was called

Item:Print(detail)

 View source »

A utility function which prints the item's details.

Parameters

  • detail boolean default: false

    Whether additional detail should be printed or not(Owner, X position, Y position)

Item:PrintData()

 View source »

A utility function printing the item's stored data.

Item:Remove(bNoReplication, bNoDelete)

 View source »

Removes the item.

Parameters

  • bNoReplication boolean

    Whether or not the item's removal should not be replicated.

  • bNoDelete boolean

    Whether or not the item should not be fully deleted

Returns

  • bool

    Whether the item was successfully deleted or not

Item:SetData(key, value, receivers, noSave, noCheckEntity)

 View source »

Sets a key within the item's data.

Parameters

  • key string

    The key to store the value within

  • value default: nil

    The value to store within the key

  • receivers table default: nil

    The players to replicate the data on

  • noSave boolean default: false

    Whether to disable saving the data on the database or not

  • noCheckEntity boolean default: false

    Whether to disable setting the data on the entity, if applicable

Item:Spawn(position, angles)

 View source »

Spawn an item entity based off the item table.

Parameters

  • position vector

    The position in which the item's entity will be spawned

  • angles angle

    The angles at which the item's entity will spawn

Returns

  • entity

    The spawned entity

Item:Transfer(invID, x, y, client, noReplication, isLogical)

 View source »

Transfers an item to a specific inventory.

Parameters

  • invID number

    The inventory to transfer the item to

  • x number

    The X position to which the item should be transferred on the new inventory

  • y number

    The Y position to which the item should be transferred on the new inventory

  • client Player

    The player to which the item is being transferred

  • noReplication boolean

    Whether there should be no replication of the transferral

  • isLogical boolean

    Whether or not an entity should spawn if the item is transferred to the world

Returns

  • bool

    Whether the transfer was successful or not

  • string

    The error, if applicable

Item:__eq(other)

 View source »

Returns true if this item is equal to another item. Internally, this checks item IDs.

Parameters

  • other Item

    Item to compare to

Returns

  • bool

    Whether or not this item is equal to the given item

Example Usage

print(ix.item.instances[1] == ix.item.instances[2])
 > false

Item:__tostring()

 View source »

Returns a string representation of this item.

Returns

  • string

    String representation

Example Usage

print(ix.item.instances[1])
 > "item[1]"

Tables

ItemFunctionStructure

 View source »

All item functions live inside of an item's functions table. An item function entry includes a few methods and fields you can use to customize the functionality and appearance of the item function. An example item function is below:

-- this item function's unique ID is "MyFunction"
ITEM.functions.MyFunction = {
    name = "myFunctionPhrase", -- uses the "myFunctionPhrase" language phrase when displaying in the UI
    tip = "myFunctionDescription", -- uses the "myFunctionDescription" language phrase when displaying in the UI
    icon = "icon16/add.png", -- path to the icon material
    OnRun = function(item)
        local client = item.player
        local entity = item.entity -- only set if this is function is being ran while the item is in the world

        if (IsValid(client)) then
            client:ChatPrint("This is a test.")

            if (IsValid(entity)) then
                client:ChatPrint(entity:GetName())
            end
        end

        -- do not remove this item from the owning player's inventory
        return false
    end,
    OnCanRun = function(item)
        -- only allow admins to run this item function
        local client = item.player
        return IsValid(client) and client:IsAdmin()
    end
}

Fields

  • name string optional

    Language phrase to use when displaying this item function's name in the UI. If not specified, then it will use the unique ID of the item function

  • tip string optional

    Language phrase to use when displaying this item function's detailed description in the UI

  • icon string optional

    Path to the material to use when displaying this item function's icon

  • OnRun function

    Function to call when the item function is ran. This function is ONLY ran on the server.

    The only argument passed into this function is the instance of the item being called. The instance will have its player field set if the item function is being ran by a player (which it should be most of the time). It will also have its entity field set if the item function is being ran while the item is in the world, and not in a player's inventory.

    The item will be removed after the item function is ran. If you want to prevent this behaviour, then you can return false in this function. See the example above.

  • OnCanRun function

    Function to call when checking whether or not this item function can be ran. This function is ran BOTH on the client and server.

    The arguments are the same as OnCanRun, and the player and entity fields will be set on the item instance accordingly. Returning true will allow the item function to be ran. Returning false will prevent it from running and additionally hide it from the UI. See the example above.

  • OnClick function optional

    This function is called when the player clicks on this item function's entry in the UI. This function is ran ONLY on the client, and is only ran if OnCanRun succeeds.

    The same arguments from OnCanRun and OnRun apply to this function.

ItemIconStructure

 View source »

Changing the way an item's icon is rendered is done by modifying the location and angle of the model, as well as the FOV of the camera. You can tweak the values in code, or use the ix_dev_icon console command to visually position the model and camera. An example entry for an item's icon is below:

ITEM.iconCam = {
    pos = Vector(0, 0, 60),
    ang = Angle(90, 0, 0),
    fov = 45
}

Note that this will probably not work for your item's specific model, since every model has a different size, origin, etc. All item icons need to be tweaked individually.

Fields

  • pos vector

    Location of the model relative to the camera. +X is forward, +Z is up

  • ang angle

    Angle of the model

  • fov number

    FOV of the camera

ItemStructure

 View source »

When creating an item class, the file will have a global table ITEM set that you use to define the item's values/methods. An example item class is below:

items/sh_brick.lua

ITEM.name = "Brick"
ITEM.description = "A brick. Pretty self-explanatory. You can eat it but you'll probably lose some teeth."
ITEM.model = Model("models/props_debris/concrete_cynderblock001.mdl")
ITEM.width = 1
ITEM.height = 1
ITEM.price = 25

Note that the below list only includes the default fields available for all items, and not special ones defined in custom item bases.

Fields

  • name string

    Display name of the item

  • description string

    Detailed description of the item

  • model string

    Model to use for the item's icon and when it's dropped in the world

  • width number default: 1

    Width of the item in grid cells

  • height number default: 1

    Height of the item in grid cells

  • price number default: 0

    How much money it costs to purchase this item in the business menu

  • category string optional

    Name of the category this item belongs to - mainly used for the business menu

  • noBusiness boolean default: false

    Whether or not to disallow purchasing this item in the business menu

  • factions table optional

    List of factions allowed to purchase this item in the business menu

  • classes table optional

    List of character classes allowed to purchase this item in the business menu. Classes are checked after factions, so the character must also be in an allowed faction

  • flag string optional

    List of flags (as a string - e.g "a" or "abc") allowed to purchase this item in the business menu. Flags are checked last, so the character must also be in an allowed faction and class

  • functions table optional

    List of all item functions that this item has. See ItemFunctionStructure on how to define new item functions