Interact system

1. 01

   Déposez la ressource

   Récupérez le script depuis votre compte Tebex, puis copiez le dossier avenida_interact/ dans resources/[avenida]/ sur votre serveur.

2. 02

   Activez dans server.cfg

   Ajoutez ensure avenida_interact. Rien n'a besoin de charger avant : depuis la 1.1.0 la ressource n'a aucune dépendance, l'ordre de chargement n'a donc pas d'importance.

3. 03

   Réglez vos valeurs par défaut

   Ouvrez config/config.lua et ajustez ce qui s'applique à tous les points : label, touche, distances showIcon et canInteract, icône, couleur, couleurs nommées, distance d'apparition des PNJ, et Config.Hud pour choisir quel HUD est masqué pendant un dialogue.

4. 04

   Retirez les démos

   Les exemples de config/entities/, config/peds/ et config/positions/ sont actifs tant que leurs fichiers sont là. Supprimez ceux dont vous ne voulez pas, le manifest globe ces dossiers, il n'y a rien d'autre à modifier.

5. 05

   Testez le rechargement à chaud

   Démarrez le serveur, puis tapez /restart avenida_interact en jeu. Les icônes disparaissent et reviennent proprement, et les points enregistrés par vos propres ressources survivent, sans relancer votre session.

Votre premier point d'interaction en 30 secondes

Créez un `myscript/client.lua` dans votre propre ressource et collez ceci. Un marqueur cyan apparaît à 30m, le prompt "E - Hello" se déroule à 2m. La seule chose qui doit tourner, c'est avenida_interact lui-même.

-- myscript/client.lua
exports.avenida_interact:positionRegister({
    coords      = vec3(-265.0, -963.6, 31.2),
    showIcon    = 30.0,           -- marker fades in at 30m
    canInteract = 2.0,            -- label unrolls at 2m
    hintIcon    = 'interact',     -- see the icon list below
    hintColor   = '#22d3ee',      -- hex, or an alias from Config.Colors
    message     = 'Hello',
    bind        = 'E',
    onInteract  = function()
        TriggerEvent('chat:addMessage', { args = { 'Hello, world!' } })
    end,
})

Exports publics groupés par domaine. Chaque ligne montre la signature d'appel

Interact Points

• positionRegister

  exports.avenida_interact:positionRegister(cfg) --> id Copier

  Enregistre un point sur des coordonnées fixes. Accepte tous les champs visuels (hintIcon, hintColor, showIcon, canInteract, offsetZ, blips) plus choices[] pour plusieurs touches sur le même point. canInteract accepte un nombre ou une fonction, vous pouvez donc conditionner le prompt à un job, un item ou un cooldown. Renvoie un id.

• pedRegister

  exports.avenida_interact:pedRegister(cfg) --> id Copier

  Fait apparaître un PNJ configuré (modèle, animDict et animName ou un scenario, blip), lui attache un point et renvoie son index. Le ped est invincible, ne fuit pas et ne tombe pas en ragdoll. Il apparaît et disparaît autour de Config.PedSpawnRange, 50m par défaut. Mettez randomComponents = false sur un vendeur nommé, sinon chaque joueur voit une tenue différente.

• pedRemove

  exports.avenida_interact:pedRemove(idx) Copier

  Ajouté en 1.1.0. Fait disparaître un ped enregistré avec pedRegister et retire son enregistrement, pour qu'un donneur de quête temporaire puisse partir une fois la quête finie.

• entityRegister

  exports.avenida_interact:entityRegister(cfg) --> id Copier

  Attache un point sur une entity existante, passée dans cfg.entity. Gère cfg.bone pour accrocher le prompt sur un bone plutôt que sur le centre de l'entity. À utiliser pour ce qu'un autre script a fait apparaître : un véhicule, un prop posé, un objet lâché.

• entityRegisterByHash

  exports.avenida_interact:entityRegisterByHash(hash, cfg) Copier

  Watcher passif : la config s'applique à toutes les entities de ce modèle, celles déjà streamées et celles qui apparaîtront. Un seul thread couvre tous les hash enregistrés et balaye toutes les 5s. C'est ce qu'il vous faut pour les ATM, les distributeurs et les portes, plutôt qu'une liste de coordonnées à maintenir.

• entityRemove

  exports.avenida_interact:entityRemove(idx) Copier

  Détache le point renvoyé par entityRegister. L'entity elle-même n'est pas touchée.

• interactCreate

  exports.avenida_interact:interactCreate(cfg) --> id Copier

  Point créé et retiré à la volée. À utiliser quand le point n'existe qu'un temps : un objectif de mission, un sac au sol, un corps à fouiller.

• interactRemove

  exports.avenida_interact:interactRemove(id) Copier

  Retire un point créé par interactCreate, et son blip s'il en déclarait un.

• unlockLastInteract

  exports.avenida_interact:unlockLastInteract() Copier

  Un point se verrouille une fois utilisé, pour qu'une touche maintenue ne le déclenche pas deux fois. Appelez ceci à la fin de votre action pour le réarmer. Si le joueur est encore à portée, le prompt revient directement, sinon il attend qu'il rentre à nouveau dans la zone.

Prompt API

• HandleTextUI

  exports.avenida_interact:HandleTextUI(id, data) --> duiHandler Copier

  Crée ou met à jour une bulle 3D autonome, sans point d'interaction derrière. Pour quand vous voulez piloter la visibilité depuis votre propre thread. Renvoie le handler à passer à Draw3DSprite.

• Draw3DSprite

  exports.avenida_interact:Draw3DSprite({ duiHandler, coords, maxDistance, hintOnly? }) Copier

  Dessine la bulle dans le monde depuis un thread de rendu, dé-étirée selon le ratio de l'écran. Avec hintOnly = true, seul le marqueur est dessiné, c'est l'état longue distance d'un point normal.

• CloseTextUI

  exports.avenida_interact:CloseTextUI(id) Copier

  Masque une bulle mais garde son DUI en mémoire, la réouverture est donc instantanée.

• RemoveTextUI

  exports.avenida_interact:RemoveTextUI(id) Copier

  Retire une bulle définitivement et libère son DUI. À utiliser quand vous savez qu'elle ne reviendra pas.

• RemoveTextUIs

  exports.avenida_interact:RemoveTextUIs() Copier

  Retire toutes les bulles actives. Appelé pour vous quand la ressource s'arrête.

• IsDuiVisible

  exports.avenida_interact:IsDuiVisible() --> boolean Copier

  Vrai tant qu'un prompt est à l'écran. Lisez-le pour éviter que vos propres prompts s'empilent par-dessus une interaction.

Key handler

• HandleHoldTextUI

  exports.avenida_interact:HandleHoldTextUI(id, data) --> duiHandler Copier

  La couche sur laquelle les points sont construits : elle dessine un prompt sur Coords et surveille sa touche depuis un thread manager à 50ms. data prend BindToHold (control index), DistanceHold, Coords, ChoicesUI et ChoicesCtrl pour un prompt multi-touches, onCallback(id) et canInteract(id, dist). Déclenche à la pression avec un debounce de 500ms, et votre callback tourne dans un pcall, donc une erreur de votre côté ne casse pas le prompt.

• CloseHoldTextUI

  exports.avenida_interact:CloseHoldTextUI(id) Copier

  Masque le prompt sans détruire l'instance, pour une sortie propre quand le joueur quitte la zone.

• RemoveHoldTextUI

  exports.avenida_interact:RemoveHoldTextUI(id) Copier

  Détruit une instance et libère son DUI.

• RemoveHoldTextUIs

  exports.avenida_interact:RemoveHoldTextUIs() Copier

  Détruit toutes les instances actives.

Exemples copier-coller pour les cas courants. À déposer dans ta ressource, ajuster les valeurs, et c'est en prod.

exports.avenida_interact:positionRegister({
    coords      = vec3(149.5, -1040.4, 29.4),
    showIcon    = 30.0,
    canInteract = 2.0,
    hintIcon    = 'bank',
    hintColor   = 'blue',
    message     = 'Use the ATM',
    bind        = 'E',
    onInteract  = function()
        TriggerEvent('myserver-banking:openATM')
    end,
    blips = {
        sprite  = 277,
        color   = 2,
        scale   = 0.8,
        text    = 'ATM',
        display = 4,
    },
})

local ATM_PROPS = {
    'prop_atm_01', 'prop_atm_02', 'prop_atm_03', 'prop_fleeca_atm',
}

for _, prop in ipairs(ATM_PROPS) do
    exports.avenida_interact:entityRegisterByHash(prop, {
        canInteract = 1.2,
        offsetZ     = 1.0,
        hintIcon    = 'bank',
        hintColor   = 'blue',
        choices = {
            {
                bind       = 'E',
                message    = 'Use the ATM',
                onInteract = function()
                    TriggerEvent('myserver-banking:atmUse')
                end,
            },
            {
                bind      = 'G',
                message   = 'Rob the ATM',
                hintColor = 'red',
                condition = function()
                    return exports['myserver-police']:hasEnoughCops(2)
                end,
                onInteract = function(entity)
                    TriggerServerEvent('myserver-robbery:startATM', NetworkGetNetworkIdFromEntity(entity))
                end,
            },
        },
    })
end

exports.avenida_interact:pedRegister({
    coords           = vec4(-1393.81, -1064.09, 3.17, 266.09),
    model            = 'a_f_y_vinewood_04',
    animDict         = 'anim@amb@waving@male',
    animName         = 'ground_wave',
    randomComponents = false,
    message          = 'Talk with Maria',
    showIcon         = 10.0,
    canInteract      = 3.0,
    hintIcon         = 'talk',
    hintColor        = 'gold',
    blips = { sprite = 119, color = 50, text = 'Lumberjack', scale = 0.8 },
    dialogue = {
        name     = 'Maria',
        startMsg = 'Hello, are you ready to start your shift?',
        elements = {
            {
                label  = 'Yes, where do I start?',
                action = function(changeDialog, close)
                    SetNewWaypoint(-584.01, 5491.59)
                    changeDialog('The forest is on your GPS now.', {
                        { label = 'Got it!', action = function(_, close) close() end },
                    })
                end,
            },
            {
                label  = 'I\'ll come back later',
                action = function(_, close) close() end,
            },
        },
    },
})

• Je n'ai vraiment pas besoin d'ox_lib ?
  Non. Depuis la 1.1.0, `bridges/compat.lua` implémente la création des DUI, les points de proximité et les helpers d'attente en natifs purs, et la ligne `@ox_lib/init.lua` est commentée dans le manifest. Si vous préférez passer par ox_lib, mettez `Config.UseOxLib = true` et décommentez cette ligne. Les deux chemins sont maintenus, celui en natifs est le défaut.
• Mon marqueur ne s'affiche pas, où chercher ?
• Ma condition de choix est ignorée
• Quelles couleurs puis-je utiliser ?
• Le prompt était étiré sur mon ultrawide
• Mes points restent visibles après l'arrêt de ma ressource
• Comment le brancher sur ESX, QBCore, Qbox, ox ou vRP ?
• Combien de points puis-je enregistrer ?