Boutique Tebex : coins et VIP

#Vue d'ensemble

La boutique premium de Socle s'ouvre en jeu avec F1. Les joueurs y dépensent deux monnaies :

Avec ces coins, ils achètent ce que tu as mis en rayon : armes, véhicules, argent (versé en banque), objets, animaux de compagnie, propriétés, packs, articles de la boutique journalière.

Tebex encaisse l'argent réel. Pour FiveM, Tebex livre un achat en faisant exécuter des commandes par ton serveur de jeu : une commande à l'achat, à l'expiration, au renouvellement, à la rétrofacturation, au remboursement (doc Tebex : les commandes).

Socle fournit quatre commandes console pour ça :

Tebex vend donc directement des coins et du VIP. Pour un véhicule, un animal ou une arme, vends des coins : c'est la boutique en jeu qui sait livrer ces articles (plaque générée, animal rangé dans « Mes animaux », arme dans l'inventaire). Il n'existe pas de caisse mystère.

#Comment Socle livre

#Commandes réservées à la console

Les quatre commandes ne fonctionnent que lancées par la console du serveur (c'est ce que fait Tebex). Un joueur qui les tape en jeu n'obtient rien, même administrateur.

#Une seule livraison par transaction

Chaque livraison est enregistrée avec son numéro de transaction, son action (coins, coins_remove, vip, vip_remove) et une période facultative. Un même trio ne s'applique qu'une fois : si Tebex renvoie la commande (ou si tu la relances), la console répond déjà traitée : ignorée et rien ne change. C'est pour ça que le numéro de transaction est obligatoire dans chaque commande.

La période est un dernier argument facultatif ([période]), sans espace, qui sert à distinguer les échéances d'un abonnement quand Tebex réutilise le même {transaction} à chaque renouvellement (voir Abonnement VIP). Sans période, rien ne change par rapport aux commandes existantes.

#Joueur absent : livraison en attente

Socle cherche le joueur parmi ceux connectés. S'il ne le trouve pas, la livraison est mise en attente et s'applique automatiquement quelques secondes après qu'il a chargé un personnage à sa prochaine connexion. Le joueur n'a donc pas besoin d'être en ligne au moment de l'achat.

Pour un VIP en attente, la durée démarre au moment de la livraison, pas au moment de l'achat.

#Remboursement d'une livraison pas encore faite

Si un retrait (socle_tebex_coins_remove ou socle_tebex_vip_remove) arrive pour une transaction dont la livraison est encore en attente, Socle annule la livraison au lieu de retirer quoi que ce soit. La console affiche livraison en attente annulée.

#Comment <joueur> est reconnu

L'argument <joueur> est comparé aux joueurs connectés :

La comparaison ignore les majuscules. Un argument ne peut pas contenir d'espace (la console découpe sur les espaces).

#Relier ta boutique Tebex au serveur

#1. Créer la boutique

1. Crée ton compte et ta boutique sur Tebex, avec FiveM comme jeu.
2. Dans le panneau de contrôle Tebex, va dans Integrations › Game Servers, clique Connect Game Server et choisis Plugin. Il n'y a rien à télécharger pour FiveM.
3. Tebex t'affiche la clé secrète du serveur. Garde-la pour toi : elle authentifie ton serveur auprès de Tebex.

Source : doc Tebex — FiveM.

#2. Ajouter la clé dans server.cfg

Ouvre server.cfg et ajoute la ligne (Tebex conseille de la mettre vers le bas du fichier) :

sv_tebexSecret "TA_CLE_SECRETE_TEBEX"

sv_tebexSecret est une convar de FiveM lui-même (doc FiveM — commandes serveur).

#3. Vérifier la connexion

1. Redémarre le serveur de jeu.
2. Retourne dans le panneau Tebex et clique Continue. Si c'est bon, le serveur est relié à la boutique.
3. Si Continue reste grisé, regarde la console du serveur : une erreur liée à Tebex y apparaît (clé mal copiée, guillemets manquants…).

#Créer les paquets

#Les variables Tebex

Dans une commande de paquet, Tebex remplace ces variables par les infos de l'achat (doc Tebex : les commandes) :

#Quel identifiant pour <joueur> ?

Utilise {id} : Socle le compare aux identifiants du joueur (license, fivem, steam, discord…), avec ou sans préfixe. Socle ne reconnaît jamais un joueur par son pseudo : un joueur peut changer de pseudo et récupérer les achats d'un autre. Ce que Tebex met exactement dans {id} dépend de la façon dont tes joueurs se connectent à ta boutique : vérifie-le avec un achat test.

Vérifie avec un achat test (voir Tester un achat) : la console doit afficher livré à … avec le bon joueur. Si la livraison reste en attente alors que l'acheteur est connecté, change de variable. Évite {hexid} : il suppose que le joueur a Steam ouvert et qu'il est en ligne.

Dans les exemples ci-dessous, on utilise {id}.

#Désactiver « Require the customer to be online »

Par défaut, Tebex attend que le joueur soit connecté pour exécuter une commande (réglage Require the customer to be online, bouton de réglages à côté de chaque commande — doc Tebex : dépannage des commandes). Désactive-le sur toutes les commandes Socle : Socle gère lui-même l'attente du joueur, au niveau du personnage.

#Paquet de coins

Commande à l'achat (onglet Initial) :

socle_tebex_coins {id} 2750 {transaction}

Commande des onglets Chargeback et Refund (même montant) :

socle_tebex_coins_remove {id} 2750 {transaction}

Exemples de paliers, à adapter à ton économie (les prix sont des exemples, pas des recommandations) :

Pour te repérer, quelques prix livrés par défaut dans la boutique en jeu : Couteau 1 500 coins, Pistolet de combat 8 000, Bravado Bison 18 000, Pfister 811 45 000, Pack Débutant 5 000, Pack Premium 60 000.

#Paliers VIP

Trois paliers sont livrés (socle/configs/vip.lua). Dans les commandes, utilise le nom technique : un palier inconnu est refusé (palier VIP inconnu).

Si tu ajoutes ou renommes des paliers dans l'administration de la boutique, utilise leurs nouveaux noms techniques.

#Paquet VIP à durée fixe (ex. VIP Or 30 jours)

Le VIP expire de toute façon seul au bout des 30 jours (la date est enregistrée à la livraison) : la commande d'expiration est une sécurité.

Pour un VIP permanent, mets 0 jour (socle_tebex_vip {id} gold 0 {transaction}) et pas de commande d'expiration.

socle_tebex_vip_remove ne retire le VIP que s'il a été accordé par cette transaction (même palier, même échéance). Si le joueur a acheté un autre VIP depuis (autre transaction Tebex, boutique en jeu, staff), l'expiration ou le remboursement du premier paquet ne touche pas au VIP actuel : la console affiche VIP actuel non accordé par cette transaction, conservé, la livraison passe au statut skipped et un log « Retrait VIP Tebex ignoré » est écrit.

#Abonnement VIP (paquet récurrent)

Tebex sait vendre des paquets récurrents (doc Tebex — paiements récurrents). Pour un VIP Or mensuel :

À chaque renouvellement, le VIP repart pour 30 jours à compter de la livraison.

#Gestion manuelle par le staff

L'administration de la boutique (F1 › Administration) reste le secours : livraison ratée, mauvais personnage, geste commercial.

Le staff qui livre a besoin des deux. Voir Administration pour attribuer les permissions.

1. Ouvre F1 › Administration.
2. Cherche le personnage par son identifiant (char1:…) ou son nom (prénom nom). La recherche renvoie un seul résultat, le premier qui correspond : vérifie le nom affiché.
3. Ajuste les coins ou la fidélité (montant ajouté, négatif pour retirer), attribue un palier VIP avec un nombre de jours (0 = permanent, maximum 3650), ou retire le VIP.

Le joueur n'a pas besoin d'être connecté. Un solde ne descend jamais sous 0. Chaque ajustement est écrit dans l'historique de la boutique.

#Rétrofacturations et remboursements

Avec les commandes des onglets Chargeback et Refund ci-dessus :

Pour un joueur qui a dépensé des coins ensuite remboursés, la reprise des articles (véhicule, arme, propriété…) se fait avec les outils staff habituels ; une sanction éventuelle se pose depuis le menu staff (Administration).

#Tester un achat

#Depuis la console du serveur

Lance la commande à la main dans la console du serveur (ou celle de txAdmin), avec ton nom de joueur et un faux numéro de transaction :

socle_tebex_coins TonPseudo 100 TEST-0001

1. Connecté en jeu, la console affiche [Tebex] coins TEST-0001 livré à TonPseudo et ton solde augmente dans F1.
2. Relance exactement la même commande : la console affiche coins TEST-0001 déjà traitée : ignorée, le solde ne bouge pas.
3. Retire le test : socle_tebex_coins_remove TonPseudo 100 TEST-0001.
4. Teste l'attente : déconnecte-toi, lance socle_tebex_coins TonPseudo 100 TEST-0002 (la console dit en attente : TonPseudo n'est pas connecté), reconnecte-toi et charge ton personnage : les coins arrivent.
5. Teste l'annulation : socle_tebex_vip TonPseudo gold 30 TEST-0003 hors ligne, puis socle_tebex_vip_remove TonPseudo TEST-0003 : la console dit livraison en attente annulée.

#Depuis Tebex

Tebex propose deux façons de tester (doc Tebex — tester un paquet) :

• Store Test Mode (paramètres de paiement) : simule un vrai paiement sans débiter le testeur. À utiliser tant que la boutique est privée, à couper avant l'ouverture.
• Manual Payment (onglet Payments) : simule la livraison d'un paquet sans passer par le paiement.

Fais au moins un achat test pour vérifier que {id} reconnaît tes joueurs.

#Où lire les traces

#Dépannage

#Récapitulatif

#Configuration

#Commandes console

Toutes : console uniquement, une seule exécution par transaction, action et période, mise en attente si le joueur n'est pas connecté. Chaque commande accepte un dernier argument facultatif [période]. Désactive « Require the customer to be online » dans Tebex.

<joueur> : ID serveur, identifiant complet (license:, fivem:, steam:, discord:…), sa valeur sans préfixe, ou nom du joueur.

#Réglages du panel (Panel › Boutique)