Features

All systems included in nc-interaction and how to use them.

NPC Dialog System

Place NPCs anywhere on your server and let players talk to them. Use it for job applications, shop clerks, quest givers, guides — anything that needs a conversation.

Why use it?

• One config, instant NPC — Add an NPC with coordinates, model, and dialog options. It spawns automatically.
• Works with any resource — Other resources can add or remove NPCs at any time via exports.
• No setup needed — Automatically detects ox_target, qb-target, or falls back to E key. No configuration required.

What does the player see?

1. NPC name floats above their head when nearby
2. Interact to start a conversation — camera focuses on the NPC with depth-of-field
3. Dialog text types out word by word with sound effects
4. Choose from dialog options — trigger events, navigate pages, open shops, or close

Dialog Pages

NPCs can have multi-page conversations. Players can navigate forward and back through dialog trees — useful for menus, quest chains, or branching choices.

Programmatic Dialogs

Show a dialog without an NPC — useful for server messages, confirmations, or tutorials:

exports['nc-interaction']:OpenDialog({
    name = 'System Message',
    greeting = 'Welcome to the server!',
    options = {
        { label = 'Got it', type = 'close' }
    }
})

Shop System

A complete buy/sell shop that works inside the NPC dialog. No separate shop resource needed.

Why use it?

• Built into the dialog — Players browse the shop while still in conversation with the NPC. No jarring UI switch.
• Smooth camera transition — Camera shifts to the side when the shop opens, and returns when it closes.
• Two ways to set up — Define shops in config for quick setup, or use exports for dynamic shops from other resources.
• Cash or card — Players choose their payment method. Server validates everything.

What does the player see?

1. Talk to a shop NPC and select "Browse Shop"
2. Camera smoothly shifts to the side
3. Shop panel appears with Buy and Sell tabs
4. Pick items, set quantity, choose payment method
5. Press ESC to close the shop — conversation continues
6. Press ESC again to leave the NPC entirely

Config Setup

Define shop NPCs in systems/shop/config.lua — they spawn automatically with their shop linked:

Config.ShopNPCs = {
    {
        id    = 'general_store_1',
        name  = 'Shop Clerk',
        model = 'mp_m_shopkeep_01',
        coords = vector4(25.7, -1347.3, 29.5, 271.0),
        shop = {
            title    = 'General Store',
            buyItems = {
                { name = 'water', label = 'Water', price = 10 },
            },
            sellItems = {},
        },
    },
}

Export Setup

Register shops from other resources for full control:

-- Server: register shop data
exports['nc-interaction']:RegisterShop('weapon_shop', {
    title = 'Ammu-Nation',
    buyItems = { { name = 'weapon_pistol', label = 'Pistol', price = 5000 } },
    sellItems = {},
})
exports['nc-interaction']:RegisterNPCShop('ammu_clerk', 'weapon_shop')

-- Client: spawn the NPC with a shop option
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' },
    }
})

Jobs System

A City Hall NPC where players can browse and apply for jobs.

Why use it?

• Ready-to-use job board — Players talk to the City Hall clerk, see available jobs, and apply instantly.
• Config-driven — Add or remove jobs by editing systems/jobs/config.lua. No code changes needed.
• Cooldown support — Prevent players from switching jobs too frequently.

What does the player see?

1. Visit the City Hall NPC
2. Choose "Find a Job" to see all available positions
3. Select a job to read the description
4. Apply — job changes immediately

License System

A separate NPC for purchasing licenses (driver's license, weapons license, etc).

Why use it?

• Standalone NPC — Licenses have their own NPC, separate from jobs. Clean and organized.
• Framework-integrated — Works with QBCore, ESX, and QBox license systems.
• Configurable prices — Set the cost for each license in config.

What does the player see?

1. Visit the License NPC
2. See available licenses with prices
3. Purchase a license — money is deducted, license is granted

Target System Compatibility

nc-interaction works with your existing target system — no extra configuration.

You can also force a specific mode in config.lua if needed.