> For the complete documentation index, see [llms.txt](https://5scripts-1.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://5scripts-1.gitbook.io/docs/assets/5s_dialogs/usage.md).

# Usage

### Basic Dialog Structure

```lua
    local dialogData = {
        id = "example_dialog", -- Unique dialog identifier
        title = "NPC Name", -- NPC's name
        role = "NPC Role", -- NPC's role/occupation
        roleColor = "#ff000077", -- Role badge color
        roleBorderColor = "#ff0000", -- Role badge border color
        text = "Welcome message", -- Initial greeting text
        ped = ped, -- NPC entity object
        options = {
            {
                title = "Option 1", -- Dialog option title
                description = "Option 1 description", -- Brief description
                text = "NPC response text", -- Text shown when option is selected
                onSelect = function()
                    -- Code executed when option is selected
                end,
                next = { -- Sub-menu options
                    {
                        title = "Sub-option 1",
                        description = "Sub-option 1 description",
                        text = "Response for sub-option 1",
                        onSelect = function()
                            -- Code executed when sub-option is selected
                        end,
                        close = true -- Closes dialog when selected and typing text will be end
                    }
                }
            }
        }
    }
```

### Properties

* `id`: Unique identifier for the dialog
* `title`: NPC's name displayed in dialog
* `role`: NPC's role or occupation
* `roleColor (optional)`: Displayed badge color
* `roleBorderColor (optional)`: Displayed badge border color
* `text`: Initial greeting message
* `ped`: Reference to the NPC entity
* `options`: Array of dialog options

#### Option Properties

* `title`: Option text shown in menu
* `description (optional)`: Additional description text
* `text`: NPC's response when selected
* `onSelect(close?, response?) (optional)`: Function triggered on selection
  * `close() (optional)` : Close dialog immediately
  * `response(text) (optional)` : Update dialog text
* `next (optional)`: Sub-menu options array
* `close (optional)`: Boolean to close dialog after selection

### Example Usage

```lua
    local dialogId = exports["5s_dialogs"]:CreateDialog(dialogData)
    exports["5s_dialogs"]:ShowDialog(dialogId)
```

### Exports

#### CreateDialog

```lua
    exports["5s_dialogs"]:CreateDialog(dialogData)
```

This function creates a new dialog and returns the dialog id

#### ShowDialog

```lua
    exports["5s_dialogs"]:ShowDialog(dialogId)
```

This function shows the dialog with the given id

#### RemoveDialog

```lua
    exports["5s_dialogs"]:RemoveDialog(dialogId, removePed)
```

This function removes the dialog with the given id, if you send second true, ped will be removed