> For the complete documentation index, see [llms.txt](https://docs.cuxial.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuxial.com/scripts/core/cuxial-interactions/configuration.md).
# Configuration
Every option of Cuxial Interactions explained: config, NPC sets and how to write your own NPC.
Behaviour lives in `shared/config.lua`. The NPCs live in `data/`, one file per set. Restart the resource after any change.
## General
| Option | Type | Default | What it does |
| ------------- | ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `debug` | boolean | `false` | Prints traces to the console: points registered, shops registered, sales. Also enabled by setting the convar `cuxial_interactions_debug` to `1`. |
| `ui.accent` | string (hex) | configurable | Accent colour of the dialogue and the shop. |
| `interaction` | string | `'target'` | How the player starts a conversation, for points that do not set their own. `'target'` = option of your target resource. `'sprite'` = key prompt on the NPC; needs `bl_sprites` running, otherwise the target is used. `'none'` = no option; the point only opens through the `Interact` export. |
## Target · `target`
| Option | Type | Default | What it does |
| ---------- | ------ | ----------------------- | ------------------------------------------------------------------------------ |
| `icon` | string | `'fas fa-comment-dots'` | Font Awesome class of the target option, for points without `targetIcon`. |
| `distance` | number | `2.5` | Metres from which the option can be used, for points without `activeDistance`. |
## Key prompt · `sprite`
Only used with `interaction = 'sprite'`.
| Option | Type | Default | What it does |
| ---------- | ------ | ------- | --------------------------------------------------------------------------------------------- |
| `key` | string | `'E'` | Letter drawn on the prompt. |
| `control` | number | `38` | GTA control that opens the conversation. `38` is E. Change it together with `key`. |
| `shape` | string | `'hex'` | Shape of the prompt, passed to `bl_sprites`. |
| `distance` | number | `2.5` | Metres from which the prompt reacts, for points without `activeDistance`. |
{% hint style="info" %}
Points without a ped always use the target, even in sprite mode.
{% endhint %}
## NPCs · `npc`
| Option | Type | Default | What it does |
| --------------- | ------ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `spawnDistance` | number | `60.0` | Metres at which the ped is created and removed, for points without their own `spawnDistance`. |
| `zOffset` | number | `-1.0` | Added to the Z of `coords` when the ped is created. With `-1.0` you can paste the coordinates taken while standing on the spot. |
| `modelTimeout` | number | `5000` | Milliseconds to wait for a ped model to load. |
| `animTimeout` | number | `2000` | Milliseconds to wait for an animation dictionary to load. |
| `fallbackModel` | string | `'a_m_y_business_01'` | Model used when a point has no model or its model does not exist. |
| `watchInterval` | number | `1000` | Milliseconds between checks of the points attached to a ped created by another resource (`entity` / `netId`). |
## Camera · `camera`
| Option | Type | Default | What it does |
| ------------ | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | boolean | `true` | `true` moves the camera in front of the NPC while talking. `false` keeps the player's camera. A point can turn it off for itself with `camera = false`. |
| `forward` | number | `1.2` | Metres in front of the NPC where the camera is placed. |
| `height` | number | `0.52` | Metres above the NPC position. |
| `yawOffset` | number | `181.0` | Degrees added to the NPC rotation so the camera faces it. |
| `transition` | number | `2000` | Milliseconds of the camera blend, in and out. |
| `settle` | number | `1500` | Milliseconds the window waits before it appears, so the camera gets there first. |
The camera only starts when the point has a ped. Points without a ped open the window at once.
## Dialogue · `dialog`
| Option | Type | Default | What it does |
| ------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `hidePlayer` | boolean | `true` | `true` makes the player's ped invisible while the window is open, so it does not block the camera. `false` leaves it visible. |
| `hideDelay` | number | `2000` | Milliseconds after opening until the player is hidden. |
| `textSpeed` | number | `25` | Milliseconds per character of the typing effect, for pages without their own `textSpeed`. |
| `conditionInterval` | number | `500` | Milliseconds the result of a point's conditions (`job`, `item`, `canInteract`) is reused before checking again. |
## Shop · `shop`
| Option | Type | Default | What it does |
| ------------- | ------ | ----------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `account` | string | `'cash'` | Account the sale is paid into, for shops without their own: `'cash'`, `'bank'` or `'black_money'`. |
| `currency` | string | `'$'` | Symbol shown next to prices and in the sale notification. |
| `maxDistance` | number | `6.0` | Metres from the shop within which the server accepts a sale, for shops without their own `distance`. |
| `maxQuantity` | number | `1000` | Maximum units in a single sale. |
| `cooldown` | number | `300` | Milliseconds a player must wait between two sales. |
| `image` | string | `'nui://ox_inventory/web/images/%s.webp'` | Image of an item without its own `image`. `%s` is the item name. |
## Player looks · `skins`
Used by the points with `usePlayerSkin = true`.
| Option | Type | Default | What it does |
| -------------- | ------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `resource` | string | `'cuxial_appearance'` | Resource that applies the appearance to the ped. If it is not running, the ped keeps the base model. |
| `activeDays` | number | `7` | Only characters played in the last days given here are used. |
| `pool` | number | `8` | Appearances loaded the first time one is needed and kept until the resource restarts. The resource loads more if the `data/` sets have more NPCs with `usePlayerSkin` than this number. |
| `defaultModel` | string | `'mp_m_freemode_01'` | Model used when a stored appearance has no model. |
| `retry` | number | `60` | Seconds until the server looks again when it found no appearance. |
## Paid NPC medic · `maria`
A service that revives the player for a fee when few medics are on duty. The buttons of the example set `Doctor`, which is off by default, use it through the server callback `cuxial_interactions:server:ReviveNpc`, which returns `true` when the player was attended.
| Option | Type | Default | What it does |
| ------------- | ------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cost` | number | `1200` | Price of the service. |
| `account` | string | `'bank'` | Account the price is taken from. |
| `job` | string | `'ambulance'` | Job whose on-duty members are counted. |
| `maxOnDuty` | number | `2` | With this many medics on duty, or more, the NPC refuses and sends the player to a hospital. |
| `revive` | table | `{ resource = 'cuxial_medical', export = 'RevivePlayer' }` | Server export called to revive the player. If the resource is not running the service does not charge. If the export fails the money is returned. |
| `set` | string | `'Doctor'` | Set of `data/` whose NPCs offer the service. If that set is off, nobody is attended. |
| `maxDistance` | number | `8.0` | Metres from one of those NPCs within which the server accepts the request. |
## NPC sets · `sets`
Each key is the name of a file in `data/`, without `.lua`. `true` loads the file; `false`, or a missing key, ignores it.
{% code title="shared/config.lua" %}
```lua
sets = {
Greeter = true,
Buyer = true,
Doctor = false,
},
```
{% endcode %}
The sets shipped with the resource are examples: change their coordinates, texts, jobs and items, or turn them off and write your own.
## Writing an NPC
A data file returns a table. Each key is an NPC; its value is the definition of the point.
{% code title="data/MyNpcs.lua" %}
```lua
return {
ScrapBuyer = {
coords = vec4(25.7, -1347.3, 29.49, 271.0),
model = 's_m_y_dealer_01',
scenario = 'WORLD_HUMAN_STAND_IMPATIENT',
behavior = { invincible = true, noTemporaryEvents = true, freeze = true },
label = 'Talk to the buyer',
activeDistance = 2.5,
blip = { id = 52, scale = 0.6, colour = 5, name = 'Scrap buyer' },
shop = {
name = 'Sam',
job = 'Buyer',
items = {
{ name = 'scrapmetal', price = 12 },
{ name = 'copper', label = 'Copper wire', price = 20 },
},
},
dialog = {
{
id = 'start',
name = 'Sam',
job = 'Buyer',
text = 'Got anything for me?',
buttons = {
{ id = 'sell', label = 'Show what I have', icon = 'hand-coins', shop = true },
{ id = 'bye', label = 'Not today', icon = 'x', close = true },
},
},
},
},
}
```
{% endcode %}
Then switch the set on:
{% code title="shared/config.lua" %}
```lua
sets = {
MyNpcs = true,
},
```
{% endcode %}
What to know about data files:
* The id of each point is `_`. The example above is `MyNpcs_ScrapBuyer`.
* A shop written in a data file is registered on the server automatically, at the coordinates of its point. Inside `shop` you can also set `account` and `distance` for that shop only.
* The item names must exist in `ox_inventory`. An item without `label` takes the label of the inventory.
* A shop only buys. The player sells items to the NPC and receives money.
* The file is loaded on the client and on the server. Functions such as `onSelect` only run on the client; do not call client natives outside a function.
* Set `enabled = false` on a point, a page or a button to switch it off without deleting it.
Every field of a point, a page, a button and a shop is listed in [Exports & events](/scripts/core/cuxial-interactions/developers.md).
## Common changes
### Talk with a key instead of the target
{% code title="shared/config.lua" %}
```lua
interaction = 'sprite',
```
{% endcode %}
`bl_sprites` must be running. To change a single NPC, set `interaction = 'sprite'` in its definition instead.
### Turn the camera off
{% code title="shared/config.lua" %}
```lua
camera = {
enabled = false,
},
dialog = {
hidePlayer = false,
},
```
{% endcode %}
Keep the other keys of both blocks as they are.
### Pay shop sales to the bank
{% code title="shared/config.lua" %}
```lua
shop = {
account = 'bank',
},
```
{% endcode %}
### Restrict an NPC to a job
{% code title="data/MyNpcs.lua" %}
```lua
ScrapBuyer = {
job = { police = 2 }, -- police, grade 2 or higher
-- ...
},
```
{% endcode %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.cuxial.com/scripts/core/cuxial-interactions/configuration.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.