Ped Interactions

Ped Interactions is a client-side system built into the bridge for spawning NPC peds with target options. Peds are created when a player enters a radius and removed when they leave, keeping entity count low.

• How it works
• Client exports
  • AddPedInteraction
  • RemovePedInteraction
• Payload
  • Target options
  • Animation
  • Component
• Ped behaviour
• Examples
  • Basic NPC with one option
  • NPC with animation and multiple options
  • NPC with weapon
  • Manual cleanup

How it works

1. You register a ped interaction with a unique ID, model, position, and target options.
2. When a player enters the radius, the ped spawns with the configured appearance, animation, and options.
3. When the player leaves the radius, the ped is removed and options are cleared.
4. When the resource that registered the interaction stops, all its ped interactions are cleaned up automatically.

ox_lib points

Ped interactions use lib.points from ox_lib for radius checks. The ped only exists while a player is nearby.

Client exports

AddPedInteraction

Registers a new ped interaction.

exports["prp-bridge"]:AddPedInteraction(id, payload)

Parameter	Type	Description
id	string	Unique identifier for this ped.
payload	PedInteractionPayload	Config (see below).

Returns: boolean, string?

• true on success
• false, "missing" if id or payload is nil
• false, "exists" if that id is already registered

RemovePedInteraction

Removes a registered ped and deletes the ped if it exists.

exports["prp-bridge"]:RemovePedInteraction(id)

Parameter	Type	Description
id	string	ID used when the ped was created.

Returns: boolean — true if removed, false if not found.

Payload

Field	Type	Required	Description
model	number | string	Yes	Ped model hash or name (e.g. "s_m_y_dealer_01").
coords	vector3	Yes	World position.
heading	number	Yes	Facing direction (0–360).
radius	number	No	Spawn/despawn distance. Default 100.0.
options	table[]	Yes	Target options (see below).
scenario	string	No	Ambient scenario (e.g. "WORLD_HUMAN_GUARD_STAND").
anim	table	No	Animation (see Animation).
component	table	No	Ped component variation.
weapon	number	No	Weapon hash.

Scenario vs anim

Use either scenario or anim, not both. If both are set, the animation is used.

Target options

Each entry in options follows the usual target option shape. The name field is set automatically.

Field	Type	Required	Description
label	string	Yes	Text in the target menu.
icon	string	No	Font Awesome icon (e.g. "fas fa-hand").
distance	number	No	Max distance to show the option.
groups	string | string[] | table	No	Job/group restriction.
items	string	No	Required item.
canInteract	function	No	Return true to show the option.
onSelect	function	No	Called when the option is selected.
event	string	No	Client event on select.
serverEvent	string	No	Server event on select.

Animation

Field	Type	Default	Description
animDict	string		Animation dictionary.
anim	string		Animation clip.
blendIn	number	8.0	Blend in speed.
blendOut	number	8.0	Blend out speed.
duration	number	-1	Duration (ms); -1 = loop.
flag	number	1	Animation flag.
playback	number	0	Playback rate.
lockX / lockY / lockZ	boolean	false	Axis lock.

Component

Ped component variation on spawn.

Field	Type	Default	Description
componentId	number	0	Component slot.
drawableId	number	0	Drawable index.
textureId	number	0	Texture index.
paletteId	number	0	Palette index.

Ped behaviour

All peds created by this system are:

• Frozen in place
• Invincible
• Unable to ragdoll, flee, or react to events
• Seeing range set to 0
• Using default component variation unless component is set

Examples

Basic NPC with one option

exports["prp-bridge"]:AddPedInteraction("my_dealer", {
    model = "s_m_y_dealer_01",
    coords = vector3(100.0, 200.0, 30.0),
    heading = 180.0,
    radius = 50.0,
    scenario = "WORLD_HUMAN_STAND_IMPATIENT",
    options = {
        {
            icon = "fas fa-comments",
            label = "Talk to Dealer",
            distance = 2.0,
            onSelect = function()
                openDealerMenu()
            end
        }
    }
})

NPC with animation and multiple options

exports["prp-bridge"]:AddPedInteraction("workshop_npc", {
    model = "s_m_y_mechanic_01",
    coords = vector3(150.0, -300.0, 40.0),
    heading = 90.0,
    radius = 30.0,
    anim = {
        animDict = "anim@amb@business@bgen@bgen_no_work@",
        anim = "stand_phone_phoneputdown_idle_nowork",
        flag = 49
    },
    options = {
        {
            icon = "fas fa-wrench",
            label = "Repair Vehicle",
            distance = 2.5,
            canInteract = function()
                return IsPedInAnyVehicle(PlayerPedId(), false)
            end,
            onSelect = function()
                repairVehicle()
            end
        },
        {
            icon = "fas fa-cart-shopping",
            label = "Buy Parts",
            distance = 2.5,
            onSelect = function()
                openPartsShop()
            end
        }
    }
})

NPC with weapon

exports["prp-bridge"]:AddPedInteraction("armed_guard", {
    model = "s_m_y_blackops_01",
    coords = vector3(200.0, 100.0, 35.0),
    heading = 270.0,
    radius = 60.0,
    scenario = "WORLD_HUMAN_GUARD_STAND",
    weapon = `weapon_carbinerifle`,
    options = {
        {
            icon = "fas fa-gun",
            label = "Talk",
            distance = 2.0,
            onSelect = function()
                openGuardMenu()
            end
        }
    }
})

Manual cleanup

AddEventHandler("onResourceStop", function(resourceName)
    if resourceName ~= GetCurrentResourceName() then return end
    exports["prp-bridge"]:RemovePedInteraction("my_dealer")
    exports["prp-bridge"]:RemovePedInteraction("workshop_npc")
end)

Auto cleanup

Ped interactions are removed automatically when the resource that created them stops. Use manual cleanup only if you need to remove a ped while the resource is still running.