Description
NPCs that play like real players. TommygunNPC replaces the vanilla scientist brain with custom AI that strafes, flanks, retreats when hurt, heals behind cover, throws grenades, and forms squads. Drop it in and every scientist on your server gets a brain upgrade.
Vanilla NPCs stand still and shoot. These ones move like players — they'll push you when they have the advantage, duck behind cover when they don't, and call nearby NPCs to help. Ten built-in archetypes let you make scavengers that flee on sight and operators that push like chads, all tunable from an in-game admin panel.
Why This Is Different
- Brain transplant model — works with ANY plugin that spawns ScientistNPCs. BotReSpawn, BetterNPC, Raidable Bases, custom events — TommygunNPC intercepts the spawn and replaces the brain. No config, no compatibility patches.
- 25 personality traits — not just difficulty sliders. Toggle traits like DucksOnReload, AvengesSquadmates, SmartGrenades, PushesLostTargets, and ErraticMovement to build NPCs with distinct combat styles.
- Squad mechanics — NPCs recruit nearby allies, follow leaders, and avenge fallen squadmates. A fight with one becomes a fight with four.
- Zero dependencies — no other plugins required. Drop it in and go.
-
Full admin panel — configure everything in-game with
/tgnpc. No JSON files, no server restarts.
Combat AI
- Dynamic state machine — idle NPCs roam their area until they spot a threat, then shift between PUSHING, STRAFING, and RETREATING based on health, range, and personality. Every fight plays out differently.
- Reaction time system — configurable delay before NPCs acquire a new target (0.1s for elites, 1.5s+ for scavengers). No more instant-lock aimbots.
- Jump and duck evasion — NPCs dodge during combat with configurable cooldowns, heights, and durations. Some archetypes jump on reload, others duck while shooting.
- Grenade system — smart grenade throws with configurable intervals. NPCs that can't reach you will flush you out.
- Healing — NPCs use medical items when health drops below threshold. Configurable heal chance and health trigger.
- Cover seeking — NPCs look for cover when retreating or reloading.
- LOS tracking — grace period before NPCs lose a target behind cover. No more instant-forget cheese.
- Sound investigation — NPCs hear gunshots and footsteps, then move to investigate.
10 Built-In Archetypes
| Archetype | Reaction Time | Damage | Behavior |
|---|---|---|---|
| Default | 0.65–1.5s | 1.0x | Vanilla-equivalent baseline |
| Scavenger | Slow | 0.8x | Timid, flees when hurt |
| Guard | Medium | 1.0x | Holds position, doesn't chase |
| Operator | Fast | 1.2x | Elite tactical, pushes aggressively |
| Soldier | Medium-Fast | 1.0x | Balanced military |
| Patrol | Medium | 1.0x | Wide roam, alert to sounds |
| Rat | Very Slow | 1.5x | Patient ambusher, high burst damage |
| MilitaryMix | Weighted pool | Mixed | Random pick from military archetypes |
| RoadMix | Weighted pool | Mixed | Random pick from road archetypes |
| ScavengerMix | Weighted pool | Mixed | Random pick from low-tier archetypes |
Create unlimited custom archetypes from the admin panel. Duplicate an existing one and tweak it, or build from scratch.
Monument Auto-Detection
TommygunNPC automatically detects all 40+ monuments on your map and lets you assign archetypes per monument. Launch Site gets Operators, Junkyard gets Scavengers, Sewer Branch gets Rats — all configurable from the admin panel. Archetype pools let you assign weighted random picks so NPCs at the same monument aren't all identical.
Squad System
- Leader recruitment — NPCs with the Leadership trait recruit nearby allies into squads (configurable radius and cooldown)
- Follower behavior — squad members roam near their leader and respond to the same threats
- Avenge mechanic — when a squadmate dies, survivors retarget the killer
- Configurable squad size — cap how large squads can grow per archetype
Performance
- FPS-based degradation — when server FPS drops below threshold (default 20), NPC think interval automatically increases from 0.1s to 0.5s
- Efficient state machine — single AttackState with priority chain, minimal per-tick overhead
- Proper cleanup — brains are removed cleanly on unload, no orphaned components
Admin Panel
Full in-game GUI via /tgnpc:
- Archetype editor — create, duplicate, delete, and configure archetypes with live sliders and toggles
- Trait editor — toggle all 25 personality traits per archetype with color-coded categories
- Combat tuning — reaction time, damage scale, aim cone, engagement range, sense range, grenade intervals
- Movement tuning — speed multipliers, strafe distances, roam range
- Squad config — squad size, recruit radius, follower roam
- Monument mapping — assign archetypes to monuments, toggle per-monument management
- Performance monitor — live FPS, NPC count, managed brain count
- Reapply button — push config changes to all active NPCs without restart
Developer API
Full API for other plugins to hook into TommygunNPC:
Archetype Management
| Method | Returns | Description |
|---|---|---|
API_SetArchetype(ScientistNPC, string) |
bool | Apply an archetype to an NPC |
API_GetArchetype(ScientistNPC) |
string | Get current archetype name |
API_RegisterArchetype(string, Dict) |
bool | Register a custom archetype at runtime |
API_UnregisterArchetype(string) |
bool | Remove a registered archetype |
API_GetArchetypeNames() |
string[] | List all available archetypes |
NPC Control
| Method | Description |
|---|---|
API_ForceTarget(ScientistNPC, BasePlayer) |
Manually set an NPC's target |
API_ClearTarget(ScientistNPC) |
Clear current target |
API_ForceRetreat(ScientistNPC) |
Force NPC to retreat |
API_TagEvent(ScientistNPC, string) |
Tag NPC with an event identifier |
API_TagEventWithArchetype(ScientistNPC, string, string) |
Tag + apply archetype in one call |
Query
| Method | Returns | Description |
|---|---|---|
API_IsManaged(BaseEntity) |
bool | Check if entity has a TommygunBrain |
API_HasBrain(ScientistNPC) |
bool | Check brain attachment status |
API_GetManagedNPCs() |
ScientistNPC[] | Get all managed NPCs |
API_GetNPCsByEvent(string) |
ScientistNPC[] | Get NPCs by event tag |
API_GetNPCsByArchetype(string) |
ScientistNPC[] | Get NPCs by archetype |
Hooks Fired
| Hook | Description |
|---|---|
OnTommygunBrainAttached(ScientistNPC, string) |
Fired when a brain is attached (includes archetype name) |
OnTommygunEventNPCSpawned(ScientistNPC, string, string) |
Fired for tagged event NPCs (includes event tag and archetype) |
Permissions
| Permission | Default | Description |
|---|---|---|
tommygunnpc.admin |
Manual grant | Access admin panel, all console commands |
Commands
| Command | Description |
|---|---|
/tgnpc |
Open admin panel |
tgnpc.reapply (console) |
Reapply config to all active NPCs |
tgnpc.killall (console) |
Kill all managed NPCs (with confirmation) |
tgnpc.doreload (console) |
Reload config from file and reapply |
Full Configuration Reference
Every archetype is built from the following fields. All of these are editable from the in-game admin panel or the JSON config.
Personality Traits (25 toggles)
Boolean flags that define how an NPC behaves. Mix and match to create unique combat personalities.
| Trait | What It Does |
|---|---|
DucksOnRoamWait |
Crouches when idle at roam destination |
DucksOnReload |
Crouches while reloading |
DucksOnStrafe |
Crouches during strafe movements |
DucksOnShoot |
Crouches while firing |
JumpsOnReload |
Jumps while reloading to dodge |
JumpsOnStrafe |
Jumps during strafe movements |
JumpsOnRetreat |
Jumps while retreating |
WideStrafer |
Uses wider strafe arcs in combat |
Leadership |
Recruits nearby NPCs into a squad |
AvengesSquadmates |
Retargets the killer when a squadmate dies |
AvoidsPlayersInCombat |
Maintains distance rather than pushing |
RunsAtPlayer |
Rushes toward target aggressively |
BacksUpClose |
Retreats when target gets too close |
PushesLostTargets |
Moves to last known position when target breaks LOS |
InvestigatesSounds |
Moves toward gunshots and footsteps |
LooksAtSounds |
Turns to face sound sources |
RetargetsThreat |
Switches to the most dangerous target |
StandsWhileShooting |
Stops moving to fire (more accurate, more vulnerable) |
RelocatesOnReload |
Moves to a new position while reloading |
ErraticMovement |
Unpredictable movement patterns |
SmartGrenades |
Throws grenades at cover positions and choke points |
FlushGrenades |
Uses grenades to flush targets out of hiding |
FlinchesOnHit |
Reacts visually when taking damage |
Walks |
Walks instead of runs when not in combat |
RoamClosely |
Stays near spawn point when roaming |
Combat
| Field | Type | Default | Description |
|---|---|---|---|
Reaction Time Min |
float | 0.65 | Fastest target acquisition delay (seconds) |
Reaction Time Max |
float | 1.5 | Slowest target acquisition delay (seconds) |
Damage Scale |
float | 1.0 | Damage output multiplier |
Aim Cone Scale |
float | 2.0 | Accuracy modifier (lower = more accurate) |
Aim Settle Time |
float | 0.2 | Time to stabilize aim on target |
Engagement Range Multiplier |
float | 1.0 | Scales combat engagement distance |
Sense Range |
float | 40 | Detection distance (meters) |
Hearing Range |
float | 80 | Sound detection distance (meters) |
Target Lost Range |
float | 50 | Distance before target is forgotten |
Memory Duration |
float | 5.0 | How long target is remembered (seconds) |
LOS Break Grace Period |
float | 1.0 | Seconds before losing a target behind cover |
Retreat Health Threshold |
float | 50 | Absolute HP below which NPC retreats |
Retreat Health Fraction Min |
float | 0.25 | HP fraction below which NPC stops retreating and fights |
Heal Below Health Fraction |
float | 0.4 | HP fraction that triggers healing attempt |
Heal Chance |
float | 0.6 | Probability of using medical item |
Use Grenades |
bool | true | Enable grenade throws |
Grenade Interval Min |
float | 8.0 | Minimum seconds between throws |
Grenade Interval Max |
float | 15.0 | Maximum seconds between throws |
Seek Cover |
bool | true | Move to cover when retreating or reloading |
Can Be Blinded |
bool | true | Affected by flashbangs |
Movement
| Field | Type | Default | Description |
|---|---|---|---|
Speed Slowest |
float | 0.33 | Crawl speed multiplier |
Speed Slow |
float | 0.33 | Walk speed multiplier |
Speed Normal |
float | 0.5 | Jog speed multiplier |
Speed Fast |
float | 0.9 | Sprint speed multiplier |
Strafe Distance Min |
float | 1.0 | Minimum lateral strafe distance (meters) |
Strafe Distance Max |
float | 6.0 | Maximum lateral strafe distance (meters) |
Roam Range |
float | 20 | How far NPC roams from home point (meters) |
Squad
| Field | Type | Default | Description |
|---|---|---|---|
Max Squad Size |
int | 5 | Maximum NPCs per squad |
Recruit Radius |
float | 10 | Distance to recruit allies (meters) |
Recruit Cooldown |
float | 15 | Seconds between recruitment attempts |
Follower Roam Radius |
float | 4.0 | How close followers stay to leader (meters) |
Jump / Duck
| Field | Type | Default | Description |
|---|---|---|---|
Jump Cooldown Min |
float | 3.0 | Minimum seconds between jumps |
Jump Cooldown Max |
float | 6.0 | Maximum seconds between jumps |
Jump Height |
float | 1.5 | Jump arc height |
Jump Duration |
float | 0.65 | Jump animation time (seconds) |
Duck Cooldown Min |
float | 3.0 | Minimum seconds between ducks |
Duck Cooldown Max |
float | 6.0 | Maximum seconds between ducks |
Duck Duration Min |
float | 0.5 | Minimum crouch hold time (seconds) |
Duck Duration Max |
float | 3.0 | Maximum crouch hold time (seconds) |
Naming (per archetype)
| Field | Type | Default | Description |
|---|---|---|---|
Override Global |
bool | false | Use archetype-specific naming instead of global |
Use Real Player Names |
bool | false | Pull names from actual players on the server |
Custom Names |
list | [] | Custom name pool for this archetype |
Display Archetype Name |
bool | false | Show archetype label in NPC name |
Name Aliases |
list | [] | Alternate display names for this archetype |
Audio (per archetype)
| Field | Type | Default | Description |
|---|---|---|---|
Override Global |
bool | false | Use archetype-specific audio settings |
Allow Radio Chatter |
bool | false | Enable radio chatter sound effects |
Global Settings
| Field | Type | Default | Description |
|---|---|---|---|
Enabled |
bool | true | Master enable/disable |
Replace Vanilla NPCs |
bool | true | Auto-replace vanilla scientist brains on spawn |
Kill NPCs In Water |
bool | false | Kill NPCs stuck swimming |
Use Real Player Names |
bool | false | Global: pull NPC names from real players |
Custom Name Pool |
list | [] | Global custom name pool |
Fallback To Vanilla Names |
bool | true | Use vanilla scientist names if pools are empty |
Allow Radio Chatter |
bool | true | Global: enable radio chatter SFX |
Degrade Under Load |
bool | true | Enable FPS-based performance degradation |
Degrade Threshold FPS |
int | 20 | FPS below which degradation kicks in |
Normal Think Interval |
float | 0.1 | NPC brain tick rate at normal FPS (seconds) |
Degraded Think Interval |
float | 0.5 | NPC brain tick rate under load (seconds) |
Support
- For all questions and feedback, dm me (1928tommygun) on my discord at discord.fragmod.com
License
TOMMYGUN'S EULA – BY USING THIS PLUGIN YOU AGREE TO THE FOLLOWING!
- Code contained in this file is not licensed to be copied, shared, resold, or modified in any way.
- You may copy the plugin freely to each server instance that your organization owns.
- Do not share this plugin with other server organizations — they must purchase their own licenses.
Customer Reviews
Discussion
Be the first to start the discussion!