Developers

The native API is client-side: call these exports from a client script. Each registration belongs to the resource that made it and is removed when that resource stops.

Scripts written for ox_target, qb-target or qtarget don't need any of this. They keep working through the bridges. The native API adds what the bridges can't: a title on the card, a key per option, holds, and an answer on the row.

Quick exampleCopy Anchor Link

local id = exports.lation_interact:addPoint({
    coords = vec3(24.1, -1345.9, 29.5),
    label = 'Register',
    icon = 'cash-register',
    options = {
        {
            label = 'Pay',
            icon = 'credit-card',
            key = 'E',
            hold = 700,
            onSelect = function(data)
                -- false shakes the row and shows the message in its place
                return false, 'Debit card required'
            end
        },
        {
            label = 'Open till',
            icon = 'cash-register',
            groups = 'cashier',
            serverEvent = 'shop:till'
        }
    }
})

ExportsCopy Anchor Link

An add export that gets invalid data prints a message in the F8 console and returns nil. The troubleshooting page lists each message.

The ox_target and qb-target exports can also be called on lation_interact. See compatibility.

Registration fieldsCopy Anchor Link

Every add export takes a registration table: the card, its options, and how it reveals. What each kind adds (coordinates, a radius, a size, a placement on an entity) is under its export.

{
    label = 'Register',          -- the card's title
    icon = 'cash-register',
    iconColor = '#22c55e',
    options = { --[[ at least one option ]] },
    stages = { grain = 8.0, name = 4.5, reach = 2.4 },
    expand = 'smart',
    reveal = 'ambient',          -- points and zones only
    passive = false,
    inVehicle = false,
    debug = false
}

Points and zonesCopy Anchor Link

A point is a spot in the world. Its card is looked at when the middle of the screen passes within 0.4 m of the spot. A zone is a sphere or a box: looking at any part of it counts, and so does standing in it.

addPointCopy Anchor Link

local id = exports.lation_interact:addPoint(data)

The quick example is a point.

addSphereCopy Anchor Link

local id = exports.lation_interact:addSphere(data)

A sphere zone goes live when the player walks inside its radius. Unless you set stages, they come from the radius: reach is the radius plus reachMargin, name is the larger of reach plus 1.8 and 1.3 times reach, and grain is the larger of reach plus 5.0 and 1.8 times reach.

exports.lation_interact:addSphere({
    coords = vec3(441.2, -981.9, 30.7),
    radius = 1.5,
    label = 'Front desk',
    options = {
        { label = 'Ring the bell', icon = 'bell', event = 'police:ringBell' }
    }
})

addBoxCopy Anchor Link

local id = exports.lation_interact:addBox(data)

A box zone goes live while the player is inside the box. Unless you set stages, name and grain are measured from the box's horizontal bounding radius: the radius plus 2.0, and the radius plus 5.0.

exports.lation_interact:addBox({
    coords = vec3(-1196.3, -890.6, 13.9),
    size = vec3(2.0, 1.0, 2.0),
    rotation = 35.0,
    label = 'Counter',
    options = {
        { label = 'Order food', icon = 'burger', onSelect = function(data) end }
    }
})

EntitiesCopy Anchor Link

Vehicles, peds and props are looked at when the middle of the screen passes through them: a vehicle's or a prop's box, a ped's body.

addEntityCopy Anchor Link

local id = exports.lation_interact:addEntity(entity, data)

Attaches options to one entity. Register the same entity more than once to give it options in several places, such as the trunk, the hood and a door. The registration is removed when the entity stops existing. Death does not remove it, so a body can still be searched.

exports.lation_interact:addEntity(vehicle, {
    label = 'Trunk',
    bone = 'boot',
    options = {
        { label = 'Search trunk', icon = 'box-open', onSelect = function(data) end }
    }
})

addModelCopy Anchor Link

local id = exports.lation_interact:addModel(models, data)

Attaches options to every instance of the models.

exports.lation_interact:addModel({ 'prop_vend_soda_01', 'prop_vend_soda_02' }, {
    label = 'Vending machine',
    options = {
        { label = 'Buy a drink', icon = 'bottle-water', serverEvent = 'shop:vend' }
    }
})

addGlobalVehicle, addGlobalPed, addGlobalPlayer, addGlobalObjectCopy Anchor Link

local id = exports.lation_interact:addGlobalVehicle(data)
local id = exports.lation_interact:addGlobalPed(data)
local id = exports.lation_interact:addGlobalPlayer(data)
local id = exports.lation_interact:addGlobalObject(data)

Attach options to every entity of a class. addGlobalPed covers peds that are not players; addGlobalPlayer covers other players.

exports.lation_interact:addGlobalPlayer({
    options = {
        { label = 'Give ID', icon = 'id-card', groups = 'police', serverEvent = 'police:showId' }
    }
})

Model and global registrations are found by looking: they apply to the entity the player aims at, so entities nobody looks at cost nothing. addModel and addGlobalObject also match static props that are part of the map, as long as the registration sets no bone, offset or boundsOffset.

PlacementCopy Anchor Link

Entity registrations (addEntity, addModel and the globals) take these fields, and use the first one set.

With no placement, a ped's options sit at its chest, an object's at the middle of its model, and a vehicle's on top of its body, with distance measured to the bodywork rather than the center.

On vehicles, a door bone (door_dside_f, door_pside_f, door_dside_r, door_pside_r) draws on the door handle when the model has one, and bonnet and boot draw in the middle of the lid. A handle bone such as handle_dside_f shares one list with its door.

reveal doesn't apply to entities: they always reveal when looked at, and setting it prints a warning once per resource. Since entities never show a point of light, only the name and reach stages matter for them.

Entities moving faster than 3 m/s show nothing until they slow down.

How registrations combineCopy Anchor Link

Registrations on the same entity at the same spot (the same bone, the same offset, or no placement) merge into one list. addEntity options come first, then addModel, then the globals, each in the order they were registered.

Options with no placement are about the whole entity, so they also appear on every other spot on that entity, after that spot's own options. A vehicle's door list can then hold both the door's options and the vehicle's.

The card's title comes from the registration whose option leads the visible list. If that one has no label, or one that only repeats its option, the next registration down the list with a label of its own titles the card. A merged list is passive only when every registration in it is.

OptionsCopy Anchor Link

{
    label = 'Pay',
    icon = 'credit-card',
    iconColor = '#22c55e',
    key = 'E',
    hold = 700,
    keepOpen = false,
    groups = 'cashier',
    items = 'debit_card',
    state = 'locked',            -- entity registrations only
    canInteract = function(data) return true end,
    onSelect = function(data) end,
    event = 'shop:paid',
    serverEvent = 'shop:pay',
    args = { price = 25 },
    allowInVehicle = false
}

Keys and holdsCopy Anchor Link

An option without a key is run by the confirm key while its row is highlighted, or by a click. The highlight starts on the first row and moves only with the mouse cursor, so on a list of several, give each option a key, or players reach the rows after the first only by holding Alt and clicking. An option with a key answers to that key or a click, not to the confirm key. If two visible options claim the same key, the first one gets it. An option that claims the confirm key itself takes every press of it, so the rows without a key can then only be clicked.

While a list is open, the game controls behind the keys it claims are turned off so one press doesn't do two things: E (pick up), F (enter vehicle), Q (cover), R (reload and light melee), G (detonate), H (headlight), TAB (weapon wheel) and SPACE (jump). Only keys used by the visible options or the confirm key are affected.

Binding W, A, S or D works, but prints a warning, since the option would fire while the player walks.

A hold option fills a ring while the key, or the mouse button on its row, stays down. Letting go early cancels it. A hold with no key of its own fills a ring around its icon and is held with the confirm key.

GatesCopy Anchor Link

groups, items and state are checked by lation interact itself. An option that fails one is hidden.

{
    label = 'Open armory',
    icon = 'gun',
    groups = { police = 2, sheriff = 2 },
    items = { 'keycard' },
    state = { key = 'locked', value = false },
    serverEvent = 'police:armory'
}

Groups are the player's job on every framework, plus the gang and citizen id on Qbox and QBCore. They are read through bridge/client.lua at most once a second. Items are read through the detected inventory; ox_inventory counts update live, others are cached for a second.

state only works on entity registrations. On a point or zone it prints a warning and the option stays hidden.

With the quick example, a player with the cashier job sees both rows, and anyone else sees Pay alone:

canInteractCopy Anchor Link

canInteract = function(data)
    return true
end

It runs on lation interact's think loop, never on the frame: about 12 times a second for the card in focus, and every 0.16 s to 0.24 s for the others in range, to know whether they have anything to show. Functions from another resource work.

Keep it quick and don't wait in it. The think loop calls it directly, so a canInteract that waits holds up every interaction's update until it returns. The card on screen stays in place and keys keep working, since those run on the frame.

canInteract is not run again when the player presses the key; only groups, items, state and passive mode are checked again then. If it raises an error, the option is hidden.

{
    label = 'Refuel',
    icon = 'gas-pump',
    canInteract = function(data)
        return GetVehicleFuelLevel(data.entity) < 90.0
    end,
    onSelect = function(data) end
}

Handling a selectionCopy Anchor Link

When an option runs, onSelect, then event, then serverEvent fire, each one that is set. They run in their own thread, so they can wait. The row answers once all three have fired.

onSelectCopy Anchor Link

onSelect = function(data)
    return ok, message
end

For addModel and global registrations, id identifies the interaction on that one entity, not the id the export returned. Use args to tell your options apart.

If onSelect raises an error, the console prints onSelect error with the resource and option label, and the row settles as done.

eventCopy Anchor Link

AddEventHandler(name, function(data) end)

A local client event, triggered on the player's client.

serverEventCopy Anchor Link

RegisterNetEvent(name, function(data) end)

Entity handles don't cross the network, so use netId on the server. It is a network event: source is the player who used the option. Any client can trigger a network event, so check on the server that the player may do what it asks.

exports.lation_interact:addModel('prop_vend_soda_01', {
    label = 'Vending machine',
    options = {
        { label = 'Buy a drink', icon = 'bottle-water', serverEvent = 'shop:vend', args = { price = 5 } }
    }
})

FeedbackCopy Anchor Link

onSelect can answer in place, on the row the player used:

onSelect = function(data)
    if not HasEnoughCash(data.args) then -- your own check
        return false, 'Not enough cash'
    end
    TriggerServerEvent('shop:pay', data.args)
    return true, 'Paid'
end

A message shows for 1.5 seconds and a check alone for 0.8 seconds. If onSelect hasn't returned after 0.1 seconds, a spinner shows on the row, and the card ignores another press until it answers. After 8 seconds without an answer it settles as done. The card also ignores a press for 0.35 seconds after an option runs.

RemovingCopy Anchor Link

exports.lation_interact:remove(id)

removePoint and removeEntity do the same for a lation interact id. An id that is already gone does nothing.

You rarely need it for cleanup: everything a resource registered is removed when it stops, and addEntity registrations go when their entity stops existing.

Hiding the layerCopy Anchor Link

suppress and releaseCopy Anchor Link

exports.lation_interact:suppress(tag)
exports.lation_interact:release(tag)

Any script can hide every interaction, for a minigame or a cutscene, under its own tag. Tags are independent: releasing one leaves the others in place, and the layer stays hidden until every tag is released. Use a tag unique to your script. The debug report shows the tag as the reason the layer is hidden.

exports.lation_interact:suppress('my_minigame')
-- ...
exports.lation_interact:release('my_minigame')

isSuppressedCopy Anchor Link

local hidden = exports.lation_interact:isSuppressed()

That covers every tag and the states in Config.Suppress. The answer is updated on lation interact's own loop, so right after a suppress call it can still read false for about a tenth of a second.

EventsCopy Anchor Link

lation interact fires no events of its own for scripts to listen to. Selections reach your script through onSelect, event and serverEvent.

lation_interact:toggleVehicleDoorCopy Anchor Link

TriggerServerEvent('lation_interact:toggleVehicleDoor', netId, door)

What the built-in door toggles use. The server passes the toggle to the client that controls the vehicle, which opens a shut door or shuts an open one; a locked vehicle's doors don't move. ox_target:toggleEntityDoor does the same under ox_target's name.

It also listens to these:

CommandsCopy Anchor Link

/interact_debug [seconds]

Records while the player tries the interaction, then prints a support report in the F8 console. Run it again to stop early. Anyone can run it, in chat or as interact_debug in F8. See troubleshooting.