Custom · origen_inventory

origen_inventory exposes three customization surfaces:

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

text

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.

lua

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

Parameter	Type	Description
`event`	`string`	Name of the hook to listen to.
`callback`	`function`	Invoked with the hook payload.
`options`	`table`	Optional hook configuration.

`removeHooks(id)` → `void`

Removes a previously registered hook by its id.

lua

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

Field	Type	Description
`item`	`table`	Item definition being created.
`metadata`	`table`	Mutable metadata table.

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

lua

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)

If you register the createItem hook and forget to return the metadata table, the item will be created with an empty metadata.

Client-side hooks

`worldpoint-interact-in`

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

Payload

Field	Type	Description
`type`	`string`	Point type (`stash`, `shop`, `crafting`, `drop`, custom).
`id`	`string`	Unique point id.
`location`	`vector3`	Point coordinates.
`label`	`string`	Display label.

`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:

lua

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.

lua

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 = {},
})

Field	Type	Description
`name`	`string`	Unique item key. If empty, generated from `label`.
`label`	`string`	Display label.
`weight`	`number`	Item weight.
`type`	`string`	Item type (`item`, `weapon`, etc.).
`image`	`string`	Image filename (must exist in your inventory image folder).
`description`	`string`	Item description.
`rarity`	`string`	Optional rarity label.
`stack`	`boolean`	Whether the item is stackable. Defaults to `true`.
`close`	`boolean`	Closes the inventory on use. Defaults to `true`.
`decay`	`number`	Optional decay duration.
`server`	`string\|table`	Optional server callback definition.
`client`	`string\|table`	Optional client callback definition.
`buttons`	`table`	Optional context-menu buttons.
`consume` / `uses`	`number`	Number of uses before the item is consumed.

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.

lua

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.

lua

exports.origen_inventory:RemoveCustomItem('origen_compass')

This is destructive. The item is removed from every active inventory and from the origen_customitems table.

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.

lua

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.

lua

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.

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.