Documentation / API d’intégration

API d’intégration

Connectez vos scripts FiveM à Adictos_WebLogs : integration.lua, WebLogsFramework (10.0), véhicules, carburant/réparation, inventaire, services et joueur prêt (ESX / QBCore / Qbox / ND).

Le fichier shared/integration.lua est l’API publique de logs. Depuis la 10.0, le bridge de framework (ESX/QB/Qbox/ND, inventaire, carburant, revive, joueur prêt) est WebLogsFramework.*. Configurez-le dans Mes serveurs → Framework ; Adictos_Core n’est pas nécessaire.

WebLogsFramework (10.0)

Adictos_WebLogs est autonome : il détecte le core et l’inventaire, donne/retire des objets, gère les casiers, le revive et le carburant. Gym / Quest / XP / Zombies utilisent Adictos_Core ; WebLogs non.

Modules du bridge (l’API publique ne change pas) :

FichierRôle
shared/framework.luaNoyau : détection, joueur, notify, noms IC, Custom
shared/framework/identifiers.luaFormat license/steam/multichar + synchronisation avec le panneau
shared/framework/lifecycle.luaonPlayerLoaded / onPlayerFullyReady
shared/framework/inventory/bridge.luaFournisseur ox / qb / ps / lj + give/remove/get
shared/framework/inventory/stashes.luaCasiers propriétaire, retours, stash de job
shared/framework/fuel.lua / revive.lua / vehicles.luaCarburant, revive et SQL de garage depuis le panneau

Utilisez shared/integration.lua, hooks/*.lua et les traductions pour les logs. Le bridge se configure dans le panneau ou via WebLogsFramework.* / exports.

API résumée

Fonction / exportUtilisation
WebLogsFramework.getName()esx, qb, qbx, nd ou custom
getPlayer / getPlayerByLicensexPlayer ou wrapper QB/ND
getInventoryProvider()ox, qb, qs ou custom (la ressource le signale au panneau)
addInventoryItem / removeInventoryItem / getInventoryItemsCRUD ox ou qb (qs/custom : hooks Custom.*)
registerOwnedStash / openOwnedStashCasier personnel (retours, APM)
executePanelReviveRevive selon le preset Framework
applyPanelFuelLive / applyPanelRepairLiveCarburant et réparation en direct
OnPlayerLoaded / OnPlayerFullyReadyExports : personnage chargé / ped dans le monde
-- 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
Mes serveurs → Gérer → Framework : mode (auto/ESX/QB/Qbox/ND), identifier, inventaire, revive et carburant. Différent de l’onglet Logs inventaire (filtres ox_lib).
Préférez les presets du panneau ou appelez WebLogsFramework.* / exports. Une mise à jour Cfx/Tebex peut écraser les modifications locales dans le Lua de la ressource.

Inclure integration.lua dans votre ressource

Ajoutez le fichier comme shared_script dans le fxmanifest.lua de votre ressource. Les fonctions serveur (log, logPlayer, listeners) n’existent que côté serveur ; côté client, vous n’avez que AdictosWebLogs.isAvailable().

fx_version 'cerulean'
game 'gta5'

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

server_scripts {
    'server/main.lua',
}
Prérequis : ensure Adictos_WebLogs doit venir avant, ou au moins être démarré lorsque votre ressource enregistre des logs. Vérifiez avec AdictosWebLogs.isAvailable() ou GetResourceState('Adictos_WebLogs') == 'started'.

Fonctions helper

FonctionDescription
AdictosWebLogs.isAvailable()Renvoie true si la ressource Adictos_WebLogs est démarrée (client et serveur).
AdictosWebLogs.log(category, action, data, sendDiscord)Envoie un log au panneau. sendDiscord vaut true par défaut. Serveur uniquement.
AdictosWebLogs.logPlayer(source, category, action, data, sendDiscord)Comme log, mais renseigne la licence et les noms à partir du source du joueur. Serveur uniquement.
AdictosWebLogs.logVehicle(action, source, data, sendDiscord)Recommandé pour les véhicules. Une seule fonction pour garage, carburant, réparation, transfert et suppression. Voir la section dédiée.
AdictosWebLogs.onLog(handler)Écoute chaque log accepté : handler(category, action, logEntry).
AdictosWebLogs.onConfigLoaded(handler)Se déclenche lorsque WebLogs charge la configuration distante du panneau.
AdictosWebLogs.onCKDone(handler)Se déclenche à la fin d’un CK : handler(identifier, success, totalDeleted).
AdictosWebLogs.onLicenseTransferDone(handler)Se déclenche à la fin d’un changement de licence : handler(oldLicense, newLicense, success, stats).
exports['Adictos_WebLogs']:ShowPendingWarnings(playerId)Affiche au joueur les avertissements du panneau qu’il n’a pas encore vus (écran rouge). Voir la section dédiée plus bas.

Exemple de base

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

Événements du système

Les noms officiels se trouvent dans AdictosWebLogs.Events. Vous pouvez les utiliser avec AddEventHandler ou les helpers d’integration.lua :

ConstanteÉvénementQuand il se déclenche
LOG_QUEUEDAdictos_WebLogs:onLogQueuedChaque fois qu’un log entre dans la file (avant l’envoi au panneau).
LOGS_SENTAdictos_WebLogs:onLogsSentAprès l’envoi d’un lot de logs au panneau.
CONFIG_LOADEDAdictos_WebLogs:onConfigLoadedConfiguration distante chargée (catégories, CK, etc.).
CONFIG_UPDATEDAdictos_WebLogs:onConfigUpdatedLe panneau pousse des changements de configuration à chaud.
CK_DONEAdictos_WebLogs:onCKDoneCK terminé depuis le panneau.
LICENSE_TRANSFER_DONEAdictos_WebLogs:onLicenseTransferDoneChangement de licence terminé.
PLAYER_BANNEDadictos:playerBannedBan appliqué depuis le panneau ou le système de sanctions.
PERMABAN_REQUESTadictos:webPermabanRequestDemande de permaban depuis le panneau.
-- 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 alternatifs (sans integration.lua)

Si vous ne voulez pas inclure le fichier partagé, vous pouvez appeler les exports de la ressource ou déclencher des événements réseau internes :

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()
L’export Log() accepte aussi un objet unique avec les champs category, action, license, player_name, etc. Pratique si vous avez déjà une table de données construite (comme dans esx_advancedgarage).

API véhicules unifiée (recommandée)

Vous n’avez besoin ni d’AdvancedParking, ni d’ox_fuel, ni d’esx_advancedgarage, ni d’aucun script particulier. Appelez simplement logVehicle() depuis votre garage, système de carburant ou mécanicien lorsque l’action est terminée en base de données. WebLogs s’occupe de la catégorie, de l’action et du texte du log.

Actions disponibles

ActionConstanteQuand l’appeler
Ranger au garagestore ou AdictosWebLogs.VehicleActions.STOREAprès avoir marqué le véhicule comme rangé en BD
Sortir du garageretrieveAprès avoir fait apparaître le véhicule pour le joueur
RéparerrepairAprès la mise à jour du moteur/de la carrosserie en BD ou sur l’entité
CarburantfuelAprès avoir changé le niveau de carburant
TransférertransferAprès avoir changé le propriétaire en BD
SupprimerdeleteAprès avoir supprimé l’enregistrement de la BD

Champs de <code>data</code>

ChampDescription
plateObligatoire. Plaque du véhicule.
fuel / fuel_before / fuel_afterNiveau de carburant (0–100).
engine_health / old_engineSanté du moteur (0–1000 dans GTA).
new_owner / targetLicense / targetNameNouveau propriétaire (transferts).
detailsTexte libre ; si vous l’omettez, WebLogs en génère un automatiquement.
via = 'panel'Indique que l’action provient du panneau web (staff).

Exemple — n’importe quel script de garage (serveur)

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

Exemple — script de carburant (serveur)

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

Exemple — mécanicien / réparation

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

Exemple — transfert ou suppression

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

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

Depuis le client (si l’événement naît côté client)

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

Sans integration.lua (export uniquement)

exports['Adictos_WebLogs']:LogVehicle('store', source, {
    plate = 'ABC 123',
    fuel = 75,
    engine_health = 900,
})
Les actions du panneau web (Garage, Réparer, Carburant, Transférer, Supprimer sur le profil du joueur) enregistrent déjà un log automatiquement avec le préfixe [Panel]. Aucun code supplémentaire n’est nécessaire pour cela.

Réparation / carburant en direct (WebLogsFramework)

Lorsque le staff clique sur Réparer ou Carburant dans Tickets, Carte en direct ou le profil du joueur, WebLogs met à jour la BD et, si le véhicule est apparu, applique le changement dans le monde. La logique se trouve dans shared/framework/fuel.lua. Elle s’utilise via WebLogsFramework.*.

Configurez le preset dans Mes serveurs → Gérer → Framework → Carburant depuis le panneau (auto, ox_fuel, LegacyFuel, ps-fuel, BD uniquement, etc.).

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

FonctionDescription
getPanelFuelTargetLevel()Niveau 0–100 configuré dans le panneau (preset Framework).
applyPanelFuelLive(vehicleHandle, fuelLevel?)Remplit le réservoir d’un véhicule apparu selon le preset (statebag ox_fuel, export SetFuel, événement custom ou BD uniquement).
applyPanelRepairLive(vehicleHandle)Répare la santé côté serveur et déclenche la réparation visuelle/physique sur tous les clients.
updateVehicleFuel(plate, propsJson, fuelLevel?)UPDATE de la colonne fuel + props JSON dans owned_vehicles / player_vehicles.
updateVehicleRepair(plate, propsJson)UPDATE du moteur/de la carrosserie en BD.

API client

FonctionDescription
applyClientVehicleFuel(vehicle, fuelLevel, exportResource?)Applique SetVehicleFuelLevel (et SetFuel s’il existe un export). Réapplique pendant plusieurs ticks pour qu’ox_fuel n’écrase pas le niveau avec l’ancienne valeur du natif.
applyClientVehicleRepair(vehicle)SetVehicleFixed, déformation, moteur/carrosserie/réservoir et saleté. Le bouton Réparer de l’APM l’utilise aussi.

Événements réseau

ÉvénementParamètresUtilisation
Adictos_WebLogs:panelSetVehicleFuelnetId, fuelLevel, exportResourceServeur → clients. exportResource vide = natif/statebag uniquement (ox_fuel).
Adictos_WebLogs:panelRepairVehiclenetIdServeur → clients. Réparation complète du véhicule streamé.

ox_fuel (recommandé)

  • Le preset auto détecte d’abord ox_fuel ; ou forcez le preset ox_fuel (type statebag).
  • Serveur : Entity(veh).state:set('fuel', level, true) — source de vérité d’ox_fuel.
  • Clients : SetVehicleFuelLevel est obligatoire si quelqu’un conduit ; sinon la boucle d’ox_fuel fait redescendre le réservoir avec GetVehicleFuelLevel.
  • N’utilisez pas l’événement client ox_fuel:setFuel pour augmenter le carburant : côté serveur il est reduceOnly (il ne fait que baisser).
  • ox_fuel n’exporte pas SetFuel ; ne choisissez pas le preset LegacyFuel si vous utilisez 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)
Le preset se choisit dans Mes serveurs → Framework → Carburant. Évitez de modifier server/map_panel.lua sauf si vous savez ce que change le builder.

Intégrations optionnelles (non obligatoires)

  • esx_advancedgarage — déjà intégré ; utilise LogVehicle en interne.
  • AdvancedParking — n’affecte que la carte en direct et la suppression automatique ; c’est vous qui ajoutez les logs de garage/carburant avec logVehicle.
  • Hook de suppression — optionnel ; détecte DeleteEntity sans que vous ayez à coder (voir ci-dessous).

Logs de véhicules — référence des catégories

SituationCatégorie suggéréeAction (action)Remarques
Envoyer le véhicule au garagevehicles_garagevehicle_storeCréez la catégorie vehicles_garage dans le panneau si elle n’existe pas.
Sortir le véhicule du garagevehicles_garagevehicle_retrieveMême catégorie que pour ranger.
Réparer le véhiculevehiclesvehicle_repairIncluez la plaque et le % moteur avant/après dans details ou raw_data.
Mettre / faire le plein de carburantvehiclesvehicle_fuelIndiquez le niveau précédent et le nouveau (0–100).
Transférer la propriétévehiclesvehicle_transferUtilisez targetLicense / targetName pour le nouveau propriétaire.
Supprimer le véhicule (script personnel)vehiclesvehicle_deleteUtilisez logVehicle('delete', …) ou ReportVehicleDelete.
Préférez toujours logVehicle() plutôt que de construire la catégorie et l’action à la main : vos logs resteront cohérents avec le panneau et avec les autres serveurs.

Hook automatique de suppression (autres ressources)

Si votre ressource appelle DeleteEntity ou DeleteVehicle sur des voitures, vous pouvez charger le hook partagé pour que WebLogs enregistre la suppression avec le nom de votre script :

shared_scripts {
    '@Adictos_WebLogs/hooks/vehicle_delete_hook.lua',  -- después de otros hooks de AP si los hay
}
Adictos_WebLogs doit être présent sur le serveur (dossier de la ressource avec hooks/vehicle_delete_hook.lua). Ce fichier figure dans files {} du manifeste de WebLogs ; s’il manque, le client affiche Failed to load script @Adictos_WebLogs/hooks/vehicle_delete_hook.lua. Ajoutez Adictos_WebLogs aux dependencies de la ressource qui charge le hook.

Le moniteur unifié de WebLogs fusionne ces rapports avec les événements d’AdvancedParking et les alertes « véhicule perdu pendant la conduite ». Configurable dans le panneau → Mes serveurs → Gérer → onglet véhicules.

Référence rapide des catégories de véhicules

  • vehicles — actions générales (spawn, suppression, monter/descendre, réparer, carburant, transférer…)
  • vehicles_garage — ranger et sortir du garage
  • vehicles_engine, vehicles_tuning, vehicles_build — autres modules du panneau (créez et activez celles que vous utilisez)
Les identifiants de catégorie doivent exister et être actifs dans Mes serveurs → Catégories. Sinon, le log peut ne pas apparaître dans le filtre attendu.

Export ShowPendingWarnings (avertissements en jeu)

Affiche au joueur l’écran rouge d’avertissement avec tous les avertissements du panneau qu’il n’a pas encore confirmés (seen_at vide). S’il y en a plusieurs, ils apparaissent dans le même message (numérotés). Le joueur doit maintenir ESPACE quelques secondes pour les marquer comme vus.

Utile lorsque, dans Mes serveurs → Gérer → Personnalisation, l’option « Afficher les avertissements automatiquement » est désactivée et que vous voulez forcer la notification depuis votre script (prison, menu admin, à la sortie d’un 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
Paramètre / retourDescription
playerIdSource du joueur sur le serveur (source). Obligatoire
Retour trueLa requête des avertissements en attente vers le panneau a été lancée
Retour falseJoueur non connecté, ID invalide ou export occupé pour ce joueur

Comportement

  • Interroge le panneau sur les avertissements de cette licence dont seen_at est vide.
  • S’il n’y en a aucun en attente, rien ne s’affiche.
  • S’il y a 1 avertissement : écran « Avertissement » avec le motif et le membre du staff.
  • S’il y en a 2 ou plus : titre « Avertissements (N) » et texte combiné [1/N] … / [2/N] … sur le même écran.
  • Une fois la touche ESPACE maintenue jusqu’au bout, tous les ID affichés passent à Vu dans le panneau et ne s’affichent plus.
  • Fonctionne même si l’option de notification automatique est désactivée.

Exemple : à la sortie de prison

RegisterNetEvent('mi_script:playerReleasedFromJail', function()
    local src = source
    if GetResourceState('Adictos_WebLogs') == 'started' then
        exports['Adictos_WebLogs']:ShowPendingWarnings(src)
    end
end)
La notification automatique (lors d’un avertissement depuis le panneau ou à la connexion) se configure dans Mes serveurs → Gérer → Personnalisation → Avertissements en jeu. L’export ne dépend pas de ce réglage.

Export AssignCommunityService / SendToCommunityService

Travaux d’intérêt général intégrés à Adictos_WebLogs (remplace esx_communityservice). La zone, les points de travail, les animations et les tenues (numéros skinchanger homme/femme) se configurent dans Mes serveurs → Gérer → Services. Vous pouvez aussi placer des points et capturer des tenues depuis /apm avec 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',
})
  • Activez le module dans Gérer → Services et retirez ensure esx_communityservice du server.cfg (n’exécutez pas les deux en même temps).
  • Si « Afficher un avertissement à l’attribution » est activé, le joueur voit l’écran rouge avec le motif.
  • Compatibilité (déjà incluse dans WebLogs) : événements esx_serviciocomunitario:sendToCommunityService / esx_communityservice:….

Joueur chargé / prêt (ESX, QBCore et Qbox)

API générique pour savoir quand le personnage est chargé et quand le joueur est réellement prêt dans le monde. Fonctionne avec ou sans multicharacter.

Il existe deux niveaux. Enregistrez des handlers côté serveur (WebLogsFramework dans shared/framework.lua + shared/framework/lifecycle.lua, ou exports) :

NiveauAPIQuand
1. PersonnageonPlayerLoaded / IsCharacterLoadedLe core dispose déjà du xPlayer / Player (après le choix du personnage en multichar, ou au chargement sans multichar)
2. Prêt dans le mondeonPlayerFullyReady / IsPlayerFullyReadyEn plus, le client confirme que le ped est actif, vivant et avec des coordonnées valides
playerConnecting / playerJoining
    │
    ▼
Multichar (optionnel) → choix du personnage
    │
    ▼
esx:playerLoaded / QBCore:OnPlayerLoaded / qbx_core:…
    │
    ▼
WebLogsFramework.onPlayerLoaded  ← personnage dans le framework
    │
    ▼
ACK client (ped vivant + coords)
    │
    ▼
WebLogsFramework.onPlayerFullyReady  ← prêt dans le monde

Utilisation recommandée

-- 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 / fonctionDescription
OnPlayerLoaded(handler)Callback lorsque le personnage est dans le framework
OnPlayerFullyReady(handler)Callback lorsque le ped est prêt dans le monde (handler(src, meta))
IsCharacterLoaded(src)Booléen : personnage chargé
IsPlayerFullyReady(src)Booléen : ACK client reçu
WebLogsFramework.getName()Renvoie esx, qb, qbx, nd ou custom

Options (Custom)

OptionPar défautUtilisation
playerReadyDelayMs1500Attente après le chargement du personnage (multichar / inventaire) avant de demander l’ACK
playerReadyRequireAlivetrueExige un ped vivant + des coords valides côté client
playerReadyTimeoutMs600000Durée maximale d’attente de l’ACK (ms ; minimum interne 30 s)
Les avertissements en jeu et les lots des tirages utilisent onPlayerFullyReady en interne, pour ne pas afficher d’interface avant que le ped n’existe.
N’utilisez pas playerConnecting / playerJoining pour donner des objets ou téléporter : le personnage peut ne pas encore exister. Préférez onPlayerFullyReady.