Plugin PvP Bot (PPvPBot)

PvpBot — Paper Port

A Paper/Spigot plugin that adds AI-driven PvP bots to your server: real fake players with combat AI, a faction system, automatic equipment, pathfinding, and world interaction. Bots fight players, mobs, and each other, using the same tools a real PvPer would.

Need a fabric version? Then check the original Fabric PvP Bot

🎮 Main Features

🤖 Bot Management

• Spawn with unique random names, or from a themed name table you define
• Mass spawn up to 50 at once, from generated names or a named table
• Real Minecraft skins, fetched by username — cooperates with SkinsRestorer if it's installed, registering the fetched skin directly in its own storage so a join listener doesn't silently overwrite it with a default
• Bots never broadcast a join message — they simply appear, no "X joined the game" spam for a squad of twenty
• latest selector reaches whatever your last spawn command produced, so you never have to type out twenty names

⚔️ Combat System

• Full melee AI: swords, axes, and vanilla 26.2 spears.
• Mace combat with real tactics, not just "always mace":
  • Wind-charge or jump launches into a smash
  • Pearl-launch combo — throw a pearl, detonate a wind charge on it mid-flight, ride the resulting teleport far higher than a self-launch ever reaches
  • Deliberately fights with an ordinary weapon some of the time (special-weapon-melee-chance) instead of maceing every engagement
  • Reads an incoming smash and answers with a shield, a dodge.
• Attribute swapping
  • Breach swap
  • Mace stun
  • Spear lunge — chains jabs past the cooldown to close distance with Lunge
• Bow and crossbow combat with draw timing and lead-prediction on strafing targets
• Mace-aware ranged play — a bot remembers for a few seconds after seeing a target holding a mace, and prioritizes loading a Slow Falling tipped arrow against them specifically instead of whatever's next in the quiver
• Critical hits from genuine jump timing, not a flat multiplier
• Miss chance and mistake chance — a bot can hesitate, fumble, or simply whiff
• Turn speed is rate-limited, not an instant snap-aim, so aim visibly swings and lags like a real player's
• A detection system: nothing is a target until a bot has line of sight, is standing close enough to notice regardless, or has been told directly. Crouching and invisibility both genuinely reduce how far off you're spotted from

🪢 Tether (Escort Discipline)

• Keeps a target player within range of a designated leader, using a small escort of bots as the enforcement
• Straying past the radius earns one real, deliberately weak warning hit with a shove back toward the leader — coming back inside the radius clears it, so the next time is a fresh incident, not an instant escalation
• Straying again while still warned (or never coming back) turns the whole escort hostile for real, exactly as if an admin had run /pvpbot attack on each of them, until manually released

🛡️ Utilities and Survival

• Auto-equip the best armour and weapon actually carried
• Auto-totem, with a short deliberate pause before it reaches the offhand
• Auto-shield, auto-food (respects saturation — won't eat past being fed), auto-potion (won't waste an enchanted gapple while a plain one is still in the bag)
• Buff potions only when there's actually a fight to buff for
• Auto-repair worn gear with Mending from nearby XP orbs
• Cobwebs to pin an enemy — rate-limited both per bot and across the whole squad, so ten bots can't chain-web one target
• Water bucket clutch — a genuine MLG on a long fall, tuned by minimum fall height and reaction window, fumbleable like everything else
• Ender pearls to escape when nearly dead, or to run down someone fleeing
• Draining

🌀 Squad Teleportation

Three ways to bring a group of bots somewhere, each reading as a different kind of arrival:

• Portal — scatters real, vanilla-sized nether portals (genuine obsidian frame, lit interior) around the destination and stands each group in one, up to 5 sharing a grounded portal or 3 sharing a floating one. Permanent: they never revert, and bots never get swept through to the actual Nether by them
• Pearl — a real thrown EnderPearl per bot, launched from high above the landing spot so vanilla's own physics bring it down — real flight, real landing pop, real minor fall damage, nothing simulated
• Rift — a themed reality-tear teleport, PvpBot's own twin of ExplosionEvent's Rift: groups onto one or several rifts (or one big shared one), and closes itself instantly behind whoever just came through
• All three share the same selector grammar (bot, all, faction <name>, overfaction <name>, random[...]) and a configurable scatter range around the destination, so nobody lands stacked on top of each other

🚶 Navigation and Movement

• Bunny-hop with per-bot jitter, so a squad doesn't hop in lockstep
• A* pathfinding around obstacles, separate from blind steering
• Building — bridges gaps and pillars up toward an unreachable target using carried blocks (or a wind charge, with no blocks to spare); digs through soft natural cover only — dirt, sand, leaves — never stone or anything player-built. Every placement and break fires the real event, so WorldGuard and similar plugins see and can refuse it
• Boards, places, and steers boats to cross real bodies of water
• Wander mode when there's nothing to fight
• Vanilla-accurate knockback, including the sprint and enchant bonus

👥 Faction System

• Create, disband, join, leave
• Hostile (war) and allied relations between factions
• Overfactions — group several factions into one coalition; everything inside is automatically allied with everything else in it
• A faction leader — one member, bot or real player, whose fights the whole faction joins. Attack them or get attacked by them, and the faction turns on that target
• Per-faction settings overrides — any global setting can be tuned per faction, so a "rookies" faction and a "sweats" faction can share a server
• Weighted kit tables for random loadouts per faction
• Faction-wide follow orders

🎒 Kit System

• Save a kit from your current inventory
• Give it to a player, a bot, or an entire faction
• Persists across restarts

🎚️ Presets

• Switch the whole server's bot behaviour in one command — casual, normal, sweaty, passive ship by default
• Save whatever's currently in force as a new preset
• Layers under faction overrides, so a faction you've hand-tuned keeps its tuning when the server preset changes

📜 Scripts

• Save a list of commands under a name, with {1}–{9} placeholders filled in from what you pass at run time
• wait <ticks> pauses a script and resumes it later without blocking the server
• Runs as whoever typed it, so it saves typing without granting anything extra

---

📋 Commands

Basic

/pvpbot spawn [name|count|names:<table>] [skinFrom|count]
/pvpbot remove <bot>
/pvpbot removeall
/pvpbot list
/pvpbot reload

Combat Orders

/pvpbot attack <bot> <target>
/pvpbot fight <bot> <bot>
/pvpbot stop <bot>
/pvpbot retreat <bot|all|faction <name>|overfaction <name>|latest> [to <player|x y z>]
/pvpbot retreat stop <bot|all|faction <name>>
/pvpbot hide <bot|all|faction <name>>
/pvpbot hide stop <bot|all|faction <name>>
/pvpbot tether <target> <leader> <bot|all|faction <name>|overfaction <name>|random[...]> [radius]
/pvpbot tether stop <target>
/pvpbot tether info <target>

Movement & Positioning

/pvpbot follow <bot> <target>
/pvpbot follow stop <bot|all>
/pvpbot guard <bot|all|faction <name>> <radius> [x y z]
/pvpbot guard stop <bot|all>
/pvpbot tp <bot|all|faction <name>> <player|bot|x y z>
/pvpbot tp portal [ground] <bot|all|faction <name>|overfaction <name>|random[...]> <player|bot|x y z> [range]
/pvpbot tp pearl <bot|all|faction <name>|overfaction <name>|random[...]> <player|bot|x y z> [range]
/pvpbot tp rift [big] <bot|all|faction <name>|overfaction <name>|random[...]> <player|bot|x y z> [range]
/pvpbot pause <bot|all|faction <name>>
/pvpbot resume <bot|all|faction <name>>

Settings

/pvpbot set <setting> <value>
/pvpbot settings [general|combat|movement|utility|ranged|detection|building]
/pvpbot faction set <faction> <setting> <value>

Factions

/pvpbot faction create|disband <name>
/pvpbot faction join|leave <faction> <member>
/pvpbot faction hostile|peace|ally|unally <a> <b>
/pvpbot faction leader <faction> <player|bot|clear>
/pvpbot faction follow <faction> <target|stop>
/pvpbot faction set <faction> <setting> <value>
/pvpbot faction info|list

Overfactions

/pvpbot overfaction create|disband <name>
/pvpbot overfaction add <overfaction> <faction>
/pvpbot overfaction remove <faction>
/pvpbot overfaction info|list

Kits

/pvpbot kit save <name>
/pvpbot kit give <player|bot> <kit>
/pvpbot kit givefaction <faction> <kit>
/pvpbot kit delete <name>
/pvpbot kit list

Presets

/pvpbot preset [name]
/pvpbot preset save <name>
/pvpbot preset delete <name>
/pvpbot preset off

Scripts

/pvpbot script create <name>
/pvpbot script add <name> <command>
/pvpbot script show <name>
/pvpbot script remove <name> <line>
/pvpbot script delete <name>
/pvpbot script run <name> [args...]
/pvpbot script list