Notificaciones y barras de progreso en FiveM: ESX, QBCore y ox_lib

Cada framework tiene su propia forma de mostrar un mensaje o una barra de progreso, y un script escrito para uno falla en otro:

attempt to index a nil value (global 'lib')

Este artículo enumera las llamadas para ESX, QBCore y ox_lib, para notificaciones y para barras de progreso, luego muestra una única función puente para que tu script funcione en el que sea que el servidor ejecute.

#Notificaciones en ESX

En el cliente:

ESX.ShowNotification('You picked up a package')

En el servidor, desde el objeto del jugador:

local xPlayer = ESX.GetPlayerFromId(source)
xPlayer.showNotification('Your order is ready')

ESX aquí es el objeto de ESX = exports['es_extended']:getSharedObject(). Las versiones recientes de ESX también aceptan un tipo y una duración después del texto. Si dependes de ellos, prueba en tu versión.

#Notificaciones en QBCore

En el cliente:

local QBCore = exports['qb-core']:GetCoreObject()

QBCore.Functions.Notify('You picked up a package', 'success', 5000)

El tipo es 'primary', 'success' o 'error', y el último valor es el tiempo en milisegundos. Desde el servidor, envía el evento al jugador:

TriggerClientEvent('QBCore:Notify', source, 'Your order is ready', 'success')

En QBox las mismas llamadas de QBCore siguen funcionando a través de su capa de compatibilidad, y las notificaciones de ox_lib son una buena alternativa.

#Notificaciones con ox_lib

ox_lib tiene su propia notificación, y funciona igual en cada framework. En el cliente:

lib.notify({
    title = 'Delivery',
    description = 'You picked up a package',
    type = 'success',
    duration = 5000,
})

El tipo es 'inform', 'success', 'warning' o 'error'. Desde el servidor, dispara el evento en el jugador:

TriggerClientEvent('ox_lib:notify', source, {
    title = 'Delivery',
    description = 'Your order is ready',
    type = 'success',
})

El global lib necesita shared_script '@ox_lib/init.lua' en tu fxmanifest.lua, como se describe en the ox_lib context menu guide. Sin él obtienes el error de lib nil arriba.

#Barras de progreso

Con ox_lib, una barra de progreso es una llamada que espera y devuelve si terminó:

if lib.progressBar({
    duration = 5000,
    label = 'Repairing the engine',
    useWhileDead = false,
    canCancel = true,
    disable = {
        move = true,
        car = true,
        combat = true,
    },
    anim = {
        dict = 'mini@repair',
        clip = 'fixing_a_ped',
    },
}) then
    print('finished')
else
    print('cancelled')
end

lib.progressCircle toma las mismas opciones y muestra un círculo en lugar de una barra. Ambas también pueden adjuntar un prop al jugador.

La versión de QBCore usa una devolución de llamada en lugar de esperar:

QBCore.Functions.Progressbar('repair_engine', 'Repairing the engine', 5000, false, true, {
    disableMovement = true,
    disableCarMovement = true,
    disableMouse = false,
    disableCombat = true,
}, {
    animDict = 'mini@repair',
    anim = 'fixing_a_ped',
    flags = 49,
}, {}, {}, function()
    print('finished')
end, function()
    print('cancelled')
end)

Los argumentos son, en orden: un nombre, la etiqueta, la duración, useWhileDead, canCancel, los controles deshabilitados, la animación, dos props, luego los callbacks de finalización y cancelación. ESX no tiene su propia barra de progreso que cada servidor comparta, así que en ESX usa lib.progressBar.

#Una función puente para todos ellos

Para mantener tus scripts libres de framework, escribe el detalle del framework una vez y llama a tus propias funciones en todas partes. Pon esto en un archivo del cliente:

local function started(name)
    return GetResourceState(name) == 'started'
end

function Notify(message, notifyType)
    notifyType = notifyType or 'inform'

    if started('ox_lib') then
        lib.notify({ description = message, type = notifyType })
    elseif started('qb-core') then
        local qbType = notifyType == 'inform' and 'primary' or notifyType
        exports['qb-core']:GetCoreObject().Functions.Notify(message, qbType)
    elseif started('es_extended') then
        exports['es_extended']:getSharedObject().ShowNotification(message)
    else
        print(message)
    end
end

-- returns true when finished, false when cancelled
function Progress(label, duration)
    if started('ox_lib') then
        return lib.progressBar({
            duration = duration,
            label = label,
            canCancel = true,
            disable = { move = true, car = true },
        })
    end

    local p = promise.new()
    exports['qb-core']:GetCoreObject().Functions.Progressbar('bridge_progress', label, duration, false, true, {
        disableMovement = true,
        disableCarMovement = true,
    }, {}, {}, {}, function() p:resolve(true) end, function() p:resolve(false) end)
    return Citizen.Await(p)
end

Ahora tu script solo llama a Notify('Done', 'success') y Progress('Working', 5000). Si ox_lib está instalado, se usa primero. De lo contrario, se usa QBCore, y las notificaciones retroceden a ESX.

La barra de progreso de retroceso solo cubre QBCore. En un servidor sin ox_lib ni QBCore, añade tu propia rama o haz que ox_lib sea una dependencia requerida con dependency 'ox_lib'.

Consejo: haz lo mismo en el servidor con una función NotifyPlayer(source, message, type), usando las llamadas de servidor de las secciones anteriores. Luego ningún otro archivo necesita saber qué framework se ejecuta.

#Lista de verificación