Documentation / Integration API

Integration API

Connect your FiveM scripts to Adictos_WebLogs: integration.lua, WebLogsFramework (10.0), vehicles, fuel/repair, inventory, services and player ready (ESX / QBCore / Qbox / ND).

shared/integration.lua is the public logging API. From 10.0 the framework bridge (ESX/QB/Qbox/ND, inventory, fuel, revive, player ready) is WebLogsFramework.*. Configure it under My servers → Framework; Adictos_Core is not required.

WebLogsFramework (10.0)

Adictos_WebLogs is self-sufficient: it detects the core and the inventory, gives/removes items, lockers, revive and fuel. Gym / Quest / XP / Zombies do use Adictos_Core; WebLogs doesn’t.

Bridge modules (the public API doesn’t change):

FileWhat it does
shared/framework.luaCore: detect, player, notify, IC names, Custom
shared/framework/identifiers.lualicense/steam/multichar format + sync to the panel
shared/framework/lifecycle.luaonPlayerLoaded / onPlayerFullyReady
shared/framework/inventory/bridge.luaox / qb / ps / lj provider + give/remove/get
shared/framework/inventory/stashes.luaOwner lockers, returns, job stash
shared/framework/fuel.lua / revive.lua / vehicles.luaFuel, revive and garage SQL from the panel

Use shared/integration.lua, hooks/*.lua and translations for logs. The bridge is configured in the panel or via WebLogsFramework.* / exports.

API summary

Function / exportUse
WebLogsFramework.getName()esx, qb, qbx, nd or custom
getPlayer / getPlayerByLicensexPlayer or QB/ND wrapper
getInventoryProvider()ox, qb, qs or custom (the resource reports it to the panel)
addInventoryItem / removeInventoryItem / getInventoryItemsox or qb CRUD (qs/custom: Custom.* hooks)
registerOwnedStash / openOwnedStashPersonal locker (returns, APM)
executePanelReviveRevive according to the Framework preset
applyPanelFuelLive / applyPanelRepairLiveLive fuel and repair
OnPlayerLoaded / OnPlayerFullyReadyExports: character loaded / ped in the world
-- Desde otro recurso (WebLogs iniciado)
local fw = WebLogsFramework.getName() -- 'esx' | 'qb' | 'qbx' | 'nd'
local inv = WebLogsFramework.getInventoryProvider() -- 'ox' | 'qb' | …

WebLogsFramework.addInventoryItem(src, 'bread', 2)
WebLogsFramework.notify(src, 'Recibido')

-- Inventario raro (qs/codem): parchea Custom después de que arranque WebLogs
WebLogsFramework.Custom.registerOwnedStash = function(opts) -- tu API
end
My servers → Manage → Framework: mode (auto/ESX/QB/Qbox/ND), identifier, inventory, revive and fuel. Different from the Inventory logs tab (ox_lib filters).
Prefer the panel presets or call WebLogsFramework.* / exports. A Cfx/Tebex update may overwrite local changes in the resource’s Lua.

Including integration.lua in your resource

Add the file as a shared_script in your resource’s fxmanifest.lua. Server functions (log, logPlayer, listeners) only exist on the server side; on the client you only have AdictosWebLogs.isAvailable().

fx_version 'cerulean'
game 'gta5'

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

server_scripts {
    'server/main.lua',
}
Requirement: ensure Adictos_WebLogs must come first, or at least be started when your resource logs. Check with AdictosWebLogs.isAvailable() or GetResourceState('Adictos_WebLogs') == 'started'.

Helper functions

FunctionDescription
AdictosWebLogs.isAvailable()Returns true if the Adictos_WebLogs resource is started (client and server).
AdictosWebLogs.log(category, action, data, sendDiscord)Sends a log to the panel. sendDiscord defaults to true. Server only.
AdictosWebLogs.logPlayer(source, category, action, data, sendDiscord)Same as log but fills in the licence and names from the player’s source. Server only.
AdictosWebLogs.logVehicle(action, source, data, sendDiscord)Recommended for vehicles. A single function for garage, fuel, repair, transfer and delete. See the dedicated section.
AdictosWebLogs.onLog(handler)Listens to every accepted log: handler(category, action, logEntry).
AdictosWebLogs.onConfigLoaded(handler)Fires when WebLogs loads the remote configuration from the panel.
AdictosWebLogs.onCKDone(handler)Fires when a CK finishes: handler(identifier, success, totalDeleted).
AdictosWebLogs.onLicenseTransferDone(handler)Fires when a licence change finishes: handler(oldLicense, newLicense, success, stats).
exports['Adictos_WebLogs']:ShowPendingWarnings(playerId)Shows the player the panel warnings they haven’t seen yet (red screen). See the dedicated section below.

Basic example

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

System events

The official names are in AdictosWebLogs.Events. You can use them with AddEventHandler or the integration.lua helpers:

ConstantEventWhen it fires
LOG_QUEUEDAdictos_WebLogs:onLogQueuedEvery time a log enters the queue (before being sent to the panel).
LOGS_SENTAdictos_WebLogs:onLogsSentAfter sending a batch of logs to the panel.
CONFIG_LOADEDAdictos_WebLogs:onConfigLoadedRemote configuration loaded (categories, CK, etc.).
CONFIG_UPDATEDAdictos_WebLogs:onConfigUpdatedThe panel pushes configuration changes live.
CK_DONEAdictos_WebLogs:onCKDoneCK completed from the panel.
LICENSE_TRANSFER_DONEAdictos_WebLogs:onLicenseTransferDoneLicence change completed.
PLAYER_BANNEDadictos:playerBannedBan applied from the panel or the sanctions system.
PERMABAN_REQUESTadictos:webPermabanRequestPermaban request from the panel.
-- 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)

Alternative exports (without integration.lua)

If you don’t want to include the shared file, you can call the resource’s exports or trigger internal network events:

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()
The Log() export also accepts a single object with category, action, license, player_name fields, etc. Useful if you already have a data table built (as in esx_advancedgarage).

You don’t need AdvancedParking, ox_fuel, esx_advancedgarage or any specific script. Just call logVehicle() from your garage, fuel system or mechanic when the action is completed in the database. WebLogs takes care of the category, the action and the log text.

Available actions

ActionConstantWhen to call it
Store in garagestore or AdictosWebLogs.VehicleActions.STOREAfter marking the vehicle as stored in the DB
Take out of garageretrieveAfter spawning the vehicle for the player
RepairrepairAfter updating engine/body in the DB or entity
FuelfuelAfter changing the fuel level
TransfertransferAfter changing the owner in the DB
DeletedeleteAfter deleting the record from the DB

<code>data</code> fields

FieldDescription
plateRequired. Vehicle plate.
fuel / fuel_before / fuel_afterFuel level (0–100).
engine_health / old_engineEngine health (0–1000 in GTA).
new_owner / targetLicense / targetNameNew owner (transfers).
detailsFree text; if you leave it out, WebLogs generates one automatically.
via = 'panel'Marks that the action came from the web panel (staff).

Example — any garage script (server)

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 })

Example — fuel script (server)

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

Example — mechanic / repair

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

Example — transfer or delete

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

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

From the client (if the event starts on the client)

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

Without integration.lua (export only)

exports['Adictos_WebLogs']:LogVehicle('store', source, {
    plate = 'ABC 123',
    fuel = 75,
    engine_health = 900,
})
Web panel actions (Garage, Repair, Fuel, Transfer, Delete on the player profile) already log automatically with the [Panel] prefix. No extra code is needed for that.

Live repair / fuel (WebLogsFramework)

When staff press Repair or Fuel in Tickets, Live map or the player profile, WebLogs updates the DB and, if the vehicle is spawned, applies the change in the world. The logic lives in shared/framework/fuel.lua. It is used via WebLogsFramework.*.

Configure the preset under My servers → Manage → Framework → Fuel from the panel (auto, ox_fuel, LegacyFuel, ps-fuel, DB only, etc.).

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

FunctionDescription
getPanelFuelTargetLevel()0–100 level configured in the panel (Framework preset).
applyPanelFuelLive(vehicleHandle, fuelLevel?)Refuels a spawned vehicle according to the preset (ox_fuel statebag, SetFuel export, custom event or DB only).
applyPanelRepairLive(vehicleHandle)Repairs health on the server and triggers the visual/physical fix on all clients.
updateVehicleFuel(plate, propsJson, fuelLevel?)UPDATE of the fuel column + JSON props in owned_vehicles / player_vehicles.
updateVehicleRepair(plate, propsJson)UPDATE of engine/body in the DB.

Client API

FunctionDescription
applyClientVehicleFuel(vehicle, fuelLevel, exportResource?)Applies SetVehicleFuelLevel (and SetFuel if there is an export). Re-applies for several ticks so ox_fuel doesn’t overwrite the level with the native’s old value.
applyClientVehicleRepair(vehicle)SetVehicleFixed, deformation, engine/body/tank and dirt. The APM Repair button uses it too.

Network events

EventParametersUse
Adictos_WebLogs:panelSetVehicleFuelnetId, fuelLevel, exportResourceServer → clients. Empty exportResource = native/statebag only (ox_fuel).
Adictos_WebLogs:panelRepairVehiclenetIdServer → clients. Full fix of the streamed vehicle.
  • The auto preset detects ox_fuel first; or force the ox_fuel preset (type statebag).
  • Server: Entity(veh).state:set('fuel', level, true) — ox_fuel’s source of truth.
  • Clients: SetVehicleFuelLevel is required if someone is driving; otherwise the ox_fuel loop lowers the tank again with GetVehicleFuelLevel.
  • Don’t use the client event ox_fuel:setFuel to raise fuel: on the server it is reduceOnly (it only lowers).
  • ox_fuel does not export SetFuel; don’t choose the LegacyFuel preset if you use 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)
The preset is chosen under My servers → Framework → Fuel. Avoid editing server/map_panel.lua unless you know what the builder changes.

Optional integrations (not required)

  • esx_advancedgarage — already integrated; it uses LogVehicle internally.
  • AdvancedParking — only affects the live map and automatic deletion; you add the garage/fuel logs yourself with logVehicle.
  • Delete hook — optional; detects DeleteEntity without you writing any code (see below).

Vehicle logs — category reference

SituationSuggested categoryAction (action)Notes
Send vehicle to the garagevehicles_garagevehicle_storeCreate the vehicles_garage category in the panel if it doesn’t exist.
Take vehicle out of the garagevehicles_garagevehicle_retrieveSame category as storing.
Repair vehiclevehiclesvehicle_repairInclude the plate and engine % before/after in details or raw_data.
Add / fill fuelvehiclesvehicle_fuelIndicate the previous and new level (0–100).
Transfer ownershipvehiclesvehicle_transferUse targetLicense / targetName for the new owner.
Delete vehicle (own script)vehiclesvehicle_deleteUse logVehicle('delete', …) or ReportVehicleDelete.
Always prefer logVehicle() over building the category and action by hand: that way your logs stay consistent with the panel and with other servers.

Automatic delete hook (other resources)

If your resource calls DeleteEntity or DeleteVehicle on cars, you can load the shared hook so WebLogs logs the deletion with your script’s name:

shared_scripts {
    '@Adictos_WebLogs/hooks/vehicle_delete_hook.lua',  -- después de otros hooks de AP si los hay
}
Adictos_WebLogs must be on the server (resource folder with hooks/vehicle_delete_hook.lua). That file goes in files {} of the WebLogs manifest; if it’s missing, the client shows Failed to load script @Adictos_WebLogs/hooks/vehicle_delete_hook.lua. Add Adictos_WebLogs to the dependencies of the resource that loads the hook.

WebLogs’ unified monitor merges these reports with AdvancedParking events and “vehicle lost while driving” warnings. Configurable in the panel → My servers → Manage → vehicles tab.

Quick reference of vehicle categories

  • vehicles — general actions (spawn, delete, get in/out, repair, fuel, transfer…)
  • vehicles_garage — store in and take out of the garage
  • vehicles_engine, vehicles_tuning, vehicles_build — other panel modules (create and enable the ones you use)
Category identifiers must exist and be active under My servers → Categories. Otherwise the log may not show up in the expected filter.

ShowPendingWarnings export (in-game warnings)

Shows the player the red warning screen with every panel warning they haven’t acknowledged yet (empty seen_at). If there are several, they appear in the same message (numbered). The player must hold SPACE for a few seconds to mark them as seen.

Useful when under My servers → Manage → Customisation you have “Show warnings automatically” turned off and want to force the notification from your script (jail, admin menu, when leaving a menu, 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
Parameter / returnDescription
playerIdThe player’s source on the server (source). Required
Returns trueThe pending-warnings query to the panel has been launched
Returns falsePlayer not connected, invalid ID, or export busy for that player

Behaviour

  • Queries the panel for that licence’s warnings with empty seen_at.
  • If there are none pending, nothing is shown.
  • If there is 1 warning: “Warning” screen with the reason and the staff member.
  • If there are 2 or more: title “Warnings (N)” and combined text [1/N] … / [2/N] … on the same screen.
  • When the SPACE hold completes, all the IDs shown become Seen in the panel and are not shown again.
  • Works even if the automatic notification toggle is turned off.

Example: on release from jail

RegisterNetEvent('mi_script:playerReleasedFromJail', function()
    local src = source
    if GetResourceState('Adictos_WebLogs') == 'started' then
        exports['Adictos_WebLogs']:ShowPendingWarnings(src)
    end
end)
The automatic notification (when warning from the panel or on connect) is configured under My servers → Manage → Customisation → In-game warnings. The export doesn’t depend on that setting.

AssignCommunityService / SendToCommunityService export

Community service built into Adictos_WebLogs (replaces esx_communityservice). The area, work points, animations and clothing (skinchanger numbers for male/female) are configured under My servers → Manage → Services. You can also place points and capture clothing from /apm with 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',
})
  • Enable the module under Manage → Services and remove ensure esx_communityservice from server.cfg (don’t run both at the same time).
  • If “Show warning on assignment” is ON, the player sees the red screen with the reason.
  • Compatibility (already inside WebLogs): events esx_serviciocomunitario:sendToCommunityService / esx_communityservice:….

Player loaded / ready (ESX, QBCore and Qbox)

Generic API to know when the character is loaded and when the player is actually ready in the world. Works with or without multicharacter.

There are two levels. Register handlers on the server (WebLogsFramework in shared/framework.lua + shared/framework/lifecycle.lua, or exports):

LevelAPIWhen
1. CharacteronPlayerLoaded / IsCharacterLoadedThe core already has the xPlayer / Player (after choosing a character in multichar, or on load without multichar)
2. Ready in the worldonPlayerFullyReady / IsPlayerFullyReadyIn addition, the client confirms the ped is active, alive and has valid coordinates
playerConnecting / playerJoining
    │
    ▼
Multichar (optional) → choose character
    │
    ▼
esx:playerLoaded / QBCore:OnPlayerLoaded / qbx_core:…
    │
    ▼
WebLogsFramework.onPlayerLoaded  ← character in framework
    │
    ▼
Client ACK (ped alive + coords)
    │
    ▼
WebLogsFramework.onPlayerFullyReady  ← ready in the world
-- 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
Export / functionDescription
OnPlayerLoaded(handler)Callback when the character is in the framework
OnPlayerFullyReady(handler)Callback when the ped is ready in the world (handler(src, meta))
IsCharacterLoaded(src)Boolean: character loaded
IsPlayerFullyReady(src)Boolean: client ACK received
WebLogsFramework.getName()Returns esx, qb, qbx, nd or custom

Options (Custom)

OptionDefaultUse
playerReadyDelayMs1500Wait after the character loads (multichar / inventory) before requesting the ACK
playerReadyRequireAlivetrueRequires a living ped + valid coords on the client
playerReadyTimeoutMs600000Maximum time waiting for the ACK (ms; internal minimum 30 s)
In-game warnings and giveaway prizes use onPlayerFullyReady internally, so no UI is shown before the ped exists.
Don’t use playerConnecting / playerJoining to give items or teleport: the character may not exist yet. Prefer onPlayerFullyReady.