# Configuration

`Floating Interaction` is configured directly through the export arguments passed from your client-side scripts.

There is no one-time registration system — every floating interaction is created, updated, and removed dynamically based on the data you send to the export.

***

Use the following export to display a floating interaction:

```lua
exports['msk_interactions']:ShowFloatingHelpNotification(data, callback)
```

***

### Basic Structure

```lua
exports['msk_interactions']:ShowFloatingHelpNotification({
    name        = 'my_unique_label',
    text        = 'Press ~INPUT_CONTEXT~ to open',
    icon        = 'fa-solid fa-box',
    image       = 'item_name',
    coords      = vec3(x, y, z),
    distance    = 5.0,
    interact    = 2.0,
    throughWall = false,
    npcData     = nil,
}, optionalCallback)
```

### Parameters

#### `name`

Defines the unique identifier of the floating interaction.

```lua
name = 'my_unique_label'
```

This value is required and should be unique for each interaction.

***

#### `text`

Defines the text displayed inside the floating label.

```lua
text = 'Press ~INPUT_CONTEXT~ to open'
```

You can use GTA input placeholders inside the text.

***

#### `icon`

Defines the Font Awesome icon displayed in the label.

```lua
icon = 'fa-solid fa-box'
```

This is optional, but recommended for a cleaner and more modern UI.

***

#### `image`

Defines an optional image displayed in the interaction.

```lua
image = 'item_name'
```

This is useful for item-based interactions when using your item image system.

***

#### `coords`

Defines the world position of the interaction.

```lua
coords = vec3(x, y, z)
```

For NPC interactions, `vec4` can also be used if a heading is needed.

***

#### `distance`

Defines the maximum render distance in meters.

```lua
distance = 5.0
```

If the player is farther away than this distance, the interaction will not be shown.

> Setting `distance = 0` makes the interaction always active regardless of player position.

***

#### `interact`

Defines the distance at which the interaction becomes active.

```lua
interact = 2.0
```

This is the range where your callback should usually handle player input.

***

#### `throughWall`

Defines whether the interaction can be shown through walls.

```lua
throughWall = false
```

Supported values:

* `false` — requires line of sight
* `true` — ignores wall checks

***

#### `npcData`

Defines optional NPC data for automatic ped spawning.

```lua
npcData = {
    Model = GetHashKey('a_m_m_tourist_01'),
    Heading = 90.0,
    AutoHeading = true,
    Anim = {
        Dict = 'amb@world_human_stand_mobile@male@text@base',
        Lib = 'base'
    },
}
```

When `npcData` is provided, the resource automatically spawns, freezes, and manages the NPC.

***

### Callback

You can provide an optional callback as the second argument.

```lua
function()
    if IsControlJustReleased(0, 51) then
        TriggerEvent('my_shop:open')
    end
end
```

The callback runs continuously while the player is within the interaction distance.

This is where you should normally handle key input and trigger your events.

***

### Minimal Example

```lua
CreateThread(function()
    while true do
        Wait(150)

        exports['msk_interactions']:ShowFloatingHelpNotification({
            name = 'my_shop',
            text = 'Press ~INPUT_CONTEXT~ to open shop',
            icon = 'fa-solid fa-shop',
            coords = vec3(123.0, 456.0, 78.9),
            distance = 8.0,
            interact = 2.0,
        }, function()
            if IsControlJustReleased(0, 51) then
                TriggerEvent('my_shop:open')
            end
        end)
    end
end)
```

***

### NPC Example

```lua
exports['msk_interactions']:ShowFloatingHelpNotification({
    name = 'my_npc',
    text = 'Press ~INPUT_CONTEXT~ to talk',
    icon = 'fa-solid fa-comment',
    coords = vec4(x, y, z, heading),
    distance = 8.0,
    interact = 2.0,
    npcData = {
        Model = GetHashKey('a_m_m_tourist_01'),
        Heading = 90.0,
        AutoHeading = true,
        Anim = {
            Dict = 'amb@world_human_stand_mobile@male@text@base',
            Lib = 'base'
        },
    },
})
```

***

### How It Works

The interaction only stays visible while the export is being called.

Once you stop calling the export, the label is removed automatically after a short delay.

This makes the system ideal for dynamic interactions, temporary prompts, NPC conversations, and location-based labels.

***

### Notes

* The export must be called continuously from a loop
* This is not a one-time registration system
* Labels are removed automatically shortly after you stop calling the export
* NPCs are spawned and removed automatically when using `npcData`
* `distance = 0` keeps the label always active
* `throughWall = true` disables the line-of-sight wall check
* Key mapping placeholders only affect the UI display, not actual input detection


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mskscripts.gitbook.io/mskscripts/scripts/floating-interaction/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.