Talking, remembering, gossiping street NPCs for FiveM, built on GTA's own ped systems.

nCore Development · intelnpc.com · Resource: ncore_npc_pro · Version: see fxmanifest.lua

What it is#

NPC Pro works on the pedestrians GTA already spawns. Every one of them gets a category, one of seven personalities, a mood and a memory, and you can walk up and talk to them. The script places a few people of its own too: the ten named characters, the life-point extras (up to 12 at a time), up to two officers at traffic-light junctions and a patrol guard. Each group has its own switch in shared/config.lua.

Ten named characters add shops, errands and a player bounty board. The rest is reactions: people see what you do, tell each other, and treat you differently the next time. Only ox_lib is required. It runs on Qbox, QBCore, ESX Legacy or on its own.

Features#

Every ambient NPC is a person#

• Every pedestrian is a civilian, gang member, cop, homeless person or prostitute, taken from the ped model, GTA's ped type and its relationship group.
• Seven personalities: coward, compliant, brave, aggressive, cop, cunning and stoic. Each one reacts differently to being aimed at, hit, robbed, threatened or provoked.
• Animals are never offered a conversation. A ped that is fleeing, in a vehicle, swimming or ragdolling can't be talked to either.
• Gang members within 70 m never flee and always fight.
• Faces change with mood, panic and hostility. Ambient peds within 40 m get facial expressions.

Talking to them#

• E with ox_target or qb-target, or the built-in [E] Talk prompt without them. G or /npcpro_talk talks to the NPC you look at.
• Walls, props and vehicles block the conversation. Glass and see-through fences don't.
• Branching dialog with follow-ups, counter-questions and a random subset of four topics per visit.
• Lines depend on time of day, weather, nearby props (ATM, fuel pump, vending machine, bench), your health, a mask, a weapon and your wanted level.
• Each NPC has a patience level. Ask too much and they say so, then end the chat. Idle too long and they walk away.
• Weapon drawn, wanted level, a mask, an attack or an injury can end a conversation, each with its own lines.
• Some NPCs refuse to talk at all. Gang members and cops do it most. Panicked, hostile or traumatized peds always do.
• Tip, bribe, rob, mug, pickpocket, threaten, provoke, flirt, help up and beg are actions in the dialog.
• Street scenes: 7 staged conversations between ambient peds. Walk up and press E, or G on one of them, to join.
• Group conversations show who is speaking.

Dialog panel#

• Letterbox bars, a name plate with role and zone, a mood badge, a trust meter, composure and patience meters, a witness counter and a body-language line.
• Typewriter chat log, held until the spoken line ends. Reply tags show tone, cost, trust lock, "asked", "more to ask" and "ends the conversation".
• Three layouts: Panel, Cinematic and Split. Owners set the default, players pick their own with /npcpro_layout or /npcpro, and the choice is saved on their PC.
• Keyboard and mouse. Scales with screen height and respects reduced motion.
• nui/theme.css has 63 documented tokens for colors, radii, widths and fonts.
• The game audio is ducked while the panel is open and restored on close.
• A scripted over-the-shoulder camera, speaking gestures, lip sync and arm IK while the NPC talks.

Voices#

• Named NPCs get a GTA voice cast to their sex, and lines are spoken in the panel.
• Bad voice names are caught at start and reported in the console.
• Pool-based barks outside the panel for hello, bye, angry and scared.

Ten named NPCs#

• Maggie, Erika, Pete, Joe, Tony, Doc, Denny, Anna, Sgt Mahoney and Candy.
• They appear when you come near and leave when you go. Each one has a schedule with a different spot per time of day, and some are off shift at night.
• They are invincible, never flee and ignore explosions.
• Add your own in data/personas.lua, no code needed, see Adding a static persona. The AddPersona and RemovePersona exports only change the client that calls them.
• Maggie and Erika have a background topic. Maggie, Erika and Candy call out to you in their own lines.

Memory, trust and gossip#

• Named NPCs remember you per character: visits, topics you asked, what they saw you do, your name, your gifts. It's kept across restarts.
• Street NPCs remember you for 10 minutes after the last contact.
• Re-meet greetings from visit count and gaps. Topics you already asked are grayed out.
• Trust from -10 to +10 in six tiers, owned by the server. Talking, polite goodbyes, purchases and jobs raise it. Robbing, threatening and provoking lower it.
• Trust changes prices: x0.85 when trusted up to x1.25 when hostile.
• When trust falls to a personality's limit, the NPC reacts and the chat ends.
• Gossip: every 45 seconds NPCs within 8 m pass on one worthy event, up to 4 hops, getting less certain each time. Heard events change greetings.
• A disguise score from helmet, mask, hood, glasses and outfit change. At 65 or more you are a stranger.

NPCs call out to you#

• A street NPC shows a speech bubble and plays a greeting bark. 23 topics: injury, weapon, mask, known wanted level, rain, storm, snow, fog, heat, late night, fuel station, shop counter and more.
• Past deeds change what they say, good or bad, seen or heard.
• Quick replies under the bubble: greet back, ask what's new, start a conversation, or "not now".
• Now and then the NPC walks up to you first. A weapon drawn or a ped hurt ends it at once.
• Street requests: an NPC asks for a cigarette or $5 to $20. The server checks the ped, the distance and the cooldown.
• Calm limits: 2 hail sessions, 3 bubbles on screen, 3 new hails a minute. Every topic has its own chance, range and cooldown in Config.hail_features.

Crime, witnesses and reactions#

• 16 on-foot reactions, plus seated reactions for drivers, passengers and riders.
• A weapon counts as aimed only inside range, in view and in sight of the ped.
• Getting hit makes the ped react and starts the witness fan-out.
• The street looks over: up to 5 nearby peds turn their heads when someone snaps.
• The fan-out reaches up to 8 witnesses within 40 m who can see it (Config.cast_witness).
• Crimes, shots and fights are reported to the server with up to 12 witnesses who saw or heard them, each with a reliability: cops high, civilians medium, gang and homeless low. A witness further than 25 m away drops one level, further than 60 m counts as low.
• Gunshots (100 m, 25 m suppressed), melee fights, explosions, public drug use and alarms are all heard or seen.
• Gang members back up a gang victim. Rival gangs only watch.
• Informants (informant = true on a persona) leak what they saw unless your disguise is high.
• Vehicle collisions are graded: nudge, bump, hit.
• Rob, mug and pickpocket with server cooldowns, distance checks and single-use loot. Robbing ambient peds needs OneSync.

Police#

• Non-lethal police is on by default. At one star or less, cops within 120 m lose their firearms and their accuracy drops to zero.
• An alpha police module (off by default) raises a wanted level for running a red light near an officer, speeding past one, hit-and-run and assaulting an officer.
• Manhunt: the crime scene is pinned as the search center and the getaway vehicle is flagged.
• A corruptible cop persona can be bribed when you are wanted. Ambient cops can be bribed too, but only with the police module on. The server prices it from your real wanted level.
• Pay damages to clear a hit-and-run, when the police module is on.
• GTA's own police is kept switched on. Every 5 seconds it turns random cops and dispatch back on, makes cops notice you and sets the max wanted level to 5, because many server packs turn these off at start. While a police job or dispatch resource from Config.engine_police.step_aside_for is running (ps-dispatch, cd_dispatch, qs-dispatch, rcore_dispatch, core_dispatch, lb-tablet, qb-policejob, qbx_police, esx_policejob, wasabi_police, origen_police) it leaves all of that alone and prints a console line naming the resource. Set Config.engine_police.force_on = true to keep it running anyway.

Trade, errands and bounties#

• Persona shops with a server catalog, stock caps, trust prices and haggling (5 to 20 percent off for 5 minutes). An ox_inventory shop screen is optional.
• Errands: ask "Got any work for me?" for a server-rolled offer. Steps are goto, scout, fetch item, deliver item and talk to. Four ship with the script.
• An errand tracker with title, step, time left, a map blip and a GPS route. /npcpro_jobs lists and abandons them. Progress is saved per character.
• A player bounty board: place a bounty with a stake, 10 percent broker fee, kills checked by the server, expiry after 72 hours with a refund. A player at a quarter of their max health or less counts as down (Config.bounty_board.down_health_fraction, default 0.25), so it also pays on frameworks that keep downed players alive. /npcpro_bounties shows the board anywhere.
• Three NPC contracts, paid when you rob or mug the target persona.

City life#

• 22 hand-placed life-point extras: Vespucci beach, downtown tourists, gang blocks, labor and nightlife. Furniture life points put someone at the ATM, on a bench, at a parking meter or at a bus stop. Config.life_points.max_active sets how many can be alive at once (12 by default), and enabled = false takes the whole layer out.
• A night-only red-light district with prostitute-category peds on curb points, and up to two officer posts at traffic-light junctions (Config.redlight_post).
• Daily routines move named NPCs through morning, day, evening and night.
• 7 street scenes: gossip on the corner, an argument, a lost tourist, a corner deal, a shift change, panhandling and cop chatter.
• Synchronized greet animations when you talk to a ped you trust, and a gang dap with gang members.
• Zone-aware crowd density through GTA's own density multiplier (Config.density_manager). Downtown is denser, Blaine County is thinner.
• Car radios on nearby traffic, boats, garbage trucks, dormant scenario groups (blimp and plane groups on by default) and the street musician scenario switched off.
• Traffic personality: nearby drivers get a driving style from their category and react when your car touches theirs.
• Guard patrol routes through GTA's own patrol system.
• Crowd director: up to 6 peds watch, film, gawk or cheer, then disperse. Crime scenes call a real ambulance and police incident with onlookers.
• Overheard gossip, 7 news headlines of the day, an audio toolkit for alarms and sounds.

Languages#

• English and Hungarian, 1000 keys each. Config.locale = 'auto' reads the server's locale convars. Add a language by dropping a file in locales/.
• Panel labels, hails, refusals, errands, bounties, shops and toasts are translated. The named and street dialog trees are English.

Framework and integrations#

• Detects Qbox, QBCore, ESX Legacy or standalone, and the inventory, notification and target systems. You can force any of them in Config.bridge.
• Peds that another resource owns are left alone: networked peds another resource spawned, ncore_inventory's preview and shopkeeper peds, and any ped a script announces with AnnouncePed. They get no hails, reactions or conversations.
• Saving in FiveM's built-in storage by default, or in MySQL with oxmysql. The tables are created for you.
• ncore_hud: trust toasts, achievements, mood toasts, purchase and reward toasts and the news caption.
• ncore_chat: 3D speech bubbles. ncore_touchgrass: bonus minutes for errands. Webhook logging for staff is optional and off by default.
• An old config keeps working: new settings are filled in with defaults.

Admin tools#

• F12 or /npcpro_menu opens the admin panel for players with the ncore_npc_pro.dev ace.
• /npcpro_test is a guided walkthrough with saved progress.
• About 60 diagnostic commands for hails, witnesses, police, scenes, patrols, audio and trust.
• Ops counters through GetMetrics and the console command npcpro_metrics.

Requirements#

Required:

• ox_lib

Optional, detected automatically:

• Qbox, QBCore or ESX Legacy (it runs standalone without one)
• ncore_inventory, ox_inventory, qb-inventory or the ESX inventory. On Qbox the items go through ox_inventory, which Qbox itself needs (ncore_inventory ships a compatibility layer under that name).
• ox_target or qb-target (a built-in target is used otherwise)
• oxmysql (only for MySQL saving)
• ncore_hud, ncore_chat, ncore_touchgrass
• OneSync, needed for street robberies, street requests, bounty kill checks and server-spawned named NPCs
• FiveM's default baseevents resource (extra kill proof for the bounty board)

Commands and keys#

The admin ace is ncore_npc_pro.dev. Grant it with add_ace group.admin ncore_npc_pro.dev allow. The full command list is in the admin panel.

Config files#

• shared/config.lua - every setting: bridges, dialog, trust, perception, police, city life, integrations, webhook logging, saving, debug.
• locales/en.lua, locales/hu.lua - player-facing text.
• data/personas.lua - the 10 named NPCs.
• data/dialogue_lines.lua, data/dialogue_ambient.lua - named and street dialog.
• data/character_archetypes.lua - the seven personalities.
• data/jobs.lua, data/bounties.lua - errands and contracts.
• data/life_points.lua, data/street_scenes.lua, data/patrols.lua - extras, scenes, guard routes.
• data/news.lua, data/feature_lines.lua - headlines and bystander lines.
• data/model_flags.lua, data/ped_flags.lua, data/speech_categories.lua - world objects, ped flags, speech categories.
• nui/theme.css - panel colors, fonts, sizes.
• sql/ncore_npc_pro.sql - tables for MySQL saving.

Convars#

• setr ncore_npc_pro:debug 1 turns debug mode on (debug visuals, and the admin tools for every player). Staging servers only, see INSTALLATION.md.
• setr ncore_npc_pro:verbose_server_log 1 prints more from the server and the police module in the console. Same as Config.verbose_server_log = true.
• The language convars are read when Config.locale = 'auto', see Language packs below.
• Webhook logging has its own convars, listed in the logging block of shared/config.lua.

Language packs#

Config.locale = 'auto' (the default) picks the language itself. The server reads lr:locale, then locale, ox:locale, esx:locale and txAdmin-locale, and uses the first one that matches a pack in locales/. It passes its pick on to the players. If nothing matches, it stays on English. You can also set Config.locale = 'en' or 'hu' directly.

To add a language, copy locales/en.lua to locales/xx.lua, change Locales['en'] to Locales['xx'] and translate the values, never the keys. Keep the %s and %d placeholders in the same order. Keys you leave out fall back to English, so a partial pack is safe. The named and street dialog trees in data/ are English and are edited there.

Adding a static persona#

Named NPCs live in data/personas.lua, one table per NPC in Config.personas. The file stays open in the Escrow edition. Pete is the shortest entry that ships. Here he is without his relationship_group line, which only repeats the default:

{
    id = 'pete', name = 'Pete', model = 's_m_y_dockwork_01',
    coords = vec4(1180.45, -3270.21, 6.02, 90.0),
    scenario = 'WORLD_HUMAN_CLIPBOARD', dialogue_id = 'pete',
    personality = 'gossipy', mood_bias = { gossipy = 20, neutral = 10 },
    archetype = 'compliant',
    role = 'a dock worker',
    schedule = {
        day   = { coords = vec4(1180.45, -3270.21, 6.02, 90.0), scenario = 'WORLD_HUMAN_CLIPBOARD' },
        night = { coords = vec4(1180.45, -3270.21, 6.02, 90.0), scenario = 'WORLD_HUMAN_SMOKING',
                  voice_line = 'routines.pete_night' },
    },
    voice = { greeting_pool = 'hello', response_pool = 'conversation', farewell_pool = 'bye', idle_pool = 'conversation' },
    interactions = { { type = 'dialogue', label = 'Talk to Pete', icon = 'fa-solid fa-comments' } },
},

Copy it below the last entry and change what you need. Restart the resource afterwards.

• id must be unique. name and role show on the panel's name plate.
• model is a GTA ped model. coords is where the NPC stands (x, y, z, heading). Without coords nothing spawns.
• scenario is what the NPC does while standing there.
• dialogue_id is the dialog tree in data/dialogue_lines.lua. Without it the id is used. To give the NPC the street dialog of its ped type instead, remove dialogue_id and set dynamic = true, the way Candy is set up.
• archetype is one of the seven personalities in data/character_archetypes.lua. mood_bias weights the mood the NPC starts in, and personality is a tag the dialog lines can match.
• schedule is optional: a spot and scenario per time of day, morning 5 to 11, day 11 to 17, evening 17 to 22 and night 22 to 5 (Config.time_of_day_bounds). Outside the blocks you list, the NPC uses coords. A block with hidden = true takes the NPC off shift. voice_line is a locale key the NPC says in that block, so remove it on your copy or add your own key.
• interactions are the entries in the target menu. An open_shop or take_job entry adds a shop or errands, see Maggie's entry. Errands themselves are in data/jobs.lua.
• hail_lines is optional. With it, the NPC calls out to you in those lines, like Maggie, Erika and Candy do.
• informant = true makes the NPC pass on what it saw, unless your disguise is high.
• relationship_group is optional. Left out, the NPC uses the friendly civilian group from Config.relationship_groups.

For developers#

Client exports, from a client script as exports.ncore_npc_pro:Name(...):

Reaction names for TriggerReaction: scream_flee, panic_flee, hands_up, stand_ground, fight_back, draw_and_fight, call_cops, comply, comply_then_call_cops, beg_for_mercy, arrest_warning, walk_away_cursing, curse_at_player, flip_off, get_out_and_fight, call_cops_at_scene, and for peds in a vehicle vehicle_freeze, vehicle_horn, vehicle_flee, vehicle_stop, vehicle_cower, vehicle_glare.

A persona added with AddPersona exists only on the client that called it. Other players don't see it and the server refuses its shop, tips and errands, so put real NPCs in data/personas.lua. Trust is kept by the server and no export raises it. SetReputation and AddReputation are still there so older scripts don't error: the first only changes the number on that player's panel until the next server update, the second always returns false.

Server exports, from a server script:

Server events. They fire with TriggerEvent on the server, so listen with AddEventHandler in a server script:

The witness, informant and dispatch payloads come from the reporting player's game. The server rate-limits them, but treat them as a report and check anything you act on. Bribes, bounties and errands are settled by the server before their event fires.

Troubleshooting#

If no named NPC shows up and you set Config.use_server_spawn = true, check that OneSync is on. With the default false, each player's game spawns them.

If GTA's police keeps coming back although your server pack switched it off, that is the engine police block in shared/config.lua doing its job. Set Config.engine_police.enabled = false, or Config.disable_ai_police = true for no GTA police at all. With a dispatch script from the step-aside list running, it stays out of the way anyway and says so in the console.

Pick KVP or MySQL before you go live. Nothing is copied between them, so switching later starts trust, memory, errands and the bounty board from empty. The old data stays where it was.

If F12 does nothing, the player has no ncore_npc_pro.dev ace. Players can rebind G and F12 in Settings > Key Bindings > FiveM. Changing Config.quick_talk_key or Config.dev_menu_key later only reaches players who never had the key bound.

On Qbox, if shops, gifts or begging fail, check that a resource named ox_inventory is started. The console prints a warning at start when it is missing.

Installation#

See INSTALLATION.md.

Updates#

Updates don't install themselves. Download the new version (Escrow from your Cfx.re account, Full source from Tebex), keep your own config and data files and copy every other file over the old ones. Settings added in a new version are listed in CHANGELOG.md. New versions are announced on intelnpc.com.

Support#

Support is on intelnpc.com, and I reply within 72 hours. Refunds follow the Tebex terms.

nCore Development is not affiliated with, approved, sponsored or endorsed by Rockstar Games.