Garry's Mod (GLua)

L'installation des plugins est réservée au propriétaire du serveur de jeux.

Guide d'installation et de configuration du plugin QuantumLogs pour Garry's Mod.

Installation

1. Téléchargez le plugin qlogs_gmod depuis votre espace client

2. Extrayez le dossier dans le répertoire addons/ de votre serveur GMod :

   garrysmod/addons/qlogs_gmod/

3. Le plugin se charge automatiquement au démarrage du serveur

Configuration

Éditez le fichier lua/qlogs/sh_config.lua :

-- URL de votre instance QuantumLogs
QLogs.Config.API_URL = "https://votre-instance.quantumlogs.cloud/logs"

-- Votre clé API (trouvable dans votre espace client)
QLogs.Config.API_TOKEN = "votre-cle-api-ici"

-- Intervalle d'envoi des logs (en secondes)
QLogs.Config.SEND_INTERVAL = 10

-- Taille maximum de la file d'attente avant envoi forcé
QLogs.Config.MAX_QUEUE_SIZE = 1000

-- Envoyer les logs même sur les serveurs LAN (utile pour le dev)
QLogs.Config.SEND_ON_LAN = true

-- Mode debug (affiche les messages dans la console)
QLogs.Config.DEBUG = false

Intégrations disponibles

Le plugin GMod dispose de 70+ intégrations configurables. Activez ou désactivez chaque type de log selon vos besoins dans la section QLogs.Config.Integrations :

Logs de base (activés par défaut)

Intégration	Measurement	Description
PlayerConnection	player_connection	Connexions de joueurs (avec map et gamemode)
PlayerKill	player_kill	Kills (arme, distance, attaquant/victime)
PlayerChat	player_chat	Messages du chat (global/team)
PlayerDamage	player_damage	Dégâts infligés (avec HP)
PlayerSpawn	player_spawn	Apparitions de joueurs
PropSpawn	prop_spawn	Spawns de props, NPCs, véhicules, SENTs, SWEPs
AdminActions	admin_action	Commandes administrateur

DarkRP (désactivés par défaut)

Intégration	Description
DarkRP_Adverts	Publicités DarkRP
DarkRP_Jobs	Changements de métier
DarkRP_Money	Transactions d'argent
DarkRP_Arrests	Arrestations
DarkRP_Warrants	Mandats
DarkRP_Lockpick	Crochetage
DarkRP_Shipments	Livraisons
...	Et bien d'autres

Mods d'administration

Intégration	Description
Admin_ULX	Commandes ULX
Admin_SAM	Commandes SAM
Admin_ServerGuard	Commandes ServerGuard
Admin_AWarn	Avertissements AWarn

Gamemodes spécifiques

TTT, Murder, Cinema, Sandbox... Chaque gamemode dispose d'intégrations dédiées.

Important : Ne supprimez pas d'entrées dans la table QLogs.Config.Integrations. Pour désactiver une intégration, mettez sa valeur à false. Supprimer une ligne peut provoquer une erreur au chargement.

Logs personnalisés (customs)

Vous pouvez envoyer vos propres logs depuis n'importe quel script serveur Lua.

Création d'un log

local point = QLogs.Protocol.Point("mon_measurement")
    :AddPlayer("player", ply)
    :AddField("value", "Description de l'événement")

QLogs.Send(point)

AddPlayer - Noms de préfixe autorisés

La méthode AddPlayer(prefix, player) crée automatiquement des tags à partir du préfixe. Seuls deux préfixes sont reconnus par le backend :

Préfixe	Tags créés	Colonnes en base
"player"	player_name, player_global_id, player_id	Oui (indexés, filtrables)
"target"	target_name, target_global_id, target_id	Oui (indexés, filtrables)

N'utilisez pas d'autres préfixes (comme "attacker", "victim", "admin", etc.). Le backend ne reconnaît que "player" et "target". Les tags avec d'autres préfixes seront silencieusement ignorés et n'apparaîtront pas dans vos logs.

Exemple correct :

-- Kill : l'attaquant est "player", la victime est "target"
local point = QLogs.Protocol.Point("player_kill")
    :AddPlayer("player", attacker)   -- Crée player_name, player_global_id, player_id
    :AddPlayer("target", victim)     -- Crée target_name, target_global_id, target_id
    :AddField("value", attacker:Nick() .. " a tué " .. victim:Nick() .. " avec AK-47")

QLogs.Send(point)

Exemple incorrect :

-- NE PAS FAIRE : "attaquant" n'est pas reconnu par le backend
local point = QLogs.Protocol.Point("player_kill")
    :AddPlayer("attaquant", attacker)   -- Tags ignorés !
    :AddPlayer("victime", victim)       -- Tags ignorés !

AddField - Restrictions

La méthode AddField(key, value) n'accepte que certains types de valeurs :

Type	Accepté	Exemple
string	Oui	"Texte du log"
number	Oui	42, 3.14
boolean	Oui	true, false
table	Non	Provoque une erreur
nil	Non	Provoque une erreur

Le champ principal doit s'appeler "value". C'est le contenu textuel qui s'affiche dans la colonne Valeur du dashboard. Mettez toutes les informations utiles dans ce champ.

AddMetadata - Données libres

Pour des données structurées supplémentaires, utilisez AddMetadata :

local point = QLogs.Protocol.Point("player_kill")
    :AddPlayer("player", attacker)
    :AddPlayer("target", victim)
    :AddField("value", attacker:Nick() .. " a tué " .. victim:Nick())
    :AddMetadata("weapon", "AK-47")
    :AddMetadata("distance", 50.5)
    :AddMetadata("headshot", true)

QLogs.Send(point)

Les métadonnées acceptent tout type (strings, nombres, tables, etc.) et sont stockées en JSON. Elles sont visibles dans le détail du log mais ne sont pas filtrables directement.

Système de personnages

Si votre serveur utilise un framework RP (DarkRP, Helix, NutScript...), vous pouvez lier les logs aux personnages des joueurs :

hook.Add("QLogs.GetCharacterID", "MonSysteme", function(ply)
    return ply:GetCharacterID()  -- Adaptez selon votre framework
end)

L'ID du personnage sera stocké dans le champ player_id des logs.

Commandes console

Commande	Description
qlogs_test <nombre>	Génère des logs de test
qlogs_flush	Force l'envoi des logs en attente
qlogs_status	Affiche la taille de la file et le mode d'envoi

Mode d'envoi

Le plugin supporte deux modes d'envoi :

Mode DLL (haute performance)

Si le module DLL est installé, le plugin l'utilise automatiquement pour :

• Des requêtes HTTP asynchrones sans bloquer Lua

• Un buffer sur disque en cas de panne réseau

• Une file d'attente de 10 000 logs en mémoire

Mode Lua (fallback)

Sans le module DLL, le plugin utilise le module reqwest de Lua pour l'envoi synchrone par lots.

Vérification

Après installation :

1. Démarrez votre serveur GMod

2. Vérifiez dans la console qu'il n'y a pas d'erreur QLogs

3. Connectez-vous au serveur et effectuez quelques actions

4. Vérifiez dans le dashboard QuantumLogs que les logs apparaissent

Activez DEBUG = true dans la configuration pour voir les messages de diagnostic dans la console du serveur.