gfx-interact

Info

Dependencies

• FiveM asset packs (dependency '/assetpacks')
• No framework dependency (fully standalone)

Installation

1. Copy Files

Copy the gfx-interact folder into your server's resources directory.

2. server.cfg

ensure gfx-interact

Note: No additional configuration file is needed. The script works out of the box.

Configuration

This script has no external configuration file (config.lua). All behavior is controlled through the export API when creating interactions.

Supported Keys

The following key bindings are available for interaction options:

Color Formats

Colors can be specified in the following formats:

• HEX: "#FF0000" or "#FF0000FF" (with alpha)
• RGB: "rgb(255, 0, 0)"
• RGBA: "rgba(255, 0, 0, 255)"

Default color: rgb(0, 253, 139) (green)

Exports

NewInteraction

Creates a new interaction point in the world.

exports["gfx-interact"]:NewInteraction(type, group, interactionData)

Parameters:

interactionData fields:

Option fields:

Returns: The interaction object.

Example - Single option (coords):

exports["gfx-interact"]:NewInteraction("coords", vector3(100.0, 200.0, 30.0), {
    id = "my-door",
    bgColor = "rgb(10, 196, 255)",
    options = {
        {
            text = "Open Door",
            key = "E",
            event = "door:open",
        }
    }
})

Example - Multiple options (coords):

exports["gfx-interact"]:NewInteraction("coords", vector3(100.0, 200.0, 30.0), {
    id = "kitchen-door",
    title = "Kitchen Door",
    options = {
        {
            text = "Open Door",
            id = "open",
        },
        {
            text = "Lock Door",
            id = "lock",
        },
        {
            text = "Knock",
            id = "knock",
        },
    }
})

Example - Entity interaction:

exports["gfx-interact"]:NewInteraction("entity", { pedHandle }, {
    id = "ped-shopkeeper",
    title = "Shopkeeper",
    options = {
        {
            text = "Talk",
            id = "talk",
            event = "shop:talk",
        },
        {
            text = "Browse Items",
            id = "browse",
            event = "shop:browse",
        },
    }
})

UpdateInteraction

Updates properties of an existing interaction.

exports["gfx-interact"]:UpdateInteraction(id, updateData)

Parameters:

Updatable fields:

Example:

exports["gfx-interact"]:UpdateInteraction("ped-shopkeeper", {
    title = "Closed Shopkeeper",
    bgColor = "#FF0000",
    options = {
        {
            text = "Shop is closed",
            id = "closed",
        }
    }
})

RemoveInteraction

Removes an interaction from the world.

exports["gfx-interact"]:RemoveInteraction(id)

Parameters:

Example:

exports["gfx-interact"]:RemoveInteraction("my-door")

Events

gfx-interact:interacted

Triggered on the client when a player interacts with any interaction point. This event fires regardless of whether the option has its own event defined.

Parameters:

Example:

RegisterNetEvent("gfx-interact:interacted", function(interactionId, optionId)
    print("Player interacted with:", interactionId, "Option:", optionId)
end)

Note: If an option has an event field defined, that event is also triggered separately with the option's context data. The gfx-interact:interacted event fires in addition to the option-specific event.

Option Events

When an option has an event field, that event is triggered via TriggerEvent with the option's context table. If no custom context is provided, the default context includes:

Example:

RegisterNetEvent("door:open", function(context)
    print("Opening door at interaction:", context.id)
    print("Entity:", context.entity)     -- if entity type
    print("Coords:", context.coords)     -- if coords type
end)

Commands

This script does not register any commands.

Features

• Standalone 3D world interaction system (no framework required)
• Two interaction types: static coordinates and entity-attached
• Single-option mode with customizable key binding
• Multi-option mode with scroll selection (mouse wheel up/down)
• Custom color support (HEX, RGB, RGBA) for background, hover, and active states
• Animated fade-in/fade-out based on player distance
• Automatic proximity detection (activates within 25 units, key prompt within 1.5 units)
• Custom font rendering (IstokWeb Bold and Regular via streamed .gfx fonts)
• Runtime texture dictionary for UI sprites
• Automatic closest-interaction detection (only one interaction active at a time)
• Full API for creating, updating, and removing interactions at runtime
• Lightweight: no NUI, no framework dependencies, pure GTA native rendering

Troubleshooting

Source

• GitHub: https://github.com/gfx-fivem/gfx-interact
• Organization: GFX-Fivem