Install & integrate

Install

1. Drop the resource. Place lrr_npc_chat into your resources/ folder.
2. Ensure dependencies. Append to server.cfg.
3. Restart. Seven demo characters spawn across the map (bar, alley, mechanic, strip club, park bench, gang corner, boardwalk hot-dog cart).

set onesync on            # REQUIRED (server-side CreatePed + state bags)
ensure ox_lib
ensure ox_target          # recommended (otherwise E-key prompt is used)
ensure lrr_npc_chat

Add a character

Drop a file into config/characters/, e.g. dani_taxi.lua:

RegisterNpc({
    id     = 'dani_taxi',
    model  = 'a_m_m_business_01',
    coords = vec4(900.5, -178.2, 73.1, 200.0),
    scenario = 'WORLD_HUMAN_SMOKING',

    speaker       = 'Dani',
    tag           = 'Taxi Dispatcher',
    mood          = 'casual',
    body_language = 'leaning on the cab',

    target = { label = 'Talk to Dani', icon = 'fa-taxi' },
    blip   = { sprite = 198, color = 5, scale = 0.7, label = 'Dispatch' },

    dialogue = {
        greeting = { "Need a ride?", "Where to, friend?" },
        topics = {
            {
                id = 'ride', label = 'Quick ride ($50)',
                text = "Take me to Vespucci.",
                tone = 'bribe', icon = 'fa-route', cost = 50,
                response = "Hop in. Five minutes.",
                fail_response = "Show me the fifty first.",
                server = function(src)
                    if not Bridge.RemoveMoney(src, 'cash', 50) then return false end
                    Bridge.AddItem(src, 'taxi_voucher', 1)
                end,
            },
            { id = 'leave', label = "Not right now.", tone = 'leave', response = "Catch you later.", terminal = true },
        },
    },
})

Add the file to shared_scripts in fxmanifest.lua. Restart. Done.

NPC schema

Spawn

Identity (NUI header)

Target / interaction

Dialogue

dialogue = {
    greeting              = 'string' or { 'pool', 'of', 'strings' },
    greeting_highlights   = { { word = 'foo', cls = 'hl-offer' } },
    opening_system_message= { type = 'default', icon = 'fa-info', text = '…' },
    topics                = { ... },     -- numbered (1-9) menu
    topic_bar             = { ... },     -- always-on T-key chip pool
}

Topic schema

Used inside topics, followups, and topic_bar.

Server hook contract

server = function(src, ctx)
    -- ctx = { npc_id, topic_path, player = { src, name, job } }
    --
    -- Return values:
    --   nil / true                          → continue normally
    --   false                                → cancel, reply with topic.fail_response
    --   false, 'short message'               → cancel, reply with that message
    --   { response='…', followups={…}, terminal=bool, highlights={…}, system_message={…} }
    --                                        → fully override the reply + next menu
end

The Bridge API

Bridge.* is in scope inside any server hook. Auto-detects framework + inventory on first call.

-- MONEY
Bridge.GetMoney(src, account)
Bridge.AddMoney(src, account, amount, reason)
Bridge.RemoveMoney(src, account, amount, reason)
-- accounts: 'cash' | 'bank' | 'black_money'

-- INVENTORY
Bridge.HasItem(src, item, count)
Bridge.AddItem(src, item, count, metadata)
Bridge.RemoveItem(src, item, count)
Bridge.GetItemCount(src, item)

-- IDENTITY
Bridge.GetPlayerName(src)
Bridge.GetJob(src)              -- { name, label, grade }

-- NOTIFY
Bridge.Notify(src, { title, description, type, duration })

-- Detect (mostly for debug)
Bridge.DetectFramework()        -- 'qbx' | 'qb' | 'esx' | 'standalone'
Bridge.DetectInventory()        -- 'ox' | 'qb' | 'esx' | 'standalone'

OneSync, persistence, state bags

The server creates every NPC via CreatePed(pedType, hash, x, y, z, h, true, true) and immediately calls SetEntityOrphanMode(ped, 2) so the engine doesn't garbage-collect the entity when no player is in scope. Each ped's lrr_npc_chat:id state bag carries its npc.id to every client that ever streams the entity. Clients listen via AddStateBagChangeHandler and decorate (scenario, ox_target, blip).

See: FiveM OneSync docs and State bags docs.

Runtime API (exports)

-- Server
exports.lrr_npc_chat:AddNpc(definition)      -- same schema as a character file
exports.lrr_npc_chat:RemoveNpc(npc_id)

-- Client
exports.lrr_npc_chat:OpenDialogue(npc_id)    -- force-start a chat
exports.lrr_npc_chat:CloseDialogue()
exports.lrr_npc_chat:IsDialogueOpen()
exports.lrr_npc_chat:GetNpcPed(npc_id)
exports.lrr_npc_chat:IsNpcPed(ped)
exports.lrr_npc_chat:GetNpcIdFromPed(ped)

Client events

AddEventHandler('lrr_npc_chat:client:npcSpawned',   function(npc_id, ped) end)
AddEventHandler('lrr_npc_chat:client:npcDespawned', function(npc_id, ped) end)
AddEventHandler('lrr_npc_chat:client:npcsLoaded',   function() end)

Demo characters

Compatibility

• FiveM, lua54, OneSync on
• QBX-Core / QB-Core / ESX / standalone
• ox_inventory / qb-inventory / esx_inventory