ox_target addBoxZone, addModel et addLocalEntity : comment ajouter des cibles

Vous ajoutez une cible dans votre script et en jeu rien ne s'affiche. Ou la console dit :

No such export addBoxZone in resource ox_target

Ceci est le guide pratique d'ox_target sur le client : la zone, le modèle et les exports d'entité, les options que vous pouvez y mettre, et comment les supprimer et les déboguer.

#Assurez-vous que ox_target est démarré en premier

Les exports n'existent que tant que ox_target s'exécute, et il a besoin d'ox_lib. Dans server.cfg, démarrez-les avant votre script :

ensure oxmysql
ensure ox_lib
ensure ox_target

ensure my_script

Ajoutez-le aussi au fxmanifest.lua de votre ressource, afin que FiveM refuse de démarrer le script sans lui :

dependency 'ox_target'

Tous les appels ci-dessous sont côté client. Mettez-les dans un fichier client, pas dans un serveur.

#Une zone boîte

Une zone boîte est un rectangle dans le monde. C'est le bon choix pour un comptoir, une porte ou un guichet automatique :

local zoneId = exports.ox_target:addBoxZone({
    coords = vec3(441.2, -981.9, 30.7),
    size = vec3(1.5, 1.0, 2.0),
    rotation = 90.0,
    debug = false,
    options = {
        {
            name = 'my_script_counter',
            icon = 'fa-solid fa-box',
            label = 'Open the counter',
            distance = 2.0,
            onSelect = function(data)
                print('selected', data.name)
            end,
        },
    },
})

coords est le centre de la boîte, size est sa largeur, longueur et hauteur, et rotation la tourne autour de l'axe vertical. Gardez le zoneId retourné si vous supprimerez la zone plus tard.

#Une zone sphère

Une sphère est plus simple quand vous ne vous souciez pas de la forme, seulement du « près de ce point » :

exports.ox_target:addSphereZone({
    coords = vec3(-1037.5, -2737.9, 20.2),
    radius = 1.5,
    options = {
        {
            name = 'my_script_sphere',
            icon = 'fa-solid fa-hand',
            label = 'Talk',
            onSelect = function()
                print('talking')
            end,
        },
    },
})

#Modèles, entités et véhicules

Pour cibler chaque objet, ped ou véhicule d'un certain modèle, utilisez addModel. Il prend un nom ou un hash de modèle, ou une liste :

exports.ox_target:addModel({ `prop_vend_soda_01`, `prop_vend_soda_02` }, {
    {
        name = 'my_script_vending',
        icon = 'fa-solid fa-bottle-water',
        label = 'Use the machine',
        distance = 1.5,
        onSelect = function(data)
            print('entity', data.entity)
        end,
    },
})

Pour cibler une entité que vous avez déjà créée sur votre client, utilisez addLocalEntity :

local ped = CreatePed(4, `a_m_m_business_01`, 441.2, -981.9, 29.7, 90.0, false, true)

exports.ox_target:addLocalEntity(ped, {
    {
        name = 'my_script_ped',
        icon = 'fa-solid fa-comment',
        label = 'Talk to him',
        onSelect = function(data)
            print('talk to', data.entity)
        end,
    },
})

Pour ajouter une option à chaque véhicule, utilisez addGlobalVehicle. D'autres exports globaux existent pour les peds, les joueurs et les objets :

exports.ox_target:addGlobalVehicle({
    {
        name = 'my_script_inspect',
        icon = 'fa-solid fa-magnifying-glass',
        label = 'Inspect vehicle',
        distance = 2.5,
        onSelect = function(data)
            print('vehicle', data.entity)
        end,
    },
})

Astuce : addLocalEntity n'existe que sur le client qui a créé l'entité. Pour une entité en réseau que d'autres joueurs devraient voir l'option, utilisez la variante en réseau (addEntity) avec l'id réseau de l'entité.

#Les champs d'option

Chaque option est une table. Ce sont les champs que vous utiliserez le plus :

canInteract reçoit l'entité et la distance, afin que vous puissiez masquer une option en fonction de n'importe quelle condition :

{
    name = 'my_script_repair',
    icon = 'fa-solid fa-wrench',
    label = 'Repair',
    distance = 2.0,
    canInteract = function(entity, distance, coords, name, bone)
        return GetVehicleEngineHealth(entity) < 900.0
    end,
    onSelect = function(data)
        print('repair', data.entity)
    end,
}

Pour les emplois, groups prend un nom ou une table, et fonctionne sur ESX, QBCore et QBox via le support de framework propre à ox_target :

groups = 'police',
-- or several, optionally with a minimum grade
groups = { police = 0, sheriff = 2 },

#Supprimer les zones et les options

Les zones sont supprimées avec l'id que l'appel a retourné :

exports.ox_target:removeZone(zoneId)

Les options ajoutées aux modèles, entités et cibles globales sont supprimées par le name que vous leur avez donné :

exports.ox_target:removeModel({ `prop_vend_soda_01` }, 'my_script_vending')
exports.ox_target:removeLocalEntity(ped, 'my_script_ped')
exports.ox_target:removeGlobalVehicle('my_script_inspect')

Nettoyez quand votre ressource s'arrête, sinon un redémarrage peut laisser des doublons derrière :

AddEventHandler('onResourceStop', function(resource)
    if resource ~= GetCurrentResourceName() then return end
    exports.ox_target:removeZone(zoneId)
    exports.ox_target:removeLocalEntity(ped, 'my_script_ped')
end)

#Déboguer une zone qui ne s'affiche pas

Définissez debug = true sur la zone. ox_target dessine alors sa forme dans le monde, de sorte que vous voyez immédiatement si la boîte est mal placée, trop petite, ou enterrée dans le sol. Les causes habituelles :

• La zone est mal placée. Les coords sont le centre, donc une boîte dont z s'assied au niveau du sol est à moitié sous terre. Relevez-la de la moitié de sa hauteur.
• La distance est trop petite. Le joueur doit être dans la distance de la zone pour voir l'option.
• Une vérification échoue. Un groups ou un canInteract qui retourne false masque l'option sans erreur. Supprimez-le temporairement pour tester.
• Deux cibles s'exécutent. Si qb-target démarre aussi, voir qb-target vs ox_target.

Par défaut, vous tenez une touche (Alt gauche) pour ouvrir l'œil de ciblage, donc testez avec elle tenue enfoncée.

#Liste de contrôle