Inicio › Documentación › Personalización · origen_inventory

Personalización · origen_inventory

origen_inventory ofrece tres vías de personalización:

  1. Hooks: escuchan eventos del inventario y modifican los datos o cancelan acciones.
  2. Objetos personalizados: registra, edita y elimina objetos en tiempo de ejecución (se guardan en origen_customitems).
  3. Puntos del mundo: registra puntos interactivos personalizados en el mapa.
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

Los hooks permiten que otros recursos se suscriban a los eventos del inventario y, o bien consulten los datos, o bien los modifiquen o cancelen la acción. Cliente y servidor exponen el mismo nombre de export: registerHook.

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

Registra un callback para el hook indicado.

lua
local hookId = exports.origen_inventory:registerHook('createItem', function(payload)
    -- payload is hook-specific
    return payload.metadata
end)
Parámetro Tipo Descripción
event string Nombre del hook que se va a escuchar.
callback function Se invoca con los datos del hook.
options table Configuración opcional del hook.

removeHooks(id) → void

Elimina un hook registrado previamente a partir de su id.

lua
exports.origen_inventory:removeHooks(hookId)

Hooks de servidor

createItem

Se dispara cuando se está creando un objeto (por ejemplo, al inicializar los metadatos). Devuelve la tabla metadata (modificada, si quieres) para aplicar los cambios.

Datos recibidos

Campo Tipo Descripción
item table Definición del objeto que se está creando.
metadata table Tabla de metadatos modificable.

Ejemplo: asignar un id de bolsa único al crear un 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)

Si registras el hook createItem y olvidas devolver la tabla de metadatos, el objeto se creará con los metadatos vacíos.

Hooks de cliente

worldpoint-interact-in

Se dispara cuando el jugador entra en el radio de interacción de un punto del mundo.

Datos recibidos

Campo Tipo Descripción
type string Tipo de punto (stash, shop, crafting, drop, personalizado).
id string Id único del punto.
location vector3 Coordenadas del punto.
label string Etiqueta que se muestra.

worldpoint-interact-out

Se dispara cuando el jugador sale del radio de interacción de un punto del mundo. Recibe los mismos datos que el anterior.

worldpoint-area-nearby

Se dispara cuando el jugador entra en la zona más amplia (zoneDistance) alrededor de un stash u otro punto que tenga una zona configurada. Sirve para cargar de forma diferida interfaces costosas.

Ejemplo: registrar cada entrada a un stash:

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)

Objetos personalizados

Los objetos personalizados se guardan en la tabla origen_customitems y se vuelven a cargar al arrancar el recurso. Las tres operaciones se ejecutan en el servidor.

AddCustomItem(data) → boolean

Añade un nuevo objeto personalizado. Devuelve false si el objeto ya existe.

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 = {},
})
Campo Tipo Descripción
name string Clave única del objeto. Si está vacía, se genera a partir de label.
label string Etiqueta que se muestra.
weight number Peso del objeto.
type string Tipo de objeto (item, weapon, etc.).
image string Nombre del fichero de imagen (debe existir en la carpeta de imágenes de tu inventario).
description string Descripción del objeto.
rarity string Etiqueta de rareza (opcional).
stack boolean Indica si el objeto es apilable. Por defecto es true.
close boolean Cierra el inventario al usarlo. Por defecto es true.
decay number Duración del deterioro (opcional).
server string|table Definición del callback de servidor (opcional).
client string|table Definición del callback de cliente (opcional).
buttons table Botones del menú contextual (opcional).
consume / uses number Número de usos antes de que se consuma el objeto.

El objeto se añade al diccionario en memoria y se sincroniza automáticamente con todos los clientes.

EditCustomItem(data) → boolean, error?

Edita un objeto personalizado existente. El campo name es obligatorio y debe coincidir con un objeto existente.

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

Devuelve false junto con una cadena de error cuando:

RemoveCustomItem(name) → boolean

Elimina un objeto de la base de datos y del inventario de todos los jugadores. Lanza un evento interno de sincronización para que los clientes descarten sus referencias en caché.

lua
exports.origen_inventory:RemoveCustomItem('origen_compass')

Esta acción es destructiva. El objeto se elimina de todos los inventarios activos y de la tabla origen_customitems.

Puntos del mundo

Los puntos del mundo muestran ubicaciones interactivas en el mapa y reaccionan a ellas. Con ellos funcionan los stashes, las tiendas, las mesas de crafteo, los drops y cualquier punto personalizado que registres.

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

Registra un único punto en tiempo de ejecución.

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 (cliente)

Elimina un punto a partir de su id.

SetWorldPointEnabled(pointId, enabled) → void (cliente)

Activa o desactiva un punto existente sin eliminarlo.

CreateBatchPoints(pointsData, pointType) → void (cliente)

Registra varios puntos a la vez.

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

ClearPoints(pointType) → void (cliente)

Elimina todos los puntos de un tipo.

RefreshAllPoints(pointType) → void (cliente)

Recarga todos los puntos de un tipo. Es útil después de cambiar los permisos de trabajo del jugador.

GetPoints(pointType) → table (cliente)

Devuelve la lista de puntos de un tipo.

GetPointCount(pointType) → number (cliente)

Devuelve el número de puntos registrados de un tipo.

HasPoint(pointId) → boolean (cliente)

Devuelve true si existe un punto con ese id.

RegisterPointType(pointType, config) → void (cliente)

Registra un tipo de punto totalmente nuevo, con su propio sprite, marcador y hooks. Úsalo cuando quieras añadir una categoría nueva junto a stash, shop, crafting y drop.

LoadPointType(pointType) → void (cliente)

Recarga la configuración de un tipo de punto.

GetWorldPointManager() → table (cliente)

Devuelve el objeto gestor de puntos subyacente. Solo para uso avanzado.

Puente SQL

El helper SQL de bridge/sql.lua ofrece funciones independientes del framework que usan todos los subsistemas internos. Normalmente no tendrás que usarlo directamente, pero su código fuente no está ofuscado (queda fuera del alcance de escrow_ignore) y tus propios scripts pueden envolverlo.