Interact system

1. 01

   Coloca el recurso

   Descarga el script desde tu cuenta Tebex y copia la carpeta avenida_interact/ en resources/[avenida]/ de tu servidor.

2. 02

   Actívalo en server.cfg

   Añade ensure avenida_interact. No hace falta que cargue nada antes: desde la 1.1.0 el recurso no tiene dependencias, así que el orden de carga da igual.

3. 03

   Fija tus valores por defecto

   Abre config/config.lua y ajusta lo que se aplica a todos los puntos: etiqueta, tecla, distancias showIcon y canInteract, icono, color, colores con nombre, distancia de aparición de los peds, y Config.Hud para elegir qué HUD se oculta durante un diálogo.

4. 04

   Quita las demos

   Los ejemplos de config/entities/, config/peds/ y config/positions/ siguen activos mientras sus archivos estén ahí. Borra los que no quieras, el manifest recorre esas carpetas, no hay nada más que tocar.

5. 05

   Prueba la recarga en caliente

   Arranca el servidor y escribe /restart avenida_interact en el juego. Los iconos desaparecen y vuelven limpios, y los puntos registrados por tus propios recursos sobreviven, sin reiniciar tu sesión.

Tu primer punto de interacción en 30 segundos

Crea un `myscript/client.lua` en tu propio recurso y pega esto. Un marcador cian aparece a 30m, el prompt "E - Hello" se despliega a 2m. Lo único que tiene que estar activo es avenida_interact.

-- 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 públicos agrupados por dominio. Cada fila muestra la firma de la llamada y qué hace, no cómo lo hace.

Interact Points

• positionRegister

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

  Registra un punto en unas coordenadas fijas. Acepta todos los campos visuales (hintIcon, hintColor, showIcon, canInteract, offsetZ, blips) más choices[] para varias teclas en el mismo punto. canInteract acepta un número o una función, así que puedes condicionar el prompt a un trabajo, un item o un cooldown. Devuelve un id.

• pedRegister

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

  Hace aparecer un NPC configurado (modelo, animDict y animName o un scenario, blip), le engancha un punto y devuelve su índice. El ped es invencible, no huye y no cae en ragdoll. Aparece y desaparece a la distancia que marca Config.PedSpawnRange, 50m por defecto. Pon randomComponents = false en un vendedor con nombre, porque si no cada jugador le verá ropa distinta.

• pedRemove

  exports.avenida_interact:pedRemove(idx) Copiar

  Añadido en la 1.1.0. Hace desaparecer un ped registrado con pedRegister y borra su registro, para que un NPC de misiones temporal pueda irse cuando la misión termina.

• entityRegister

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

  Engancha un punto a una entity existente, pasada en cfg.entity. Admite cfg.bone para colgar el prompt de un bone en vez del centro de la entity. Úsalo para lo que otro script haya hecho aparecer: un vehículo, un prop colocado, un objeto tirado.

• entityRegisterByHash

  exports.avenida_interact:entityRegisterByHash(hash, cfg) Copiar

  Watcher pasivo: la config se aplica a todas las entities de ese modelo, las ya cargadas y las que aparezcan después. Un único thread cubre todos los hashes registrados y hace una pasada cada 5s. Es lo que quieres para cajeros, máquinas expendedoras y puertas, en vez de mantener una lista de coordenadas.

• entityRemove

  exports.avenida_interact:entityRemove(idx) Copiar

  Desengancha el punto devuelto por entityRegister. La entity en sí no se toca.

• interactCreate

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

  Punto en tiempo de ejecución, que creas y quitas cuando hace falta. Úsalo cuando el punto solo existe un rato: un objetivo de misión, una bolsa en el suelo, un cuerpo que registrar.

• interactRemove

  exports.avenida_interact:interactRemove(id) Copiar

  Quita un punto creado con interactCreate, y su blip si declaraba uno.

• unlockLastInteract

  exports.avenida_interact:unlockLastInteract() Copiar

  Un punto se bloquea al usarse, para que una tecla mantenida no lo dispare dos veces. Llama a esto al final de tu acción para rearmarlo. Si el jugador sigue dentro del alcance, el prompt vuelve enseguida. Si no, espera a que se acerque otra vez.

Prompt API

• HandleTextUI

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

  Crea o actualiza una burbuja 3D autónoma, sin punto de interacción detrás. Para cuando quieres controlar la visibilidad desde tu propio thread. Devuelve el handler que pasas a Draw3DSprite.

• Draw3DSprite

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

  Dibuja la burbuja en el mundo desde un thread de render, corregida según la proporción de la pantalla. Con hintOnly = true solo se dibuja el marcador, que es el estado a larga distancia de un punto normal.

• CloseTextUI

  exports.avenida_interact:CloseTextUI(id) Copiar

  Oculta una burbuja pero mantiene su DUI en memoria, así que reabrirla es instantáneo.

• RemoveTextUI

  exports.avenida_interact:RemoveTextUI(id) Copiar

  Quita una burbuja del todo y libera su DUI. Úsalo cuando sepas que no va a volver.

• RemoveTextUIs

  exports.avenida_interact:RemoveTextUIs() Copiar

  Quita todas las burbujas activas. Se llama automáticamente cuando el recurso se para.

• IsDuiVisible

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

  Verdadero mientras hay un prompt en pantalla. Léelo para que tus propios prompts no se apilen encima de una interacción.

Key handler

• HandleHoldTextUI

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

  La capa sobre la que se construyen los puntos: dibuja un prompt en Coords y vigila su tecla desde un thread manager a 50ms. data toma BindToHold (índice de control), DistanceHold, Coords, ChoicesUI y ChoicesCtrl para un prompt de varias teclas, onCallback(id) y canInteract(id, dist). Dispara al pulsar con un debounce de 500ms, y tu callback se ejecuta dentro de un pcall, así que un error tuyo no rompe el prompt.

• CloseHoldTextUI

  exports.avenida_interact:CloseHoldTextUI(id) Copiar

  Oculta el prompt sin destruir la instancia, para una salida limpia cuando el jugador deja la zona.

• RemoveHoldTextUI

  exports.avenida_interact:RemoveHoldTextUI(id) Copiar

  Destruye una instancia y libera su DUI.

• RemoveHoldTextUIs

  exports.avenida_interact:RemoveHoldTextUIs() Copiar

  Destruye todas las instancias activas.

Ejemplos para copiar y pegar en los casos más habituales. Los metes en tu recurso, ajustas los valores y a producción.

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,
            },
        },
    },
})

• ¿De verdad no necesito ox_lib?
  No lo necesitas. Desde la 1.1.0 `bridges/compat.lua` implementa la creación de DUI, los puntos de proximidad y los helpers de espera solo con natives, y la línea `@ox_lib/init.lua` está comentada en el manifest. Si prefieres pasar por ox_lib, pon `Config.UseOxLib = true` y descomenta esa línea. Los dos caminos siguen soportados, y el nativo es el que viene por defecto.
• Mi marcador no aparece, ¿dónde miro?
• La condición de mi opción no se aplica
• ¿Qué colores puedo usar?
• El prompt salía estirado en mi ultrawide
• Mis puntos siguen visibles después de parar mi recurso
• ¿Cómo lo conecto a ESX, QBCore, Qbox, ox o vRP?
• ¿Cuántos puntos puedo registrar?