Home › Documentation › Custom · origen_inventory

Custom · origen_inventory

origen_inventory exposes three customization surfaces:

1. Hooks — listen to inventory events and modify payloads or cancel actions.
2. Custom Items — register, edit and remove items at runtime (persisted in origen_customitems).
3. World Points — register custom interactive points on the map.

config/
├── hooks.lua          -- Hook examples (server + client)
modules/
├── customItems.lua    -- AddCustomItem / EditCustomItem / RemoveCustomItem implementation
client/functions/
├── f_hooks.lua        -- registerHook / removeHooks (client-side)
└── f_worldpoint.lua   -- World point exports

Hooks

Hooks let external resources subscribe to inventory events and either inspect the payload, mutate it, or cancel the action. Both client and server expose the same export name: registerHook.

registerHook(event, callback, options?) → string (id)

Registers a callback for the named hook.

local hookId = exports.origen_inventory:registerHook('createItem', function(payload)
    -- payload is hook-specific
    return payload.metadata
end)

removeHooks(id) → void

Removes a previously registered hook by its id.

exports.origen_inventory:removeHooks(hookId)

Server-side hooks

createItem

Triggered when an item is being created (e.g. metadata initialization). Return the (potentially mutated) metadata table to apply changes.

Payload

Example — assign a unique bag id when creating a paperbag:

exports.origen_inventory:registerHook('createItem', function(payload)
    local metadata = payload.metadata
    local item = payload.item
 
    if item.name == 'paperbag' and not metadata.bagId then
        metadata.bagId = math.random(1000, 9999)
    end
 
    return metadata -- you MUST return the metadata table
end)

Client-side hooks

worldpoint-interact-in

Fires when the player enters the interaction range of a world point.

Payload

worldpoint-interact-out

Fires when the player leaves the interaction range of a world point. Same payload as above.

worldpoint-area-nearby

Fires when the player enters the wider zone (zoneDistance) around a stash or other point with a configured zone. Used to lazy-load expensive UI.

Example — log every stash entry:

exports.origen_inventory:registerHook('worldpoint-interact-in', function(payload)
    if payload.type ~= 'stash' then return end
    print(('Player entered stash %s at %s'):format(payload.id, payload.label))
end)

Custom Items

Custom items are persisted in the origen_customitems table and reloaded on resource start. All three operations are server-side.

AddCustomItem(data) → boolean

Adds a new custom item. Returns false if the item already exists.

exports.origen_inventory:AddCustomItem({
    name = 'origen_compass',
    label = 'Compass',
    weight = 200,
    type = 'item',
    image = 'origen_compass.png',
    description = 'Always points to the next adventure.',
    rarity = 'rare',
    stack = false,
    close = true,
    decay = nil,
    server = nil,
    client = nil,
    buttons = {},
})

The item is added to the in-memory dictionary and synced to all clients automatically.

EditCustomItem(data) → boolean, error?

Edits an existing custom item. The name field is required and must match an existing item.

exports.origen_inventory:EditCustomItem({
    name = 'origen_compass',
    label = 'Magic Compass',
    weight = 150,
})

Returns false plus an error string when:

• data is missing or has no name ('invalid_item_data').
• The item does not exist ('item_not_found').

RemoveCustomItem(name) → boolean

Deletes an item from the database and from every player's inventory. Triggers an internal sync event so clients drop their cached references.

exports.origen_inventory:RemoveCustomItem('origen_compass')

World Points

World points render and react to interactive locations on the map. They power stashes, shops, crafting tables, drops and any custom point you register.

CreateWorldPoint(pointId, pointData, pointType) → void (client)

Registers a single point at runtime.

exports.origen_inventory:CreateWorldPoint('my_lab_table', {
    label = 'Underground Lab',
    location = vector3(2541.92, 4684.31, 34.05),
    -- marker = { type = 27, size = vector3(0.3, 0.3, 0.3), color = vector4(255, 0, 0, 150) },
    -- sprite = { enabled = true, icon = 'lucide:flask-conical' },
}, 'crafting')

RemoveWorldPoint(pointId) → void (client)

Removes a point by id.

SetWorldPointEnabled(pointId, enabled) → void (client)

Enables or disables an existing point without removing it.

CreateBatchPoints(pointsData, pointType) → void (client)

Registers multiple points at once.

exports.origen_inventory:CreateBatchPoints({
    ['stash_1'] = { label = 'Stash 1', location = vector3(...) },
    ['stash_2'] = { label = 'Stash 2', location = vector3(...) },
}, 'stash')

ClearPoints(pointType) → void (client)

Removes every point of a given type.

RefreshAllPoints(pointType) → void (client)

Reloads every point of a type — useful after changing job permissions on the player.

GetPoints(pointType) → table (client)

Returns the list of points for a given type.

GetPointCount(pointType) → number (client)

Returns the count of registered points for a given type.

HasPoint(pointId) → boolean (client)

Returns true if a point with the given id exists.

RegisterPointType(pointType, config) → void (client)

Registers an entirely new point type with its own sprite, marker and hooks. Use this when you want to add a brand-new category alongside stash, shop, crafting and drop.

LoadPointType(pointType) → void (client)

Reloads the configuration for a point type.

GetWorldPointManager() → table (client)

Returns the underlying point manager object. Advanced use only.

SQL bridge

The SQL helper at bridge/sql.lua provides framework-agnostic helpers that all internal subsystems use. You generally do not interact with it directly, but the source is unobfuscated (it lives outside escrow_ignore's scope) and can be wrapped by your own scripts.