Npc

Easy to create Non-Player-Character (NPC) for your REDM resource.

Example

------------------------------------------------------------------------------
-- Step 1: Get API
------------------------------------------------------------------------------

---@type NssLibsNpcApi
local npc_api = exports.nss_libs:getNpcApi(GetCurrentResourceName())

------------------------------------------------------------------------------
-- Step 2: Create NPC object
------------------------------------------------------------------------------

local model_name = 'S_M_M_NBXRIVERBOATDEALERS_01'
local outfit = 0 -- nil/false = random outfit
local x = 0
local y = 0
local z = 0
local heading = 180

---@type NssLibsNpcEntityApi
local npc = npc_api.create(model_name, x, y, z, heading, outfit)

------------------------------------------------------------------------------
-- Step 3: Configure NPC object
------------------------------------------------------------------------------

npc.setScale(1)
   .setScenario('WORLD_HUMAN_WRITE_NOTEBOOK')
   .setWeapon('weapon_shotgun_semiauto')
   .addAnimation(
        'amb_camp@prop_camp_butcher@resting@rabbit@male_a@idle_a',
        'idle_c',
        10000, -- delay/duration until next animation
        true, -- looping
        1, -- times to play
        npc.ANIMATE_ONLY_UPPER_BODY) -- animate only upper body
   .addAnimation(
        'amb_camp@prop_camp_butcher@resting@rabbit@male_a@idle_a',
        'idle_b',
        3000, -- delay/duration until next animation
        false, -- no looping
        3, -- play 3 times with a delay of 3000ms
        npc.ANIMATE_FULL_BODY) -- animate full body
   .addTimeWindow(8, 0, 12, 0) -- visible from 8:00 to 12:00 in-game-time
   .addTimeWindow(14, 0, 20, 0) -- visible from 14:00 to 20:00 in-game-time

------------------------------------------------------------------------------
-- Step 4: Show NPC
------------------------------------------------------------------------------

-- With performance mode to prevent too much entities
local spawn_radius = 20 -- in meters
npc.startRangeCheck(spawn_radius)

-- Without performance mode
npc.show()

---

Methods

exports.nss_libs:getNpcApi(resource_name)

Param	Type	Default	Description
resource_name	string	—	The name of the resource that wants to use the API

Returns NssLibsNpcApi — the NPC api for the given resource

---

NssLibsNpcApi

.create(model, x, y, z, heading, outfit?)

Param	Type	Default	Description
model	string	—	The model of the NPC entity
x	number	—	The x position of the NPC entity
y	number	—	The y position of the NPC entity
z	number	—	The z position of the NPC entity
heading	number	—	The heading of the NPC entity
outfit	number?	—	The outfit of the NPC entity. If nil or false, a random outfit will be used

Returns NssLibsNpcEntityApi — the NPC entity api

---

exports.nss_libs:getNpcConfigApi(resource_name)

Param	Type	Default	Description
resource_name	string	—	The name of the resource that wants to use the API

Returns NssLibsNpcConfigApi — the NPC config api for creating NPCs from definition tables

---

NssLibsNpcConfigApi

.createFromConfig(definition)

Creates a fully configured NPC from a single definition table. This includes the NPC entity itself, optional blips, prompts, animations, time windows, weapons, scenarios and the range check. No need to manually wire up multiple APIs.

Param	Type	Default	Description
definition	NssLibsNpcDefinition	—	The NPC definition table (see below)

Returns NssLibsNpcEntityApi|nil — the NPC entity api, or nil if validation fails

Definition Structure

Property	Type	Required	Default	Description
id	string	yes	—	Unique identifier for the NPC
name	string	yes	—	Display name of the NPC
coords	table	yes	—	Position: { x, y, z, heading }
look	table	yes	—	Appearance: { model, outfit?, scale? }
prevent_place_on_ground	boolean	no	false	Disable ground placement (for custom interiors)
weapon	string	no	—	Weapon to equip
scenario	string	no	—	Scenario to play
spawn_radius_in_meters	number	no	100	Distance at which the NPC spawns
animations	table[]	no	—	Array of animation definitions
time_windows	table[]	no	—	Array of time window definitions
blip	table	no	—	Blip configuration
prompts	table[]	no	—	Array of prompt page definitions

Minimal Example

---@type NssLibsNpcConfigApi
local npc_config = exports.nss_libs:getNpcConfigApi(GetCurrentResourceName())

local npc = npc_config.createFromConfig({
    id = 'my_blacksmith',
    name = 'Blacksmith',
    coords = { x = -700.0, y = -1291.0, z = 43.0, heading = 180.0 },
    look = { model = 'S_M_M_NBXRIVERBOATDEALERS_01' },
})

Full Example

---@type NssLibsNpcConfigApi
local npc_config = exports.nss_libs:getNpcConfigApi(GetCurrentResourceName())

local npc = npc_config.createFromConfig({
    id = 'my_butcher',
    name = 'Butcher',
    coords = { x = -700.0, y = -1291.0, z = 43.0, heading = 180.0 },
    look = {
        model = 'A_M_M_UniCorpse_01',
        outfit = 0,     -- nil = random outfit
        scale = 1.0,
    },
    prevent_place_on_ground = false,
    weapon = 'WEAPON_REVOLVER_CATTLEMAN',
    scenario = 'WORLD_HUMAN_WRITE_NOTEBOOK',
    spawn_radius_in_meters = 80,
    animations = {
        {
            anim_dict = 'amb_camp@prop_camp_butcher@resting@rabbit@male_a@idle_a',
            anim_name = 'idle_c',
            delay_in_ms = 10000,
            loop = true,
            times = 1,
            anim_only_upper_body = false,
        },
    },
    time_windows = {
        { start_hour = 8, start_minute = 0, end_hour = 12, end_minute = 0 },
        { start_hour = 14, start_minute = 0, end_hour = 20, end_minute = 0 },
    },
    blip = {
        icon = 'blip_shop_butcher',
        default_color = 'BLIP_MODIFIER_MP_COLOR_32',
        time_window_color = 'BLIP_MODIFIER_MP_COLOR_1',  -- optional: changes color in time window
        scale = 0.2,
        title = 'Butcher',
        modifiers = { 'BLIP_MODIFIER_MP_COLOR_32' },      -- optional
    },
    prompts = {
        {
            page_label = 'Butcher',
            page_radius_in_meters = 2,
            page_prompts = {
                {
                    prompt_label = 'Trade',
                    prompt_key = 0x760A9C6F,
                    prompt_type = 'just_pressed',
                    prompt_callback = function(entity, npc_id, npc_name)
                        print('Trading with ' .. npc_name)
                    end,
                },
                {
                    prompt_label = 'Talk',
                    prompt_key = 0xDEB34313,
                    prompt_type = 'standard_hold_prompt',
                    prompt_callback = function(entity, npc_id, npc_name)
                        print('Talking to ' .. npc_name)
                    end,
                    prompt_release_callback = function(entity, npc_id, npc_name)
                        print('Stopped talking to ' .. npc_name)
                    end,
                },
            },
        },
    },
})

-- The returned npc can still be used for further chaining
npc.onShow(function()
    print('NPC is now visible')
end)

Available Prompt Types

Type	Description
just_pressed	Fires once when key is pressed
pressed	Fires continuously while key is held
just_released	Fires once when key is released
released	Fires continuously while key is released
standard_hold_prompt	RedM hold prompt style
standardized_hold_prompt	Alternative hold prompt style

---

NssLibsNpcEntityApi

.getEntity()

Returns the NPC entity or nil if the entity is not created.

Returns number|nil — the entity handle

---

.destroy()

Removes the NPC entity and all related distance checks.

---

.show()

Shows the NPC entity.

Returns NssLibsNpcEntityApi — chainable

---

.hide()

Hides the NPC entity.

Returns NssLibsNpcEntityApi — chainable

---

.setCoords(x, y, z, heading)

Sets the coordinates of the NPC entity.

Param	Type	Default	Description
x	number	—	The x position of the NPC entity
y	number	—	The y position of the NPC entity
z	number	—	The z position of the NPC entity
heading	number	—	The heading of the NPC entity

Returns NssLibsNpcEntityApi — chainable

---

.setModel(model, outfit?)

Sets the model of the NPC entity.

Param	Type	Default	Description
model	string	—	The model of the NPC entity
outfit	number?	—	The outfit of the NPC entity. If nil or false, a random outfit will be used

See model documentation for a list of models.

Returns NssLibsNpcEntityApi — chainable

---

.setOutfit(outfit)

Sets the outfit of the NPC entity.

Param	Type	Default	Description
outfit	number?	—	The outfit of the NPC entity. If nil or false, a random outfit will be used

Returns NssLibsNpcEntityApi — chainable

---

.setSpawnRadius(radius)

Sets the spawn radius of the NPC entity.

Param	Type	Default	Description
radius	number	—	The spawn radius of the NPC entity

Returns NssLibsNpcEntityApi — chainable

---

.setScale(scale)

Sets the scale of the NPC entity.

Param	Type	Default	Description
scale	number	—	The scale of the NPC entity

Returns NssLibsNpcEntityApi — chainable

---

.setScenario(scenario)

Sets the scenario of the NPC entity.

Param	Type	Default	Description
scenario	string	—	The scenario of the NPC entity

See scenario documentation for a list of scenarios.

Returns NssLibsNpcEntityApi — chainable

---

.setWeapon(weapon)

Sets the weapon of the NPC entity.

Param	Type	Default	Description
weapon	string	—	The weapon of the NPC entity

See weapons documentation for a list of weapons.

Returns NssLibsNpcEntityApi — chainable

---

.resetAnimations()

Resets the animations of the NPC entity.

Returns NssLibsNpcEntityApi — chainable

---

.addAnimation(anim_dict, anim_name, delay_in_ms, loop, times, only_upper_body)

Sets the animation of the NPC entity.

Param	Type	Default	Description
anim_dict	string	—	The animation dictionary
anim_name	string	—	The animation name
delay_in_ms	number	—	The delay until next animation
loop	boolean	—	If true, the animation will be looped
times	number	—	The number of times the animation will be played
only_upper_body	boolean	—	If true, only the upper body will be animated

See the following links for a list of animations:

• mega dict animations
• ingame animations

Returns NssLibsNpcEntityApi — chainable

---

.addTimeWindow(start_hour, start_minute, end_hour, end_minute)

Adds a time window to the NPC entity. If the time is in the given time window, the NPC entity will be shown.

Param	Type	Default	Description
start_hour	number	—	The start hour of the time window
start_minute	number	—	The start minute of the time window
end_hour	number	—	The end hour of the time window
end_minute	number	—	The end minute of the time window

Returns NssLibsNpcEntityApi — chainable

---

.startRangeCheck(radius?)

Starts a range check for the NPC entity. If the player enters the given radius, the NPC entity will be shown. If the player leaves the given radius, the NPC entity will be hidden.

Param	Type	Default	Description
radius	number?	—	The radius in meters. If not set default radius will be used

Returns NssLibsNpcEntityApi — chainable

---

.update()

Updates the NPC entity (destroys and recreate it).

Returns NssLibsNpcEntityApi — chainable

---

.hasTimeWindows()

Returns boolean — true if the NPC entity has at least one time window

---

.isInTimeWindow()

Returns boolean — true if the NPC entity is in a time window or has no time windows

---

.onShow(callback)

Sets the callback function which will be called when the NPC entity is shown.

Param	Type	Default	Description
callback	function	—	The callback function

Returns NssLibsNpcEntityApi — chainable

---

.onHide(callback)

Sets the callback function which will be called when the NPC entity is hidden.

Param	Type	Default	Description
callback	function	—	The callback function

Returns NssLibsNpcEntityApi — chainable

---

.onEnterTimeWindow(callback)

Sets the callback function which will be called when the NPC entity enters a time window.

Param	Type	Default	Description
callback	function	—	The callback function

Returns NssLibsNpcEntityApi — chainable

---

.onLeaveTimeWindow(callback)

Sets the callback function which will be called when the NPC entity leaves a time window.

Param	Type	Default	Description
callback	function	—	The callback function

Returns NssLibsNpcEntityApi — chainable

---

.disablePlaceOnGround()

Disables the place on ground feature of the NPC entity.

TIP

Useful if your NPC stuck in the ground after spawning (most case in custom buildings).

Returns NssLibsNpcEntityApi — chainable

---

.enablePlaceOnGround()

Enables the place on ground feature of the NPC entity. This is the default behavior.

Returns NssLibsNpcEntityApi — chainable

---