Le plugin de vote Serveur Privé pour les serveurs FiveM (2.0) est disponible

Le plugin de vote FiveM Serveur Privé permet de récompenser automatiquement les joueurs qui votent pour votre serveur : argent en jeu, items, ou toute action personnalisée via des hooks Lua. Il fonctionne avec ESX, QBCore et Qbox, nécessite oxmysql et un serveur FiveM build 9515 ou supérieur, et s'installe en décompressant un dossier dans resources. La version 2.0 intègre l'autodétection des frameworks. Voici comment le mettre en place étape par étape.

Ce qu'il faut retenir

Le plugin sp-vote détecte les votes Serveur Privé toutes les 30 secondes via l'API et déclenche la récompense en jeu, sans commande à saisir par le joueur.
Trois frameworks supportés officiellement : ESX, QBCore et Qbox. L'autodétection via Config.Framework = 'auto' évite toute configuration manuelle dans 90 % des cas.
La récompense se règle simplement (Config.Reward.Money) ou via une fonction Lua personnalisée (Config.Reward.Handler) pour brancher n'importe quelle mécanique de votre économie.
Deux événements Lua (preVoteReward et postVoteReward) permettent de conditionner ou tracer chaque récompense sans toucher au code du plugin.

Installation en 7 étapes

La procédure prend une dizaine de minutes sur un serveur déjà en place. Compter plus long si oxmysql ou le framework RP ne sont pas encore installés.

Téléchargez la dernière version du plugin depuis la page plugins Serveur Privé et décompressez le dossier sp-vote dans le dossier resources de votre serveur FiveM.
Installez oxmysql si ce n'est pas déjà fait, et configurez sa connexion à la base de données de votre serveur.
Ouvrez sp-vote/config.lua et choisissez la valeur de Config.Framework : 'auto' pour l'autodétection (recommandé), ou explicitement 'esx', 'qbcore' ou 'qbox'.
Renseignez Config.Token avec le token API de votre fiche Serveur Privé, disponible dans votre espace de gestion. Gardez-le privé, ne le partagez avec personne, ne le commitez pas dans un repo public.
Réglez Config.Locale sur 'fr' ou 'en' selon la langue de votre communauté, et Config.Reward.Money sur le montant par vote (500 par défaut).
Dans server.cfg, ordonnez les ensure dans le bon ordre : ensure oxmysql, puis votre framework (ensure es_extended, ensure qb-core ou ensure qbx_core), puis ensure sp-vote.
Redémarrez le serveur. Au premier démarrage, le plugin crée automatiquement la table sp_vote_rewards dans votre base de données. Vérifiez dans les logs qu'aucune erreur d'accès n'est remontée.

Aucun fichier SQL à importer manuellement, aucune migration à jouer. La table est créée et mise à jour automatiquement au démarrage, à condition que le compte SQL ait bien les droits CREATE et ALTER. Le ZIP inclut les messages joueurs en français et en anglais dans le même paquet : la sélection se fait via Config.Locale, le code source et les messages console restent en anglais.

Notre avis

Ne testez pas le plugin directement sur votre serveur de production. Créez une instance FiveM de test avec la même version, le même framework et une base de données jetable. Une erreur de configuration côté Config.Token, un handler Lua qui plante, ou une commande de récompense mal paramétrée peuvent perturber l'économie de votre serveur ou générer des logs bruités dans votre framework. Une fois la mécanique validée sur le serveur de test, la bascule en production prend cinq minutes.

Comment le joueur reçoit sa récompense

La procédure côté joueur est volontairement réduite au minimum. Voici ce qui se passe concrètement.

Vous redirigez le joueur sur la fiche de votre serveur sur Serveur Privé et il vote en indiquant son pseudo FiveM, celui affiché en jeu, pas le nom de son personnage RP.
Le plugin interroge notre API toutes les 30 secondes pour récupérer la liste des votes récents.
Dès qu'un vote est identifié comme non traité, le plugin exécute la logique de récompense : ajout d'argent, item, effet personnalisé, selon la configuration.
Si le joueur est en jeu au moment du vote, la récompense est attribuée immédiatement. S'il est hors ligne, elle est mise en attente et attribuée à sa prochaine connexion.

Un point d'attention à communiquer à votre communauté : un pseudo est modifiable et ne constitue pas une preuve d'identité. Un joueur qui change son pseudo FiveM entre le vote et la connexion risque de ne pas recevoir sa récompense, le plugin cherchant le pseudo exact utilisé lors du vote. Un rappel visible sur votre fiche ou votre Discord évite les tickets de support récurrents.

Personnaliser la récompense : argent, items ou logique métier

La configuration par défaut donne un montant fixe en argent à chaque vote. Pour la majorité des serveurs, ça suffit. Pour ceux qui veulent aller plus loin, une fonction Lua personnalisée prend le relais.

Configuration simple : montant fixe en argent

Éditez sp-vote/config.lua et réglez la valeur :

Config.Reward.Money = 500

Cette valeur est attribuée directement dans le portefeuille du joueur, selon la logique par défaut du framework détecté. Aucune ligne de code Lua à écrire.

Configuration avancée : handler Lua personnalisé

Pour toute logique plus complexe (versement sur compte bancaire, ajout d'un item, récompense conditionnelle, boost temporaire), on utilise Config.Reward.Handler. Cette fonction remplace complètement Config.Reward.Money. Voici les exemples officiels pour chaque framework, versant 750 sur le compte bancaire du joueur.

Exemple ESX :

Config.Reward.Handler = function(source, player, vote)
    if not player.getAccount('bank') then
        return false
    end
    return player.addAccountMoney('bank', 750, 'serveur-prive-vote') ~= false
end

Exemple QBCore :

Config.Reward.Handler = function(source, player, vote)
    return player.Functions.AddMoney('bank', 750, 'serveur-prive-vote') == true
end

Exemple Qbox :

Config.Reward.Handler = function(source, player, vote)
    return exports.qbx_core:AddMoney(source, 'bank', 750, 'serveur-prive-vote') == true
end

Choisissez un seul exemple, celui qui correspond à votre framework, et placez-le dans sp-vote/config.lua. Aucune modification côté client n'est nécessaire.

Retour de la fonction : ce que ça signifie vraiment

Le comportement du plugin dépend directement de ce que retourne votre handler. Trois cas à connaître.

Retour	Comportement du plugin	Cas d'usage
true	Vote marqué comme récompensé, aucun retry	Récompense attribuée avec succès
false	Retry automatique au prochain passage (environ 30 secondes)	Joueur temporairement injoignable ou condition non remplie
Erreur Lua ou retour manquant	Vote bloqué pour vérification manuelle	Bug dans le handler à corriger avant reprise

Pour les votes bloqués en vérification manuelle, deux commandes console permettent de trancher après contrôle du paiement :

sp_vote_resolve <voted_at> rewarded <username...>
sp_vote_resolve <voted_at> retry <username...>

La première marque le vote comme récompensé sans retry. La seconde relance le processus au prochain passage du plugin.

Nos conseils

Testez votre handler personnalisé sur un compte de test avant de le déployer. Une erreur classique consiste à retourner nil à la place de true après une opération réussie, ce qui bloque le vote en vérification manuelle et remplit inutilement votre file d'attente. Une seconde erreur fréquente : oublier le cas où le joueur n'a pas encore chargé son compte bancaire (ESX) au moment du vote. Le return false dans ce cas permet un retry naturel dès que le compte est prêt, sans intervention.

Événements Lua : personnaliser autour de la récompense

Deux événements permettent d'agir avant et après chaque récompense, sans toucher au code du plugin.

preVoteReward : conditionner ou annuler

L'événement sp-vote:preVoteReward(playerSource, vote) se déclenche avant l'attribution de la récompense. Appeler CancelEvent() annule définitivement la récompense pour ce vote, sans réessai. Cas d'usage typiques : ne pas récompenser un joueur en instance parallèle, filtrer selon son grade, appliquer une règle temporelle.

postVoteReward : journaliser ou notifier

L'événement sp-vote:postVoteReward(playerSource, vote) se déclenche après une récompense réussie. Idéal pour logger dans votre système de suivi, envoyer une notification Discord, ou déclencher un effet visuel en jeu.

Exemple complet côté serveur

Voici un exemple qui combine les deux événements : annulation hors de l'instance 0, journalisation des récompenses accordées.

AddEventHandler('sp-vote:preVoteReward', function(playerSource, vote)
    if GetPlayerRoutingBucket(playerSource) ~= 0 then
        CancelEvent()
    end
end)

AddEventHandler('sp-vote:postVoteReward', function(playerSource, vote)
    print(('[sp-vote] Reward confirmed for %s (source %s, player %s, vote %s)'):format(
        vote.username, tostring(playerSource), vote.player_identifier, vote.voted_at
    ))
end)

Le payload vote contient trois champs : username (pseudo FiveM utilisé pour voter), voted_at (horodatage du vote) et player_identifier (identifiant persistant du personnage préfixé selon le framework). Attention à playerSource dans le postVoteReward : il peut être nil après une déconnexion ou un changement de personnage entre le vote et l'attribution. Toujours vérifier avant de l'utiliser dans un appel qui l'exige. Le vote.player_identifier reste disponible dans tous les cas.

Gestion des votes en attente et rétention

Le plugin gère automatiquement le cycle de vie des votes sans intervention manuelle, avec deux règles simples.

Nettoyage horaire. Le plugin exécute un nettoyage automatique chaque heure. Un vote payé ou annulé est supprimé de la table uniquement quand le vote ET son paiement (ou son annulation) datent tous les deux de plus de 7 jours. Cette rétention laisse suffisamment de temps pour investiguer un litige joueur sans surcharger la base de données à long terme.

Conservation des votes en cours. Les votes en attente d'attribution (joueur hors ligne, retry actif) et ceux bloqués pour vérification manuelle sont conservés indéfiniment. Aucun risque de perdre un vote légitime à cause d'un joueur qui ne s'est pas connecté depuis 2 semaines : la récompense l'attend à sa prochaine session.

Vous êtes bloqué ou vous rencontrez un problème ? Nos développeurs peuvent vous aider à intégrer et configurer le plugin FiveM. Ouvrez un ticket sur notre Discord, nous vous répondons rapidement.

Foire aux questions

Le plugin est-il gratuit ?

Oui. Le plugin de vote FiveM Serveur Privé est entièrement gratuit à télécharger et à utiliser. Aucune fonctionnalité n'est verrouillée derrière un abonnement, aucun frais d'installation, aucune limitation liée à la taille de votre serveur ou au nombre de votes traités.

Fonctionne-t-il avec les serveurs FiveM hébergés chez Oxygenserv, Minestrator ou tout autre provider ?

Oui, le plugin fonctionne sur n'importe quel hébergement FiveM qui accepte l'ajout de ressources personnalisées dans le dossier resources. Aucune dépendance à un hébergeur spécifique. Vérifiez simplement que votre offre autorise l'installation de ressources tierces et l'utilisation d'oxmysql, ce qui est le cas de la quasi-totalité des offres FiveM du marché.

Que se passe-t-il si le joueur vote avec le mauvais pseudo FiveM ?

Le vote est comptabilisé côté Serveur Privé mais aucune récompense n'est attribuée en jeu, puisque le plugin ne trouve pas de joueur correspondant à ce pseudo. La récompense reste en attente indéfiniment tant qu'aucun joueur ne se connecte avec ce pseudo exact. Communiquez systématiquement à votre communauté d'utiliser leur pseudo FiveM affiché en jeu, pas leur nom de personnage RP.

Peut-on donner des récompenses différentes selon le type de joueur (VIP, staff, débutant) ?

Oui, via Config.Reward.Handler. La fonction reçoit l'objet player du framework, sur lequel vous pouvez lire n'importe quelle propriété (grade, job, groupe VIP, ancienneté) et adapter le montant ou le type de récompense en conséquence. C'est l'un des cas d'usage les plus fréquents du handler personnalisé.

Le plugin gère-t-il les redémarrages de serveur pendant le processus de récompense ?

Oui. Les votes sont persistés en base de données dès leur récupération depuis l'API. Un redémarrage serveur en plein milieu d'un traitement ne fait perdre aucun vote : au redémarrage, le plugin reprend la liste des votes non traités et poursuit les attributions.

Peut-on utiliser le plugin sans framework RP (serveur PvP classique) ?

Non officiellement. Le plugin nécessite ESX, QBCore ou Qbox pour fonctionner. Un serveur FiveM PvP pur sans framework RP n'a pas le socle attendu par le plugin. Un contournement partiel est possible en installant un framework minimaliste juste pour le plugin, mais ce n'est pas la configuration recommandée.

Comment vérifier que le plugin communique bien avec l'API Serveur Privé ?

Consultez les logs de votre serveur FiveM après le démarrage de sp-vote. Le plugin logge son état de connexion, ses appels API et les récompenses attribuées. Un vote de test depuis votre fiche Serveur Privé (avec un pseudo présent sur le serveur) permet de valider toute la chaîne en moins d'une minute. Si les logs n'affichent aucun appel API, vérifiez d'abord la valeur de Config.Token et l'accès sortant HTTPS de votre serveur.