Skip to content

Actor Configuration Options

enabled

  • boolean
  • Whether the actor is enabled by default in the options menu or not.
    -- Yes
    enabled = true
    -- No
    enabled = false
    

class

  • string | table
  • NPC entity class. May be in the form of a string or a list of strings.
    -- string
    class = 'npc_citizen'
    -- table
    class = {
        'npc_citizen',
        'npc_metropolice'
    }
    

name

  • string
  • The name of the actor, which is displayed in the options menu.
    -- string
    name = 'Amogus'
    

fullness

  • number
  • Percentage filling from 0 to 100. Used when changing the slider for the total number of NPCs on the map.
    -- number
    -- If the npc limit is 30, then it will be 50% of the number 30.
    fullness = 50
    

limit

  • number
  • Sets a fixed number of NPCs to spawn by default. Attention: this parameter is not compatible with "fullness". But you can still change this slider individually.
    -- number
    -- When changing the slider for the total number of NPCs, the limit will always be at a value of - 5.
    limit = 5
    

team

  • table
  • Team to which the actor belongs. Default teams: residents, police, bandits, zombies.
    -- table
    -- is in the team of citizens
    team = { 'residents' }
    -- is a member of the citizen and police team
    team = { 'residents', 'police' }
    

weapons

  • table
  • A weapon that an actor can spawn with. The weapon is not in the hands, it is "in the pocket". NPC takes (spawns) weapons if necessary.
    -- table
    weapons = { 'weapon_pistol' }
    weapons = { 'weapon_pistol', 'weapon_shotgun' }
    

getting_weapon_chance

  • boolean | number
  • The chance at which an NPC can get a weapon. If set to "false", the NPC will always take weapons.
    -- number
    -- 20% chance to spawn with a weapon
    getting_weapon_chance = 20
    -- boolean
    -- always take a weapon
    getting_weapon_chance = false
    

money

  • table | number
  • How much money can an NPC throw away after death. Works if there are handlers and mods for money. You can specify a fixed or random amount.
    -- number
    -- Always throw away "30" money upon death.
    money = 30
    -- table
    -- Throw away a random amount of money from "1" to "20". If 0 falls out, then nothing will come of it.
    money = { 0, 20 }
    

health

  • table | number
  • How much health the npc can spawn with. You can specify a fixed or random number.
    -- number
    -- The NPC spawns with "50" health each time.
    health = 50
    -- table
    -- The NPC spawns with a random amount of health from "30" to "100".
    health = { 30, 100 }
    

weapon_skill

  • number | enum
  • Sets weapon proficiency (Read More). Works for NextBot actors too (it scales their spread). An actor that was spawned without a weapon and picked one up always shoots with WEAPON_PROFICIENCY_POOR.
    -- number / enum
    weapon_skill = WEAPON_PROFICIENCY_POOR
    

replics

  • table
  • Sets the lines to be spoken by NPCs in different states: now and then an actor in that state (state_names) or state group (state_groups) says a random phrase of the table bgNPC.cfg.replics[id] (text and voice, see Voices).
    replics = {
        state_groups = { ['calm'] = 'calm' },
        state_names = { ['fear'] = 'fear', ['run_from_danger'] = 'fear' },
    }
    

max_vehicle

  • number
  • Sets the maximum number of vehicles to spawn.
    -- number
    -- Spawn a maximum of 2 cars for a given actor type.
    max_vehicle = 2
    

vehicle_multiply_speed

  • table
  • Speed multiplier by state group.
    vehicle_multiply_speed = { danger = 4 }
    

enter_to_exist_vehicle_chance

  • number
  • Chance for an existing or new actor to get into a transport on the map, instead of being removed or teleported.
    -- number
    -- 10% chance to board an existing vehicle on the map.
    enter_to_exist_vehicle_chance = 10
    

vehicles_strict_color_chance

  • number
  • Works if random colors (vehicles_random_color) are enabled. Sets limits on bright colors, making them less toxic.
    -- number
    -- 25% chance of setting a strict color.
    vehicles_strict_color_chance = 25
    

vehicles_random_color

  • boolean
  • Enable color randomization for vehicles.
    -- boolean
    -- Turn on random colors.
    vehicles_random_color = true
    -- boolean
    -- Turn off random colors.
    vehicles_random_color = false
    

vehicles_random_skin

  • boolean
  • Switch of random skins for vehicles.
    -- boolean
    -- Enable random skins.
    vehicles_random_skin = true
    -- boolean
    -- Disable random skins.
    vehicles_random_skin = false
    

vehicles_random_bodygroups

  • boolean
  • Random bodygroup switcher for vehicles.
    -- boolean
    -- Enable random bodygroups.
    vehicles_random_bodygroups = true
    -- boolean
    -- Disable random bodygroups.
    vehicles_random_bodygroups = false
    

vehicle_group

  • string
  • Sets the primary group for this actor's car.
    -- string
    -- Allows only actors from the police group to get into the car
    vehicle_group = 'police'
    

vehicles

  • table
  • A list of cars that can be created for this actor. All major vehicle bases must be supported. If there are problems with any base - let me know.
    -- table
    -- Sets the actor's vehicles list
    vehicles = {
        'sim_fphys_pwavia',
        'sim_fphys_pwgaz52',
        'sim_fphys_pwhatchback',
    }
    

Legacy range fields

at_random_range, at_damage_range and at_protect_range are obsolete and unused. State selection uses relative weights from the corresponding tables; they need not sum to 100.

at_random

  • table
  • Actions that the actor will perform after a random period of time.
    -- 50% chance to walk, 50% chance to rest
    at_random = {
        ['walk'] = 50,
        ['idle'] = 50,
    }
    

at_damage

  • table
  • Actions that the actor will take if he is attacked.

at_protect

  • table
  • Actions an actor will take if his ally is attacked.

respawn_delay

  • number
  • Set the spawn delay in seconds from the moment the actor dies. Each death of the type queues one delayed spawn, so several deaths come back one per delay. Inherited through inherit; a child turns it off with 0 (not false).
    -- The actor will spawn 5 seconds after death if the global spawn delay is less than this limit.
    respawn_delay = 5
    

wanted_level

  • number
  • Relevant only in the case of an active module on the "Wanted System". Set the level at which NPCs can spawn (1 to 5)
    -- Compare actors only if wanted level - 3
    wanted_level = 3
    

disable_states

  • boolean
  • Possibility to turn off Background NPCs state logic. This allows you to spawn NPCs on the map, but not change their original behavior.
    -- NPCs will not use the state system of their Background NPCs
    disable_states = true
    

validator

  • function
  • Checks the validity of the data before creating the actor. Can cancel the creation of the actor if it returns "false".
    -- @self - config data
    -- @npc_type - actor type/id
    validator = function(self, npc_type)
        -- Cancels the creation of an actor if its class is not in the list of NPCs.
        if list.Get('NPC')[self.class] == nil then
            return false
        end
    end,
    

inherit

  • string
  • Inherits data from another actor. Useful if you don't want to overwrite the same parameters all the time.
    -- For example, this is our main actor.
    bgNPC.cfg:SetActor('actor_1', {
        enabled = true,
        name = 'Actor 1',
        class = 'npc_citizen',
        fullness = 64,
        team = { 'residents' },
        health = 1000,
        at_random = {
            ['walk'] = 50,
            ['idle'] = 50,
        },
        at_damage = { ['defense'] = 100 },
        at_protect = { ['defense'] = 100 }
    })
    
    -- This actor uses the "inherit" parameter to borrow the missing parameters it takes from "actor_1"
    bgNPC.cfg:SetActor('actor_2', {
        enabled = true,
        name = 'Actor 2',
        inherit = 'actor_1',
        team = { 'bandits' },
        at_protect = { ['fear'] = 100 },
    })
    
    -- This actor uses the "inherit" parameter to borrow missing parameters, which it takes from "actor_2", which previously borrowed data from "actor_1".
    -- But there is also a team parameter where we explicitly specify from which actor we want to borrow data.
    -- The "@" sign is used to indicate the actor from which we want to borrow a similar field.
    bgNPC.cfg:SetActor('actor_3', {
        enabled = true,
        name = 'Actor 3',
        inherit = 'actor_2',
        team = '@actor_1',
        at_damage = { ['fear'] = 100 },
        at_protect = { ['fear'] = 100 }
    })
    

random_skin

  • boolean
  • Enables an option for NPCs to spawn with random skins.
    -- Enable random skins
    random_skin = true
    -- Disable random skins
    random_skin = false
    

random_bodygroups

  • boolean
  • Enables an option for NPCs to spawn with random bodygroups.
    -- Enable random bodygroups
    random_bodygroups = true
    -- Disable random bodygroups
    random_bodygroups = false
    

default_models

  • boolean
  • Enables or disables the use of standard NPC models. Useful if you use custom models.
    -- Enable default models
    default_models = true
    -- Disable default models
    default_models = false
    

models

  • table
  • Sets a list of custom npc models.
    models = {
        'models/smalls_civilians/pack1/hoodie_male_01_f_npc.mdl',
        'models/smalls_civilians/pack1/hoodie_male_02_f_npc.mdl',
        'models/smalls_civilians/pack1/zipper_female_01_f_npc.mdl',
        'models/smalls_civilians/pack1/zipper_female_02_f_npc.mdl',
    }
    

relationship

  • table
  • Set values for relations that will be applied to the actor after spawning (Read More).
    relationship = {
        ['@player'] = D_HT, -- Hate the players
        ['@actor'] = D_HT,  -- Hate other actors
        ['@team'] = D_LI,   -- Befriend team members
        ['@npc'] = D_NU,    -- Be neutral towards other NPCs
    }
    

bsmod_damage_animation_disable

  • boolean
  • Compatibility with BSmod addon. Prevents the addon from using animations on actors.
    -- Disable animations
    bsmod_damage_animation_disable = true
    -- Enable animations
    bsmod_damage_animation_disable = false
    

Current behavior and gang fields

Configs resolve through bgNPC.Config.GetActor, are cached and copied into each actor. New values do not change existing actors. Vehicle/brain behavior runs on the server; type definitions should exist in both realms.

Field Value Purpose
brain fsm / goap Brain under bgn_brain=auto; a forced cvar takes precedence.
carry_items false / table { chance = 5, items = { 'ration', 'suitcase', 'newspaper' }, drop_lifetime = 30 }: rare items on unarmed actors; enables a per-type checkbox. See carry rules.
goap_set police / gangster / citizen GOAP goal set; otherwise derived from teams.
gang string Gang identity for alliance, visible-ally support and pack walking.
heavy_chance 35 Heavy member percentage for built-in gangs.
light_weapons table Light member weapon classes.
heavy_weapons table Heavy member weapon classes.
mechanics table Per-actor subsystem flags; see below.

Built-in mechanics flags default to true: movement_controller, use_vehicle, call_for_help, fear, fear_scream, enemies_controller, targets_controller, states_controller, animator_controller, enhanced_npc_ignore, inpc_ignore.

An explicit boolean false disables that mechanic; missing/non-boolean values use its default. For inpc_ignore = false, the core does not set the iNPC ignore flag during creation. Existing actors keep their copies. With regeneration = true, regeneration_time sets the interval (default 1 second) and regeneration_max_health sets the ceiling (default entity max health). Regeneration adds one HP per interval and never reduces health that already exceeds the ceiling.

Combat support, cvar defaults and models: gangs. Sources: actor/sh_actor.lua, config/actors/sh_gangs.lua, brain/sv_brain.lua.