# Configuration

`NPC Dialog System` uses a simple configuration file located in:

* `data/config.lua`

It also includes editable client-side and server-side event files for custom dialog actions.

### Configuration File

* `data/config.lua` — main configuration
* `client/events.lua` — custom client event handlers
* `server/events.lua` — custom server event handlers

### Localization

```lua
Locale = 'en' -- 'en' or 'pl'
```

Defines which language should be used.

Supported values:

* `en`
* `pl`

To add a new language, copy `locales/en.json` and create your own language file.

***

### TTS Configuration

The resource supports both ElevenLabs and OpenAI for text-to-speech.

```lua
TTS = {
    Provider = 'elevenlabs',

    ElevenLabs = {
        ApiKey = '',
        Model = 'eleven_multilingual_v2',
        OutputFormat = 'mp3_22050_32',
    },

    OpenAI = {
        ApiKey = '',
        Model = 'tts-1',
        ResponseFormat = 'mp3',
    },

    Cache = true,
}
```

#### `Provider`

Defines which TTS provider should be used.

Supported values:

* `elevenlabs`
* `openai`

#### `Cache`

```lua
Cache = true
```

When enabled, generated audio is cached in memory so the same text does not trigger repeated API calls.

> Restarting the resource clears the cache.

#### API Keys

API keys can be set directly in the config or through server convars.

Example:

```lua
set elevenlabs_api_key "your_key_here"
set openai_api_key "your_key_here"
```

***

### Voice Configuration

```lua
Voices = {
    default_male   = { elevenLabsId = 'onwK4e9ZLuTAKqWW03F9', openAiVoice = 'onyx' },
    default_female = { elevenLabsId = 'EXAVITQu4vr4xnSDxMaL', openAiVoice = 'nova' },
    deep_male      = { elevenLabsId = 'VR6AewLTigWG4xSOukaG', openAiVoice = 'echo' },
    old_male       = { elevenLabsId = 'JBFqnCBsd6RMkjVDRZzb', openAiVoice = 'fable' },
    young_female   = { elevenLabsId = 'cgSgspJ2msm6clMCkdW9', openAiVoice = 'shimmer' },
    raspy_male     = { elevenLabsId = 'cjVigY5qzO86Huf0OWal', openAiVoice = 'echo' },
    child          = { elevenLabsId = 'cgSgspJ2msm6clMCkdW9', openAiVoice = 'shimmer' },
}

DefaultVoice = {
    Male = 'default_male',
    Female = 'default_female',
}
```

#### Custom Voices

To add a custom voice, copy an existing entry and replace the ElevenLabs voice ID or OpenAI voice name.

If no voice is assigned to an NPC, the resource automatically selects:

* `DefaultVoice.Male` for male peds
* `DefaultVoice.Female` for female peds

***

### Admin Command

```lua
Commands = {
    DialogsAdmin = {
        Name = 'dialogsadmin',
        Groups = { 'admin', 'developer' },
    },
}
```

#### `Name`

Defines the command used to open the admin panel.

#### `Groups`

Defines which permission groups can access the dialog admin system.

***

### Dialog Fields

Each NPC dialog can be configured in the in-game UI.

#### Available Fields

* **NPC Name** — display name shown in the dialog
* **NPC Model** — ped model name or hash
* **Floating text** — text shown above the NPC
* **Icon** — Font Awesome icon shown next to the prompt
* **Interaction distance** — max distance for interaction
* **Voice** — TTS voice profile or automatic voice selection
* **Animation** — idle animation dictionary and name
* **Blocked jobs** — jobs that cannot interact with the NPC
* **Map blip** — optional blip settings
* **Hidden** — hides the NPC without removing it from the database

***

### Dialog Pages

Each dialog contains one or more pages.

Each page can include:

* **NPC Text** — text spoken by the NPC
* **Buttons** — interactive options shown to the player
* **Selection list** — optional dropdown-style option list

#### Button Actions

Each button can:

* go to another page
* trigger a client event
* trigger a server event
* close the dialog

***

### Creating a Dialog

Dialogs are created directly in-game through the admin panel.

#### Steps

1. Use `/dialogsadmin`
2. Click **New dialog**
3. Fill in the NPC name, model, floating text, voice, and animation
4. Click **Pick** to place the NPC in the world
5. Add dialog pages, text, and buttons
6. Click **Create dialog**

The NPC will spawn immediately for all players.

***

### Triggering Events from Buttons

Buttons can trigger custom client or server events.

Example button configuration:

```
Event: msk_dialogs:fishing:openInfo
Params: {}
```

#### Client-side example

Use `client/events.lua`:

```lua
RegisterNetEvent('msk_dialogs:fishing:openInfo', function()
    exports['prp_fishing']:OpenMenu()
end)
```

#### Server-side example

Use `server/events.lua` for server event handlers.

> Both `client/events.lua` and `server/events.lua` are not escrowed, so you can edit them freely.

***

### Notes

* `Cache = true` stores generated TTS audio in memory
* Cached audio is cleared after a resource restart
* `client/events.lua` and `server/events.lua` are fully editable
* If no voice is assigned, the resource auto-selects a default male or female voice


---

# 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/npc-dialog-system/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.