Interact system

1. 01

   Drop the resource

   Grab the script from your Tebex account, then copy the avenida_interact/ folder into resources/[avenida]/ on your server.

2. 02

   Enable in server.cfg

   Add ensure avenida_interact. Nothing has to load before it: since 1.1.0 the resource has no dependency, so load order does not matter.

3. 03

   Set your defaults

   Open config/config.lua and tune what applies to every point: label, key, showIcon and canInteract distances, icon, color, named colors, ped spawn range, and Config.Hud to pick which HUD is hidden during a dialogue.

4. 04

   Remove the demos

   The examples in config/entities/, config/peds/ and config/positions/ are live as long as their files are there. Delete the ones you do not want, the manifest globs those folders so there is nothing else to edit.

5. 05

   Test the hot reload

   Start the server, then type /restart avenida_interact in game. Icons disappear and come back cleanly, and points registered by your own resources survive, without restarting your session.

Your first interaction point in 30 seconds

Create a `myscript/client.lua` in your own resource and paste this. A cyan marker appears at 30m, the "E - Hello" prompt unrolls at 2m. The only thing that has to be running is avenida_interact itself.

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

Public exports grouped by domain. Each row shows the call signature and what it does, not how it does it.

Interact Points

• positionRegister

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

  Registers a point on fixed coordinates. Takes every visual field (hintIcon, hintColor, showIcon, canInteract, offsetZ, blips) plus choices[] for several keys on the same point. canInteract accepts a number or a function, so you can gate the prompt on a job, an item or a cooldown. Returns an id.

• pedRegister

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

  Spawns a configured NPC (model, animDict and animName or a scenario, blip), attaches a point on it and returns its index. The ped is invincible, will not flee and will not ragdoll. It spawns and despawns around Config.PedSpawnRange, 50m by default. Set randomComponents = false on a named vendor, otherwise every player sees a different outfit.

• pedRemove

  exports.avenida_interact:pedRemove(idx) Copy

  Added in 1.1.0. Despawns a ped registered with pedRegister and drops its registration, so a temporary quest giver can leave when the quest is over.

• entityRegister

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

  Attaches a point onto one existing entity, passed as cfg.entity. Supports cfg.bone to hook the prompt on a bone instead of the entity center. Use it for something another script spawned: a vehicle, a placed prop, a dropped item.

• entityRegisterByHash

  exports.avenida_interact:entityRegisterByHash(hash, cfg) Copy

  Passive watcher: the config applies to every entity of that model, the ones already streamed and the ones that appear later. A single thread covers all registered hashes and sweeps every 5s. This is what you want for ATMs, vending machines and doors, rather than a coordinate list to maintain.

• entityRemove

  exports.avenida_interact:entityRemove(idx) Copy

  Detaches the point returned by entityRegister. The entity itself is left alone.

• interactCreate

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

  Runtime point, created and removed on demand. Use it when the point only exists for a while: a mission objective, a bag on the ground, a body to search.

• interactRemove

  exports.avenida_interact:interactRemove(id) Copy

  Removes a point created by interactCreate, and its blip if it declared one.

• unlockLastInteract

  exports.avenida_interact:unlockLastInteract() Copy

  A point locks itself once used, so a held key does not fire it twice. Call this at the end of your action to re-arm it. If the player is still in range the prompt comes straight back, otherwise it waits for them to walk in again.

Prompt API

• HandleTextUI

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

  Creates or updates a standalone 3D bubble, without any interaction point behind it. For when you want to drive visibility from your own thread. Returns the handler you pass to Draw3DSprite.

• Draw3DSprite

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

  Draws the bubble in world space from a render thread, un-stretched against the screen aspect. With hintOnly = true only the marker is drawn, which is the long distance state of a normal point.

• CloseTextUI

  exports.avenida_interact:CloseTextUI(id) Copy

  Hides a bubble but keeps its DUI in memory, so reopening is instant.

• RemoveTextUI

  exports.avenida_interact:RemoveTextUI(id) Copy

  Removes a bubble for good and frees its DUI. Use it when you know it will not come back.

• RemoveTextUIs

  exports.avenida_interact:RemoveTextUIs() Copy

  Removes every active bubble. Called for you when the resource stops.

• IsDuiVisible

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

  True while a prompt is on screen. Read it to keep your own prompts from stacking on top of an interaction.

Key handler

• HandleHoldTextUI

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

  The layer the points are built on: it draws a prompt at Coords and watches its key from a 50ms manager thread. data takes BindToHold (control index), DistanceHold, Coords, ChoicesUI and ChoicesCtrl for a multi-key prompt, onCallback(id) and canInteract(id, dist). It fires on press with a 500ms debounce, and your callback runs in a pcall so an error on your side does not break the prompt.

• CloseHoldTextUI

  exports.avenida_interact:CloseHoldTextUI(id) Copy

  Hides the prompt without destroying the instance, for a clean exit when the player leaves the zone.

• RemoveHoldTextUI

  exports.avenida_interact:RemoveHoldTextUI(id) Copy

  Destroys one instance and frees its DUI.

• RemoveHoldTextUIs

  exports.avenida_interact:RemoveHoldTextUIs() Copy

  Destroys every active instance.

Real-world copy-paste examples. Drop them into your own resource, tweak the values, ship.

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

• Do I really not need ox_lib?
  You do not. Since 1.1.0 `bridges/compat.lua` implements DUI creation, proximity points and the wait helpers on plain natives, and the `@ox_lib/init.lua` line is commented out in the manifest. If you would rather route that through ox_lib, set `Config.UseOxLib = true` and uncomment that line. Both paths are supported, the native one is the default.
• My marker does not show up, where do I look?
• My choice condition is ignored
• What colors can I use?
• The prompt looked stretched on my ultrawide
• My points stay visible after my resource stops
• How do I plug it into ESX, QBCore, Qbox, ox or vRP?
• How many points can I register?