Usage

nn_interaction Documentation

A comprehensive interaction system for FiveM resources that provides targeting and text display functionality for entities, models, coordinates, and global objects.

Installation
Configuration
Data Structure
API Reference
- Local Entity Interactions
- Model Interactions
- Global Interactions
- Coordinate Interactions
- Utility Functions
Examples
Advanced Usage

Installation

Place the nn_interaction resource in your resources folder
Add ensure nn_interaction to your server.cfg
Configure the settings in config.lua if needed

Configuration

The script uses config.lua for default settings:

cfg.Interaction = {
    default = {
        hideSquare = false,          -- Hide the interaction square
        checkVisibility = false,     -- Check if entity is visible
        distance = 10.0,            -- Maximum interaction distance
        distanceText = 1.0,         -- Text display distance
        showInVehicle = false,      -- Show interactions while in vehicle
        offset = {
            text = {x = 0.0, y = 0.0, z = 0.2},    -- Text offset
            target = {x = 0.0, y = 0.0, z = 0.0}   -- Target offset
        },
        duration = 1000,            -- Interaction duration in ms
        key = "E",                  -- Default interaction key
        icon = "fa-solid fa-user",  -- Default FontAwesome icon
    },
    maximumDistance = 50.0,         -- Maximum detection distance
    keyScrollUp = "TOP",            -- Key to scroll up options
    keyScrollDown = "DOWN",         -- Key to scroll down options
}

Data Structure

All interaction functions use a similar data structure:

local data = {
    -- Core settings
    hideSquare = false,                    -- Hide interaction square (optional)
    checkVisibility = true,                -- Check entity visibility (optional)
    distance = 3.0,                        -- Interaction distance (optional)
    distanceText = 1.5,                    -- Text display distance (optional)
    showInVehicle = false,                 -- Show while in vehicle (optional)
    bone = "head",                         -- Specific bone to target (optional)
    ignoreModel = {GetHashKey("prop_car")}, -- Models to ignore (optional)
    
    -- Offset configuration
    offset = {
        text = {x = 0.0, y = 0.0, z = 0.2},
        target = {x = 0.0, y = 0.0, z = 0.0}
    },
    
    -- Options array
    options = {
        {
            name = "unique_option_name",       -- Unique identifier
            label = "Interact",               -- Display text
            icon = "fa-solid fa-hand",        -- FontAwesome icon
            key = "E",                        -- Interaction key
            duration = 500,                   -- Animation duration
            onSelect = function(entity)       -- Callback function
                -- Your interaction logic here
                print("Interacted with entity:", entity)
            end
        }
    }
}

API Reference

Local Entity Interactions

These functions work with specific entity IDs.

addInteractionLocalEntity(name, entity, data, resource)

Adds an interaction to a specific local entity.

Parameters:

name (string): Unique interaction name
entity (number|table): Entity ID or table of entity IDs
data (table): Interaction data structure
resource (string, optional): Resource name (auto-detected if not provided)

addTextLocalEntity(name, entity, data, resource)

Adds text display to a specific local entity.

removeLocalEntity(entity, name, option, resource)

Removes interactions from local entities.

Parameters:

entity (number|table): Entity ID(s) to remove from
name (string, optional): Specific interaction name to remove
option (string, optional): Specific option to remove
resource (string, optional): Resource name

hideLocalEntity(entity, name)

Temporarily hides interactions on local entities.

showLocalEntity(entity, name)

Shows previously hidden interactions on local entities.

Model Interactions

These functions work with entity model hashes and apply to all entities of that model.

addInteractionModel(name, model, data, resource)

Adds interactions to all entities of a specific model.

Parameters:

name (string): Unique interaction name
model (number|table): Model hash or table of model hashes
data (table): Interaction data structure
resource (string, optional): Resource name

addTextModel(name, model, data, resource)

Adds text display to all entities of a specific model.

removeModel(model, name, option, resource)

Removes interactions from model-based interactions.

hideModel(model, name)

Temporarily hides interactions on model-based interactions.

showModel(model, name)

Shows previously hidden model-based interactions.

Global Interactions

These functions work with entity types (ped, vehicle, player, object).

addInteractionGlobal(name, entityType, data, resource)

Adds interactions to all entities of a specific type.

Parameters:

name (string): Unique interaction name
entityType (string|table): Entity type ("ped", "vehicle", "player", "object")
data (table): Interaction data structure
resource (string, optional): Resource name

addTextGlobal(name, entityType, data, resource)

Adds text display to all entities of a specific type.

removeGlobal(entityType, name, option, resource)

Removes global interactions.

hideGlobal(entityType, name)

Temporarily hides global interactions.

showGlobal(entityType, name)

Shows previously hidden global interactions.

Coordinate Interactions

These functions create interactions at specific world coordinates.

addInteractionCoords(name, coords, data, resource)

Adds interaction at specific coordinates.

Parameters:

name (string): Unique interaction name
coords (vector3|table): Coordinates or table of coordinates
data (table): Interaction data structure
resource (string, optional): Resource name

addTextCoords(name, coords, data, resource)

Adds text display at specific coordinates.

removeCoords(coords, name, option, resource)

Removes coordinate-based interactions.

hideCoords(coords, name)

Temporarily hides coordinate interactions.

showCoords(coords, name)

Shows previously hidden coordinate interactions.

Utility Functions

removeResource(resource)

Removes all interactions created by a specific resource.

Examples

Basic Entity Interaction

-- Add interaction to a specific vehicle
local vehicle = GetVehiclePedIsIn(PlayerPedId(), false)

exports['nn_interaction']:addInteractionLocalEntity("repair_vehicle", vehicle, {
    distance = 5.0,
    options = {
        {
            name = "repair",
            label = "Repair Vehicle",
            icon = "fa-solid fa-wrench",
            key = "E",
            onSelect = function(entity)
                -- Repair the vehicle
                SetVehicleFixed(entity)
                SetVehicleDeformationFixed(entity)
                print("Vehicle repaired!")
            end
        }
    }
})

Model-Based Interactions

-- Add interaction to all ATMs
local atmModel = GetHashKey("prop_atm_01")

exports['nn_interaction']:addInteractionModel("atm_banking", atmModel, {
    distance = 2.0,
    checkVisibility = true,
    options = {
        {
            name = "withdraw",
            label = "Withdraw Money",
            icon = "fa-solid fa-credit-card",
            onSelect = function(entity)
                -- Open banking menu
                TriggerEvent('banking:openATM')
            end
        },
        {
            name = "deposit",
            label = "Deposit Money",
            icon = "fa-solid fa-money-bill",
            onSelect = function(entity)
                -- Open deposit menu
                TriggerEvent('banking:openDeposit')
            end
        }
    }
})

Global Interactions

-- Add interaction to all players
exports['nn_interaction']:addInteractionGlobal("player_menu", "player", {
    distance = 3.0,
    bone = "head",
    options = {
        {
            name = "give_money",
            label = "Give Money",
            icon = "fa-solid fa-dollar-sign",
            onSelect = function(entity)
                local targetPlayer = GetPlayerServerId(NetworkGetPlayerIndexFromPed(entity))
                TriggerServerEvent('economy:giveMoney', targetPlayer)
            end
        }
    }
})

Coordinate-Based Interactions

-- Add interaction at specific location
local shopCoords = vector3(373.875, 325.896, 103.566)

exports['nn_interaction']:addInteractionCoords("shop_entrance", shopCoords, {
    distance = 2.0,
    distanceText = 5.0,
    offset = {
        text = {x = 0.0, y = 0.0, z = 1.0},
        target = {x = 0.0, y = 0.0, z = 0.0}
    },
    options = {
        {
            name = "enter_shop",
            label = "Enter Shop",
            icon = "fa-solid fa-store",
            key = "E",
            duration = 1000,
            onSelect = function()
                -- Enter shop logic
                TriggerEvent('shop:enter')
            end
        }
    }
})

Text-Only Display

-- Add text display without interaction
local infoCoords = vector3(100.0, 200.0, 30.0)

exports['nn_interaction']:addTextCoords("info_display", infoCoords, {
    distanceText = 10.0,
    options = {
        {
            label = "Welcome to Los Santos!",
            icon = "fa-solid fa-info-circle"
        }
    }
})

Advanced Vehicle Bone Targeting

-- Target specific vehicle parts
exports['nn_interaction']:addInteractionGlobal("vehicle_parts", "vehicle", {
    distance = 3.0,
    bone = "door_dside_f", -- Front left door
    options = {
        {
            name = "open_door",
            label = "Open Door",
            icon = "fa-solid fa-door-open",
            onSelect = function(entity)
                SetVehicleDoorOpen(entity, 0, false, false)
            end
        }
    }
})

Multiple Options with Conditions

exports['nn_interaction']:addInteractionModel("police_vehicle", GetHashKey("police"), {
    distance = 4.0,
    options = {
        {
            name = "enter_driver",
            label = "Enter as Driver",
            icon = "fa-solid fa-car",
            onSelect = function(entity)
                if IsVehicleSeatFree(entity, -1) then
                    TaskWarpPedIntoVehicle(PlayerPedId(), entity, -1)
                else
                    print("Driver seat is occupied!")
                end
            end
        },
        {
            name = "search_vehicle",
            label = "Search Vehicle",
            icon = "fa-solid fa-search",
            onSelect = function(entity)
                -- Only allow if player is a police officer
                if GetPlayerJob() == "police" then
                    TriggerEvent('police:searchVehicle', entity)
                else
                    print("You must be a police officer!")
                end
            end
        }
    }
})

Advanced Usage

Dynamic Interaction Management

-- Function to dynamically add/remove interactions based on conditions
function ManageShopInteractions(isOpen)
    local shopCoords = vector3(373.875, 325.896, 103.566)
    
    if isOpen then
        exports['nn_interaction']:addInteractionCoords("shop", shopCoords, {
            distance = 2.0,
            options = {
                {
                    name = "enter",
                    label = "Enter Shop",
                    icon = "fa-solid fa-store",
                    onSelect = function()
                        TriggerEvent('shop:enter')
                    end
                }
            }
        })
    else
        exports['nn_interaction']:removeCoords(shopCoords, "shop")
        
        -- Add closed sign
        exports['nn_interaction']:addTextCoords("shop_closed", shopCoords, {
            distanceText = 5.0,
            options = {
                {
                    label = "Shop is Closed",
                    icon = "fa-solid fa-times-circle"
                }
            }
        })
    end
end

Resource Cleanup

-- Automatically clean up interactions when resource stops
AddEventHandler('onResourceStop', function(resourceName)
    if GetCurrentResourceName() == resourceName then
        exports['nn_interaction']:removeResource(resourceName)
    end
end)

Performance Considerations

Use checkVisibility = true for entities that might be behind walls
Set appropriate distance values to avoid unnecessary processing
Use hideSquare = true for text-only displays
Clean up unused interactions to maintain performance
Use model-based interactions instead of multiple entity-specific ones when possible

Error Handling

The script includes built-in error handling and will log warnings for:

Invalid entity IDs
Incorrect parameter types
Non-existent interactions during removal
Missing required parameters

Enable debug mode in config.lua to see detailed logging:

cfg.Debug = true

Previousnn_interaction NextInstallation

Last updated 27 days ago

nn_interaction Documentation

Table of Contents

Installation

Configuration

Data Structure

API Reference

Local Entity Interactions

Model Interactions

Global Interactions

Coordinate Interactions

Utility Functions

Examples

Basic Entity Interaction

Model-Based Interactions

Global Interactions

Coordinate-Based Interactions

Text-Only Display

Advanced Vehicle Bone Targeting

Multiple Options with Conditions

Advanced Usage

Dynamic Interaction Management

Resource Cleanup

Performance Considerations

Error Handling