Introduction à l’API Cfx.re : tout ce que les débutants doivent savoir

L’API Cfx.re est au cœur de tout serveur FiveM et RedM en 2025, permettant aux développeurs d’exploiter des fonctions natives, de gérer les joueurs, de manipuler les entités et de créer des expériences immersives. Ce guide débutant vous accompagne pas à pas pour comprendre comment utiliser l’API Cfx.re efficacement, depuis l’installation des outils jusqu’à la création de vos premiers scripts professionnels.

Qu’est-ce que l’API Cfx.re et pourquoi l’utiliser ?

L’API Cfx.re représente l’ensemble des fonctions natives et des événements mis à disposition par la plateforme Cfx.re (CitizenFX) pour développer sur FiveM et RedM. Elle permet de communiquer entre le client et le serveur, de manipuler des entités du jeu (véhicules, PNJ, objets), de gérer les permissions, de stocker des données et bien plus encore.

Les avantages majeurs de l’API Cfx.re

En 2025, l’API Cfx.re offre une documentation exhaustive, régulièrement mise à jour, accessible via le site officiel de Cfx.re. Elle intègre des milliers de natives GTA V et RDR2, ainsi que des fonctions spécifiques FiveM comme RegisterCommand, TriggerEvent, AddEventHandler ou encore exports. Voici pourquoi elle est incontournable :

• Polyvalence : compatible avec Lua, JavaScript et C#, elle s’adapte à tous les profils de développeurs.
• Performance : optimisée pour gérer des centaines de joueurs simultanément sans latence.
• Communauté active : forums, Discord officiel et dépôts GitHub regorgent d’exemples concrets.
• Évolutivité : mises à jour régulières intégrant les nouvelles natives Rockstar et correctifs de sécurité.

Documentation officielle et ressources

La documentation de l’API Cfx.re est disponible sur docs.fivem.net. Ce portail centralise toutes les natives, événements et exemples de code. Chaque fonction est détaillée avec ses paramètres, valeurs de retour et cas d’usage typiques. Pour débuter, familiarisez-vous avec les sections Client Functions, Server Functions et Events.

Préparer son environnement de développement pour l’API Cfx.re

Avant de coder, vous devez configurer un environnement stable et performant. Cela inclut l’installation du serveur FiveM, d’un éditeur de code adapté et la compréhension de la structure des ressources.

Installer un serveur FiveM local

Pour tester vos scripts sans risque, installez un serveur local. Téléchargez les artefacts FiveM depuis le site officiel Cfx.re. Décompressez l’archive, lancez FXServer.exe (Windows) ou run.sh (Linux), puis éditez le fichier server.cfg pour définir le nom du serveur, le nombre de slots et les ressources à charger automatiquement.

Si vous préférez une solution clé en main, Location FiveM propose des hébergements optimisés avec l’API Cfx.re pré-configurée, bases de données MariaDB, panel de gestion et support francophone réactif, idéal pour éviter les complications techniques.

Choisir un éditeur de code

Visual Studio Code (VS Code) est l’éditeur le plus populaire en 2025 pour développer avec l’API Cfx.re. Installez les extensions suivantes pour maximiser votre productivité :

• Lua (sumneko.lua) : autocomplétion, diagnostics et analyse syntaxique.
• vscode-fivem : snippets spécifiques FiveM et intégration natives.
• Bracket Pair Colorizer : facilite la lecture des blocs imbriqués.
• GitLens : gestion de versions et collaboration sur GitHub.

Structure d’une ressource FiveM

Chaque script FiveM est une ressource organisée dans un dossier contenant au minimum un fichier fxmanifest.lua. Ce manifeste déclare le nom, la version, les fichiers client et serveur, ainsi que les dépendances. Exemple type :

fx_version 'cerulean'
game 'gta5'

author 'VotreNom'
description 'Ma première ressource avec l\'API Cfx.re'
version '1.0.0'

client_scripts {
    'client.lua'
}

server_scripts {
    'server.lua'
}

Créez ensuite client.lua et server.lua pour coder respectivement côté joueur et côté serveur.

Premiers pas avec l’API Cfx.re : commandes, événements et natives

Une fois l’environnement prêt, explorez les concepts fondamentaux de l’API Cfx.re : commandes, événements et natives. Ces trois piliers constituent la base de tout script FiveM.

Créer une commande simple

Les commandes permettent aux joueurs d’interagir via le chat. Utilisez RegisterCommand côté client ou serveur. Exemple côté serveur dans server.lua :

RegisterCommand('hello', function(source, args, rawCommand)
    local playerName = GetPlayerName(source)
    TriggerClientEvent('chat:addMessage', -1, {
        args = { 'Serveur', 'Bonjour ' .. playerName .. ' !' }
    })
end, false)

Tapez /hello dans le jeu et le serveur répondra dans le chat. La fonction GetPlayerName est une native de l’API Cfx.re qui récupère le pseudo du joueur.

Gérer les événements (AddEventHandler et TriggerEvent)

Les événements synchronisent les actions entre client et serveur. AddEventHandler écoute un événement, TriggerEvent (local) ou TriggerClientEvent/TriggerServerEvent (réseau) le déclenche. Exemple : notifier tous les clients quand un joueur se connecte (dans server.lua) :

AddEventHandler('playerConnecting', function(playerName, setKickReason, deferrals)
    local src = source
    deferrals.defer()
    Wait(0)
    deferrals.update('Vérification en cours...')
    Wait(1000)
    deferrals.done()
    TriggerClientEvent('chat:addMessage', -1, {
        args = { 'Connexion', playerName .. ' vient de rejoindre le serveur !' }
    })
end)

Utiliser les natives GTA V

Les natives sont des fonctions du moteur Rockstar, accessibles via l’API Cfx.re. Consultez la liste exhaustive des natives pour manipuler le gameplay. Exemple côté client (client.lua) pour donner une arme :

RegisterCommand('arme', function()
    local playerPed = PlayerPedId()
    GiveWeaponToPed(playerPed, GetHashKey('WEAPON_PISTOL'), 250, false, true)
    SetPedAmmo(playerPed, GetHashKey('WEAPON_PISTOL'), 250)
    print('Pistolet donné !')
end, false)

PlayerPedId(), GiveWeaponToPed et GetHashKey sont des natives de l’API Cfx.re. GetHashKey convertit un nom en identifiant numérique utilisé par le moteur.

Communiquer entre client et serveur

Créez un script où le client demande au serveur de vérifier une condition avant d’exécuter une action. Dans client.lua :

RegisterCommand('heal', function()
    TriggerServerEvent('monScript:demandeHeal')
end, false)

AddEventHandler('monScript:reponseHeal', function(autorise)
    if autorise then
        local playerPed = PlayerPedId()
        SetEntityHealth(playerPed, GetEntityMaxHealth(playerPed))
        print('Vous avez été soigné !')
    else
        print('Action refusée par le serveur.')
    end
end)

Dans server.lua :

AddEventHandler('monScript:demandeHeal', function()
    local src = source
    -- Vérifier une condition (ex: cooldown, permission)
    local autorise = true
    TriggerClientEvent('monScript:reponseHeal', src, autorise)
end)

Ce schéma garantit la sécurité : le client ne peut pas tricher, seul le serveur décide.

Techniques avancées et bonnes pratiques avec l’API Cfx.re

Maîtriser l’API Cfx.re implique d’adopter des méthodes professionnelles : gestion des exports, optimisation des performances, sécurisation des scripts et debugging efficace.

Utiliser les exports pour partager des fonctions

Les exports permettent à d’autres ressources d’appeler vos fonctions. Dans fxmanifest.lua, déclarez :

export 'maFonction'

Dans server.lua ou client.lua, définissez la fonction :

function maFonction(param)
    return 'Résultat : ' .. param
end

Une autre ressource peut l’appeler via exports['nom_ressource']:maFonction('test'). Cela favorise la modularité et la réutilisabilité du code.

Optimiser les performances

L’API Cfx.re offre des outils de profilage via la commande profiler dans la console F8. Identifiez les boucles coûteuses et remplacez Citizen.Wait(0) par des délais adaptés (ex: Wait(1000) pour 1 seconde). Évitez les natives dans des boucles infinies sans condition de sortie. Utilisez CreateThread pour les tâches asynchrones :

Citizen.CreateThread(function()
    while true do
        Wait(5000)
        print('Tâche toutes les 5 secondes')
    end
end)

Sécuriser vos scripts

Validez toujours les données côté serveur. Ne faites jamais confiance aux événements déclenchés par le client. Utilisez des ACE (Access Control Entries) pour restreindre les commandes :

RegisterCommand('admin', function(source, args)
    if IsPlayerAceAllowed(source, 'command.admin') then
        print('Commande admin exécutée')
    else
        print('Accès refusé')
    end
end, false)

Ajoutez dans server.cfg :

add_ace group.admin command.admin allow
add_principal identifier.steam:110000XXXXXXXX group.admin

Debugging avec l’API Cfx.re

Utilisez print() et la console F8 pour afficher des variables. Pour des logs serveur, consultez le fichier server.log. La commande restart nom_ressource recharge la ressource sans redémarrer le serveur. Pour intercepter les erreurs Lua, encadrez le code dans pcall :

local success, err = pcall(function()
    -- Code à risque
end)
if not success then
    print('Erreur : ' .. err)
end

Intégrer des bases de données

L’API Cfx.re supporte MySQL via mysql-async ou oxmysql. Installez la ressource, ajoutez-la dans server.cfg, puis configurez connection_string. Exemple de requête avec oxmysql dans server.lua :

local oxmysql = exports.oxmysql

RegisterCommand('checkdb', function(source)
    oxmysql:query('SELECT * FROM users WHERE id = ?', {source}, function(result)
        if result[1] then
            print('Utilisateur trouvé : ' .. result[1].name)
        end
    end)
end, false)

Cela permet de persister les données joueurs (inventaire, argent, permissions) de manière fiable et scalable.

Ressources et frameworks populaires

Des frameworks comme ESX, QBCore ou vRP encapsulent l’API Cfx.re pour accélérer le développement. Ils fournissent des systèmes de jobs, d’inventaire, de banque et de permissions prêts à l’emploi. Consultez leurs documentations respectives et leurs dépôts GitHub pour comprendre comment ils exploitent les natives et événements de l’API Cfx.re.

Cas pratique : créer un script de téléportation avec l’API Cfx.re

Consolidons les acquis en développant un script complet de téléportation. Le joueur tape /tp x y z pour se déplacer aux coordonnées spécifiées. Le serveur valide la commande avant d’autoriser le téléport.

Fichier fxmanifest.lua

fx_version 'cerulean'
game 'gta5'

author 'Guide API Cfx.re'
version '1.0.0'

client_scripts { 'client.lua' }
server_scripts { 'server.lua' }

Fichier server.lua

RegisterCommand('tp', function(source, args)
    if #args < 3 then
        TriggerClientEvent('chat:addMessage', source, { args = { 'Erreur', 'Usage: /tp x y z' } })
        return
    end

    local x, y, z = tonumber(args[1]), tonumber(args[2]), tonumber(args[3])
    if not x or not y or not z then
        TriggerClientEvent('chat:addMessage', source, { args = { 'Erreur', 'Coordonnées invalides' } })
        return
    end

    if IsPlayerAceAllowed(source, 'command.tp') then
        TriggerClientEvent('monScript:teleporter', source, x, y, z)
    else
        TriggerClientEvent('chat:addMessage', source, { args = { 'Erreur', 'Permission refusée' } })
    end
end, false)

Fichier client.lua

AddEventHandler('monScript:teleporter', function(x, y, z)
    local playerPed = PlayerPedId()
    SetEntityCoords(playerPed, x, y, z, false, false, false, true)
    print('Téléportation effectuée vers ' .. x .. ', ' .. y .. ', ' .. z)
end)

Configuration des permissions

Dans server.cfg, ajoutez :

add_ace group.moderator command.tp allow
add_principal identifier.steam:VOTRE_ID group.moderator

Seuls les modérateurs pourront se téléporter. Testez en lançant la ressource via ensure nom_ressource dans le fichier de configuration ou start nom_ressource en console.

Ce script démontre la puissance de l’API Cfx.re : validation serveur, communication réseau, utilisation de natives (SetEntityCoords, PlayerPedId) et gestion des permissions ACE.

Ressources complémentaires et communauté

Pour progresser avec l’API Cfx.re, exploitez les ressources communautaires. Le forum officiel Cfx.re (forum.cfx.re) centralise questions, tutoriels et annonces. Le Discord FiveM regroupe des milliers de développeurs prêts à partager astuces et corrections de bugs.

Sur GitHub, explorez les dépôts open-source (ex: ESX, QBCore, standalone scripts) pour étudier du code professionnel. Lisez les issues et pull requests pour comprendre les bonnes pratiques et les évolutions de l’API Cfx.re.

Enfin, si vous souhaitez vous concentrer sur le développement sans gérer l’infrastructure, Location FiveM propose des serveurs haute performance avec l’API Cfx.re entièrement configurée, bases de données incluses, sauvegardes automatiques et support technique francophone disponible 7j/7.

En maîtrisant l’API Cfx.re en 2025, vous débloquez un potentiel créatif illimité pour concevoir des serveurs FiveM uniques, performants et sécurisés. Les concepts abordés dans ce guide – commandes, événements, natives, exports, sécurité et optimisation – constituent les fondations solides sur lesquelles bâtir vos projets ambitieux. Pratiquez régulièrement, consultez la documentation officielle et échangez avec la communauté pour affiner vos compétences et rester à jour sur les dernières évolutions de la plateforme Cfx.re.

FAQ