nc-interaction

A lightweight NPC interaction & dialog system for FiveM. Register NPCs from any resource using exports — with automatic target system detection, camera animation, typing effects, and built-in shop system.

Overview

nc-interaction lets you spawn NPC peds and attach interactive dialog menus to them. Other resources can register NPCs dynamically via exports, making it a shared interaction layer across your entire server.

Key Features

• Exports-based API — 9 client exports for full NPC & dialog control from any resource
• Target System Auto-Detection — ox_target / qb-target detected automatically, E key fallback
• Dialog Camera — Smooth camera transition with depth-of-field blur
• Typing Effect — Word-by-word text reveal with configurable speed
• Multi-Option Responses — client/server events, inline text responses, or close
• NPC Name Display — 3D floating name above NPC heads within draw distance
• Blip Support — Optional map blips per NPC with full customization
• Animation & Scenario — Per-NPC animation dict/clip or scenario
• Shop System — Built-in buy/sell UI with smooth camera transition, config NPCs or exports
• Jobs & License System — City Hall NPC for job applications and license purchases
• Programmatic Dialogs — Open dialog without NPC via OpenDialog export
• Zero Dependencies — No framework required (works standalone)

Requirements

Quick Start

ensure nc-interaction

That's it. NPCs defined in config.lua will spawn automatically.

How It Works

1. Config NPCs — Define NPCs in Config.NPCs table (model, coords, options)
2. Export NPCs — Or register from other resources: exports['nc-interaction']:AddNPC({...})
3. Target/E Key — Players interact via ox_target, qb-target, or E key proximity
4. Dialog Opens — Camera focuses on NPC, text types out, options appear
5. Option Selected — Triggers client/server events, shows response text, or closes
6. Shop Opens — Camera shifts smoothly, shop UI appears alongside dialog

Events

Listen for interaction lifecycle from other resources:

-- When a player starts interacting with an NPC
AddEventHandler('nc-interaction:started', function(npcId, data)
    print('Player started talking to: ' .. npcId)
end)

-- When a player finishes interacting
AddEventHandler('nc-interaction:ended', function(npcId)
    print('Player finished talking to: ' .. npcId)
end)