Convertir un script QBCore en QBox : qbx_core, ox_inventory, ox_target

Vous avez un script écrit pour QBCore et un serveur exécutant QBox. Parfois il démarre et fonctionne, parfois la console se remplit d'erreurs à propos d'un qb-inventory, qb-target ou qb-menu manquant. Voici l'ordre pour le porter, et les endroits où il casse généralement.

Si vous choisissez encore un core, le même travail de l'autre direction est dans convertir un script ESX en QBCore.

#Ce que QBox change et ce qu'il garde

QBox est construit sur qbx_core plus les ressources Overextended : ox_lib, oxmysql, ox_inventory et ox_target. Il garde une couche de compatibilité, donc exports['qb-core']:GetCoreObject() répond toujours et PlayerData a la même forme (citizenid, job, charinfo, metadata, money). C'est pourquoi beaucoup de scripts fonctionnent sans modification.

Ce qu'il ne garde pas, c'est les vieilles ressources utilitaires QB. Là où QBCore utilisait qb-inventory, qb-target, qb-menu, qb-input et qb-progressbar, QBox attend ox_inventory, ox_target et ox_lib. Ce sont les parties que vous portez.

La première étape est s'assurer que le core démarre correctement :

ensure oxmysql
ensure ox_lib
ensure qbx_core
ensure ox_inventory
ensure ox_target
ensure my_script

Supprimez tout dossier qb-core restant, puisque deux cores entrent en conflit. Voir QBCore est nil : GetCoreObject si l'objet manque.

#Étape 1 : dépendances dans le manifest

fx_version 'cerulean'
game 'gta5'
lua54 'yes'

shared_script '@ox_lib/init.lua'

dependencies { 'qbx_core', 'ox_lib', 'ox_inventory', 'ox_target' }

@ox_lib/init.lua c'est ce qui vous donne le global lib. S'il n'est pas trouvé, voir ox_lib init.lua non trouvé.

#Étape 2 : obtenir le joueur

Les deux fonctionnent sur QBox. Le premier est le style de compatibilité, le second est la façon QBox :

-- QBCore style (still works through the compatibility layer)
local QBCore = exports['qb-core']:GetCoreObject()
local Player = QBCore.Functions.GetPlayer(source)

-- QBox style
local player = exports.qbx_core:GetPlayer(source)
if player then
    print(player.PlayerData.citizenid, player.PlayerData.job.name)
end

Les deux retournent nil pour un joueur qui n'est pas chargé, donc gardez la vérification nil. Pour trouver un joueur chargé par citizen id, QBox a aussi GetPlayerByCitizenId. Quand vous portez, vous pouvez laisser les appels QBCore en place et les remplacer un par un plus tard.

#Étape 3 : inventaire

C'est où la plupart des scripts cassent. qb-inventory et ox_inventory ne partagent pas les définitions d'éléments ou les noms de fonctions.

local src = source
local ok = exports.ox_inventory:AddItem(src, 'water', 2, { quality = 100 })
if not ok then
    lib.notify(src, { description = 'Your inventory is full', type = 'error' })
end

AddItem retourne une valeur fausse quand l'élément n'existe pas ou ne peut pas être porté, donc vérifiez-le. Les définitions d'éléments bougent aussi. QBCore les garde dans qb-core/shared/items.lua, ox_inventory dans ox_inventory/data/items.lua. Ajoutez chaque élément que le script utilise là, dans le format ox_inventory. Comment faire cela est dans ajouter des éléments à ox_inventory, et le format QBCore d'où vous venez est dans ajouter des éléments à qb-inventory.

Les éléments utilisables sont aussi enregistrés différemment : QBCore.Functions.CreateUseableItem devient un export défini dans la définition de l'élément dans ox_inventory, qui pointe vers une fonction dans votre script. Les appels QBCore peuvent toujours fonctionner via la couche de compatibilité, donc testez un élément avant de le réécrire.

#Étape 4 : notifications, progression et menus avec ox_lib

ox_lib remplace les ressources utilitaires QB séparées. Les appels sont proches de ce que vous connaissez :

-- QBCore
QBCore.Functions.Notify('Done', 'success', 5000)

-- ox_lib (client)
lib.notify({ title = 'Job', description = 'Done', type = 'success', duration = 5000 })

-- QBCore: QBCore.Functions.Progressbar(...) with a callback
-- ox_lib: returns true when completed, false when cancelled
if lib.progressBar({
    duration = 5000,
    label = 'Repairing',
    useWhileDead = false,
    canCancel = true,
    disable = { car = true, move = true },
    anim = { dict = 'mini@repair', clip = 'fixing_a_ped' },
}) then
    print('finished')
else
    print('cancelled')
end

Les menus bougent de qb-menu à lib.registerContext et lib.showContext, et les formulaires d'entrée de qb-input à lib.inputDialog. Les exemples complets sont dans notifications et barres de progression sur ESX, QBCore et ox_lib et menus de contexte ox_lib.

#Étape 5 : ox_target au lieu de qb-target

qb-target prend un nom, des coordonnées et une table d'options dans sa propre disposition. ox_target prend une table :

-- qb-target
exports['qb-target']:AddBoxZone('my_zone', vector3(215.0, -810.0, 30.7), 1.5, 1.5, {
    name = 'my_zone', heading = 0, minZ = 29.7, maxZ = 32.7,
}, {
    options = { { event = 'my_script:client:open', icon = 'fas fa-box', label = 'Open', job = 'police' } },
    distance = 2.0,
})

-- ox_target
exports.ox_target:addBoxZone({
    coords = vector3(215.0, -810.0, 30.7),
    size = vector3(1.5, 1.5, 3.0),
    rotation = 0,
    options = {
        { name = 'my_zone_open', icon = 'fas fa-box', label = 'Open', groups = 'police',
          onSelect = function() TriggerEvent('my_script:client:open') end },
    },
})

Remarquez que event devient onSelect (ou event fonctionne toujours pour un événement client), et job devient groups. Les détails sont dans qb-target vs ox_target et zones ox_target.

#Ce qui casse généralement

• Erreurs d'éléments manquants. L'élément existe dans le fichier partagé de qb-core mais pas dans ox_inventory. Ajoutez-le.
• No such export pour qb-inventory, qb-target ou qb-menu. Le script les appelle directement : portez ces appels, ou il ne s'exécutera jamais.
• Callbacks. lib.callback est le style QBox. Si un script utilise toujours QBCore.Functions.CreateCallback, testez-le et déplacez-le vers ox_lib s'il échoue : voir callbacks serveur.
• Jobs et gangs avec grades. QBox a ses propres données de job et de groupe. Testez chaque vérification de job, surtout les comparaisons de service et de grade.
• Cores mélangés. Une ressource qb-core restante démarrée à côté de qbx_core.
• Ordre de démarrage. Votre script au-dessus de ox_lib, ox_inventory ou qbx_core dans server.cfg.

#Checklist