🧟 Core AI and Horde Logic

• The zombies do not bunch up chaotically. The plugin continuously calculates and assigns dynamic position coordinates to each member.

  • Dynamic Grid Advance: Squads advance in structured ranks, increasing speed if they fall behind to maintain cohesive pressure.

  • Surround Protocol: When closing in on a target, NPCs transition into an 8-axis surrounding perimeter to trap the player.

  Advanced Siege & Base Assault AI

  When attacking players sheltering inside bases, the horde switches to raid mode:

  • Slot Distribution: NPCs spread out along structure perimeters rather than stacking on a single point, assaulting multiple sections simultaneously.

  • Target Prioritization: Melee units relentlessly attack foundations, doors, and barricades with material-based impact effects (wood, stone, metal) and configurable siege damage.

  • Breach Demolition: Boss units equipped with rocket launchers unleash heavy structural ordnance from optimal standoff distances.

  Ranged Combat & Dynamic Reload System

  Humanoid NPCs can be equipped with ranged weaponry (pistols, shotguns, rifles, and flamethrowers):

  • Custom Aim Controller: Custom aimbot logic handles real-time pitch and yaw adjustments for lethal precision.

  • Realistic Reload Cycles: Running out of ammunition triggers network reload animations and pauses firing for a dynamic duration based on magazine capacity.

  • Automatic Ammo Supply: Integrated inventory management ensures NPCs replenish ammunition automatically without endless infinite-spam glitches.

  Acoustic Gunshot & Threat Detection

  • Acoustic Sound Detection: Swarms possess directional hearing. Gunfire within configurable acoustic range immediately alerts nearby hordes, even if they have not taken damage.

  • Silencer & Suppressor Support: Fully respects weapon attachments - suppressed weapons significantly shrink the detection radius.

  • Retaliation Alert: Damaging any member of a squad or the commander instantly flags the attacker and turns the entire horde hostile.

  NPC Interaction Modes

  Administrators can fine-tune how hordes interact with external Rust NPCs (Scientists, Tunnel Dwellers, Patrols):

  • Attack: Engages any external NPC encountered on sight.

  • Passive: Defensive behavior only (retaliates when engaged).

  • Ignore: Completely bypasses external NPCs to focus exclusively on player targets.

  Overhauled Elite Boss AI

  Elite Commanders command the battlefield with dedicated tactical routines:

  • Rearline Positioning: The Boss maneuvers behind the frontline infantry (~5.5m behind the swarm centroid), using minions as meat shields while laying down support fire.

  • Heavy Weapon Tuning: Adjustable damage scaling (Low, Medium, High) for heavy armaments such as the Minigun, HMLMG, and M249.

  • Smart Rocket Trajectory: Calculates line of sight, vertical elevation, and pitch angles to launch real explosive rockets with configurable structural and splash damage.

  • Dynamic Outfit Themes: Support for built-in visual archetypes (Juggernaut, Tactical, Raider, Scientist, Demon, Krieg, Abyss, Nomad) or custom skin configurations.

  Advanced State Machine

  Swarms transition seamlessly across three operational states:

  • Dynamic Patrol: Fluid patrol behavior with randomized actions (Walk, Halt & Scan, Sprint) calculated via NavMesh and terrain height validation.

  • Chase: Cohesive squad advancement maintaining structured spacing.

  • Attack: Coordinated melee strikes, suppressive gunfire, and tactical grenade throws (F1, Beancan, Molotov, Smoke).

⚔️🔥 Base Assaults and Humanized NPCs

Ordnance & Grenades

NPCs utilize explosive and tactical consumables to flush out entrenched players:

• Ordnance Arsenal: Supports F1 Frag Grenades, Beancan Grenades, Molotov Cocktails, and Smoke Grenades (with toggleable smoke visibility).

• Ballistic Trajectories: Real-time physics calculations apply realistic arc velocities based on distance to the target.

• Squad Cooldown Control: A shared swarm cooldown prevents overwhelming grenade spam, while min/max distance thresholds (5m - 25m) ensure safe deployment.

• Anti-Structure Safety: When Base Raiding is disabled, NPCs intelligently suppress grenade throws near building privilege and structures.

Intelligent Structure Sieging

The AI dynamically adapts its breach strategy according to equipped weaponry:

• Melee Demolition: Close-combat zombies assault foundations, doors, embrasures, and barricades. Hits are staggered with subtle micro-delays to generate authentic rhythmic pounding sounds.

• Suppressing Fire: Gun-wielding mercenaries do not waste bullets on indestructible walls - they lay down suppressive fire and track player sightlines while melee units breach.

• Heavy Siege Demolition (Boss): Commanders armed with Rocket Launchers maintain standoff distance and unleash high-yield rockets directly against player fortifications.

Full Friendly Fire Protection

• Entity Owner Resolution: Custom damage tracing tracks explosive origin (creatorEntity), completely preventing zombies and bosses from killing each other with rockets, shrapnel, or lingering fire patches.

• Self-Damage Immunity: Protects throwers from accidental self-annihilation during close-quarters engagements.

Granular Combat Configuration

• Configurable Siege Damage: Fine-tune exact HP damage dealt to structures per strike.

• Melee Aggression Scaling: Adjust strike cooldowns (1.0x to 2.0x multipliers) to speed up or slow down zombie assault cadence.

• Boss Weapon Balancing: Choose between Low, Medium, or High damage scaling for military heavy weaponry (M249, HMLMG, Minigun).

Dynamic Material FX

Every structural hit triggers precise visual particle effects and authentic impact audio based on the exact building tier:

• Wood: Splinter debris and blunt impact sounds.

• Stone & Concrete: Dust puffs and chipping sound effects.

• Metal & High Quality: Spark bursts and heavy metallic clangs across doors, garage doors, sheet metal, and armored blocks.

🎭 Visual, Sound, and Loot Customization

• Transform your horde from classic undead into apocalyptic mercenary factions with complete clothing and armor loadouts:

  Humanoid NPC Archetypes (8 Presets)

  • Military: Full BDU uniform, combat boots, tactical gloves, and ballistic armor.

  • Survival: Improvised wood armor, tank top, and beanie.

  • Scavenger: Paintball suit, work boots, and tactical gloves.

  • Jason: Collared shirt, jacket, work trousers, and the iconic hockey mask.

  • Raider: Balaclava, hoodie, boots, and roadsign armor.

  • Ghost: Spectral white ghost sheet and hide attire.

  • Maniac: Horse head mask, shorts, tank top, and combat boots.

  • Prisoner: Orange/burlap prison garments, bandana, beanie, and light protection.

  Elite Boss Outfits (8 Presets + Custom Skins)

  • Juggernaut: Heavy plate helmet, jacket, and pants combo.

  • Tactical: Metal chestplate, metal facemask, hoodie, and combat pants.

  • Raider: Roadsign jacket, kilt, and heavy gas mask.

  • Scientist: Full heavy scientist hazmat protection.

  • Demon: Scarecrow suit paired with the demonic ox mask.

  • Krieg: Authentic militarized Krieg trenchcoat suit.

  • Abyss: Deep-sea diver atmospheric hazmat suit.

  • Nomad: Rugged post-apocalyptic nomad suit.

  • Custom & Skinned: Define custom clothing item lists or assign custom Steam Workshop Skin IDs (bossSkinId).

  Loot Control and Performance Optimization

  • Loot option: Choose whether NPCs leave behind corpses and loot backpacks or vanish without a trace.

  • Prohibited item blacklist: Specify the exact shortnames of items to be automatically removed from corpse inventories.

  • Exploit prevention: Removes heavy gear and large backpacks from inventories upon death if looting is disabled.

  • Automatic dawn cleanup: Automatically removes NPC corpses and abandoned backpacks at daybreak to maximize FPS and server performance.

⚙️ Population Control and Performance

Memory & Performance Optimization

• Improved active swarm tracking.

• Enhanced target validation.

• Reduced CPU overhead.

• Fixed boss routines that could continue after death.

• Guaranteed memory cleanup.

• Optimized formation system capable of handling large swarms (50+ NPCs).

Smart Spawning

• Improved /swarm here command.

• Hordes now spawn in front of the administrator.

• Advanced NavMesh sampling.

• Safety validation prevents spawns underwater or inside rocks.

• Tool Cupboard (TC) Protection: Toggleable TC avoidance supports both standard vanilla building.

• Safe Zone Immunity: NPCs will never spawn inside monuments or NPC safe zones (Bandit Camp, Outpost, Fishing Villages).

Strict Global Limits

Configure maximum simultaneous:

• Zombies

• Swarms

Across the entire server to protect performance.

Spawn Cycle & Cleanup

Configure zombies to:

• Spawn only at night.

• Self-destruct at dawn.

Smart Entity Cleanup

Automatic tracking and removal of:

• Dropped backpacks

• Expired event entities

Prevents unnecessary server bloat.

Detailed Debug Logging

Diagnostic messages for:

• Swarm generation

• Spawn attempts

• Configuration troubleshooting

• Featured by:

  ✅ New: Real-time Visual Config Panel (/swp)

  ✅ 50+ Configurable Settings

  ✅ 8+ Strategic Performance Checks

  ✅ 10+ Administrative Commands

  ✅ 85+ Granular Configuration Settings: : Total customization over combat, patrols, health and outfits

  ✅ Optimized for Servers with 50 - 150+ Players

  ✅ Languages: English, Spanish

📊  Administration Tools

• In-Game Graphical Interface (ZSProPanel Integration)

  Full native integration with the optional ZSProPanel (/swp) in-game GUI:

  • Zero Restarts or File Edits: Modify all plugin settings directly through an intuitive visual interface without touching .json files.

  • Live Telemetry Dashboard: Real-time data feed displays active target players, individual squad states (Patrol / Chase / Attack), boss counts, server time, and memory sets.

  • One-Click Triggers: Spawn squads, dispatch bosses, pause spawns, or purge the map directly from the panel.

  Status Reports

  The /swarm status command provides real-time information including:

  • System State: Live operational status ([ENABLED] / [DISABLED]).

  • Active Swarms: Current active squads vs. maximum global swarm capacity.

  • Global Entity Counter: Active zombies alive vs. server-wide hard limit.

  • Active Boss Count: Real-time tally of spawned Elite Commanders.

  • Spawn Probability: Current per-player roll chance percentage.

  • Active Archetype: Displays the currently selected entity model (scarecrow vs. npc_human).

  • Automated Intervals: Optionally broadcast these telemetry reports to staff at custom minute intervals.

  • Full Multi-Language Support: Localized out of the box in both English and Spanish.

  Advanced Debug Logging **

  A new diagnostic layer provides detailed logs for:

  • Swarm generation

  • Boss spawning

  • Event cleanup

  • Failed spawn attempts

  Allowing precise troubleshooting of configuration issues.

  Custom Announcement System

  Broadcast automated server messages with:

  • Custom HEX colors

  • Unique prefixes

  • Fully configurable formatting

🖥️ Server Integration, Commands & Permissions

Zombie Swarm Pro features a dedicated permission architecture to manage administrative access and staff immunity without requiring full server administrator (Auth Level 2) rights.

🔑 permission:

• If you want to grant access to moderators, event organizers, or specific players without giving them full admin rights, use the following Oxide permission:

  • zombieswarmpro.admin

  Grants full authorization to execute all /swarm chat commands, monitor status telemetry, dispatch targeted swarms, and force event states.

  • zombieswarmpro.ignore

  Grants complete stealth and targeting immunity against all swarms:

  • NPCs will never spawn around or target players with this permission.

  • Gunfire from these players bypasses acoustic gunshot detection.

  • If a squad is chasing a target that gains this permission, it immediately abandons the pursuit and returns to patrol.

  To grant this permission, use your console (F1) or RCON:

  • oxide.grant user <PlayerName or SteamID> zombieswarmpro.admin

  • oxide.grant group <GroupName> zombieswarmpro.admin

🧩 Admin Commands:

• /swp: Open the Pro Visual Configuration GUI (Panel).

• /swarm status: Shows active swarms, total zombies on the map, and current entity type.

• /swarm toggle: Pauses or resumes the automatic swarm generation on the server.

• /swarm clear: Immediately clears all swarms, zombies, and corpses from the map.

• /swarm reload: Reloads the configuration file without restarting the server.

• /swarm entity [npc_human | scarecrow]: Changes the NPC type in real-time.

• /swarm here: Forces a swarm to spawn exactly at your current position.

• /swarm attack "Player Name": Summons a swarm against a specific player instantly.

• /swarm boss "Player Name": Sends a Boss directly to attack a specific player.

• /swarm cancel "Player Name": Cancels and removes an active swarm attacking a specific player.

• /swarm msg: Broadcasts a custom announcement to all players.

⚙️ Configuration file:

{
  "General Settings": {
    "Debug Mode (true/false)": false,
    "Enable Auto Status Message": true,
    "Status Message Interval (Minutes)": 5.0,
    "Enable Invisibility Perm (true/false)": true,
    "Admins Can Fight (Ignore Invis for Admins)": false
  },
  "Broadcast Settings (Admin Messages)": {
    "Enable Automatic Broadcast (true/false)": false,
    "Broadcast Interval (Minutes)": 30.0,
    "Admin Broadcast Message": "This is just an example message (replace).",
    "Broadcast Prefix (Label)": "[Zombie Swarm]",
    "Prefix Color (HEX)": "#ff6b6b"
  },
  "Swarm Settings": {
    "Zombies Per Swarm (Amount)": 15,
    "Max Global Zombies (Total NPC Limit)": 80,
    "Max Global Swarms (Limit)": 15,
    "Spawn Probability per Player (0-100%)": 30,
    "Swarms Per Player (Limit)": 2,
    "Maintain Swarm Size (Refill missing zombies)": false,
    "Spawn Cooldown per Player (Seconds)": 600.0
  },
  "Time Settings": {
    "Start Hour (0-24h)": 12.0,
    "End Hour (0-24h)": 8.0
  },
  "Spawn Settings": {
    "Spawn Min Distance (Meters)": 80.0,
    "Spawn Max Distance (Meters)": 90.0,
    "Spawn Tick (Seconds)": 0.3,
    "Prevent Spawn In TC Range (true/false)": false,
    "Custom TC Distance in Meters (0 = Vanilla TC Zone)": 0.0
  },
  "Combat Settings": {
    "Enable Base Raiding AI (true/false)": false,
    "Damage to Structures (HP per hit)": 1.0,
    "Zombie Speed Fraction (0.1 - 1.0 multiplier)": 0.1,
    "Player Detection Range (Meters)": 80.0,
    "Attack Distance (Meters)": 2.0,
    "Formation Slot Radius (Meters)": 1.5,
    "Control Logic Tick (Seconds)": 0.5,
    "Attack When Shot (true/false)": true,
    "Shot Alert Duration (Seconds)": 30.0,
    "Zombie Melee Attack Speed Multiplier (1.0 - 2.0)": 1.0,
    "Zombie Health (HP)": 200.0,
    "Interaction with other NPCs (attack / passive / ignore)": "ignore",
    "Enable Gunshot / Noise Detection (true/false)": true,
    "Gunshot Detection Range (Meters)": 150.0,
    "Respect Silencers / Suppressors (true/false)": true,
    "Silenced Gunshot Detection Range (Meters)": 12.0
  },
  "Grenade Settings": {
    "Enable Grenades (true/false)": true,
    "Allow Smoke Grenades (true/false)": false,
    "Grenade Type (f1, beancan, smoke, molotov, random)": "random",
    "Grenade Throw Probability (0-100%)": 5,
    "Grenade Throw Cooldown (Seconds)": 30.0,
    "Disable Zombie Friendly Fire (Explosions/Fire)": true,
    "Min Throw Distance (Meters)": 5.0,
    "Max Throw Distance (Meters)": 25.0,
    "F1 Prefab Path (Fallback)": "assets/prefabs/weapons/f1 grenade/grenade.f1.deployed.prefab",
    "Beancan Prefab Path (Fallback)": "assets/prefabs/weapons/beancan grenade/grenade.beancan.deployed.prefab",
    "Smoke Prefab Path (Fallback)": "assets/prefabs/tools/smoke grenade/grenade.smoke.deployed.prefab",
    "Molotov Prefab Path (Fallback)": "assets/prefabs/weapons/molotov cocktail/grenade.molotov.deployed.prefab"
  },
  "Patrol Settings": {
    "Patrol Random Behavior (true/false)": true,
    "Patrol Run Probability (0-100%)": 40,
    "Patrol Stop Probability (0-100%)": 30,
    "Patrol Stop Duration (Seconds)": 3.0,
    "Patrol Walk Duration (Seconds)": 10.0,
    "Patrol Run Duration (Seconds)": 8.0,
    "Patrol Waypoint Interval (Seconds)": 25.0,
    "Patrol Radius (Meters)": 150.0
  },
  "Entity Settings": {
    "Entity Type (scarecrow, npc_human, random)": "scarecrow"
  },
  "NPC Human Settings": {
    "NPC Human Clothing (military, survival, scavenger, jason, raider, ghost, maniac, prisoner, random)": "random",
    "Ranged Weapon Chance (0-100%)": 30,
    "List of Melee Weapons": [
      "machete",
      "bone.club",
      "salvaged.cleaver",
      "hatchet"
    ],
    "List of Ranged Weapons (pistols and shotguns)": [
      "pistol.semiauto",
      "pistol.revolver",
      "pistol.m92",
      "shotgun.pump"
    ],
    "Enable NPC Human Armor (true/false)": true
  },
  "Boss Settings": {
    "Enable Boss NPC (true/false)": true,
    "Boss Only with NPC Human Type (true/false)": false,
    "Boss Spawn Probability (0-100%)": 100,
    "Boss Optimal Range (Meters)": 15.0,
    "Boss Health (HP)": 800.0,
    "Boss Rocket Damage to Structures (HP)": 150.0,
    "Boss Rocket Cooldown (Seconds)": 5.0,
    "Boss Vision/Engagement Range (Meters)": 30.0,
    "Boss Rocket Splash Radius (Meters)": 3.0,
    "Boss Outfit Type (juggernaut, tactical, raider, scientist, demon, krieg, abyss, nomad, random)": "random",
    "Boss Weapon (rocketlauncher, hmlmg, minigun, flamethrower, m249, random)": "random",
    "Boss Heavy Weapon Damage Level (low, medium, high)": "medium",
    "Boss Custom Clothing List (Used if Type is empty)": [
      "heavy.plate.helmet",
      "heavy.plate.jacket",
      "heavy.plate.pants"
    ],
    "Boss Clothing Skin ID (0 = default)": 0
  },
  "Visual & Sound Settings": {
    "Enable Glowing Eyes (true/false)": true,
    "Enable Zombie Sound Effects (true/false)": true,
    "Death Sound Prefab": "assets/bundled/prefabs/fx/player/gutshot_scream.prefab",
    "Ambient/Scream Sound Prefab": "assets/bundled/prefabs/fx/player/beartrap_scream.prefab"
  },
  "Loot & Corpse Settings": {
    "Enable Drop Loot (true/false)": false,
    "Clear Corpses in the end (true/false)": true,
    "Clear Backpacks in the end (true/false)": true,
    "Prohibited Items List (Blacklist from drop/loot)": []
  }
}

🖥️  Control Panel (GUI):

🔷 Support

If you find any bugs or would like to see new features, please let me know and we’ll gladly find a way to implement them.

This plugin is constantly being maintained and will continue to evolve with smart new features, gameplay improvements, and more fun mechanics.

Your feedback helps shape the future of this project.