NPCs

The client-side NPCs global provides a range-based NPC spawn/despawn manager. Never spawn NPCs via raw CreatePed — using NPCs ensures they are automatically spawned when a player enters range and despawned when they leave, preventing entity count bloat.

Registering an NPC

NPCs.register(id, template)

NPCs.register('mymodule:fishingShopkeeper', {
    model  = 'a_m_m_beach_01',
    coords = vector4(1234.5, -1234.5, 28.0, 180.0),
    range  = 50.0,       -- spawn/despawn radius in metres
    freeze = true,       -- freeze in place (default: true)
    scenario = 'WORLD_HUMAN_STAND_IMPATIENT',
})

Field	Type	Default	Description
model	string	required	Ped model name
coords	vector4	required	Position and heading
range	number	50.0	Spawn/despawn radius in metres
freeze	boolean	true	Freeze the ped in place
scenario	string	nil	Ambient scenario to play
onSpawn	function	nil	Called with the ped handle after spawn
onDespawn	function	nil	Called with the ped handle before despawn

Unregistering an NPC

NPCs.unregister('mymodule:fishingShopkeeper')

Call this in your module's stop handler to clean up.

Full Example — Shop NPC with Interaction

-- boot.lua (client-side)
AddEventHandler('module:boot', function()
    NPCs.register('mymodule:shopkeeper', {
        model    = 'ig_redneck',
        coords   = vector4(-1234.5, 678.9, 25.0, 90.0),
        range    = 40.0,
        scenario = 'WORLD_HUMAN_CLIPBOARD',

        onSpawn = function(ped)
            -- attach a blip or target zone when in range
        end,

        onDespawn = function(ped)
            -- clean up blip or target zone
        end,
    })
end)

AddEventHandler('module:stop', function()
    NPCs.unregister('mymodule:shopkeeper')
end)

How It Works

NPCs runs a background Citizen.CreateThread that checks player distance to all registered NPC coords each tick. When the player enters range, it requests the model, spawns the ped, and calls onSpawn. When the player leaves range, it calls onDespawn and deletes the entity. This is entirely client-side — NPCs registered this way are local to each player.

API Reference

Method	Description
NPCs.register(id, template)	Register an NPC definition for range-based spawning
NPCs.unregister(id)	Remove an NPC definition and despawn if currently spawned

Client-only

NPCs is a client-side global. It is not available in server scripts.

See Also

• Keybinds →
• Events →