Skip to content

Server API

Run gameplay changes on SERVER. Many methods are declared in sh_ files for compatibility but depend on a server body, brain, provider or gameplay module.

bgNPC.Actor.New(...) is the unchecked class constructor; extensions should use bgNPC.Actor.Create(...). actor:StopStaticSequence() is an alias of ResetSequence().

Actor

bgNPC.Combat.ResolveVehicleAttacker(attacker, inflictor) resolves a valid siege payload owner from the attacker, falling back to the optional inflictor, then resolves a driven vehicle to its driver. Without a valid owner or vehicle conversion it returns the supplied attacker; an engine IsVehicle() entity without a valid driver returns nil. Existing one-argument calls remain valid. Damage handlers pass both entities before team/protection checks. Source: api/sv_combat.lua.

ShareEnemyMemory

actor:ShareEnemyMemory(source, enemy) copies another actor's observed position and original timestamp only when this actor already knows the enemy, the source memory is at most 60 seconds old and this actor has no newer known position. Returns whether it copied memory. Does not add enemies or change reactions. Source: actor/components/sh_enemies.lua.

bgNPC.Combat.IsInCombatRadius(actor) returns whether a living combat actor has any living known enemy within a fixed 1000 units (inclusive); this is independent of observer cameras. Source: api/sv_combat.lua.

AddEnemy

actor:AddEnemy(ent, reaction, always_visible)

Adds an entity enemy with optional reaction and always_visible flag; hooks, team rules may reject it.

Source: lua/background_npcs_core/actor/components/sh_enemies.lua.

Method page.

AddTarget

actor:AddTarget(ent)

Adds a valid entity target unless already present; requires targets_controller.

Source: lua/background_npcs_core/actor/components/sh_targets.lua.

Method page.

AddTeam

actor:AddTeam(team_name)

Adds a non-empty team name without duplicates, applying the same enemy/wanted/arrest reconciliation as SetTeam.

Source: lua/background_npcs_core/actor/components/sh_team.lua.

AvoidDVVehicle

actor:AvoidDVVehicle(goal)

Internal pedestrian detour update; returns whether avoidance is active.

Source: lua/background_npcs_core/actor/components/sh_movement.lua.

CallForHelp

actor:CallForHelp(enemy)

Asks living teammates within 1000 units who have LOS to the caller to react to the enemy. Seeing the enemy is not required; FOV is not checked. The caller needs call_for_help, a valid enemy and positive health. BGN_PreCallForHelp can cancel; arrest protection, enemy restrictions and protection cooldown still apply.

Source: lua/background_npcs_core/actor/components/sh_combat.lua.

Method page.

CallStateAction

actor:CallStateAction(state_name, func_name, ...)

Calls a registered callback with this actor and extra arguments; nil state_name uses the current state.

Source: lua/background_npcs_core/actor/components/sh_state.lua.

Method page.

CheckMoveUpdate

actor:CheckMoveUpdate(tag, time)

Per-tag throttle; first call returns false, later calls return true once the requested interval expires.

Source: lua/background_npcs_core/actor/components/sh_movement.lua.

ClearSchedule

actor:ClearSchedule()

Legacy body-specific schedule API; prefer WalkToPos/StopWalk.

Source: lua/background_npcs_core/actor/components/sh_movement.lua.

Method page.

Create

bgNPC.Actor.Create(npc, npc_type, custom_uid, not_sync_actor_on_client, not_auto_added_to_list)

Creates and registers an actor; returns the actor or nil for an invalid entity. Prefer bgNPC.Actor.Create(npc, npc_type); Create validates the entity and actor type before invoking the class constructor. Optional arguments: custom_uid, not_sync_actor_on_client, not_auto_added_to_list. Do not bind an entity twice.

Source: lua/background_npcs_core/actor/sh_actor.lua.

CreateFakePlayerMethodsForNPC

actor:CreateFakePlayerMethodsForNPC()

Internal compatibility adapter for NPCs; not an actor creation API.

Source: lua/background_npcs_core/actor/components/sh_combat.lua.

DropToFloor

actor:DropToFloor()

Delegates floor placement to the body or valid entity.

Source: lua/background_npcs_core/actor/sh_actor.lua.

EnemiesRecalculate

actor:EnemiesRecalculate()

Updates counts, drops dead/forgotten enemies and assigns the nearest to the body; requires a valid body.

Source: lua/background_npcs_core/actor/components/sh_enemies.lua.

Method page.

EnterVehicle

actor:EnterVehicle(vehicle, animate)

Accepts a valid vehicle entity (chassis); resolves or creates its BGN provider internally. Boarding is checked again after 0.5 seconds; no synchronous success result. With animate the actor stops and turns to the car first (no animation); the method returns the delay in seconds. Actor/UID persist, entity changes. Requires DV support and provider access.

Source: lua/background_npcs_core/actor/components/sh_vehicle.lua.

Method page.

ExitVehicle

actor:ExitVehicle(forced)

Returns true on a completed exit. A blocked exit retains the seat. Recreates the saved NPC/NextBot body.

Source: lua/background_npcs_core/actor/components/sh_vehicle.lua.

Method page.

Fear

actor:Fear()

Runs the fear mechanic only when enabled.

Source: lua/background_npcs_core/actor/components/sh_combat.lua.

FearScream

actor:FearScream()

Emits the configured fear voice when allowed.

Source: lua/background_npcs_core/actor/components/sh_combat.lua.

Method page.

FoldWeapon

actor:FoldWeapon()

Removes the active weapon unless disable_fold_weapon is set.

Source: lua/background_npcs_core/actor/components/sh_combat.lua.

Method page.

GetActorWeapon

actor:GetActorWeapon()

Returns the assigned weapon class, not a weapon entity. That assignment is not part of the regular client snapshot.

Source: lua/background_npcs_core/actor/components/sh_combat.lua.

Method page.

GetBody

actor:GetBody()

Returns the server body adapter or nil. It is replaced across boarding/exiting.

Source: lua/background_npcs_core/actor/sh_actor.lua.

GetBrain

actor:GetBrain()

Returns the server brain or nil.

Source: lua/background_npcs_core/actor/sh_actor.lua.

GetClosestPointInRadius

actor:GetClosestPointInRadius(radius)

Returns the nearest navigation point around this actor, or nil.

Source: lua/background_npcs_core/actor/components/sh_movement.lua.

Method page.

GetClosestPointToPoint

actor:GetClosestPointToPoint(pos, radius)

Returns a navigation point in radius closest to pos, or nil.

Source: lua/background_npcs_core/actor/components/sh_movement.lua.

Method page.

GetDistantPointInRadius

actor:GetDistantPointInRadius(radius)

Returns the farthest navigation point around this actor, or nil.

Source: lua/background_npcs_core/actor/components/sh_movement.lua.

Method page.

GetDistantPointToPoint

actor:GetDistantPointToPoint(pos, radius)

Returns a navigation point in radius farthest from pos, or nil.

Source: lua/background_npcs_core/actor/components/sh_movement.lua.

Method page.

GetRandomState

actor:GetRandomState()

Returns a weighted at_random state name or none for empty/zero weights.

Source: lua/background_npcs_core/actor/components/sh_state.lua.

Method page.

GetReactionForDamage

actor:GetReactionForDamage(enemy)

Chooses a damage reaction through the brain or weighted at_damage; wanted actors retreat instead of defense.

Source: lua/background_npcs_core/actor/components/sh_state.lua.

Method page.

GetReactionForProtect

actor:GetReactionForProtect(enemy)

Chooses at_protect reaction with cooldown and civilian participation checks.

Source: lua/background_npcs_core/actor/components/sh_state.lua.

Method page.

GetVehicle

actor:GetVehicle()

Returns the chassis or nil. Requires the server vehicle provider; use InVehicle for a client occupancy check.

Source: lua/background_npcs_core/actor/components/sh_vehicle.lua.

Method page.

GetVehicleAI

actor:GetVehicleAI()

Returns the DV controller or nil; requires the server provider.

Source: lua/background_npcs_core/actor/components/sh_vehicle.lua.

Method page.

GetVehicleGroup

actor:GetVehicleGroup()

Returns the first configured group, or police/taxi/residents fallback.

Source: lua/background_npcs_core/actor/components/sh_vehicle.lua.

GetWalkPos

actor:GetWalkPos()

Returns the current position goal or nil.

Source: lua/background_npcs_core/actor/components/sh_movement.lua.

GetWalkTarget

actor:GetWalkTarget()

Returns the followed entity (possibly NULL).

Source: lua/background_npcs_core/actor/components/sh_movement.lua.

GiveWeapon

actor:GiveWeapon(weapon_class)

Changes the assigned weapon class; does not equip it immediately. nil clears the assignment.

Source: lua/background_npcs_core/actor/components/sh_combat.lua.

Init

actor:Init(npc, npc_type, custom_uid, not_sync_actor_on_client, not_auto_added_to_list)

Internal constructor used by the class system. Use bgNPC.Actor.Create instead.

Source: lua/background_npcs_core/actor/sh_actor.lua.

IsCivilian

actor:IsCivilian()

Returns true for residents that are not police.

Source: lua/background_npcs_core/actor/components/sh_state.lua.

IsExecutingCombatSchedule

actor:IsExecutingCombatSchedule()

Checks whether the server body is busy shooting/reloading.

Source: lua/background_npcs_core/actor/components/sh_movement.lua.

IsSequenceFinished

actor:IsSequenceFinished()

Checks animation completion, respecting loop duration.

Source: lua/background_npcs_core/actor/components/sh_animation.lua.

Method page.

IsSequenceLoopFinished

actor:IsSequenceLoopFinished()

Checks the loop deadline; an unlimited active loop is not finished.

Source: lua/background_npcs_core/actor/components/sh_animation.lua.

Method page.

IsStateDelay

actor:IsStateDelay()

Checks local state_delay; this deadline is not in the regular client snapshot. Use on the server.

Source: lua/background_npcs_core/actor/components/sh_state.lua.

Method page.

IsStayingOut

actor:IsStayingOut()

Checks the stay-out deadline.

Source: lua/background_npcs_core/actor/components/sh_state.lua.

IsWanted

actor:IsWanted()

Queries the server wanted module for the current entity.

Source: lua/background_npcs_core/actor/components/sh_state.lua.

PlayNextStaticSequence

actor:PlayNextStaticSequence()

Consumes the queued animation; returns whether it started processing it.

Source: lua/background_npcs_core/actor/components/sh_animation.lua.

Method page.

PlayStaticSequence

actor:PlayStaticSequence(sequence_name, loop, loop_time, action)

Returns boolean; loop_time nil or 0 loops indefinitely. Requires a body and supported sequence. An action callback returning true can reject stopping.

Source: lua/background_npcs_core/actor/components/sh_animation.lua.

Method page.

PoliceFights

actor:PoliceFights(enemy)

Checks whether nearby police already fight enemy for civilian participation rules.

Source: lua/background_npcs_core/actor/components/sh_state.lua.

PrepareWeapon

actor:PrepareWeapon(weapon_class, switching)

Equips/selects weapon_class or the assigned weapon through bgNPC.Combat.EquipActor.

Source: lua/background_npcs_core/actor/components/sh_combat.lua.

Method page.

RandomState

actor:RandomState()

Chooses and applies a weighted at_random state unless PreRandomState cancels; returns the resulting state name.

Source: lua/background_npcs_core/actor/components/sh_state.lua.

Method page.

RecalculationTargets

actor:RecalculationTargets()

Removes invalid target entries. This is the implemented name; TargetsRecalculate is not defined.

Source: lua/background_npcs_core/actor/components/sh_targets.lua.

Method page.

Remove

actor:Remove()

Unregisters the actor and removes its current entity.

Source: lua/background_npcs_core/actor/sh_actor.lua.

RemoveActor

actor:RemoveActor()

Unregisters once, stops the brain and releases its vehicle provider. Does not itself remove the entity.

Source: lua/background_npcs_core/actor/sh_actor.lua.

RemoveAllEnemies

actor:RemoveAllEnemies()

Calls enemy removal hooks, then clears remaining enemy storage.

Source: lua/background_npcs_core/actor/components/sh_enemies.lua.

Method page.

RemoveAllTargets

actor:RemoveAllTargets()

Calls target removal hooks, then forcibly clears any remaining targets.

Source: lua/background_npcs_core/actor/components/sh_targets.lua.

Method page.

RemoveEnemy

actor:RemoveEnemy(ent, index)

Removes by entity or index (index takes priority); hooks can reject removal. Returns remaining count.

Source: lua/background_npcs_core/actor/components/sh_enemies.lua.

Method page.

RemoveTarget

actor:RemoveTarget(ent, index)

Removes a target by entity or index (index takes priority); returns the remaining count.

Source: lua/background_npcs_core/actor/components/sh_targets.lua.

Method page.

ResetSequence

actor:ResetSequence()

Stops static animation unless the callback rejects it or chains another animation.

Source: lua/background_npcs_core/actor/components/sh_animation.lua.

Method page.

ResetStateDelay

actor:ResetStateDelay()

Clears the state-transition deadline.

Source: lua/background_npcs_core/actor/components/sh_state.lua.

Method page.

Say

actor:Say(say_text, say_time, voice_sound, animation_sequence)

Broadcasts text (default 5 seconds), optionally emits a sound and plays an animation.

Source: lua/background_npcs_core/actor/components/sh_speech.lua.

Method page.

SayReplic

actor:SayReplic(replic_id, replic_index, say_time, voice_sound, animation_sequence)

Broadcasts a phrase ID/index for client localization; missing phrases are ignored.

Source: lua/background_npcs_core/actor/components/sh_speech.lua.

SetGender

actor:SetGender(gender_name)

Sets the actor gender string. Regular server sync propagates it.

Source: lua/background_npcs_core/actor/sh_actor.lua.

Method page.

SetName

actor:SetName(name)

Sets the actor name string; nil leaves it unchanged. Regular server sync propagates it.

Source: lua/background_npcs_core/actor/sh_actor.lua.

Method page.

SetNextSequence

actor:SetNextSequence(sequence_name, loop, loop_time, action)

Queues one sequence with loop settings and optional callback.

Source: lua/background_npcs_core/actor/components/sh_animation.lua.

Method page.

SetReaction

actor:SetReaction(reaction)

Stores a reaction string or nil; does not execute it.

Source: lua/background_npcs_core/actor/components/sh_state.lua.

Method page.

SetSchedule

actor:SetSchedule(schedule)

Legacy numeric engine schedule API; NextBots map only supported schedules.

Source: lua/background_npcs_core/actor/components/sh_movement.lua.

Method page.

SetState

actor:SetState(state, data, forced)

Returns the new {state, data} table or nil when rejected. state=nil means none. forced bypasses normal locks/delays/validator, but mechanics/alive checks and pre-hooks can still reject the transition.

Source: lua/background_npcs_core/actor/components/sh_state.lua.

Method page.

SetStateDelay

actor:SetStateDelay(time)

Blocks ordinary state transitions for time seconds from CurTime().

Source: lua/background_npcs_core/actor/components/sh_state.lua.

Method page.

SetTeam

actor:SetTeam(team_data)

Replaces this actor’s team list; nil clears it. SERVER removes mutual enemy entries with new teammates and clears body targets. Joining residents removes wanted; sharing the primary officer’s team removes this actor’s arrest. Use this setter instead of editing data.team directly.

Source: lua/background_npcs_core/actor/components/sh_team.lua.

SetWalkType

actor:SetWalkType(move_type)

Accepts walk, run, a numeric schedule, or nil (walk).

Source: lua/background_npcs_core/actor/components/sh_movement.lua.

Method page.

ShouldExitVehicle

actor:ShouldExitVehicle()

Evaluates server dismount conditions; does not perform the exit.

Source: lua/background_npcs_core/actor/components/sh_vehicle.lua.

StateLock

actor:StateLock(lock)

Sets the transition lock; nil/false unlocks.

Source: lua/background_npcs_core/actor/components/sh_state.lua.

Method page.

StayOutOfFight

actor:StayOutOfFight(time)

Suppresses defense participation for time seconds (default 15) and resets the GOAP plan.

Source: lua/background_npcs_core/actor/components/sh_state.lua.

StopWalk

actor:StopWalk()

Clears goals, chase and DV detour, then resets walk type.

Source: lua/background_npcs_core/actor/components/sh_movement.lua.

Method page.

SyncFunction

actor:SyncFunction(name, ply, data)

Server-only compatibility sender: bgNPC.Net.Send(name, ply, self.uid, data). Receive with bgNPC.Net.Receive; SNet is no longer required.

Source: lua/background_npcs_core/actor/sh_actor.lua.

Method page.

TakeVehicleDamage

actor:TakeVehicleDamage(amount, attacker, inflictor)

Applies occupant damage through reaction hooks and stored character health; lethal damage emits death hooks and removes the actor.

Source: lua/background_npcs_core/actor/components/sh_vehicle.lua.

Think

actor:Think()

Legacy entry point; the normal actor update service owns brain updates. Do not add a duplicate Think loop.

Source: lua/background_npcs_core/actor/sh_actor.lua.

UpdateMovement

actor:UpdateMovement()

Internal scheduled path-following service; do not add a second update loop.

Source: lua/background_npcs_core/actor/components/sh_movement.lua.

Method page.

UpdateStateData

actor:UpdateStateData(data)

Replaces the current state data table; does not merge it.

Source: lua/background_npcs_core/actor/components/sh_state.lua.

Method page.

Voice

actor:Voice(voice_id, fallback)

Broadcasts a voice event; each client selects its own language/fallback. Combat/contact events are throttled per actor.

Source: lua/background_npcs_core/actor/components/sh_speech.lua.

VoiceSay

actor:VoiceSay(sound_path, sound_level, pitch_percent, volume, channel, sound_flags, dsp)

Emits an explicit sound on the current entity using EmitSound defaults.

Source: lua/background_npcs_core/actor/components/sh_speech.lua.

Method page.

WalkDestinationExists

actor:WalkDestinationExists()

Checks for a position or valid followed target.

Source: lua/background_npcs_core/actor/components/sh_movement.lua.

WalkToPos

actor:WalkToPos(pos, move_type, path_type)

Starts travel to a Vector or node:GetPos(); nil stops. Requires a navigable path. Finishing is reported through BGN_ActorFinishedWalk.

Source: lua/background_npcs_core/actor/components/sh_movement.lua.

Method page.

WalkToTarget

actor:WalkToTarget(target, move_type, path_type)

Follows an entity with periodic path rebuilds; nil/invalid target stops.

Source: lua/background_npcs_core/actor/components/sh_movement.lua.

Method page.

Walking

actor:Walking()

Reports body movement; body adapters only exist on the server.

Source: lua/background_npcs_core/actor/components/sh_movement.lua.

Method page.

Namespaces and services

API Contract / source
bgNPC:SpawnActor(npc_type, desiredPosition, enableSpawnEffect, require_hidden, owner) Creates an actor; owner is optional. When supplied, requires a valid living player (or admin), lets PlayerSpawnNPC veto the resolved NPC class before creation, sets creator and emits PlayerSpawnedNPC for gamemode counting. Menu/Tool pass their player; automatic population omits it. Check the result before use. Source: spawner/sv_spawner.lua.
bgNPC.Statistics.AddKill(attacker, actor) Adds and synchronizes a kill count.
bgNPC.Statistics.Reset(attacker), ResetAll() Clears and synchronizes statistics.
bgNPC.Actors.Rebind(actor, npc) Internal body replacement; updates registries/references and emits BGN_ActorEntityChanged. Use the normal vehicle lifecycle instead of calling directly.
bgNPC.Combat Weapon skill/equipment, fighting checks, resolving vehicle attackers and enemies: api/sv_combat.lua.
bgNPC.Nav Provider selection, loading and pathfinding: nav/sv_nav.lua; see navigation.
bgNPC.GOAP Planner actions/sensors: see brains.
bgNPC.Tasks Cooperative work with yield/wait/budget; core/sh_tasks.lua. Each realm has its own scheduler.

bgNPC.Combat.CanPoliceUseStunstick(officer, suspect) returns the SERVER baton eligibility from wanted status, kill evidence, that officer's witnessed harm and whether any of the officer's enemies has hit someone from farther than 500 units. bgNPC.Combat.ResetPoliceThreat(suspect) clears kill evidence/counters and officer harm records; use only for a completed reset, not initial wanted escalation. BGN_PostVehicleDamage(actor, attacker, amount) fires on SERVER after virtual seated health is updated, before death handling.

bgNPC.Combat.CanWitness(actor, attacker, check_view) checks a living observer, a valid attacker, distance up to 2500 and LOS to the attacker; actor attackers also require FOV. check_view = true requires FOV for any attacker. It returns a visibility boolean and may return the LOS hit entity as its second value. BGN_ConfirmedDamage(attacker, target, amount) fires on SERVER after positive actual damage, including seated health, after recording the initiator and evaluating existing-arrest harm limits; initial arrest and witnesses run from this notification. Consensual brawls and ignored attackers are excluded; friend mode keeps its existing player-side reaction override instead of dispatching this notification for player conflicts. BGN_PostReactionTakeDamage remains a pre-application reaction hook and does not prove actual damage. See conflicts.

bgNPC.Combat.IsAttackingEnemy(actor, target, attacker) returns a SERVER boolean: the target is already that observer's enemy, while observer and attacker have no enemy-list hostility or D_HT in either direction. It reads configured actor relationships, body dispositions (including NextBots) and available entity Disposition methods. Invalid entities and direct hits on the observer return false; missing optional methods do not imply hatred. ResolveEnemy returns nil for this exception before selection by initiator, team or wanted status; the observer stays out of that hit. The predicate does not change teams, enemy lists or conflict memory.