Features

Free | Download on Tebex

Detailed explanation of all nc-interaction features.

NPC System

Ped Spawning

• Automatic model loading with timeout protection
• Frozen, invincible, non-reactive peds (no ragdoll, no damage)
• Default component variation applied automatically
• Supports both ped model names (string) and hashes (number)

Animation & Scenario

Each NPC supports one of two idle behaviors:

Scenario takes priority if both are defined. See GTA Scenarios for the full list.

Map Blips

Optional per-NPC blip configuration:

blip = {
    enabled = true,     -- Show on map
    sprite = 280,       -- Blip icon (fivem.net/docs/game-references/blips/)
    color = 3,          -- Blip color
    scale = 0.8,        -- Blip size
    label = 'NPC Name', -- Blip display name
    category = 7        -- Optional category for map filter
}

Target System

Auto-Detection

When Config.TargetSystem = 'auto':

1. Check if ox_target resource is started → use ox_target
2. Check if qb-target resource is started → use qb-target
3. Neither found → fallback to E key proximity

When a target system is detected, E key is completely disabled to avoid conflicts.

Target Registration

NPCs are registered as local entity targets with:

• Custom label (defaults to NPC name)
• Custom icon (defaults to fas fa-comment)
• Distance matching Config.InteractDistance

Hot-Reload

If ox_target or qb-target restarts while nc-interaction is running, all NPC targets are automatically re-registered.

E Key Fallback

When no target system is available:

• A slow background thread (500ms) scans for the closest NPC within InteractDistance
• A fast render thread draws the NPC name above the closest NPC's head
• Pressing E opens the dialog with the closest NPC
• No extra overhead when no NPC is nearby (thread sleeps at 500ms)

NPC Name Display

NPC names are displayed as 3D floating text above their heads:

• Visible within Config.DrawDistance (default 10.0)
• Shows the NPC's name property
• Only renders when at least one NPC is within draw distance
• Thread sleeps when no nearby NPCs are detected

Dialog System

Camera

When a dialog opens:

1. Player character turns to face the NPC
2. Scripted camera transitions to NPC's face
3. Depth of field blur activates (configurable)
4. All player controls are disabled (except mouse look)

Camera positioning:

• Calculated from NPC heading + configurable distance/height
• Smooth ease-in/ease-out transitions
• DOF focus on NPC with blurred background

Typing Effect

Dialog text appears word-by-word:

• Configurable speed via Config.TypingSpeed (ms per word)
• Sound effect on each word
• Click or press Space/Enter to skip to full text
• Options only appear after typing completes

Dialog Options

Set close = false on client/server options to keep the dialog open after the event fires.

Sound Effects

5 configurable GTA native sounds:

• open — Dialog opens
• close — Dialog closes
• select — Option selected
• hover — Mouse over option
• typing — Each word typed

NUI

Built with Vue 3 + Vite:

• Minimal, clean design
• ESC key to close
• Responsive option buttons with hover effects
• Smooth enter/leave transitions

Programmatic Dialogs

Open dialogs without spawning an NPC using the OpenDialog export:

exports['nc-interaction']:OpenDialog({
    name = 'System',
    greeting = 'This is a message from the server.',
    options = {
        { label = 'OK', type = 'close' }
    }
})

• No camera animation (no NPC ped)
• Full NUI dialog with typing effect
• Automatically cleaned up on close

Distance Safety

A background thread monitors distance during interaction:

• Checks every 1000ms
• If player moves more than 3× InteractDistance away, dialog auto-closes
• Prevents stuck dialogs from teleportation or disconnects

Resource Cleanup

When nc-interaction stops:

• All NPC peds are deleted
• All blips are removed
• All target registrations are cleared
• Active dialog is closed
• Camera is restored to normal