Creating a Custom Item Behavior

Item behaviors allow you to create completely custom interaction logic for items registered in Config.Items.

A behavior can define available controls, spawned objects, placement support, placed-object actions, primary interactions, custom actions, and cancellation logic.

Behavior files are located in: shared/behaviors/

After creating a behavior, register it using RegisterBehavior and assign its name to the item’s behavior option.

---

1. Create the Behavior

local CustomBehavior = {}

A behavior is a Lua table containing the methods used by VMS Needs during the item interaction lifecycle.

Method	Required	Purpose
GetControls	No	Defines the available interaction controls and item description.
PrimaryAction	No	Handles the primary use action.
HandleAction	No	Handles additional named controls.
GetObjects	No	Defines which objects should be spawned and attached.
CanPlace	No	Determines whether the item can currently be placed.
PlacedActions	No	Adds actions to an item after it has been placed.
CancelAction	No	Defines what happens when the player cancels item usage.

Only implement the methods required by your custom interaction.

2. GetControls

function CustomBehavior:GetControls()
    local controls = {
        {
            key = 'E',
            label = 'Primary Action',
            name = 'use',
        },
        {
            key = 'G',
            label = 'Custom Action',
            name = 'example_control',
        },
    }

    local description = 'Example description'

    return controls, description
end

Returned values

Value	Description
controls	List of controls available for the current item.
description	Optional text displayed alongside the controls.

Control fields

Field	Description
key	Keyboard key displayed and listened for by the controls system.
label	Text displayed to the player. Use TRANSLATE(...) for localized labels.
name	Internal action identifier passed to the behavior.

The action named use calls PrimaryAction. Other action names are passed to HandleAction.

3. PrimaryAction

PrimaryAction is called when the player activates the control with the action name use.

function CustomBehavior:PrimaryAction()
    print('Player used the primary action')
end

For consumable items, you can call the internal ConsumeItem function to use the configured animations and status changes.

function CustomBehavior:PrimaryAction()
    ConsumeItem(function(action)
        if action == 'started' then
            print('Consumption started')
        elseif action == 'finished' then
            print('Consumption finished')
        end
    end)
end

4. HandleAction

HandleAction receives all named controls other than the primary use action.

function CustomBehavior:HandleAction(action)
    if action == 'example_control' then
        print('Player used the custom action')
    end
end

The action value matches the name configured in GetControls.

5. GetObjects

GetObjects defines the objects spawned while the item is being used.

function CustomBehavior:GetObjects(data)
    local item = Config.Items[data.name]

    return {
        {
            model = item.models.default,
            attach = item.attaches.hand,
        },
    }
end

Parameters

Field	Description
data.name	Current item name.
data.metadata	Current item metadata.
data.visualState	Optional visual state requested by the behavior.

Returned object fields

Field	Description
model	Model name or hash to spawn.
attach	Attachment configuration used for the object.

Advanced Example - Dynamic Model

function CustomBehavior:GetObjects(data)
    local item = Config.Items[data.name]
    local visualState = data.visualState or 'hand'

    local model

    if data.metadata.isLit then
        model = Object.GetVisualModel(
            item.models.joint.lit,
            data.metadata.value,
            item.size
        )
    else
        model = item.models.joint.unlit
    end

    return {
        {
            model = model,
            attach = item.attaches[visualState],
        },
    }
end

This example changes the model according to item metadata and remaining item size.

6. CanPlace

CanPlace determines whether the currently used item can be placed in the world.

function CustomBehavior:CanPlace()
    return true
end

Return true to allow placement or false to prevent it.

7. PlacedActions

PlacedActions defines the interactions available after the item has been placed in the world.

function CustomBehavior:PlacedActions(item)
    return {
        allowDefault = {
            take = false,
            pour = false,
        },

        options = {
            {
                name = 'custom_action',
                icon = 'fa-solid fa-xmark',
                label = 'sweep_away',
                actionControl = 'H',
                distance = 2.0,

                action = function()
                    print('Player used the placed-item action')
                end,

                canInteract = function()
                    return not currentItem.name
                end,
            },
        },
    }
end

allowDefault

Field	Description
take	Enables the built-in action for picking up the placed item.
pour	Enables the built-in pouring action when supported.

Custom option fields

Field	Description
name	Unique action identifier.
icon	Target-system icon.
label	Translation suffix used by the target and 3D Text modules.
actionControl	Key used for the 3D Text interaction.
distance	Maximum interaction distance.
action	Function executed after selecting the action.
canInteract	Optional function determining whether the action is currently available.

For label = 'sweep_away', the system uses target.sweep_away or 3dtext.sweep_away, depending on the active interaction system.

8. PackClientMetadata

PackClientMetadata allows a behavior to send only the metadata required on the client after a placed item is synchronized.

By default, VMS Needs does not send the complete metadata of placed items to clients in order to minimize the amount of data transferred during the initial synchronization. If your behavior requires specific metadata on the client (for example, to determine available interactions in PlacedActions), return only the required values from this function.

function CustomBehavior:PackClientMetadata(metadata)
    if metadata and metadata.isLine then
        return {
            isLine = true
        }
    end

    return nil
end

Return a table containing only the metadata required by the client, or nil if no metadata needs to be synchronized.

9. CancelAction

CancelAction defines what happens when the player closes or cancels the current item interaction.

function CustomBehavior:CancelAction()
    print('Player canceled item usage')

    CancelUsage()
end

CancelUsage() hides or returns the item according to its current state and configured item behavior.

function CustomBehavior:CancelAction()
    ThrowItem()
end

Use ThrowItem() when the item should be discarded instead of returned to the inventory.

10. Register the Behavior

RegisterBehavior('custom_behavior', CustomBehavior)

The registration name must match the behavior option configured for the item.

['my_item'] = {
    behavior = 'custom_behavior',

    -- Other item configuration...
}

11. Complete Example

local CustomBehavior = {}

function CustomBehavior:GetControls()
    return {
        {
            key = 'E',
            label = 'Use',
            name = 'use',
        },
        {
            key = 'G',
            label = 'Custom Action',
            name = 'custom_action',
        },
        {
            key = Config.Controls.MAIN.CANCEL,
            label = 'Put Away',
            name = 'cancel',
        },
    }, 'Custom item'
end

function CustomBehavior:GetObjects(data)
    local item = Config.Items[data.name]

    return {
        {
            model = item.models.default,
            attach = item.attaches.hand,
        },
    }
end

function CustomBehavior:PrimaryAction()
    print('Primary action used')
end

function CustomBehavior:HandleAction(action)
    if action == 'custom_action' then
        print('Custom action used')
    end
end

function CustomBehavior:CanPlace()
    return true
end

function CustomBehavior:CancelAction()
    CancelUsage()
end

RegisterBehavior('custom_behavior', CustomBehavior)

Behavior-specific configuration

A custom behavior decides which entries are required inside models, attaches, animation, and particles. When creating a new behavior, you are responsible for reading and using those configuration entries inside the behavior file.

We recommend copying the built-in behavior closest to your intended interaction and using it as a starting point.