> ## Documentation Index
> Fetch the complete documentation index at: https://lationscripts.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Interact - Globals

> Make a whole class of entity interactive with the addGlobal family

The `addGlobal*` exports register **rules** for an entire class of entity - every vehicle, every NPC, every other player, every object - with no per-entity registration.

```lua theme={null}
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)
```

Returns a rule id (number) on success, or `nil` with a console error explaining what's wrong. `exports.lation_interact:remove(id)` removes the rule and every anchor it created, immediately. Rules are also cleaned up when your resource stops.

<Note>
  This page covers what globals add on top of the shared vocabulary. The anchor fields (`label`, `options`, `icon`, `stages`, `expand`, `reveal`, `debug`), the option table, condition gates, and handlers are documented in [Options](/docs/interact/api/options).
</Note>

## Parameters

<ParamField path="data" type="table" required>
  The anchor template - all the shared [anchor fields](/docs/interact/api/options#anchor-fields) plus the same placement fields `addEntity` takes:

  * `bone` (string) - bone the anchor rides on each matching entity (e.g. `'boot'`); missing bones fall through to `offset`, then to the entity center
  * `offset` (vector3) - entity-**local** offset from the center, rotating with the entity
</ParamField>

What each export matches:

* **`addGlobalVehicle`** - every vehicle. The one you're sitting in is excluded by default - see [your own vehicle](#behavior-notes) below.
* **`addGlobalPed`** - every NPC ped. Never players, never your own ped.
* **`addGlobalPlayer`** - every *other* player's ped. Never your own.
* **`addGlobalObject`** - every object.

Across all model and global rules combined, at most the nearest `24` matches are active at once - over the cap, the nearest win.

## Merging

Globals merge into the same per-spot stacks as every other source, at the lowest priority: **explicit `addEntity` > model rules > globals**. One trunk rule plus a mission vehicle's own trunk option is one stack, mission option on top. See [Merging](/docs/interact/api/models#merging) for a worked example.

<Warning>
  On a rule-created anchor, the handler payload's `data.id` identifies which entity's stack fired - it is not the rule id. Keep the id your `addGlobal*` call returned; that's the one `remove(id)` takes.
</Warning>

## Behavior Notes

<AccordionGroup>
  <Accordion title="Quiet until looked at" icon="eye">
    Rule-created anchors default to `reveal = 'focus'`: nothing renders until the player looks at the entity, so a street full of cars and peds stays perfectly quiet. Pass `reveal = 'ambient'` on the rule to mark every match with a grain of light from a distance.
  </Accordion>

  <Accordion title="Your own vehicle" icon="car-side">
    `addGlobalVehicle` skips the vehicle you're sitting in by default. Glovebox-style scripts that expect their options while seated need `Config.IncludeOwnVehicle = true`.
  </Accordion>

  <Accordion title="Moving entities" icon="gauge-high">
    A match moving faster than `3.0 m/s` holds at the grain stage and can't be focused - a passing car earns a point of light, not a prompt. It becomes interactable the moment it slows down.
  </Accordion>

  <Accordion title="Shared export names" icon="code-merge">
    The `addGlobal*` names are also ox\_target export names, told apart by shape: a native spec always carries an `options` array, while ox-style calls route to the [compatibility bridge](/docs/interact/compat/ox-target).
  </Accordion>
</AccordionGroup>

## Example

A pickpocket option on every NPC - one rule, registered once at resource start:

```lua theme={null}
local pickpocket = exports.lation_interact:addGlobalPed({
    options = {
        {
            label = 'Pickpocket',
            icon = 'hand-sparkles',
            hold = 3000,           -- ring fills for 3s
            items = 'lockpick',    -- hidden without one
            canInteract = function(data)
                return not IsPedInAnyVehicle(data.entity, false)
            end,
            serverEvent = 'crime:pickpocket'
        }
    }
})

-- later, if the mechanic ever needs to retire the rule
exports.lation_interact:remove(pickpocket)
```

Every option here is gated - matched peds show nothing at all to anyone without a lockpick.