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.

Table of Contents

• Installation

• Configuration

• Data Structure

• API Reference

  • Local Entity Interactions

  • Model Interactions

  • Global Interactions

  • Coordinate Interactions

  • Utility Functions

• Examples

• Advanced Usage

Installation

1. Place the nn_interaction resource in your resources folder

2. Add ensure nn_interaction to your server.cfg

3. 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