Shared API¶
Loaded in both realms. Client reads reflect received data, not an authoritative simulation. Check for a missing actor and validate its entity.
Actor¶
EnemiesCount¶
actor:EnemiesCount()
Returns the tracked enemy count.
Source: lua/background_npcs_core/actor/components/sh_enemies.lua.
EqualStateGroup¶
actor:EqualStateGroup(group_name)
Checks the current state against a group name or list.
Source: lua/background_npcs_core/actor/components/sh_state.lua.
GetActiveWeapon¶
actor:GetActiveWeapon()
Returns a weapon entity or NULL; a seated visual may have no active weapon. Carried parcels, suitcases/briefcases and newspapers return NULL through this actor API; the native entity can still expose them.
Source: lua/background_npcs_core/actor/components/sh_combat.lua.
GetAngles¶
actor:GetAngles()
Returns current entity angles, or Angle(0, 0, 0) if unavailable.
Source: lua/background_npcs_core/actor/sh_actor.lua.
GetClass¶
actor:GetClass()
Returns the original character class, not necessarily the current visual entity class.
Source: lua/background_npcs_core/actor/sh_actor.lua.
GetData¶
actor:GetData()
Returns this actor’s mutable configuration copy; changing it affects this actor. Global config changes do not update existing actors.
Source: lua/background_npcs_core/actor/sh_actor.lua.
GetEnemy¶
actor:GetEnemy()
Returns the selected living enemy or NULL: a direct attacker from the last 5 seconds, then the siege/squad target, then the previous valid combat target, then the nearest living enemy. GetNearEnemy remains the distance-only query. CLIENT uses only its received local data; SERVER owns combat selection.
Source: lua/background_npcs_core/actor/components/sh_enemies.lua.
GetFirstEnemy¶
actor:GetFirstEnemy()
Returns the first valid enemy or NULL.
Source: lua/background_npcs_core/actor/components/sh_enemies.lua.
GetFirstTarget¶
actor:GetFirstTarget()
Returns the first target entry or NULL.
Source: lua/background_npcs_core/actor/components/sh_targets.lua.
GetGender¶
actor:GetGender()
Returns the stored gender or unknown.
Source: lua/background_npcs_core/actor/sh_actor.lua.
GetGenderByModel¶
actor:GetGenderByModel()
Infers gender from the character model (saved model while seated); no argument. Returns female, male or unknown.
Source: lua/background_npcs_core/actor/sh_actor.lua.
GetHealth¶
actor:GetHealth()
Alias in behavior for Health(); use instead of assuming GetNPC():Health exists.
Source: lua/background_npcs_core/actor/sh_actor.lua.
GetLastEnemy¶
actor:GetLastEnemy()
Returns the last valid enemy or NULL.
Source: lua/background_npcs_core/actor/components/sh_enemies.lua.
GetLastReaction¶
actor:GetLastReaction()
Returns the last stored reaction.
Source: lua/background_npcs_core/actor/components/sh_state.lua.
GetLastTarget¶
actor:GetLastTarget()
Returns the last target entry or NULL.
Source: lua/background_npcs_core/actor/components/sh_targets.lua.
GetMaxHealth¶
actor:GetMaxHealth()
Returns the body/entity maximum or saved occupant maximum; 0 when unavailable.
Source: lua/background_npcs_core/actor/sh_actor.lua.
GetNPC¶
actor:GetNPC()
Returns the current entity, possibly NULL during replacement. In a car it is a DV visual entity. Fetch it again after BGN_ActorEntityChanged and validate with IsValid.
Source: lua/background_npcs_core/actor/sh_actor.lua.
GetName¶
actor:GetName()
Returns the stored display name.
Source: lua/background_npcs_core/actor/sh_actor.lua.
GetNearEnemy¶
actor:GetNearEnemy()
Returns the nearest valid enemy or NULL.
Source: lua/background_npcs_core/actor/components/sh_enemies.lua.
GetNearTarget¶
actor:GetNearTarget()
Returns the nearest valid target entity or NULL.
Source: lua/background_npcs_core/actor/components/sh_targets.lua.
GetOldState¶
actor:GetOldState()
Returns the previous state name.
Source: lua/background_npcs_core/actor/components/sh_state.lua.
GetOldStateData¶
actor:GetOldStateData()
Returns the previous state data table; client snapshots do not carry full server state data.
Source: lua/background_npcs_core/actor/components/sh_state.lua.
GetPos¶
actor:GetPos()
Returns the current entity position, or Vector(0, 0, 0) if unavailable.
Source: lua/background_npcs_core/actor/sh_actor.lua.
GetRelationship¶
actor:GetRelationship(value, default)
Returns the configured relationship for an entity/actor, falling back to default.
Source: lua/background_npcs_core/actor/components/sh_team.lua.
GetState¶
actor:GetState()
Returns the current state name.
Source: lua/background_npcs_core/actor/components/sh_state.lua.
GetStateData¶
actor:GetStateData()
Returns the current mutable state data table; client snapshots contain only the state name.
Source: lua/background_npcs_core/actor/components/sh_state.lua.
GetStateGroupName¶
actor:GetStateGroupName()
Returns the registered group of the current state.
Source: lua/background_npcs_core/actor/components/sh_state.lua.
GetTarget¶
actor:GetTarget(index)
Returns the target at index (default 1), or NULL.
Source: lua/background_npcs_core/actor/components/sh_targets.lua.
GetType¶
actor:GetType()
Returns the actor configuration ID, for example citizen.
Source: lua/background_npcs_core/actor/sh_actor.lua.
HasActiveWeapon¶
actor:HasActiveWeapon()
Returns whether GetActiveWeapon yields a valid entity.
Source: lua/background_npcs_core/actor/components/sh_combat.lua.
HasEnemy¶
actor:HasEnemy(ent)
Returns whether ent is in the enemy list. SERVER returns false for a current teammate even if an old list entry remains; CLIENT reads its received list snapshot.
Source: lua/background_npcs_core/actor/components/sh_enemies.lua.
HasNoEnemies¶
actor:HasNoEnemies()
Returns true when the enemy count is zero.
Source: lua/background_npcs_core/actor/components/sh_enemies.lua.
HasNoTargets¶
actor:HasNoTargets()
Returns true when the target count is zero.
Source: lua/background_npcs_core/actor/components/sh_targets.lua.
HasSequence¶
actor:HasSequence(sequence_name)
Case-insensitive check of the stored sequence name.
Source: lua/background_npcs_core/actor/components/sh_animation.lua.
HasState¶
actor:HasState(state)
Accepts a state name or list of names; returns boolean.
Source: lua/background_npcs_core/actor/components/sh_state.lua.
HasStateGroup¶
actor:HasStateGroup(state_name, group_name)
Checks a specified state against a group name or list.
Source: lua/background_npcs_core/actor/components/sh_state.lua.
HasTarget¶
actor:HasTarget(ent)
Returns whether ent occurs in the target list.
Source: lua/background_npcs_core/actor/components/sh_targets.lua.
HasTeam¶
actor:HasTeam(value)
Accepts a team name/list/entity/actor. Gang membership has special rules; do not infer alliance solely from the bandits tag.
Source: lua/background_npcs_core/actor/components/sh_team.lua.
Health¶
actor:Health()
Returns character health, including stored occupant health. Returns 0 when unavailable; safe in both realms.
Source: lua/background_npcs_core/actor/sh_actor.lua.
InVehicle¶
actor:InVehicle()
Server checks the provider; client reads bgn_vehicle_entered on the current entity.
Source: lua/background_npcs_core/actor/components/sh_vehicle.lua.
IsAlive¶
actor:IsAlive()
Returns whether the character is alive; on the server a dead actor is also unregistered.
Source: lua/background_npcs_core/actor/sh_actor.lua.
IsAnimationPlayed¶
actor:IsAnimationPlayed()
Checks the actor animation flag and Animator state.
Source: lua/background_npcs_core/actor/components/sh_animation.lua.
IsLoopSequence¶
actor:IsLoopSequence()
Returns the stored animation-loop flag.
Source: lua/background_npcs_core/actor/components/sh_animation.lua.
IsMeleeWeapon¶
actor:IsMeleeWeapon()
Checks the active/assigned class against configured melee weapons; no class returns false.
Source: lua/background_npcs_core/actor/components/sh_combat.lua.
IsNPC¶
actor:IsNPC()
Checks whether the current entity is an engine NPC.
Source: lua/background_npcs_core/actor/sh_actor.lua.
IsNextBot¶
actor:IsNextBot()
Checks whether the current entity is a NextBot.
Source: lua/background_npcs_core/actor/sh_actor.lua.
IsStateLock¶
actor:IsStateLock()
Returns the stored lock flag.
Source: lua/background_npcs_core/actor/components/sh_state.lua.
IsValid¶
actor:IsValid()
Checks the current entity only; not equivalent to alive.
Source: lua/background_npcs_core/actor/sh_actor.lua.
IsValidSequence¶
actor:IsValidSequence(sequence_name)
Checks model sequence availability; false while seated.
Source: lua/background_npcs_core/actor/components/sh_animation.lua.
TargetsCount¶
actor:TargetsCount()
Returns the tracked target count.
Source: lua/background_npcs_core/actor/components/sh_targets.lua.
actors¶
Source: lua/background_npcs_core/api/sh_actors.lua.
| Signature |
|---|
bgNPC.Actors.Get(npc) |
bgNPC.Actors.IsActor(npc) |
bgNPC.Actors.GetByUid(uid) |
bgNPC.Actors.GetFirst() |
bgNPC.Actors.GetAll() |
bgNPC.Actors.Count(actor_type) |
bgNPC.Actors.GetByType(actor_type) |
bgNPC.Actors.GetAllNPCs() |
bgNPC.Actors.GetNPCsByType(actor_type) |
bgNPC.Actors.HasNPC(npc) |
bgNPC.Actors.Filter(predicate) |
bgNPC.Actors.GetByTeam(team) |
bgNPC.Actors.GetByState(state) |
bgNPC.Actors.GetInRadius(center, radius) |
bgNPC.Actors.GetNearest(center) |
bgNPC.Actors.GetNearestByType(center, actor_type) |
bgNPC.Actors.ShareTeam(npc1, npc2) |
config¶
Source: lua/background_npcs_core/api/sh_config.lua.
| Signature |
|---|
bgNPC.Config.GetActor(actor_type) |
bgNPC.Config.GetActorTypes() |
bgNPC.Config.ActorExists(actor_type) |
bgNPC.Config.ClearCache() |
bgNPC.Config.SaveDefaults() |
bgNPC.Config.Reset() |
bgNPC.Config.GetWantedLevel(data) |
bgNPC.Config.IsTypeActive(actor_type) |
bgNPC.Config.GetFullness(actor_type) |
bgNPC.Config.GetTypeLimit(actor_type) |
states¶
Source: lua/background_npcs_core/api/sh_states.lua.
| Signature |
|---|
bgNPC.States.Register(state_name, group_name, callbacks) |
bgNPC.States.Exists(state_name) |
bgNPC.States.GetGroup(state_name) |
bgNPC.States.Call(state_name, func_name, ...) |
bgNPC.States.HasAction(state_name, func_name) |
modes¶
Source: lua/background_npcs_core/api/sh_modes.lua.
| Signature |
|---|
bgNPC.Modes.IsPeaceful() |
bgNPC.Modes.IsFriend() |
bgNPC.Modes.IsAggressive() |
vision¶
Source: lua/background_npcs_core/api/sh_vision.lua.
| Signature |
|---|
bgNPC.Vision.HasLineOfSight(watcher, ent, channel) |
bgNPC.Vision.NPCCanSeePos(ent, pos, fov) |
bgNPC.Vision.PlayerCanSeePos(ply, pos, radius) |
bgNPC.Vision.AnyActorSees(ent, exclude) |
bgNPC.Vision.ActorsThatSee(ent) |
channel is an optional diagnostic label (default los). It does not change the LOS predicate or its boolean/hit-entity returns. SERVER records the existing result only for subscribed actors with the vision layer enabled; CLIENT does not send sight telemetry.
statistics¶
Source: lua/background_npcs_core/api/sh_statistics.lua.
| Signature |
|---|
bgNPC.Statistics.Get(attacker, actor_type) |
bgNPC.Statistics.GetSum(attacker) |
assert¶
Source: lua/background_npcs_core/api/sh_assert.lua.
| Signature |
|---|
bgNPC.Assert.Arg(index, value, spec, func_name) |
bgNPC.Assert.Field(owner_name, field_name, value, spec) |
bgNPC.Assert.True(condition, message, ...) |
bgNPC.Assert.NonEmptyString(index, value, func_name) |
bgNPC.Assert.Is(value, spec) |
bgNPC.Assert.RegisterType(type_name, checker) |
core¶
Source: lua/background_npcs_core/api/sh_core.lua.
| Signature |
|---|
bgNPC.Combat.IsIgnored(ent) |
bgNPC.Util.GetCVar(name) |
bgNPC.Util.IsDebug() |
bgNPC.Util.Log(message, tag) |
bgNPC.Util.IsVectorInWater(pos) |
bgNPC.Util.GetActivePlayerTool(tool_name, ply) |
bgNPC.Util.Warning(message) |
bgNPC.Modules.Get(module_name) |
bgNPC.Modules.Register(module_name, module_table) |
points¶
Source: lua/background_npcs_core/api/sh_points.lua.
| Signature |
|---|
bgNPC.Points.Count() |
bgNPC.Points.GetAll(link_type) |
bgNPC.Points.GetInRadius(center, radius, link_type) |
bgNPC.Points.GetRandom(center, radius, link_type) |
bgNPC.Points.GetClosestInRadius(center, radius, link_type) |
bgNPC.Points.GetDistantInRadius(center, radius, link_type) |
bgNPC.Points.GetIndexesInRadius(center, radius, link_type) |
bgNPC.Points.GetClosestInChunk(center, link_type) |
bgNPC.Points.GetDistantInChunk(center, link_type) |
bgNPC.Points.GetClosestToPosInChunk(center, pos, link_type) |
bgNPC.Points.GetDistantToPosInChunk(center, pos, link_type) |
bgNPC.Points.FindPath(start_pos, end_pos, iteration_limit, link_type, actor) |
Data contracts¶
Points.GetRandomreturns a Vector or nil; an empty graph radius query stays empty instead of selecting elsewhere. NavMesh sampling uses actual areas. On CLIENT this API returns nil.Actors.Get,GetByUid,GetFirstand nearest lookups can return nil.GetAll, type lists and NPC lists expose internal storage: do not mutate them.Config.GetActorreturns a cached resolved table or nil: copy before editing. After changingbgNPC.cfg.actors, callConfig.ClearCache; existing actors keep their own copies.States.Register(name, group, callbacks)registers behavior callbacks in each realm where executed. Execute AI callbacks on the server.Pointswraps the active navigation provider. Its useful graph/path data is server-side; use the navigation editor's synchronization for client route editing.Statistics.Getreturns a count for a type, or a table without a type;GetSumreturns the total. Client data arrives via network events.Modules.Get(name)may return nil; availability depends on realm and load stage. A shared accessor does not make a server module available on the client.