Skip to content

Navigation

Actors move with the help of one navigation provider, chosen per map (bgNPC.Nav, server only).

Provider Data Used when
custom own node graph, data/background_npcs/graph/<map>.dat a route file (or an old route file) exists for the map
navmesh the map's NavMesh the map ships a NavMesh
nodegraph the map's maps/graphs/<map>.ain no NavMesh, but the map has an HL2 node graph
custom (empty) generated at runtime none of the above

The addon never starts the engine's NavMesh generation.

Console

Command / cvar Meaning
bgn_nav_provider auto\|navmesh\|nodegraph\|custom force a provider (auto by default)
bgn_nav_info print the active provider and its size
bgn_nav_reload reload navigation data
bgn_nav_generate generate nodes over the whole map (flood fill from spawn points and players)
bgn_nav_generate around [radius] generate only around you
bgn_nav_generate stop stop the generator
bgn_nav_generator_max_nodes node limit of the generator (15000)
bgn_dynamic_nodes 1 keep generating around players on maps without saved data
bgn_convert_legacy_nodes [map] convert an old route file (background_npcs/nodes/<map>.dat) to the new format
bgn_compile pack route, seats and Decent Vehicle waypoints into a Lua file for the Workshop
bgn_save_map save the active movement graph to your duplications

Save for the Workshop (bgn_compile) also downloads the route pack to the calling admin's computer: garrysmod/data/background_npcs/compile/bgn_compile_<map>.txt. A result window shows the path and explains how to rename it to .lua and put it in the published addon's lua/autorun/server folder. The pack includes the current graph, including one loaded from a duplication.

Old route files are converted automatically on load, so map packs made for older versions keep working. Unversioned routes and versions 1.0–1.2 are supported from data/citizens_points/ and data/background_npcs/nodes/ (.dat or .json). Loading leaves the original files intact. Automatic loading saves the converted route in the current format to data/background_npcs/graph/<map>.dat. A valid new graph takes precedence; a broken graph is rebuilt from a legacy route when available. Large graphs bypass JSON's 15,000-entry limits and keep their coordinates without rounding. Saved point and link counts are checked when loading; a mismatch is reported as corruption. Autocomplete for bgn_convert_legacy_nodes lists server maps with legacy routes and no new graph yet. Without an argument, the command converts the current map.

Select a route in the spawn menu's Duplications tab to load it on the server and into the point editor. Old SLibrary BGN_NODES duplications work without SLibrary. Save the route from the editor to keep it after a map restart; loading a duplication does not overwrite the saved route. Saving and loading require admin rights, and new duplications can only be loaded on their original map.

Editing routes

The Point editor tool edits the custom graph: create points, link them ("walk" links), remove them, then save with the panel button (cl_citizens_save_route). The Path finder tool shows the path an actor would take between two points.

API (server)

bgNPC.Points.Count()
bgNPC.Points.GetInRadius(center, radius, link_type)   -- point objects with :GetPos()
bgNPC.Points.GetRandom(center, radius, link_type)
bgNPC.Points.FindPath(start_pos, end_pos, nil, link_type, actor) -- list of Vector, never empty
bgNPC.Nav.GetProvider()   -- the active provider
bgNPC.Nav.GetInfo()       -- { provider, points, links, source }

bgNPC.NodeGraph is the graph class behind the custom provider (spatial hash, typed links, A*).

Points.GetRandom returns a Vector or nil when there are no suitable points; an empty graph radius query does not fall back to another part of the map. NavMesh samples use the loaded list of areas, not a guessed continuous range of area IDs. Run bgn_nav_reload after changing the mesh externally.

Hooks

Hook Realm Arguments
BGN_NavProviderChanged server provider
BGN_NavGeneratorFinished server graph, added_count
BGN_NavEditorGraphLoaded client graph
BGN_PreLoadRoutes, BGN_PostLoadRoutes server OUTDATED, still called
BGN_LoadingClientRoutes client OUTDATED, still called

Emergency cars (Decent Vehicle)

Police cars (npc_dvbgn_police) chasing an enemy, and ambulances sent to a body (actor.drive_target_pos), ignore traffic rules: siren on, no stopping at red lights or giving way. The route is the shortest one over the DV waypoints taken in both directions, with jumps to waypoints within 600 units in sight (lane changes, the opposite side of the road). When the target is in plain sight the car drives straight at it. Paths are refreshed every 3 s, every 1 s within 1000 units of the target. While an actor sits in a police car or an ambulance, players can't get in (locked sound).

Doors

Cvar (server) Default Meaning
bgn_npc_open_doors 1 actors open closed doors on their way; 0: only open doors are walked through
bgn_npc_open_locked_doors 0 locked doors too: unlocked to open, locked again when closed after 10 s

Menu: General → Doors. bgNPC.Util.CanActorOpenDoor(door) checks both, bgNPC.Util.IsDoorOpen(door) tells an open door (prop_door_rotating, func_door*). Engine NPCs get CAP_OPEN_DOORS only while doors are allowed, NextBots open only the doors allowed; paths route only through doors that are open or may be opened. An open door is not "opened" again: the opening animation used to stop actors in the doorway. On the server, CanActorOpenDoor also rejects doors reserved by hold_door, including when opening locked doors is enabled. GOAP can close and hold an open door when desperate; police can breach that temporary hold. See door shelter and breaching.

Doorways: an actor within 90 units of a door doesn't collide with other actors (COLLISION_GROUP_NPC_SCRIPTED, actor/events/sv_door_pass.lua), so a crowd going both ways passes instead of jamming. Players and props still collide; sitting or riding actors keep their group.