Comprendre et utiliser les exports et events dans FiveM

Comprendre comment utiliser exports et events FiveM constitue une étape fondamentale pour tout développeur souhaitant créer des scripts performants et modulaires en 2025. Les exports permettent de partager des fonctions entre ressources, tandis que les events assurent la communication client-serveur et inter-ressources. Ce guide complet vous accompagne pas à pas dans la maîtrise de ces mécanismes essentiels, avec des exemples concrets, des bonnes pratiques et des astuces d’optimisation pour transformer vos projets FiveM en expériences fluides et professionnelles.

Comprendre les exports FiveM : partage de fonctions entre ressources

Les exports représentent le système natif de FiveM pour exposer des fonctions d’une ressource vers d’autres. Contrairement aux événements qui transmettent des données, les exports retournent directement des valeurs, ce qui les rend particulièrement adaptés aux opérations synchrones comme la récupération d’informations de joueur, de statut ou de configuration.

Déclaration d’un export côté serveur

Pour déclarer un export serveur, utilisez la syntaxe suivante dans votre script Lua :

exports('getNomJoueur', function(source)
    local xPlayer = ESX.GetPlayerFromId(source)
    if xPlayer then
        return xPlayer.getName()
    end
    return nil
end)

Cette fonction devient accessible depuis n’importe quelle autre ressource via exports['nom_ressource']:getNomJoueur(source). L’avantage majeur réside dans la simplicité d’utilisation : pas besoin de callback complexe, la valeur est retournée immédiatement.

Déclaration d’un export côté client

Côté client, le principe reste identique. Voici un exemple pour exposer une fonction qui vérifie si un joueur est en véhicule :

exports('estEnVehicule', function()
    local ped = PlayerPedId()
    return IsPedInAnyVehicle(ped, false)
end)

D’autres ressources peuvent alors appeler exports['ma_ressource']:estEnVehicule() pour obtenir un booléen instantanément. Cette approche favorise la réutilisabilité du code et évite les duplications.

Bonnes pratiques pour les exports

• Nommage explicite : utilisez des noms de fonctions clairs (getPlayerMoney, isPlayerAdmin) pour faciliter la maintenance
• Validation des paramètres : vérifiez toujours la validité des arguments reçus pour éviter les erreurs runtime
• Documentation : commentez vos exports avec les paramètres attendus et les valeurs de retour
• Performance : évitez les opérations lourdes dans les exports appelés fréquemment

Pour héberger vos scripts et tester vos exports dans des conditions professionnelles, LocationFiveM propose des serveurs optimisés avec des performances garanties et un support technique réactif.

Maîtriser les events FiveM : communication client-serveur efficace

Les events (événements) constituent le système de messagerie de FiveM. Ils permettent une communication asynchrone entre client et serveur, ainsi qu’entre différentes ressources. Contrairement aux exports, les events ne retournent pas de valeur directement mais déclenchent des actions à distance.

Types d’événements dans FiveM

Exemple pratique : système de notification

Côté serveur, enregistrement et déclenchement de l’événement :

RegisterServerEvent('monscript:envoyerNotification')
AddEventHandler('monscript:envoyerNotification', function(message)
    local _source = source
    TriggerClientEvent('monscript:afficherNotif', _source, message)
end)

Côté client, réception et traitement :

RegisterNetEvent('monscript:afficherNotif')
AddEventHandler('monscript:afficherNotif', function(message)
    SetNotificationTextEntry('STRING')
    AddTextComponentString(message)
    DrawNotification(false, false)
end)

Cette architecture garantit que seul le serveur peut déclencher l’affichage de notifications, renforçant la sécurité contre les abus clients.

Sécurisation des events

La sécurité des événements représente un enjeu majeur en 2025. Voici les règles d’or :

• Validation serveur systématique : ne faites jamais confiance aux données reçues du client
• Vérification des permissions : contrôlez toujours les droits avant d’exécuter une action sensible
• Rate limiting : limitez la fréquence d’appel des events pour éviter le spam
• Logs détaillés : enregistrez les actions importantes pour détecter les comportements suspects

Exemple de validation robuste :

RegisterServerEvent('banque:retirerArgent')
AddEventHandler('banque:retirerArgent', function(montant)
    local _source = source
    local xPlayer = ESX.GetPlayerFromId(_source)
    
    if not xPlayer then return end
    if type(montant) ~= 'number' or montant  50000 then
        banPlayer(_source, 'Tentative de retrait invalide')
        return
    end
    
    if xPlayer.getAccount('bank').money >= montant then
        xPlayer.removeAccountMoney('bank', montant)
        xPlayer.addMoney(montant)
    end
end)

Exports vs Events : quand utiliser chaque méthode ?

Choisir entre exports et events FiveM dépend du contexte et des besoins spécifiques de votre script. Chaque méthode présente des avantages distincts qui la rendent plus adaptée à certaines situations.

Utilisez les exports quand :

• Vous avez besoin d’une valeur de retour immédiate (getPlayerMoney, isPlayerOnline)
• L’opération est synchrone et rapide (pas d’attente de base de données)
• Vous créez une API publique pour votre ressource
• La fonction est appelée fréquemment et nécessite des performances optimales

Utilisez les events quand :

• L’action nécessite une communication client-serveur
• Vous devez notifier plusieurs ressources ou joueurs simultanément
• L’opération est asynchrone (requêtes base de données, délais)
• Vous implémentez des systèmes d’hooks permettant à d’autres ressources de réagir

Combinaison des deux approches

Les développeurs expérimentés combinent souvent exports et events pour créer des systèmes robustes. Par exemple, un système d’inventaire pourrait exposer un export getItemCount(itemName) pour les vérifications rapides, tout en utilisant des events inventory:itemAdded pour notifier les autres ressources des changements.

-- Export pour lecture rapide
exports('getItemCount', function(source, itemName)
    return inventoryData[source][itemName] or 0
end)

-- Event pour modification avec notification
RegisterServerEvent('inventory:addItem')
AddEventHandler('inventory:addItem', function(itemName, count)
    local _source = source
    inventoryData[_source][itemName] = (inventoryData[_source][itemName] or 0) + count
    TriggerEvent('inventory:itemAdded', _source, itemName, count)
end)

Performance et optimisation

Les exports sont généralement plus performants pour les appels locaux répétés, car ils n’impliquent pas de sérialisation réseau. En revanche, les events sont indispensables dès qu’une communication réseau est nécessaire. Selon une analyse technique publiée sur la documentation officielle FiveM, les exports peuvent être jusqu’à 40% plus rapides pour les opérations locales.

Cas d’usage avancés et patterns de développement

La maîtrise complète des exports et events FiveM passe par l’application de patterns éprouvés qui structurent efficacement vos projets et facilitent la collaboration en équipe.

Pattern Observer avec les events

Le pattern Observer permet à plusieurs ressources de réagir à un événement sans couplage fort. Par exemple, un système de mort de joueur :

-- Ressource principale
AddEventHandler('gameEventTriggered', function(name, args)
    if name == 'CEventNetworkEntityDamage' then
        local victim = args[1]
        local attacker = args[2]
        if IsEntityDead(victim) and IsEntityAPed(victim) then
            local victimId = NetworkGetPlayerIndexFromPed(victim)
            TriggerEvent('joueur:estMort', victimId, attacker)
        end
    end
end)

-- Autres ressources peuvent écouter
AddEventHandler('joueur:estMort', function(victimId, attacker)
    -- Statistiques, logs, pénalités, etc.
end)

Système de middleware pour validation

Créez un système de middleware réutilisable pour valider les events :

function createSecuredEvent(eventName, validator, handler)
    RegisterServerEvent(eventName)
    AddEventHandler(eventName, function(...)
        local _source = source
        local args = {...}
        
        if validator(_source, table.unpack(args)) then
            handler(_source, table.unpack(args))
        else
            print(('Event %s bloqué pour %s'):format(eventName, GetPlayerName(_source)))
        end
    end)
end

-- Utilisation
createSecuredEvent('shop:acheterItem', 
    function(source, itemId, quantity)
        return type(itemId) == 'string' and type(quantity) == 'number' and quantity > 0
    end,
    function(source, itemId, quantity)
        -- Logique d'achat sécurisée
    end
)

Exports asynchrones avec callbacks

Bien que les exports soient synchrones, vous pouvez implémenter des callbacks pour les opérations asynchrones :

exports('recupererDonneesDB', function(playerId, callback)
    MySQL.Async.fetchAll('SELECT * FROM users WHERE identifier = @id', {
        ['@id'] = GetPlayerIdentifier(playerId, 0)
    }, function(result)
        if callback then callback(result) end
    end)
end)

-- Appel depuis une autre ressource
exports['ma_ressource']:recupererDonneesDB(source, function(data)
    print('Données récupérées:', json.encode(data))
end)

Gestion d’état centralisée

Pour les projets complexes, créez une ressource dédiée à la gestion d’état exposant des exports et diffusant des events :

-- Ressource 'gamestate'
local serverState = {
    meteo = 'CLEAR',
    heure = 12,
    joueurs = {}
}

exports('getState', function(key)
    return serverState[key]
end)

function setState(key, value)
    serverState[key] = value
    TriggerClientEvent('gamestate:updated', -1, key, value)
end

exports('setState', setState)

Cette architecture favorise la cohérence des données et simplifie le débogage. Pour tester ces architectures avancées dans des conditions optimales, les serveurs proposés sur LocationFiveM offrent les ressources nécessaires avec des temps de réponse minimaux et une stabilité maximale.

Debugging et monitoring

Implémentez un système de logging pour tracer les appels d’exports et events :

local function logEvent(eventType, eventName, source, data)
    local logEntry = {
        timestamp = os.time(),
        type = eventType,
        name = eventName,
        source = source,
        data = data
    }
    -- Envoi vers système de monitoring
    TriggerEvent('logger:save', logEntry)
end

-- Wrapper pour RegisterServerEvent
function RegisterTrackedServerEvent(eventName, handler)
    RegisterServerEvent(eventName)
    AddEventHandler(eventName, function(...)
        logEvent('server_event', eventName, source, {...})
        handler(...)
    end)
end

Cette approche permet d’identifier rapidement les problèmes de performance ou les tentatives d’exploitation.

Maîtriser comment utiliser exports et events FiveM en 2025 vous permet de concevoir des scripts modulaires, performants et sécurisés. Les exports excellent dans la récupération synchrone de données, tandis que les events gèrent brillamment les communications asynchrones et les notifications multi-ressources. En combinant judicieusement ces deux mécanismes et en appliquant les patterns avancés présentés dans ce guide, vous développerez des systèmes robustes et maintenables qui élèveront la qualité de votre serveur FiveM. L’investissement dans la compréhension profonde de ces fondamentaux se traduit directement par des expériences de jeu fluides et une architecture technique solide.

FAQ