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

# World Interactions

> Use the bridge for world interactions in your own scripts — Interact prompts, Zones, and Blips, all themed and self-cleaning.

The bridge ships client-side world helpers you can use in any resource: **Interact** for "press E" prompts on points and entities, **Zones** for area triggers, and **Blips** for the map. They are pure-Lua libraries that load into your VM, follow the [theme accent](/atlas-bridge/theming), and free themselves when your resource stops.

These are **client-side** namespaces.

## Interact

`Bridge.Interact` puts a keycap on a world point or entity. When the player is within `distance`, the keycap shows; within `expandDistance` it expands into a navigable option list (arrow keys / scroll to move, the confirm key to select). A single-option shorthand also works.

```lua theme={null}
local h = Bridge.Interact.Add({
    coords = vec3(215.7, -810.1, 30.7),
    label = 'Storage locker',
    key = 'E',                 -- confirm key: a letter or a control id
    distance = 2.5,            -- show the keycap within this range (m)
    expandDistance = 1.2,      -- expand to the option list within this range (m)
    options = {
        { label = 'Open stash', icon = 'box',
          onSelect = function() openStash() end },
        { label = 'Toggle lock', icon = 'lock',
          canInteract = function() return isOwner end,
          onSelect = function() toggleLock() end },
    },
})

h.Remove()
```

Single-option shorthand — pass `label` + `onSelect` directly, no `options` list:

```lua theme={null}
Bridge.Interact.Add({ coords = vec3(...), label = 'Fish', onSelect = startFishing })
```

### Anchor to a moving entity

Pass `entity` or `netId` instead of `coords` to track a moving object; `offset` shifts the anchor from its origin.

```lua theme={null}
Bridge.Interact.Add({
    netId = vehicleNetId,
    offset = vec3(0.0, 0.0, 1.0),
    label = 'Inspect vehicle',
    onSelect = inspect,
})
```

### Options & fields

<ParamField path="coords | entity | netId" type="vector3 | integer">
  The anchor. Use `coords` for a fixed point, or `entity` / `netId` to track a moving object.
</ParamField>

<ParamField path="label" type="string">
  Text shown when the prompt is collapsed (and the default option label).
</ParamField>

<ParamField path="key" type="string | integer" default="E">
  The confirm key. A letter (`'E'`, `'F'`, `'G'`, `'H'`, `'K'`, `'N'`, `'M'`, `'B'`, `'R'`, `'SPACE'`) or a raw control id.
</ParamField>

<ParamField path="distance" type="number" default="2.0">
  Range at which the keycap appears.
</ParamField>

<ParamField path="expandDistance" type="number">
  Range at which the prompt expands into the option list.
</ParamField>

<ParamField path="offset" type="vector3">
  Offset from the anchor entity's origin.
</ParamField>

<ParamField path="options" type="table[]">
  The option list. Each option: `label`, `icon`, `canInteract` (a function returning a boolean), `onSelect`.
</ParamField>

<ParamField path="canInteract" type="fun(): boolean">
  Top-level gate for the whole prompt (single-option form).
</ParamField>

An option's `onSelect` runs **in your resource's VM**, so it sees your script's state directly — there is no event bus.

### Suspend & resume

Hide all of your resource's prompts under a named reason (reference-counted, so nested suspends are safe). Useful while a menu is open.

```lua theme={null}
Bridge.Interact.Suspend('inMenu')
-- ... menu open ...
Bridge.Interact.Resume('inMenu')
```

| Method                             | Effect                                       |
| ---------------------------------- | -------------------------------------------- |
| `Bridge.Interact.Add(opts)`        | Add a prompt; returns `{ id, Remove }`.      |
| `Bridge.Interact.Remove(id)`       | Remove a prompt by id.                       |
| `Bridge.Interact.Suspend(reason?)` | Hide this resource's prompts under a reason. |
| `Bridge.Interact.Resume(reason?)`  | Lift a suspend reason.                       |

<Note>
  `Bridge.Interact` is the bridge's own interaction system and is always available. For entity/zone targeting that integrates with `ox_target` / `qb-target`, use [`Bridge.Target`](/atlas-bridge/ui/target) instead.
</Note>

## Zones

`Bridge.Zones` fires callbacks as the player crosses area boundaries. `onEnter` / `onExit` fire on boundary crossing; `onInside` runs per-frame while inside. Use zones for static areas (job zones, safe zones, blip triggers); for "press E" prompts use Interact above. One adaptive scan loop drives every zone, so they are cheap at idle.

```lua theme={null}
local z = Bridge.Zones.Box(vec3(...), { x = 4, y = 4, z = 3 }, {
    heading = 45.0,
    onEnter  = function() Bridge.Notify.Info('Entered the shop') end,
    onExit   = function() end,
    onInside = function() end,   -- per-frame while inside
})

z:Remove()
```

### Shapes

<CodeGroup>
  ```lua Sphere theme={null}
  local z = Bridge.Zones.Sphere(vec3(...), 5.0, { onEnter = fn, onExit = fn })
  ```

  ```lua Box theme={null}
  -- size is full dimensions { x, y, z }; opts.heading rotates around Z
  local z = Bridge.Zones.Box(vec3(...), { x = 4, y = 4, z = 3 }, { heading = 45.0, onEnter = fn })
  ```

  ```lua Circle theme={null}
  -- a vertical cylinder; opts.height (default 8) sets the band, or pass minZ / maxZ
  local z = Bridge.Zones.Circle(vec3(...), 3.0, { height = 6.0, onEnter = fn })
  ```

  ```lua Poly theme={null}
  -- 3+ vertices (x,y used); opts.minZ / opts.maxZ bound the height
  local z = Bridge.Zones.Poly({ vec3(...), vec3(...), vec3(...) }, { minZ = 30.0, maxZ = 34.0, onEnter = fn })
  ```
</CodeGroup>

### The zone handle

```lua theme={null}
z:IsInside()    -- boolean
z:Distance()    -- distance to the zone center
z:Disable()     -- stop firing (fires onExit if currently inside)
z:Enable()
z:Remove()
```

| Constructor                                 | Shape                             |
| ------------------------------------------- | --------------------------------- |
| `Bridge.Zones.Sphere(coords, radius, opts)` | A sphere.                         |
| `Bridge.Zones.Box(coords, size, opts)`      | A heading-rotated box.            |
| `Bridge.Zones.Circle(coords, radius, opts)` | A vertical cylinder.              |
| `Bridge.Zones.Poly(points, opts)`           | A polygon with optional Z bounds. |

All `opts` accept `onEnter`, `onExit`, `onInside`, `enabled`, `id`, and `data`.

## Blips

`Bridge.Blips` wraps the GTA blip natives with a tracked handle, and frees every blip your resource created when it stops.

```lua theme={null}
local b = Bridge.Blips.Add({
    coords = vec3(...),
    sprite = 280,
    color = 5,
    scale = 0.8,
    label = 'Bank',
    shortRange = true,
})

b:SetColor(3):SetRoute(true)   -- chainable
b:Remove()
```

### Radius blip

```lua theme={null}
local r = Bridge.Blips.AddRadius({ coords = vec3(...), radius = 50.0, color = 1, alpha = 128 })
```

### Options & handle

<ParamField path="coords" type="vector3" required>
  Blip position.
</ParamField>

<ParamField path="sprite" type="integer" default="1">
  Blip sprite id (coord blips only).
</ParamField>

<ParamField path="color" type="integer" default="0">
  Blip color id.
</ParamField>

<ParamField path="scale" type="number" default="0.8" />

<ParamField path="label" type="string">
  Map name for the blip.
</ParamField>

<ParamField path="display / shortRange / alpha / route / routeColor" type="various">
  Standard blip styling; `route = true` draws a GPS route to the blip.
</ParamField>

The handle is chainable: `SetColor`, `SetSprite`, `SetScale`, `SetAlpha`, `SetLabel`, `SetRoute(on, color?)`, plus `Exists()` and `Remove()`.

| Method                         | Effect                                   |
| ------------------------------ | ---------------------------------------- |
| `Bridge.Blips.Add(opts)`       | Add a coord blip; returns a handle.      |
| `Bridge.Blips.AddRadius(opts)` | Add a radius blip; returns a handle.     |
| `Bridge.Blips.Clear()`         | Remove every blip this resource created. |

<Tip>
  Need a glowing in-world icon instead of a map blip? `Bridge.MarkerProp.Spawn({ coords, icon })` spawns a ground-snapped, theme-recolored marker prop. `Bridge.Interact` can spawn one automatically via its `marker` option.
</Tip>