API de integración

El archivo shared/integration.lua es la API pública de Adictos_WebLogs: funciona aunque el resto del recurso esté encriptado. Úsalo para registrar logs desde tus scripts, escuchar eventos del sistema o reaccionar cuando termina un CK o un cambio de licencia.

Incluir integration.lua en tu recurso

Añade el archivo como shared_script en el fxmanifest.lua de tu recurso. Las funciones de servidor (log, logPlayer, listeners) solo existen en el lado servidor; en cliente solo tienes AdictosWebLogs.isAvailable().

fx_version 'cerulean'
game 'gta5'

shared_scripts {
    '@Adictos_WebLogs/shared/integration.lua',
}

server_scripts {
    'server/main.lua',
}

Funciones helper

Ejemplo básico

local function logVenta(source, plate, precio)
    if not AdictosWebLogs.isAvailable() then return end

    AdictosWebLogs.logPlayer(source, 'vehicles', 'vehicle_sell', {
        details = ('Vendió %s por $%s'):format(plate, precio),
        raw_data = { plate = plate, price = precio },
    }, true)
end

Eventos del sistema

Los nombres oficiales están en AdictosWebLogs.Events. Puedes usarlos con AddEventHandler o los helpers de integration.lua:

-- Escuchar todos los logs de vehículos
AdictosWebLogs.onLog(function(category, action, entry)
    if category ~= 'vehicles' and category ~= 'vehicles_garage' then return end
    print(('[WebLogs] %s / %s — %s'):format(category, action, entry.details or ''))
end)

-- O con AddEventHandler directamente
AddEventHandler(AdictosWebLogs.Events.CONFIG_LOADED, function()
    print('WebLogs: categorías sincronizadas con el panel')
end)

Exports alternativos (sin integration.lua)

Si no quieres incluir el archivo compartido, puedes llamar a los exports del recurso o disparar eventos de red internos:

exports['Adictos_WebLogs']:Log('economy', 'payment', { amount = 500, details = 'Pago nómina' }, true)
exports['Adictos_WebLogs']:LogPlayer(source, 'jobs', 'duty_on', { details = 'Entró de servicio' })

-- Mismo efecto vía evento (servidor)
TriggerEvent('Adictos_WebLogs:Log', 'general', 'custom_event', { details = '...' }, false)

-- Lista de eventos disponibles
local events = exports['Adictos_WebLogs']:GetEvents()

API unificada de vehículos (recomendada)

No necesitas AdvancedParking, ox_fuel, esx_advancedgarage ni ningún script concreto. Solo llama a logVehicle() desde tu garaje, sistema de combustible o mecánico cuando la acción se complete en la base de datos. WebLogs se encarga de la categoría, la acción y el texto del log.

Acciones disponibles

Campos de <code>data</code>

Ejemplo — cualquier script de garaje (servidor)

shared_scripts { '@Adictos_WebLogs/shared/integration.lua' }

-- Tras guardar en TU tabla owned_vehicles / player_vehicles:
AdictosWebLogs.logVehicle(AdictosWebLogs.VehicleActions.STORE, source, {
    plate = plate,
    fuel = fuelLevel,
    engine_health = engineHealth,
})

-- Tras sacar del garaje:
AdictosWebLogs.logVehicle('retrieve', source, { plate = plate, engine_health = engineHealth })

Ejemplo — script de combustible (servidor)

-- Funciona con LegacyFuel, ps-fuel, ox_fuel, CDN-fuel o script propio
RegisterNetEvent('mi_fuel:pagado', function(plate, oldFuel, newFuel)
    AdictosWebLogs.logVehicle('fuel', source, {
        plate = plate,
        fuel_before = oldFuel,
        fuel_after = newFuel,
    })
end)

Ejemplo — mecánico / reparación

AdictosWebLogs.logVehicle('repair', source, {
    plate = plate,
    old_engine = engineHealthBefore,
})

Ejemplo — transferencia o borrado

AdictosWebLogs.logVehicle('transfer', adminSource, {
    plate = plate,
    new_owner = newOwnerLicense,
    targetName = newOwnerName,
})

AdictosWebLogs.logVehicle('delete', source, { plate = plate })

Desde cliente (si el evento nace en client)

-- En client.lua (con integration.lua cargado)
AdictosWebLogs.logVehicle('fuel', {
    plate = plate,
    fuel_before = 20,
    fuel_after = 100,
})

Sin integration.lua (solo export)

exports['Adictos_WebLogs']:LogVehicle('store', source, {
    plate = 'ABC 123',
    fuel = 75,
    engine_health = 900,
})

Reparar / Gasolina en vivo (framework.lua)

Cuando el staff pulsa Reparar o Gasolina en Tickets, Mapa en vivo o el perfil del jugador, WebLogs actualiza la BD y, si el vehículo está spawneado, aplica el cambio en el mundo. La lógica vive en shared/framework.lua (archivo plano, no se encripta) para que puedas adaptarla a tu servidor.

Configura el preset en Mis servidores → Gestionar → Framework → Gasolina desde el panel (auto, ox_fuel, LegacyFuel, ps-fuel, solo BD, etc.).

API servidor (<code>WebLogsFramework</code>)

API cliente (mismo archivo)

Eventos de red

ox_fuel (recomendado)

• Preset auto detecta ox_fuel primero; o fuerza preset ox_fuel (tipo statebag).
• Servidor: Entity(veh).state:set('fuel', level, true) — fuente de verdad de ox_fuel.
• Clientes: SetVehicleFuelLevel obligatorio si alguien conduce; si no, el loop de ox_fuel vuelve a bajar el depósito con GetVehicleFuelLevel.
• No uses el evento cliente ox_fuel:setFuel para subir gasolina: en servidor es reduceOnly (solo baja).
• ox_fuel no exporta SetFuel; no elijas preset LegacyFuel si usas ox_fuel.

-- Ejemplo: rellenar / reparar un vehículo spawneado desde tu script (servidor)
local veh = -- handle de entidad del vehículo
if veh and DoesEntityExist(veh) then
    local level = WebLogsFramework.getPanelFuelTargetLevel()
    WebLogsFramework.applyPanelFuelLive(veh, level)
    WebLogsFramework.applyPanelRepairLive(veh)
end

-- Cliente (p. ej. menú admin propio)
WebLogsFramework.applyClientVehicleRepair(cache.vehicle)
WebLogsFramework.applyClientVehicleFuel(cache.vehicle, 100)

Integraciones opcionales (no obligatorias)

• esx_advancedgarage — ya integrado; usa LogVehicle internamente.
• AdvancedParking — solo afecta al mapa en vivo y al borrado automático; los logs de garaje/fuel los pones tú con logVehicle.
• Hook de borrado — opcional; detecta DeleteEntity sin que programes nada (ver abajo).

Logs de vehículos — referencia de categorías

Hook automático de borrado (otros recursos)

Si tu recurso llama a DeleteEntity o DeleteVehicle sobre coches, puedes cargar el hook compartido para que WebLogs registre el borrado con el nombre de tu script:

shared_scripts {
    '@Adictos_WebLogs/hooks/vehicle_delete_hook.lua',  -- después de otros hooks de AP si los hay
}

El monitor unificado de WebLogs fusiona estos reportes con eventos de AdvancedParking y avisos de “vehículo perdido mientras conduces”. Configurable en el panel → Mis servidores → Gestionar → pestaña de vehículos.

Referencia rápida de categorías de vehículos

• vehicles — acciones generales (spawn, delete, subir/bajar, reparar, fuel, transferir…)
• vehicles_garage — guardar y sacar de garaje
• vehicles_engine, vehicles_tuning, vehicles_build — otros módulos del panel (crea y activa las que uses)

Export ShowPendingWarnings (avisos in-game)

Muestra al jugador la pantalla roja de aviso con todos los avisos del panel que aún no ha confirmado (seen_at vacío). Si hay varios, salen en el mismo mensaje (numerados). El jugador debe mantener ESPACIO unos segundos para marcarlos como vistos.

Útil cuando en Mis servidores → Gestionar → Personalización tienes desactivado «Mostrar avisos automáticamente» y quieres forzar la notificación desde tu script (jail, menú admin, al salir de un menú, etc.).

-- playerId = source del jugador (server ID de FiveM)
if GetResourceState('Adictos_WebLogs') ~= 'started' then return end

local ok = exports['Adictos_WebLogs']:ShowPendingWarnings(playerId)
if not ok then
    -- Jugador offline, ID inválido, o ya hay una petición en curso
    print('No se pudieron mostrar avisos pendientes')
end

Comportamiento

• Consulta al panel los avisos con seen_at vacío de esa licencia.
• Si no hay pendientes, no muestra nada.
• Si hay 1 aviso: pantalla «Aviso» con el motivo y el staff.
• Si hay 2 o más: título «Avisos (N)» y texto combinado [1/N] … / [2/N] … en la misma pantalla.
• Al completar el hold de ESPACIO, todos los IDs mostrados pasan a Visto en el panel y no se vuelven a mostrar.
• Funciona aunque el toggle de notificación automática esté desactivado.

Ejemplo: al liberar de jail

RegisterNetEvent('mi_script:playerReleasedFromJail', function()
    local src = source
    if GetResourceState('Adictos_WebLogs') == 'started' then
        exports['Adictos_WebLogs']:ShowPendingWarnings(src)
    end
end)

Export AssignCommunityService / SendToCommunityService

Servicios comunitarios integrados en Adictos_WebLogs (sustituye esx_communityservice). La zona, puntos de trabajo, animaciones y ropa (números skinchanger hombre/mujer) se configuran en Mis servidores → Gestionar → Servicios. También desde /apm puedes colocar puntos y capturar ropa con ROPA HOMBRE / ROPA MUJER.

-- Por source (jugador online)
exports['Adictos_WebLogs']:SendToCommunityService(playerId, 10, 'Motivo')

-- Por licencia (panel / scripts)
exports['Adictos_WebLogs']:AssignCommunityService({
    license = 'abc123...',
    actions = 10,
    motivo = 'VDM',
})

• Activa el módulo en Gestionar → Servicios y quita ensure esx_communityservice del server.cfg (no ejecutes ambos a la vez).
• Si «Mostrar aviso al asignar» está ON, el jugador ve la pantalla roja con el motivo.
• Compatibilidad (ya dentro de WebLogs): eventos esx_serviciocomunitario:sendToCommunityService / esx_communityservice:….

Jugador cargado / listo (ESX, QBCore y Qbox)

API genérica para saber cuándo el personaje está cargado y cuándo el jugador está realmente listo en el mundo. Funciona con o sin multicharacter.

Hay dos niveles. Registra handlers en el servidor (WebLogsFramework en shared/framework.lua, o exports):

playerConnecting / playerJoining
    │
    ▼
Multichar (opcional) → elige personaje
    │
    ▼
esx:playerLoaded / QBCore:OnPlayerLoaded / qbx_core:…
    │
    ▼
WebLogsFramework.onPlayerLoaded  ← personaje en framework
    │
    ▼
Cliente ACK (ped vivo + coords)
    │
    ▼
WebLogsFramework.onPlayerFullyReady  ← listo en el mundo

Uso recomendado

-- Esperar a que el jugador esté jugable (avisos, premios, TP, etc.)
WebLogsFramework.onPlayerFullyReady(function(playerId, meta)
    -- meta.alive, meta.coords, meta.framework ('esx' | 'qb' | 'qbx')
    print(('Jugador %s listo (%s)'):format(playerId, tostring(meta.framework)))
end)

-- Solo personaje en framework (sin esperar ped)
WebLogsFramework.onPlayerLoaded(function(playerId)
    print('Personaje cargado: ' .. playerId)
end)

-- Exports equivalentes (desde otro recurso)
exports['Adictos_WebLogs']:OnPlayerFullyReady(function(src, meta) end)
exports['Adictos_WebLogs']:OnPlayerLoaded(function(src) end)

if exports['Adictos_WebLogs']:IsPlayerFullyReady(src) then
    -- ped listo
end
if exports['Adictos_WebLogs']:IsCharacterLoaded(src) then
    -- personaje en framework
end

Opciones (Custom en framework.lua)