$ USD
Cadre QBOX – Guide complet
Surétendu (Ox) est la base moderne des serveurs FiveM. Ce guide vous explique comment installer, configurer et migrer en toute sécurité vers ox_inventaire, ox_lib, cible_ox, et oxmysqlVous bénéficierez d'un code copiable, de valeurs par défaut et de modèles éprouvés pour l'interface utilisateur, les interactions et les données. Des manuels sont également inclus. qb-inventaire → ox_inventory et mysql-async → oxmysql. Sauvegardez votre serveur et votre base de données avant toute modification.
TL;DR : Quel composant Ox pour quoi ?
| Composant | But | API de base | Utilisation typique | Chemin de migration | Pièges courants |
|---|---|---|---|---|---|
| ox_inventaire | Inventaire et objets, réserves, boutiques | Ajouter un élément, Supprimer l'élément, RegisterStash, RegisterShop | Objets de joueur, réserves de travail, boutiques de vendeurs | qb-inventaire → ox_inventory | Schéma d'élément incorrect, doublons d'invs en cours d'exécution, manquants assurer commande |
| ox_lib | Utilitaires, interface utilisateur, assistants | ajouterCommande, contexte d'enregistrement/afficherContexte, boîte de dialogue d'entrée, barre de progression, zones/points | Menus, invites, limites de débit, logique de zone | N / A | Mélanger les bibliothèques d'interface utilisateur, sans attendre les rappels |
| cible_ox | Ciblage d'interaction | addBoxZone, ajouterSphereZone, ajouter une entité, ajouter un modèle | Cibles oculaires sur les accessoires/piétons/zones | qtarget → ox_target (facultatif) | Zones superposées, conditions de travail manquantes |
| oxmysql | Pilote MySQL | requête, célibataire, scalaire, insérer, préparer, transaction | Persistance de la base de données, classements, audits | mysql-async → oxmysql | Requêtes non indexées, concaténation de chaînes non sécurisée |
Conseil: Commencer par oxmysql et ox_lib, puis migrer inventaire et cible. Validez chaque étape sur un serveur de préparation.
En rapport: https://fivemx.com/frameworks/ · https://fivemx.com/framework-conversion/
Prérequis et base de référence
- Artefact de serveur récent, txAdmin, et un cadre (QBCore ou ESX).
- Node.js n'est pas requis pour Ox, mais votre pile NUI (le cas échéant) peut l'utiliser.
- Ordre de démarrage des ressources :
oxmysql→ox_lib→ox_inventaire→ le reste. Mettre cible_ox au début des bibliothèques d'interface utilisateur/d'interaction. - Liste de contrôle:
- Le pare-feu autorise le trafic DB ; l'utilisateur DB a le moins de privilèges.
- Définissez les variables de production et de développement ; activez les avertissements de requête lente dans la phase de préparation.
- Sauvegardes pour les configurations de base de données et de ressources.
En rapport: https://fivemx.com/how-to-install-qbcore/ · https://fivemx.com/how-to-customize-qbcore-scripts/ · https://fivemx.com/qbcore-scripts/
Installer et configurer : ox_inventory
Installer
Ajoutez la ressource et assurez-vous qu'elle après ox_lib.
-- resources/[ox]/ox_inventory/fxmanifest.lua (extrait) fx_version 'cerulean' jeu 'gta5' lua54 'oui' shared_scripts { '@ox_lib/init.lua', 'config.lua' } client_scripts { 'client/*.lua' } server_scripts { '@oxmysql/lib/MySQL.lua', 'server/*.lua' }
serveur.cfg:
assurer oxmysql assurer ox_lib assurer ox_inventory
Configuration de base
Définir les éléments (poids, pile, métadonnées). Chemin typique : ox_inventory/data/items.lua.
retour { eau = { label = 'Bouteille d'eau', poids = 200, pile = vrai, fermer = vrai, description = 'Restez hydraté.' }, sandwich = { label = 'Sandwich', poids = 300, pile = vrai } }
Enregistrer un planque et un boutique au démarrage du serveur :
-- server/stash_shop.lua CreateThread(function() exports.ox_inventory:RegisterStash('pd_evidence', 'Preuves policières', 100, 100000, false, {police = 2}) exports.ox_inventory:RegisterShop('corner_store', { name = '24/7 Market', inventory = { { name = 'water', price = 8 }, { name = 'sandwich', price = 12 } } }) end)
Notions de base de l'interface utilisateur
- Glisser-déposer, diviser, empiler ; raccourcis clavier configurables.
- Utiliser métadonnées pour les séries, les qualités, la péremption.
Test rapide
Donnez-vous un objet et ouvrez l'inventaire :
-- server/debug.lua RegisterCommand('giveme', function(src) exports.ox_inventory:AddItem(src, 'water', 1) fin, vrai)
Erreurs courantes
Avertissement: Faire pas Exécutez deux inventaires simultanément. Désactivez complètement qb-inventory avant d'activer ox_inventory.
Conseil: Élément de correspondance noms exactement sur les données d'emploi/d'artisanat et d'inventaire.
En rapport: https://fivemx.com/fivem-inventory-scripts/ · https://fivemx.com/qbcore-scripts/
Installer et configurer : ox_lib
Essentiel
Cœur Des outils que vous utiliserez partout :
-- Commandes lib.addCommand('healme', { help = 'Soignez-vous (administrateur uniquement).', restricted = 'group.admin' }, function(src) TriggerClientEvent('fivemx:heal', src) end) -- Menus contextuels lib.registerContext({ id = 'shop_menu', title = 'Marché 24/7', options = { { title = 'Acheter de l'eau ($8)', event = 'fivemx:buy', args = { item = 'water', price = 8 } }, { title = 'Acheter un sandwich ($12)', event = 'fivemx:buy', args = { item = 'sandwich', price = 12 } } } }) -- plus tard lib.showContext('shop_menu')
Mini livre de cuisine
- Boîte de dialogue de saisie & progrès avec un flux attendu :
-- client local input = lib.inputDialog('Craft Coffee', { { type = 'number', label = 'Beans (g)', default = 18, min = 1, max = 60 } }) si input then local ok = lib.progressBar({ duration = 3500, label = 'Brewing…', useWhileDead = false, canCancel = true }) si ok then TriggerServerEvent('fivemx:craft:coffee', input[1]) end end
- Rappels (le serveur valide, le client attend) :
-- serveur lib.callback.register('fivemx:buyItem', function(src, item, price) -- valider le travail/les coordonnées/etc. puis facturer + octroyer -- renvoyer vrai/faux et message renvoyer exports.ox_inventory:AddItem(src, item, 1) end) -- client local success = lib.callback.await('fivemx:buyItem', false, 'water', 8)
En rapport: https://fivemx.com/frameworks/ · https://fivemx.com/framework-conversion/
Installer et configurer : ox_target
Entités et os
Associer des actions à des actions spécifiques piétons/véhicules/objets ou leurs os.
-- cibler une entité par modèle exports.ox_target:addModel(`prop_vend_soda_02`, { { name = 'vending_buy', icon = 'fa-solid fa-bottle-water', label = 'Buy a Drink', onSelect = function(data) TriggerEvent('fivemx:openVending') end } })
Zones
Créez des boîtes/sphères/polygones 3D avec des conditions de travail.
-- Zone de boîte devant la caisse enregistreuse exports.ox_target:addBoxZone({ coords = vec3(25.7, -1347.3, 29.5), size = vec3(1.6, 1.2, 1.0), rotation = 0.0, debug = false, options = { { label = 'Open Shop', icon = 'fa-solid fa-store', groups = { police = 0, ambulance = 0 }, -- anyone; exemple de filtre de groupe onSelect = function() lib.showContext('shop_menu') end } } })
Exemples
- Cible de cachette pour les preuves policières.
- Artisanat à distance à l'intérieur d'un atelier.
En rapport: https://fivemx.com/qbcore-scripts/ · https://fivemx.com/fivem-inventory-scripts/
Installer et configurer : oxmysql
Pourquoi oxmysql
- Instructions préparées, pooling, API asynchrone/en attente.
- Meilleures performances et sécurité que le SQL string-concat.
Aide-mémoire sur les API
-- lire plusieurs lignes locales = MySQL.query.await('SELECT id, name FROM players WHERE job = ?', { 'police' }) -- lire une seule ligne locale player = MySQL.single.await('SELECT * FROM players WHERE identifier = ?', { identifier }) -- valeur scalaire local count = MySQL.scalar.await('SELECT COUNT(*) FROM stash_items WHERE stash = ?', { 'pd_evidence' }) -- insérer local id = MySQL.insert.await('INSERT INTO logs (event, source) VALUES (?, ?)', { 'buy_water', src }) -- informations locales préparées et mises en cache = MySQL.prepare.await('SELECT label, weight FROM items WHERE name = ?', { 'water' }) -- transaction MySQL.transaction.await(function() MySQL.query.await('UPDATE accounts SET money = argent - ? OÙ identifiant = ?', { 12, identifiant }) MySQL.query.await('INSÉRER DANS achats (identifiant, article) VALEURS (?, ?)', { identifiant, 'sandwich' }) fin)
Hygiène des index et des schémas
ALTER TABLE joueurs ADD INDEX idx_players_identifier (identifiant); ALTER TABLE achats ADD INDEX idx_purchases_identifier_created (identifiant, created_at);
Gestion des erreurs
Conseil: Activez les avertissements de requête lente dans la phase de préparation et ajoutez les index appropriés avant le lancement.
En rapport: https://fivemx.com/mysql-async-to-oxmysql/ · https://fivemx.com/sql-identifiers-migration/ · https://fivemx.com/converting-fivem-scripts/
Manuels de migration (prêts à copier-coller)
qb-inventaire → ox_inventory
Cartographie des concepts
| Concept | qb-inventaire | ox_inventaire |
|---|---|---|
| Articles | qb-core/shared/items.lua | ox_inventory/data/items.lua |
| Cachettes | Logique de stockage des tâches/joueurs dans les scripts | RegisterStash(id, label, slots, weight, owner, groups, coords) |
| Boutiques | boutiques qb ou personnalisées | RegisterShop(id, { inventaire = {..} }) |
Mesures
- Désactivez qb-inventory et toutes les interfaces utilisateur dépendantes de l’inventaire.
- Installer ox_lib, ox_inventaire, oxmysql dans cet ordre.
- Articles portuaires →
données/éléments.lua(conserver les noms/poids/métadonnées). - Remplacer les appels d'ajout/suppression d'éléments par
exports.ox_inventory:Ajouter un élément/Supprimer un élément. - Enregistrez les réserves/boutiques côté serveur ; migrez les données de sauvegarde des réserves si applicable.
- Test sur la mise en scène ; vérifier le glisser/empiler/diviser et les réserves de tâches.
Liste de contrôle (avant/après)
| Zone | Avant | Après | Risque |
|---|---|---|---|
| Ressources | qb-inventaire activé | qb-inventory supprimé, ox_inventory assuré | Faible |
| Articles | éléments dans qb partagés | articles dans données/éléments.lua | Moyen (dénomination) |
| Cachettes | implicite | explicite RegisterStash | Faible |
| Boutiques | boutiques qb | RegisterShop | Faible |
Exemple : ajouter/supprimer remplacer
-- avant (pseudo-code qb-inventory) -- QBCore.Functions.AddItem(src, 'eau', 1) -- après (ox_inventory) exports.ox_inventory:AddItem(src, 'eau', 1) exports.ox_inventory:RemoveItem(src, 'sandwich', 1)
En rapport: https://fivemx.com/fivem-inventory-scripts/
mysql-async → oxmysql
Rechercher/remplacer des modèles
| appel mysql-async | équivalent oxmysql |
|---|---|
MySQL.Async.fetchAll(sql, paramètres, cb) | MySQL.query(sql, paramètres) / .attendre |
MySQL.Async.fetchScalar(sql, params, cb) | MySQL.scalar(sql, paramètres) / .attendre |
MySQL.Async.execute(sql, params, cb) | MySQL.query(sql, paramètres) ou MySQL.update/insert / .attendre |
concaténation de chaînes "..var.." | ? espaces réservés avec tableau de paramètres |
| manuel BEGIN/COMMIT | MySQL.transaction.await(function() ... end) |
Exemple de refactorisation
-- avant MySQL.Async.fetchAll('SELECT * FROM utilisateurs WHERE identifier = @id', { ['@id'] = identifier }, function(rows) -- use rows end) -- après les lignes locales = MySQL.query.await('SELECT * FROM utilisateurs WHERE identifier = ?', { identifier })
Déclarations préparées
utilisateur local = MySQL.prepare.await('SELECT id, job FROM utilisateurs WHERE identifiant = ?', { identifier })
Avertissement: Ne faites jamais confiance aux commentaires des clients. Validez toujours sur serveur et utilisez des espaces réservés.
En rapport: https://fivemx.com/mysql-async-to-oxmysql/ · https://fivemx.com/sql-identifiers-migration/ · https://fivemx.com/converting-fivem-scripts/
Des modèles qui vendent : créer des emplois et des interfaces utilisateur avec la pile Ox
Un travail de livraison minimal qui lie cible_ox (interagir), ox_lib (interface utilisateur), ox_inventaire (récompenses), et oxmysql (audit).
-- client/jobs_delivery.lua local drop = vec3(120.4, -1039.2, 29.2) exports.ox_target:addBoxZone({ coords = drop, size = vec3(1.4, 1.0, 1.0), rotation = 340.0, options = { { name = 'deliver_crate', label = 'Livrer la caisse', icon = 'fa-solid fa-box', onSelect = function() local ok = lib.progressBar({ duration = 4000, label = 'Dépose…' }) if ok then TriggerServerEvent('fivemx:job:deliverCrate') end end } } })
-- server/jobs_delivery.lua RegisterNetEvent('fivemx:job:deliverCrate', function() local src = source -- limite de débit par minute (très simple) local ok = exports.ox_inventory:AddItem(src, 'water', 1) si ok alors MySQL.insert.await('INSERT INTO job_logs (identifier, event) VALUES (?, ?)', { GetPlayerIdentifier(src, 0), 'deliver_crate' }) TriggerClientEvent('ox_lib:notify', src, { title = 'Livraison', description = 'Vous avez reçu Eau x1', type = 'success' }) end end)
En rapport: https://fivemx.com/qbcore-scripts/ · https://fivemx.com/fivem-inventory-scripts/
Performance et sécurité
- Éliminez les interactions avec les cibles ; évitez les zones qui se chevauchent.
- Mettre en cache les lectures fréquentes ; indice colonnes utilisées dans WHERE/JOIN.
- Maintenez les ticks du serveur bas ; déplacez les boucles lourdes hors du thread principal.
- Sécurité : valider côté serveur, limiter les actions économiques, consigner les événements sensibles.
Conseil: Activez les avertissements de requête lente dans la phase de préparation ; expédiez les index avec les migrations.
En rapport: https://fivemx.com/converting-fivem-scripts/ · https://fivemx.com/sql-identifiers-migration/
Harnais de débogage et de test
- Ajouter un débogage commandes protégé par des permissions.
- Enregistrez les échecs de la base de données et les courts-circuits en cas d'erreur.
- Testez le rechargement à chaud en redémarrant des ressources uniques (pas la pile entière).
lib.addCommand('oxping', { help = 'Vérification de l'état de santé', restricted = 'group.admin' }, function(src) local ok = MySQL.scalar.await('SELECT 1') == 1 TriggerClientEvent('ox_lib:notify', src, { title = 'Santé Ox', description = ok et 'DB OK' ou 'DB FAIL', type = ok et 'success' ou 'error' }) end)
En rapport: https://fivemx.com/frameworks/ · https://fivemx.com/framework-conversion/
Ressources internes et prochaines étapes
- Cadres : https://fivemx.com/frameworks/ · https://fivemx.com/framework-conversion/
- QBCore: https://fivemx.com/how-to-install-qbcore/ · https://fivemx.com/how-to-customize-qbcore-scripts/ · https://fivemx.com/qbcore-scripts/
- Migrations : https://fivemx.com/mysql-async-to-oxmysql/ · https://fivemx.com/sql-identifiers-migration/ · https://fivemx.com/converting-fivem-scripts/
- Centre d'inventaire : https://fivemx.com/fivem-inventory-scripts/
Parcourir la boutique pour les scripts testés qui suivent ces modèles.
FAQ
ox_inventory est-il plus rapide que qb-inventory ?
Généralement oui. Il met l'accent sur l'efficacité de l'interface utilisateur et des opérations côté serveur, avec des valeurs par défaut judicieuses pour les piles, les pondérations et les métadonnées.
Puis-je mélanger qb-inventory et ox_inventory ?
Non recommandé. Arrêtez complètement qb-inventory avant d'activer ox_inventory pour éviter les doublons de gestionnaires et la désynchronisation des éléments.
Dois-je réécrire SQL pour oxmysql ?
Principalement recherche/remplacement. Remplacer la concaténation de chaînes par des espaces réservés, adopter *.attendre API et ajout des index manquants.
Comment sécuriser les interactions ox_target ?
Utiliser groupes/job vérifie côté client mais revalide toujours sur le serveur (distance, travail, propriété de l'objet) avant les récompenses.
Qu'en est-il de la compatibilité ESX ?
La pile Ox est indépendante du framework. Mappez les événements ESX aux gestionnaires de serveur et assurez la cohérence des noms d'inventaire.
Comment évaluer les appels DB ?
Utilisez EXPLAIN, activez les avertissements de requête lente et comparez les délais avant/après l’ajout d’index.
Où dois-je définir les articles pour ox_inventory ?
Dans ox_inventory/data/items.luaGardez les étiquettes courtes et les poids réalistes.
Puis-je conserver qtarget lors de la migration vers ox_target ?
Temporairement, mais évitez les zones qui se chevauchent. Migrez fonctionnalité par fonctionnalité et supprimez qtarget lorsque la parité est atteinte.
Comment migrer les données de stockage ?
Créer un équivalent RegisterStash Entrées et exécutez SQL pour renommer les anciens identifiants de réserve avec les nouvelles clés si nécessaire. Testez en staging.
Comment définir les poids et les limites ?
Les poids vivent dans éléments.luaLes capacités de stockage/magasin font partie de RegisterStash/RegisterShop arguments.
Comment puis-je limiter les achats ou les tâches ?
Utiliser lib.addCommand/callbacks avec des temps de recharge simples en mémoire et une validation côté serveur.
Oxmysql prend-il en charge les transactions ?
Oui, enveloppez les séquences atomiques dans MySQL.transaction.await(function() ... end).
Comment gérer NUI avec Ox ?
Ox fonctionne parfaitement avec n'importe quelle NUI ; conservez simplement la logique d'interface utilisateur lourde côté client et les validations côté serveur.
Quel est l’ordre de migration le plus sûr ?
oxmysql → ox_lib → ox_inventory → ox_target. Valider après chaque étape.
Journal des modifications et crédits
| Version | Date | Remarques |
|---|---|---|
| v1.0 | 2025-09-05 | Publication initiale avec les manuels d'installation, de configuration et de migration. |
Dernière mise à jour : 2025-09-05
Crédits et sources : Documentation trop étendue (ox_inventory, ox_lib, ox_target), référence oxmysql, documentation Cfx.re et meilleures pratiques de la communauté.
Conclusion et prochaines étapes
Les deux systèmes peuvent gérer une ville de premier plan. La différence réside dans l'importance de l'héritage que vous souhaitez transmettre et dans le degré de standardisation que vous souhaitez pour votre avenir.
Prochaines étapes :
- Explorer Scripts QBOX → https://fivemx.com/qbox-scripts/
- Explorer Scripts QBCore → https://fivemx.com/qbcore-scripts/
- En savoir plus sur Conversion du cadre → https://fivemx.com/framework-conversion
Références externes (en savoir plus)
- QBOX GitHub (qbx_core) → https://github.com/Qbox-project/qbx_core
- QBCore GitHub (qb-core) → https://github.com/qbcore-framework/qb-core
- FiveM Docs — Manifeste de ressources (fxmanifest.lua) → https://docs.fivem.net/docs/scripting-reference/resource-manifest/resource-manifest/
