API de proveedores

La versión actual de la API de proveedores es 1. Los nombres de proveedor deben estar en minúsculas, tener como máximo 64 caracteres y contener solo letras, dígitos, _, . o -. Las prioridades deben ser números finitos entre -100000 y 100000.

Registrar un proveedor de servidor

local ok, errorMessage = exports.humalike:RegisterProvider(domain, descriptor)

domain es player, inventory, dispatch o actions. El registro debe hacerse desde un recurso externo. Devuelve true si tiene éxito o false más un motivo estable y legible cuando el descriptor es rechazado. Todo descriptor requiere:

Campo	Tipo	Descripción
`name`	string	Nombre del proveedor usado por su convar de selección.
`apiVersion`	number	Debe ser `1`.
`priority`	number	En `auto` gana la prioridad disponible más alta.
`Available`	function, opcional	Devuelve `true` cuando las dependencias están listas; opcionalmente devuelve `false, reason`.

Descriptor de jugador

Callback	Obligatorio	Contrato
`GetCharacterId(source)`	Sí	Devuelve un id estable del personaje activo o `nil`.
`GetCharacterName(source)`	Sí	Devuelve el nombre visible del personaje activo o `nil`.
`IsCharacterLoaded(source)`	Sí	Devuelve exactamente `true` cuando el estado de juego está listo.
`HasJob(source, names, requireDuty)`	No	Devuelve exactamente `true` cuando coincide uno de los trabajos solicitados y se cumplen los requisitos de servicio.
`Notify(source, message, kind)`	No	Muestra una notificación al jugador.

kind puede ser success, error, warning o inform. Trata los tipos desconocidos como informativos.

Descriptor de inventario

exports.humalike:RegisterProvider('inventory', {
    name = 'my_inventory',
    apiVersion = 1,
    priority = 100,
    AddItem = function(source, itemName, quantity, metadata)
        return true
    end,
})

AddItem debe devolver exactamente true tras aceptar la operación. Devuelve false si el inventario está lleno, el objeto es desconocido, los metadatos son inválidos o por cualquier otro rechazo.

Descriptor de dispatch

exports.humalike:RegisterProvider('dispatch', {
    name = 'my_dispatch',
    apiVersion = 1,
    priority = 100,
    Report = function(kind, payload)
        return true
    end,
})

Traduce el kind y el payload neutrales a tu recurso de dispatch. Devuelve false solo cuando el reporte fue rechazado; nil cuenta como aceptado tras un callback correcto.

Descriptor de acciones

exports.humalike:RegisterProvider('actions', {
    name = 'my_actions',
    apiVersion = 1,
    priority = 100,
    SupportedActions = { 'hand_over_money' },
    RunAction = function(action, source, npcCoords, params)
        return true
    end,
})

Las claves de acción deben empezar por una letra minúscula, contener solo letras minúsculas, dígitos y _, y tener como máximo 64 caracteres. RunAction debe devolver exactamente true tras completar o aceptar la acción; es opcional para un proveedor cuyo SupportedActions esté vacío. Valida source, la distancia a npcCoords, los permisos, los identificadores, las cantidades y todos los params en el servidor. El nombre de la acción no es una autorización. El mismo descriptor declara las observaciones del servidor que la integración puede reportar (consulta Observaciones del servidor):

exports.humalike:RegisterProvider('actions', {
    name = 'my_actions',
    apiVersion = 1,
    priority = 100,
    SupportedActions = {},
    Namespace = 'myserver',
    Observations = {
        item_given = {
            fields = { item = 'string', quantity = 'integer' },
            template = {
                en = 'the character handed you {quantity} x {item}',
                pl = 'postać wręczyła ci {quantity} x {item}',
            },
        },
    },
})

Namespace coincide con ^[a-z][a-z0-9]{1,15}$ y es obligatorio en cuanto Observations no esté vacío. Prefija cada clave en el cable (myserver:item_given), de modo que una clave del servidor nunca coincida con un tipo de evento integrado.
Observations asigna hasta 32 claves (^[a-z][a-z0-9_]{0,31}$) a una definición con hasta 8 fields, nombrados como las claves y tipados como string, integer, number o boolean, y una template con al menos uno de los idiomas que ofrece el panel (se usa el idioma del NPC; si no, inglés; si no, el primero declarado). Cada línea tiene como máximo 400 caracteres sin caracteres de control, sus {placeholders} nombran campos declarados y no contiene otras llaves. Una plantilla también se dimensiona por su renderizado en el peor caso — cada aparición de un marcador con el valor más ancho de su campo (64 caracteres para un string, 21 para un number, 17 para un integer, 5 para un boolean) — que debe mantenerse dentro de 912 caracteres.

El recurso aplica todo esto en RegisterProvider: un descriptor que incumple una regla es rechazado con el motivo y no se registra nada.

Anular el registro de un proveedor de servidor

local ok, errorMessage = exports.humalike:UnregisterProvider(domain, name)

Solo el recurso propietario puede anular el registro de su proveedor. Detener el propietario realiza esta limpieza automáticamente.

Estado del servidor

local status = exports.humalike:GetProviderStatus()

El resultado contiene:

apiVersion y runtimeEpoch;
selected, un mapa compacto por dominio;
domains, incluyendo para cada uno su ajuste, estado, motivo, proveedor seleccionado y todos los candidatos registrados.

Los estados son selected, disabled, unavailable, ambiguous o degraded. Un fallo en un callback degrada el proveedor seleccionado; un callback correcto posterior limpia el estado de fallo.

Registrar un proveedor de interacción de cliente

local ok, errorMessage = exports.humalike:RegisterInteractionProvider({
    name = 'my_target',
    apiVersion = 1,
    priority = 100,
    Available = function() return true end,
    watchedResources = { 'my-target' },
    Add = function(id, entity, options) return true end,
    Remove = function(id) end,
    Progress = function(durationMs, label) return true end,
})

Add y Remove son obligatorios. Progress es opcional. Add debe devolver exactamente true cuando el registro tiene éxito. Progress devuelve exactamente true al completarse y false si se cancela o falla. watchedResources enumera las dependencias cuyo inicio/parada debe provocar la reevaluación del proveedor.

exports.humalike:UnregisterInteractionProvider('my_target')
local status = exports.humalike:GetInteractionProviderStatus()

El estado de cliente informa de apiVersion, runtimeEpoch, el ajuste, el estado, el motivo y el proveedor seleccionado.

Evento ready

AddEventHandler('humalike:integration:ready', function(info)
    print(info.apiVersion, info.runtimeEpoch)
end)

El evento es local y se emite de forma independiente en el servidor y en el cliente tras cada inicio de Humalike. Vuelve a registrar los proveedores de ese lado cuando se dispare.

Primeros pasos

Configurar

Integrar

Operar

Registrar un proveedor de servidor

Descriptor de jugador

Descriptor de inventario

Descriptor de dispatch

Descriptor de acciones

Anular el registro de un proveedor de servidor

Estado del servidor

Registrar un proveedor de interacción de cliente

Evento ready

Siguiente

​Registrar un proveedor de servidor

​Descriptor de jugador

​Descriptor de inventario

​Descriptor de dispatch

​Descriptor de acciones

​Anular el registro de un proveedor de servidor

​Estado del servidor

​Registrar un proveedor de interacción de cliente

​Evento ready

​Siguiente

Registrar un proveedor de servidor

Descriptor de jugador

Descriptor de inventario

Descriptor de dispatch

Descriptor de acciones

Anular el registro de un proveedor de servidor

Estado del servidor

Registrar un proveedor de interacción de cliente

Evento ready

Siguiente