All exports are client-side only — call them from client scripts in your resource. For same-resource callbacks, use RegisterAction({...}) (global) instead of the export; Lua function closures do not survive across export boundaries.
Register a new voice action.
Syntax
| Name | Type | Required | Description |
|---|---|---|---|
name | string | ✅ | Unique action identifier |
phrases | string[] | ✅ | Spoken phrases; use {var} for variable slots |
trigger | table | ✅ | What fires on match — see Trigger types |
layer | string | — | Layer to assign: "ambient", "context", "global", or custom |
group | string | — | Batch enable/disable group name |
tags | string[] | — | Filter tags for queryActions |
description | string | — | Max 200 chars; used by LLM tier matching |
minSimilarity | number | — | Match confidence threshold (0.0–1.0, default 0.7) |
condition | function | — | function(data) return boolean — pre-execution gate |
variableAliases | table | — | Synonym map { amount = "sum" } |
variableTypes | table | — | Type coercion { amount = "number" } |
variableDefaults | table | — | Fallback values { size = "large" } |
numberNormalization | boolean | — | Enable automatic word-to-number parsing (e.g. "five" → 5) |
Returns: { success = true, data = { name = "action_name" } }
Your Script
Unregister one action, all from a resource, or all from the calling resource.
Syntax
| Name | Type | Description |
|---|---|---|
target | string | Action name, "@resource_name" for all from a resource, or omit for calling resource |
Returns: { success = true, data = { count = 1 } }
Your Script
Query registered actions with optional filters.
Syntax
| Name | Type | Description |
|---|---|---|
filter.name | string | Match by exact action name |
filter.group | string | Match by group name |
filter.tag | string | Match by tag |
filter.enabled | boolean | Match by enabled state |
filter.resource | string | Match by source resource name |
Returns: { success = true, data = { actions = { ... }, count = 5 } }
Your Script
Enable or disable a single action, a named group, or all actions.
Syntax
| Name | Type | Description |
|---|---|---|
target | string | Action name, "#group_name" for a group, "*" for all |
enabled | boolean | true to enable, false to disable |
Returns: { success = true, data = { affected = 1 } }
Your Script
Get the enabled state of an action or group.
Syntax
| Name | Type | Description |
|---|---|---|
target | string | Action name, "#group_name", or omit for full disabled state |
Returns (action/group): { success = true, data = { enabled = true } }
Returns (nil target): { success = true, data = { disabledActions = { ... }, disabledGroups = { ... } } }
Your Script
Register a custom layer for voice context management.
Syntax
| Name | Type | Description |
|---|---|---|
config.name | string | Unique layer identifier |
config.priority | number | Conflict resolution priority (default 50) |
config.exclusive | boolean | Only one group active at a time (default true) |
config.disableAmbient | boolean | Disable ambient layer when active (default true) |
config.disableLayers | string[] | Other layers to disable when entered |
config.promptHints | string[] | STT vocabulary hints for improved recognition |
config.proximityPriority | boolean | Enable proximity-based layer yielding — closer entity wins conflicts |
Returns: { success = true, data = { name = "shop" } }
Your Script
Activate a layer with a specific action group.
Syntax
| Name | Type | Description |
|---|---|---|
layerName | string | Registered layer name |
groupName | string | Group name to activate (matches group on registered actions) |
options.promptHints | string[] | Override STT hints for this session |
options.customHints | table | Bypass automatic hint collection with explicit hint objects |
Returns: { success = true, data = { layer = "shop", group = "voice_shop_1" } }
Your Script
Deactivate a layer and restore previous state.
Syntax
| Name | Type | Description |
|---|---|---|
layerName | string | Layer name to exit |
Returns: { success = true, data = { layer = "shop" } }
Your Script
Switch to a different action group within an already-active layer.
Syntax
| Name | Type | Description |
|---|---|---|
layerName | string | Active layer name |
groupName | string | New group to activate |
Returns: { success = true, data = { layer = "banking", group = "voice_bank_confirm" } }
Your Script
Enable or disable a layer globally.
Syntax
| Name | Type | Description |
|---|---|---|
layerName | string | Layer name |
enabled | boolean | Enable or disable |
Returns: { success = true, data = { layer = "npc_interact", enabled = false } }
Your Script
Update a layer's priority or conflict rules at runtime.
Syntax
| Name | Type | Description |
|---|---|---|
layerName | string | Layer name |
config.priority | number | New priority value |
config.disableAmbient | boolean | Update ambient disable rule |
config.disableLayers | string[] | Replace conflicting layers list |
Returns: { success = true, data = { layer = "shop" } }
Your Script
Override the visible voice hints for the current session of an active layer.
Syntax
| Name | Type | Description |
|---|---|---|
layerName | string | Active layer name |
hints | table[] | Array of { name, phrase, layer? } hint objects |
Returns: { success = true, data = { layer = "shop", count = 2 } }
Your Script
Update the proximity distance for a layer registered with proximityPriority. The layer with the smallest distance wins conflicts.
Syntax
| Name | Type | Description |
|---|---|---|
layerName | string | Layer name |
distance | number | nil | Distance to nearest target, or nil to clear proximity |
Returns: { success = true, data = { layer = "npc_interact" } }
Your Script
Check whether a layer should yield to a closer proximity competitor. Returns true if another active layer with proximityPriority has a smaller distance.
Syntax
| Name | Type | Description |
|---|---|---|
layerName | string | Layer name to check |
Returns: boolean
Your Script
Get the currently active custom layer and group.
Syntax
Returns: { success = true, data = { layer = "shop", group = "voice_shop_1" } } — data is nil if no custom layer is active.
Your Script
Get the current state of a specific layer.
Syntax
| Name | Type | Description |
|---|---|---|
layerName | string | Layer name to inspect |
Returns: { success = true, data = { enabled, activeGroup, priority, exclusive, disableAmbient, disableLayers } }
Your Script
Get all registered layers and their current state.
Syntax
Returns: { success = true, data = { layers = { [name] = { enabled, activeGroup, priority, ... } } } }
Your Script
Synthesize and play TTS audio — global or 3D positioned.
Syntax
| Name | Type | Description |
|---|---|---|
text | string | Text to speak |
options.voice | string | table | Voice name string, or { name, rate, pitch, volume, stability, similarityBoost } object |
options.rate | number | Speech rate shorthand (default 1.0) — overridden by voice.rate if both set |
options.pitch | number | Pitch shift shorthand (default 1.0) — overridden by voice.pitch if both set |
options.volume | number | Volume level shorthand (default 1.0) — overridden by voice.volume if both set |
options.entity | number | Ped entity handle for 3D positioned audio |
options.maxDistance | number | Hearing range for 3D audio (default 30.0) |
options.animation | table | false | false to disable all animation, or { lipSync, gesture, gestureDict, gestureAnim, returnToIdle, idleScenario } |
options.showSubtitle | boolean | Display subtitle synced to TTS duration |
options.immediateSubtitle | boolean | Display subtitle immediately without waiting for TTS timing |
options.npcName | string | Display name shown in subtitles |
options.networked | boolean | Broadcast speech to other players via state bags |
Returns: { success = true, data = { soundId = "sound_12345_6789", is3D = true } }
Your Script
Stop TTS playback — all sounds or a specific one.
Syntax
| Name | Type | Description |
|---|---|---|
soundId | string | Specific 3D sound ID to stop, or omit to stop everything |
Returns: { success = true, data = { stopped = 1 } }
Your Script
Retrieve the available TTS voice list from the browser engine.
Syntax
| Name | Type | Description |
|---|---|---|
callback | function | function(result) called with { success, data = { voices } } |
timeout | number | Timeout in milliseconds (default 5000) |
Without callback: returns { success = true, data = { pending = true, listenEvent = "onex-voiceInteraction:tts:voices" } }
Your Script
Get the configured or auto-detected TTS voice for a ped.
Syntax
| Name | Type | Description |
|---|---|---|
entity | number | Ped entity handle |
Returns: { success = true, data = { voice = "en-US-GuyNeural", gender = "male", stability = 0.5, similarityBoost = 0.75, cached = false, isDefault = false } }
Your Script
Clear the voice assignment cache for a specific ped or all peds.
Syntax
| Name | Type | Description |
|---|---|---|
entity | number | Ped entity handle, or omit to clear all |
Returns: { success = true, data = { cleared = 1 } }
Your Script
Get complete NPC configuration and defaults for an entity or model name.
Syntax
| Name | Type | Description |
|---|---|---|
target | number | string | Ped entity handle or model name string (e.g. "mp_m_freemode_01") |
Returns: { success = true, data = { config, voice, animation, audio, personality, traits, gender, isDefault } }
Your Script
Check whether an NPC has specific traits. Optional traits are probability-rolled and cached.
Syntax
| Name | Type | Description |
|---|---|---|
entity | number | Ped entity handle |
traitIds | string | string[] | Single trait ID or array of trait IDs |
Returns: { success = true, data = { [traitId] = { hasTrait, isRequired, probability, rolledProbability, cached } } }
| Field | Type | Description |
|---|---|---|
hasTrait | boolean | Whether the NPC has this trait |
isRequired | boolean | Whether the trait is required (not probability-based) |
probability | number | Configured probability (0.0–1.0) |
rolledProbability | number | Actual rolled value used to determine hasTrait |
cached | boolean | Whether this result came from the roll cache |
Your Script
Query traits by entity, tag, or definition name.
Syntax
| Name | Type | Description |
|---|---|---|
query.entity | number | Get all traits for a specific ped |
query.tag | string | Filter by trait tag (combinable with entity) |
query.definition | string | true | Get a specific trait definition, or true for all |
Your Script
Clear cached trait roll results for a ped, forcing a re-roll on the next checkNPCTraits call.
Syntax
| Name | Type | Description |
|---|---|---|
entity | number | Ped entity handle — required, clears only this ped |
Returns: { success = true, data = { cleared = 1 } }
Your Script
High-level convenience export that combines layer registration, action registration, and greeting speech into a single call.
Syntax
| Name | Type | Required | Description |
|---|---|---|---|
config.id | string | ✅ | Unique interaction identifier |
config.entity | number | ✅ | Ped entity handle |
config.npcName | string | — | Display name for subtitles |
config.greeting | string | — | TTS greeting spoken on start |
config.greetingOptions | table | — | Options passed to speak() for the greeting |
config.layer | table | — | Layer config { priority, exclusive, disableAmbient } |
config.group | string | — | Action group name |
config.actions | table[] | — | Array of action definitions to register |
config.autoCleanup | boolean | — | Auto-cleanup when player moves away |
Returns: { success = true, data = { interactionId, layerName, groupName, registeredActions, actionErrors? } }
Your Script
Stop an active NPC interaction, cleaning up actions and exiting the layer.
Syntax
| Name | Type | Description |
|---|---|---|
id | string | Interaction identifier from startNPCInteraction |
options.stopSpeech | boolean | Also stop any active TTS playback |
Returns: { success = true, data = { interactionId, actionsRemoved, layerExited } }
Your Script
Store a key-value pair scoped to an action group.
Syntax
| Name | Type | Description |
|---|---|---|
group | string | Group name scope |
key | string | Context key |
value | any | Value to store |
Your Script
Retrieve a stored context value.
Syntax
Get all key-value pairs for a group.
Syntax
Check if a context key exists.
Syntax
Remove a specific context key.
Syntax
Clear all context for a group.
Syntax
Clear all context across all groups.
Syntax
Merge a table into an existing context value.
Syntax
Increment a numeric context value.
Syntax
Push a value onto a context array.
Syntax
Enable or disable automatic context clearing when exiting a layer.
Syntax
Get context usage statistics.
Syntax
Returns: { success = true, data = { groups, totalKeys, totalSize } }
Last updated 3 months ago