Random world pedestrians respond to players who speak near them. No scripted NPCs required — the addon hooks into GTA's existing pedestrian population. Optionally, LLM-powered conversation generates unique, contextual responses.
Config file: shared/ambient-npc/default.lua
| Type | boolean |
| Default | true |
Master toggle for the ambient NPC addon.
| Type | number |
| Default | 5.0 |
Distance in metres at which a player's voice triggers a response from nearby pedestrians.
| Type | number |
| Default | 10.0 |
Distance in metres the addon scans for eligible pedestrians to respond.
These are top-level fields on AmbientNPCConfig.
| Setting | Default | Purpose |
|---|---|---|
responseCooldown | 2000 ms | Minimum time between any ambient NPC response |
greetingCooldown | 30000 ms | Per-NPC cooldown before the same ped greets again |
perPedCooldown | 15000 ms | Per-pedestrian cooldown before the same ped responds again |
These are top-level fields on AmbientNPCConfig that control which pedestrians are eligible to respond.
| Setting | Default | Purpose |
|---|---|---|
excludeInVehicle | true | Skip pedestrians sitting in vehicles |
requireLineOfSight | true | Only respond if the ped has line of sight to the player |
excludeDeadOrDying | true | Skip dead or critically injured pedestrians |
excludePlayers | true | Skip other player characters |
excludeScriptPeds | true | Skip mission-critical or scripted peds |
allowMissionEntities | false | Allow peds flagged as mission entities |
populationTypeFilter | true | Filter by population group |
When populationTypeFilter = true, only peds matching these GTA population type IDs are eligible. All five random population types are allowed by default.
Array of ped model hash strings to exclude from ambient interactions. Empty by default.
| Type | boolean |
| Default | true |
Prefer the NPC the player is facing over a slightly closer one behind them.
| Type | number |
| Default | 0.5 |
Blends distance and facing direction when selecting the target NPC. 0 = pure distance, 1 = strong facing preference.
| Type | string |
| Default | "3d" |
| Values | "3d" | "2d" | "icon" |
Controls where voice hint phrases are displayed.
"3d" — floating bubble above the targeted NPC's head"2d" — screen overlay (always visible)"icon" — icon only, no phrase suggestions
Voice layer configuration for the addon.
| Type | boolean |
| Default | true |
Master toggle for NPC TTS speech during ambient interactions.
| Type | number |
| Default | 10.0 |
3D audio hearing range for ambient NPC TTS speech (metres).
Individual toggles for each response category:
| Setting | Default | Purpose |
|---|---|---|
stopToTalkChance | 90 | % chance the NPC stops walking to respond (LLM mode always stops) |
resumeWanderDelay | 5000 ms | Time before the NPC resumes their original state after no interaction |
wanderRadius | 20.0 m | Fallback wander radius when restoreState = false |
restoreState | true | Restore the NPC's original task/animation after the conversation ends |
When a pedestrian is playing a phone animation, they can be configured to ignore or deflect player voice input.
| Type | boolean |
| Default | true |
| Type | number (%) |
| Default | 70 |
Percentage chance that a phone-busy pedestrian refuses to respond.
Pedestrians can call 911 or the doctor in response to player voice input or nearby events.
| Type | boolean |
| Default | true |
Master toggle for the emergency call system.
Both share the same structure:
| Field | Default | Purpose |
|---|---|---|
enabled | true | Enable this call type |
callDuration | 5000 ms | Time the NPC stays on the phone before dispatch triggers |
refuseChance | 15 % | Chance the NPC refuses to call (hostile NPCs may override) |
onDispatch.type | "client" | "client" or "server" for the dispatch event |
onDispatch.event | nil | Custom event to fire on dispatch — nil disables |
Set onDispatch.event to integrate with custom dispatch resources such as ps-dispatch or cd_dispatch. Set type = "server" if your dispatch resource listens for server events.
When LLM is available (BYOK configured and Config.LLM.enableAddonLLM = true), ambient NPCs generate unique conversational responses instead of using predefined phrase pools.
| Type | number |
| Default | 10 |
Number of previous message turns to include in the LLM context for each conversation.
| Type | number |
| Default | 200 |
Maximum character length for LLM-generated responses.
| Type | string |
| Default | "" |
Optional additional instructions appended to the system prompt for all ambient NPC LLM conversations. Use to customize personality or restrict topics.
Last updated 14 days ago