Base de données et bridge

Lectures prises en charge#

La connexion est activée par défaut sur chaque serveur et ne demande aucune ligne dans server.cfg. Pour la couper sur un serveur, ouvrez-le dans Serveurs et utilisez « Disable connection » sur la carte Tosun Connect ; la même carte la réactive. Avec set tosun_db_bridge_manual "1" dans server.cfg, tosun_db_bridge_enabled et tosun_db_bridge_money_write sont lus dans server.cfg comme avant, et chacun reste désactivé s’il ne vaut pas "1". Si l’ancien miroir complet est activé volontairement (ts.panelMirror.enabled = true dans configs/anticheat_config.lua), le bridge reste désactivé pour que ce miroir continue de fonctionner. Les schémas QBCore/ESX compatibles exposent certains joueurs, inventaires, véhicules et journaux. Ce n’est pas un explorateur complet de base.

Requêtes limitées et modification du solde#

Au repos, le panel est interrogé en HTTPS environ toutes les 10 secondes, sans lecture de la base de jeu. Maximum 25 résultats par page et une tâche à la fois. La modification du solde en ligne (fixer depuis le panel l’argent liquide ou le solde bancaire d’un personnage connecté) est activée par défaut. Elle est réservée aux utilisateurs du panel ayant le rôle admin ou owner (droit économie). Le personnage doit être connecté et le solde actuel attendu doit correspondre ; sinon stale_balance est renvoyé et rien ne change. Le panel affiche un récapitulatif à confirmer avant l’envoi, et chaque demande est inscrite au journal d’audit. L’opération remplace le total, elle ne l’augmente pas. Un résultat incertain n’est jamais relancé automatiquement ; vérifiez d’abord le solde en jeu. Pour arrêter les lectures et la modification du solde sur un serveur, utilisez « Disable connection » sur la carte Tosun Connect. Pour garder les lectures sans modification du solde, passez en mode manuel : set tosun_db_bridge_manual "1" et set tosun_db_bridge_enabled "1", sans set tosun_db_bridge_money_write "1".

Relier le serveur de jeu existant#

Le pont utilise votre connexion oxmysql. Le panel transmet des tâches prises en charge via HTTPS ; le serveur les exécute localement et renvoie les données sélectionnées. Aucun mot de passe MySQL à copier dans le site ni port MySQL à exposer.

1. La connexion est activée par défaut pour chaque serveur ; avec tosun-ac 9.6.14 ou ultérieur, inutile de l’activer. Pour la couper sur un serveur : Serveurs → le serveur → carte Tosun Connect → « Disable connection ». Si l’ancien miroir complet est activé volontairement avec ts.panelMirror.enabled = true dans configs/anticheat_config.lua, le pont reste désactivé automatiquement pour que l’ancien miroir continue de fonctionner.
2. Avec tosun-ac 9.6.14 ou ultérieur, aucune ligne server.cfg n’est nécessaire pour la connexion ; seule la ligne set tosun_ac_license avec la bonne licence reste requise. Les anciennes lignes tosun_db_bridge_enabled et tosun_db_bridge_money_write sont alors ignorées et peuvent être supprimées ; un serveur qui exécute encore un ancien paquet en a besoin jusqu’à l’installation du nouveau paquet. La modification des soldes en ligne est aussi activée par défaut et réservée aux utilisateurs du panel ayant le rôle admin ou owner.
3. Autorisez HTTPS sortant vers admin.tosundev.com, vérifiez la console et demandez une petite liste de joueurs.

# Exécuter dans la console serveur :
tosunac_db_status

Site communautaire avec la seule licence#

Votre site communautaire lit les données du jeu via la même connexion Tosun Connect. Si aucun paramètre de base de données du jeu n’est saisi pour le serveur dans le panel, le site n’a besoin ni d’utilisateur MySQL, ni de GRANT, ni du port 3306 ouvert : les pages Joueurs, Bannissements, Détections de l’anticheat et Journaux chargent leurs données depuis le serveur de jeu à l’ouverture.

Dans ce mode, le site ne peut pas rechercher, filtrer, débannir, ajouter des bannissements ni modifier l’argent ou les inventaires. Pour lever un bannissement, utilisez /ts unban <banID> en jeu ou ts unban <banID> dans la console du serveur. Chaque page est une nouvelle requête traitée en 10 secondes environ ; si le serveur de jeu est hors ligne ou si la connexion est désactivée sur la carte Tosun Connect, la page l’indique au lieu d’afficher une liste vide.

Les noms, métiers, soldes, inventaires et modèles de véhicules nécessitent tosun-ac 9.6.17 ou plus récent sur le serveur de jeu. Avec les anciens paquets, certains serveurs MySQL/MariaDB ne renvoient que l’ID du personnage.

Une connexion directe à la base de données du jeu est facultative. Ajoutez-la seulement si vous voulez la recherche et la modification sur le site : créez un utilisateur de base de données qui ne peut se connecter que depuis l’adresse IP du serveur du panel Tosun (le support peut la confirmer), donnez-lui SELECT, INSERT, UPDATE et DELETE sur la base du jeu, n’ouvrez le port 3306 qu’à cette adresse et saisissez les informations dans les paramètres de base de données du serveur, sous Serveurs (Direct MySQL · Advanced). Le panel ne les enregistre qu’après un test de connexion réussi. Sans ces informations, la configuration avec la seule licence reste utilisée.

• Joueurs : 25 personnages par page avec l’ID du personnage, le nom et le métier. L’équipe voit aussi l’argent liquide et la banque.
• L’équipe (modérateur et plus) peut cliquer sur un personnage pour voir son statut en ligne, ses soldes et son inventaire, et charger ses véhicules.
• Bannissements et détections de l’anticheat : 25 enregistrements par page, en lecture seule. Les détections vont des plus anciennes aux plus récentes ; les bannissements suivent l’ordre des ID de ban.
• Les totaux du tableau de bord pour les joueurs, bannissements et détections affichent « — » : la connexion n’a pas d’opération de comptage, aucun nombre n’est donc estimé.

Données disponibles et limites#

Lectures possibles : joueurs, détails d’un personnage, ses véhicules, bannissements et détections. QBCore/Qbox utilisent généralement players et player_vehicles ; ESX users et owned_vehicles. Colonnes et index doivent être compatibles. ready ne garantit pas la lecture d’une table personnalisée.

L’inventaire contient des champs sélectionnés, un volume stocké borné et au plus 100 entrées parcourues. Métadonnées arbitraires, stashes et tables personnalisées ne sont pas intégralement copiés. Un inventaire tronqué est partiel : un objet absent du résultat peut exister. Utilisez les outils d’inventaire du jeu pour une vérification complète.

Comprendre statut et charge#

Au repos, le pont contacte le panel environ toutes les dix secondes sans lire la base du jeu. Un seul travail s’exécute à la fois. Les pages utilisent un curseur et contiennent au plus 25 résultats. Passez à la suite plutôt que de recharger la première page. Les métadonnées demandées sont mises en cache cinq minutes.

• oxmysql_unavailable : vérifier ordre de démarrage et connexion.
• unsupported_framework / schema_unavailable : vérifier framework, tables et colonnes réels.
• unsupported_index : faire vérifier la clé nécessaire, sans créer un index à l’aveugle sur un serveur chargé.
• request_expired / statut ancien : vérifier réseau et ancienneté avant une nouvelle lecture.

• Frameworks
• Mesurer les performances

Modifier les soldes délibérément#

La modification des soldes en ligne est activée par défaut. Les utilisateurs du panel ayant le rôle admin ou owner (droit économie) peuvent fixer le total espèces ou banque d’un personnage compatible connecté après le résumé de confirmation. L’opération fixe un solde absolu ; elle n’ajoute pas le montant à chaque tentative. Le solde précédent attendu est vérifié ; s’il ne correspond pas, stale_balance est renvoyé et rien ne change. Chaque demande est inscrite au journal d’audit.

Aucun repli vers le SQL hors ligne. Un résultat incertain reste enregistré pour empêcher les répétitions automatiques. Ne donnez pas le rôle admin ou owner aux simples lecteurs. Pour arrêter la modification des soldes sur un serveur, utilisez « Disable connection » sur sa carte Tosun Connect (cela arrête aussi les lectures) ou le mode manuel avec set tosun_db_bridge_manual "1" : tosun_db_bridge_enabled et tosun_db_bridge_money_write sont alors lus dans server.cfg et chacun reste désactivé sauf s’il vaut "1".

1. Lisez personnage et solde, vérifiez le montant final et exécutez une fois.
2. Avec stale_balance, relisez : le joueur a pu dépenser ou gagner entre-temps.
3. Avec unknown_outcome, arrêtez-vous et comparez solde réel et traces. Aucun nouvel essai avant clarification.

• API et identifiants

Distinguer une liste enregistrée du détail en direct#

La liste des joueurs lit les personnages enregistrés ; ce n’est pas un flux continu en direct. Le détail peut remplacer les soldes sauvegardés par les valeurs du framework en ligne compatible et lire les objets ox_inventory actuels du joueur quand ils sont disponibles. Choisissez le character_id permanent, pas un numéro de session mémorisé. Dans le panneau, consultez les soldes indisponibles et l’avertissement d’inventaire incomplet avant d’interpréter des zéros ou une liste complète. Les développeurs peuvent lire les indicateurs balance_available et inventory_truncated correspondants. Un champ indisponible ou partiel ne prouve aucune perte. Les véhicules présentent des champs enregistrés sélectionnés, sans prouver qu’un véhicule est apparu ou participe à une session de garage active.

1. Comparez un personnage connu au jeu à une heure notée, avec son état en ligne et le compte choisi.
2. En cas d’écart, vérifiez identité, requête de liste ou détail et indicateurs de disponibilité avant toute action.
3. Après reconnexion ou changement de personnage, demandez un nouveau détail au lieu de réutiliser le précédent.

Paginer les enquêtes plutôt que vider la base#

La file accepte au maximum trois requêtes en attente ou prises par serveur et douze nouvelles requêtes par minute. Un travail expire après 120 secondes ; les résultats sont temporaires et deviennent éligibles au nettoyage cinq minutes après l’expiration du travail, sans heure de suppression garantie. Ces limites permettent une gestion ciblée, pas une collecte complète automatisée. Utilisez la pagination du panneau ; les développeurs suivent has_more et next_cursor pour la même opération et le même personnage. Une page suivante vide diffère d’une requête échouée. Les clés uniques et index de propriétaire des véhicules sont vérifiés pour refuser les structures incompatibles. Ne renommez pas de colonnes et n’ajoutez pas d’index en production uniquement pour masquer une erreur sans évaluer application et plan de requête.

1. Lisez une page du panneau à la fois. Une intégration conserve curseur et opération ensemble et continue seulement si has_more est vrai.
2. En cas de queue_full ou rate_limited, attendez les travaux ouverts plutôt que de rouvrir les vues.
3. Faites évaluer unsupported_index sur une copie ; les métadonnées peuvent rester en cache cinq minutes.

Suspendre l’accès sans effacer les opérations incertaines#

Pour une simple inspection, accordez les seules lectures nécessaires ; seuls les rôles admin et owner peuvent modifier les soldes. Pour arrêter la connexion d’un serveur, ouvrez Serveurs → le serveur → carte Tosun Connect et choisissez « Disable connection » ; toutes les lectures et modifications de solde de ce serveur s’arrêtent, et la même carte permet de la réactiver. Pour garder les lectures sans modification de solde, utilisez le mode manuel : ajoutez set tosun_db_bridge_manual "1" et set tosun_db_bridge_enabled "1" dans server.cfg et laissez tosun_db_bridge_money_write absent ou à "0". En mode manuel, ces deux valeurs sont lues dans server.cfg et chacune reste désactivée sauf si elle vaut "1" ; sans set tosun_db_bridge_enabled "1", le mode manuel arrête donc aussi les lectures. Le panneau marque les travaux ouverts ou pris comme échoués ; une écriture d’argent prise reçoit unknown_outcome, car son effet a pu se produire. Le registre d’opérations du jeu n’est donc pas un cache jetable. Supprimer ses KVP pour forcer un essai peut enlever la preuve empêchant une répétition. Vérifiez aussi l’accès aux données capturées : le pont ne rend pas privées les captures ou traces publiquement partagées.

1. Avant la déconnexion prévue, terminez les lectures et examinez l’argent incertain avec soldes actuels et audit.
2. Vérifiez ensuite panneau et tosunac_db_status ; ne présentez pas une nouvelle inspection en file comme réussie.
3. Après la réactivation sur la carte, commencez par une lecture et ne modifiez aucun solde avant la vérification des droits, capacités et opérations incertaines.

# Server console / Sunucu konsolu:
tosunac_db_status

Examiner le schéma sans modifier les données des joueurs#

En cas de schema_unavailable ou unsupported_index, vérifiez d’abord que la base réellement utilisée par le jeu est sélectionnée. L’exemple ci-dessous lit uniquement les noms et types de colonnes; il ne modifie ni soldes, ni inventaires, ni véhicules. Ce n’est pas une étape obligatoire d’installation. Un administrateur de base autorisé peut l’exécuter dans son outil privé habituel pour rechercher une erreur de schéma. N’envoyez pas de SQL au pont du panel: il accepte uniquement les opérations définies.

Les lectures QBCore/Qbox exigent citizenid, money, job et charinfo dans players; ESX exige identifier, accounts et job dans users. La présence de la table ne suffit pas. La clé du personnage doit avoir un type pris en charge et un index unique sur une seule colonne entière.

Les lectures de véhicules vérifient aussi les index adaptés au propriétaire et à la clé du véhicule. Cela évite de forcer des requêtes coûteuses. Ne renommez pas une table de garage personnalisé pour masquer l’erreur; demandez d’abord aux développeurs du framework et du garage d’évaluer la compatibilité.

• Notez le code d’erreur, la version du framework et la lecture concernée.
• Comparez colonnes et index; ne joignez pas de lignes de joueurs au support.
• Évaluez les modifications sur une copie de test. Le cache du schéma peut ne pas reconnaître immédiatement la nouvelle structure.

SELECT TABLE_NAME, COLUMN_NAME, COLUMN_TYPE
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
  AND TABLE_NAME IN ('players', 'users', 'player_vehicles', 'owned_vehicles')
ORDER BY TABLE_NAME, ORDINAL_POSITION
LIMIT 128;

Le personnage apparaît, mais la liste des véhicules est vide#

Supposons qu’un personnage choisi dans la liste des joueurs s’ouvre correctement, mais que ses véhicules n’apparaissent pas. Distinguez d’abord un résultat terminé avec succès d’une tâche en échec. Une liste vide réussie signifie que cette lecture n’a renvoyé aucun enregistrement correspondant; elle ne prouve pas l’absence de véhicule dans tous les systèmes. query_failed, schema_unavailable et unsupported_index ne sont pas des listes vides.

Vérifiez que la sélection utilise le même character_id permanent. Un numéro de session pouvant changer après reconnexion ne remplace pas la clé du personnage. QBCore/Qbox utilise player_vehicles.citizenid pour le propriétaire; ESX utilise owned_vehicles.owner. Si un garage personnalisé emploie une autre table ou un autre format, le pont standard ne découvre pas automatiquement ces enregistrements.

Choisir le mauvais personnage d’un compte à plusieurs personnages peut donner le même symptôme. Demandez au responsable autorisé du garage de vérifier le contexte d’un véhicule connu côté jeu. Modifier un solde, recréer un véhicule ou vider la table source n’est pas nécessaire au diagnostic.

• Conservez ID du serveur, référence de personnage masquée, heure et état de la tâche.
• Continuez la pagination avec le même personnage; ne transférez pas un curseur à un autre.
• Précisez au support si le résultat était vide avec succès ou accompagné d’un code exact; retirez les données personnelles.

Distinguer nombres, texte et champs indisponibles#

Le pont ne reproduit pas une ligne brute : il normalise les champs pris en charge avec des types et longueurs définis. L’argent du personnage est lu depuis des nombres JSON. Ainsi 1200 et "1200" ont des types stockés différents ; un script transformant l’argent en texte peut rendre le solde indisponible. Le panneau affiche — pour un solde indisponible ; cela ne signifie pas un solde nul. L’inventaire sélectionne nom, libellé, quantité, slot et qualité ; métadonnées arbitraires, contenus de stash et comptes commerciaux ne font pas partie du résultat.

Les valeurs de véhicule comme carburant, moteur et état peuvent revenir sous forme de texte ; leur format ne suffit pas pour un calcul. La longueur de schéma char/varchar des clés compatibles est au plus 96 ; la clé transmise est aussi limitée à 96 octets, une limite différente pour les caractères multioctets ; int, bigint et mediumint sont également acceptés. Une clé binaire personnalisée n’est pas présumée standard. Textes longs et inventaire peuvent être tronqués ; une omission n’est pas une suppression. Faites vérifier le format source avant de diagnostiquer un champ manquant. Évaluez les conversions avec le contrat des données du jeu en test, sans modifier la production pour remplir l’écran.

Valider une écriture avec un exemple concret#

Pour une correction autorisée et approuvée, imaginez passer les espèces d’un personnage connecté de 1200 à 1250. Le total final cible est 1250 ; saisir 50 fixe le solde à cinquante au lieu d’ajouter cinquante. Vérifiez le compte espèces ou banque et associez l’identité persistante aux détails récents en direct. La confirmation indique personnage, compte et passage du montant actuel au nouveau total. Le montant final est entier et non négatif ; monnaies personnalisées et comptes commerciaux ne remplacent pas cette opération.

Ne terminez pas la validation à l’entrée en file. Vérifiez le résultat achevé du même personnage et compte avec before=1200 et after=1250, puis lisez normalement l’état actuel. Une dépense ultérieure peut le changer sans justifier un renvoi automatique. Examinez l’hypothèse périmée derrière stale_balance et l’effet non vérifié de unknown_outcome. Conservez référence, heure et résultat nettoyé. En cas d’incertitude, aucune nouvelle écriture avant de réévaluer le solde réel et la correction voulue.

Un délai de réponse n’annule pas le SQL#

L’attente par défaut d’une réponse SQL est de 5 000 ms. query_timeout met fin à l’attente du panel ; la requête réelle peut encore s’exécuter. La capacité SQL reste occupée jusqu’à son premier vrai callback, et une autre lecture renvoie query_busy. Une réponse tardive ne modifie pas l’affichage précédent. Si aucun callback n’arrive, le délai ne libère pas automatiquement la capacité. L’administrateur du serveur doit vérifier la connexion et la base de données ; redémarrer la ressource ne prouve pas l’annulation du SQL.

Seul le propriétaire du serveur peut, s’il le souhaite, ajouter la ligne set suivante dans server.cfg. La valeur est limitée à 1 000–10 000 ms ; un nombre invalide ou infini donne 5 000 ms. Ce réglage n’accélère pas le SQL et ne relance pas les requêtes automatiquement.

La modification des soldes en ligne est activée par défaut pour les utilisateurs du panel ayant le rôle admin ou owner (permission économie) ; en mode manuel (set tosun_db_bridge_manual "1"), elle reste désactivée tant que tosun_db_bridge_money_write ne vaut pas "1". Elle exige un personnage pris en charge et en ligne ainsi qu’une confirmation dans le panel. L’opération remplace seulement le total en liquide ou en banque après vérification du solde actuel attendu ; elle ne se rabat jamais sur une écriture SQL hors ligne. unknown_outcome ou une ambiguïté de connexion n’est jamais relancé automatiquement. Vérifiez le solde en direct et les journaux d’audit avant une nouvelle écriture ; ne supprimez pas les enregistrements KVP d’opérations incertaines pour forcer une répétition.

set tosun_db_bridge_query_timeout_ms "5000"

Un seul SQL dans la bonne base#

tosun-ac/INSTALL.sql est l’unique point d’importation SQL du nouveau ZIP. N’importez pas une seconde ancienne copie du schéma. Il cible la base de jeu FiveM/oxmysql, pas la base des comptes ou du thème du site loué. Les colonnes anciennes manquantes sont réparées avant les valeurs par défaut; bannissements et réglages personnels sont conservés.

1. Sauvegardez la base de jeu et vérifiez son nom.
2. Importez uniquement INSTALL.sql dans HeidiSQL/phpMyAdmin ou nommez explicitement la base avec mysql.
3. tosunac_db_check vérifie une requête, tosunac_db_status l’état du pont. Le pont est actif par défaut et ne demande aucune ligne dans server.cfg. enabled=false est normal en mode manuel (set tosun_db_bridge_manual "1") sans tosun_db_bridge_enabled "1", ou si l’ancien miroir complet (ts.panelMirror.enabled = true dans configs/anticheat_config.lua) est activé volontairement; la licence ne crée pas de connexion MySQL.
4. La connexion du panneau (Tosun Connect) et la modification du solde en ligne sont actives par défaut. N’ajoutez ni tosun_db_bridge_enabled ni tosun_db_bridge_money_write dans server.cfg; à partir du package 9.6.14, les anciennes lignes sont ignorées et peuvent être supprimées (les packages plus anciens en ont encore besoin tant que le package actuel n’est pas installé). Seuls les utilisateurs du panneau avec le rôle admin ou owner fixent un solde: le personnage doit être en ligne, le solde attendu doit correspondre (sinon stale_balance, rien ne change), le panneau affiche un résumé à confirmer avant l’envoi, chaque requête est inscrite au journal d’audit et un résultat incertain n’est jamais relancé automatiquement; vérifiez d’abord le solde en jeu. L’opération fixe le total, elle n’ajoute pas. Pour couper toute la connexion sur un serveur (cela arrête toutes les lectures du panneau et toutes les modifications de solde): Panneau → Serveurs → le serveur → carte Tosun Connect → Disable connection; vous pouvez la réactiver depuis la même carte. Gardez le mot de passe sur le serveur de jeu.

mysql -u YOUR_DB_USER -p YOUR_GAME_DATABASE < tosun-ac/INSTALL.sql

# txAdmin console:
tosunac_db_check
tosunac_db_status