Exports

All exports are client-side unless noted. Use them from any resource to register NPCs, manage options, control dialogs, and manage shops.

AddNPC

Spawn an NPC with interaction dialog.

local npcId = exports['nc-interaction']:AddNPC({
    id = 'my_npc',
    name = 'Shop Keeper',
    subtitle = 'General Store',
    model = 's_m_m_shopkeep_01',
    coords = vector4(25.0, -1347.0, 29.5, 270.0),
    greeting = 'Welcome! What can I get you?',
    scenario = 'WORLD_HUMAN_STAND_IMPATIENT',
    blip = {
        enabled = true,
        sprite = 52,
        color = 2,
        scale = 0.8,
        label = 'General Store'
    },
    options = {
        { label = 'Buy Supplies',  icon = '🛒', type = 'client', event = 'myshop:open' },
        { label = 'Sell Items',    icon = '💰', type = 'server', event = 'myshop:sell', args = { 'all' } },
        { label = 'Ask about deals', icon = '❓', response = 'Everything is 20% off today!' },
        { label = 'Leave',         icon = '👋', type = 'close' },
    }
})
-- Returns: string (npcId) or nil on failure

Required fields: id, model, coords

If an NPC with the same id already exists, it will be replaced.

RemoveNPC

Remove a spawned NPC by ID. Deletes the ped, blip, and target registration.

local success = exports['nc-interaction']:RemoveNPC('my_npc')
-- Returns: boolean

If the player is currently interacting with this NPC, the dialog closes automatically.

AddOption

Add a dialog option to an existing NPC.

local success = exports['nc-interaction']:AddOption('my_npc', {
    label = 'New Option',
    icon = '✨',
    type = 'client',
    event = 'myresource:newFeature'
})
-- Returns: boolean

RemoveOption

Remove a dialog option by its label text.

local success = exports['nc-interaction']:RemoveOption('my_npc', 'New Option')
-- Returns: boolean

GetNPC

Get the data table for a specific NPC.

local data = exports['nc-interaction']:GetNPC('my_npc')
-- Returns: table { id, name, model, coords, options, ... } or nil

GetAllNPCs

Get all registered NPC data.

local all = exports['nc-interaction']:GetAllNPCs()
-- Returns: table { [id] = data, ... }

for id, data in pairs(all) do
    print(id, data.name)
end

OpenDialog

Open a dialog without spawning an NPC. Useful for programmatic/UI-only dialogs.

local success = exports['nc-interaction']:OpenDialog({
    name = 'System Message',
    subtitle = 'Server Info',
    greeting = 'Welcome to the server! Please read the rules.',
    options = {
        { label = 'I understand', type = 'client', event = 'rules:accepted', icon = '✅' },
        { label = 'Show rules',   response = '1. Be respectful\n2. No cheating\n3. Have fun!' },
    }
})
-- Returns: boolean (false if already interacting)

The dialog is cleaned up automatically when closed.

CloseDialog

Close the currently active dialog.

exports['nc-interaction']:CloseDialog()

IsInteracting

Check if the player is currently in a dialog.

local active = exports['nc-interaction']:IsInteracting()
-- Returns: boolean

Full Example

A complete example of registering an NPC from another resource:

-- client/main.lua of your resource

CreateThread(function()
    -- Wait for nc-interaction to be ready
    while GetResourceState('nc-interaction') ~= 'started' do
        Wait(500)
    end

    exports['nc-interaction']:AddNPC({
        id = 'police_chief',
        name = 'Chief Williams',
        subtitle = 'Los Santos Police Department',
        model = 's_m_y_cop_01',
        coords = vector4(441.0, -982.0, 30.7, 180.0),
        greeting = 'Officer. What do you need?',
        animation = { dict = 'anim@amb@nightclub@peds@', clip = 'rcmme_amanda1_stand_loop_cop', flag = 49 },
        blip = {
            enabled = true,
            sprite = 60,
            color = 29,
            scale = 0.9,
            label = 'Police Chief'
        },
        options = {
            { label = 'Request Duty',     icon = '🔫', type = 'client', event = 'police:requestDuty' },
            { label = 'View Warrants',    icon = '📋', type = 'server', event = 'police:viewWarrants' },
            { label = 'Report Crime',     icon = '🚨', type = 'server', event = 'police:report', args = { 'crime' } },
            { label = 'Ask about wanted', icon = '❓', response = 'Check the board. We have several persons of interest.' },
            { label = 'Dismiss',          icon = '👋', type = 'close' },
        }
    })
end)

-- Listen for custom events
RegisterNetEvent('police:requestDuty', function()
    -- Your duty logic here
    TriggerServerEvent('police:toggleDuty')
end)

Cleanup on Resource Stop

NPCs are automatically cleaned up when nc-interaction stops. If your resource stops and you want to remove your NPC:

AddEventHandler('onResourceStop', function(res)
    if res ~= GetCurrentResourceName() then return end
    exports['nc-interaction']:RemoveNPC('police_chief')
end)

Server Exports (Shop System)

The following exports are server-side and used for the built-in shop system.

RegisterShop

Register a shop with buy/sell item definitions.

exports['nc-interaction']:RegisterShop('my_shop', {
    title    = 'Hardware Store',
    subtitle = 'Tools & Parts',
    buyItems = {
        { name = 'hammer',     label = 'Hammer',     price = 50 },
        { name = 'screwdriver', label = 'Screwdriver', price = 30 },
    },
    sellItems = {
        { name = 'metalscrap', label = 'Metal Scrap', price = 10 },
    },
})
-- Returns: boolean

OpenShop

Open a registered shop for a specific player.

exports['nc-interaction']:OpenShop(source, 'my_shop')
-- Returns: boolean

RegisterNPCShop

Link an existing NPC to a registered shop. When the NPC's action = 'openShop' option is selected, this shop opens.

exports['nc-interaction']:RegisterNPCShop('my_npc_id', 'my_shop')
-- Returns: boolean

Server Shop Example

-- server/main.lua of your resource

-- Register a shop
exports['nc-interaction']:RegisterShop('weapon_shop', {
    title    = 'Ammu-Nation',
    subtitle = 'Weapons & Ammo',
    buyItems = {
        { name = 'weapon_pistol',  label = 'Pistol',       price = 5000 },
        { name = 'ammo-9',         label = '9mm Ammo x24', price = 250 },
    },
    sellItems = {},
})

-- Link to an NPC (NPC must have action = 'openShop' option)
exports['nc-interaction']:RegisterNPCShop('ammu_clerk', 'weapon_shop')

-- client/main.lua of your resource

CreateThread(function()
    while GetResourceState('nc-interaction') ~= 'started' do Wait(500) end

    exports['nc-interaction']:AddNPC({
        id = 'ammu_clerk',
        name = 'Gun Dealer',
        model = 's_m_y_ammucity_01',
        coords = vector4(22.0, -1105.0, 29.8, 160.0),
        greeting = 'Welcome to Ammu-Nation.',
        options = {
            { label = 'Browse Weapons', icon = '🔫', action = 'openShop' },
            { label = 'Leave',          icon = '👋', type = 'close' },
        }
    })
end)