PvPBot

PvPBot adds PvP bots to Paper 1.21.11 that play Minecraft the way real players do.

Most "PvP bots" are NPCs on rails: they run at the nearest player, swing, and die the same way every time. PvPBot bots are different. Each one is a full player entity that walks with vanilla physics, attacks with vanilla cooldowns and uses items through the same code paths a real client does. They strafe and crit, raise shields, break your shield with an axe, eat when they are hurt, pearl away when they are cornered, bridge over gaps, fall out of the sky with a mace, and follow a leader like a real squad.

You can spawn one to practice against, or a few hundred to fight a war.

The goal isn't a bot that fights. The goal is a bot that plays.

⚡ Quick Start

/pvpbot kit create diamond              # save your current inventory as a kit
/pvpbot masspawn 20 diamond red         # 20 bots, wearing it, in faction "red"
/pvpbot masspawn 20 diamond blue
/pvpbot faction red attack blue         # send red at blue
/pvpbot faction red formation wedge     # or line them up first
/pvpbot set red difficulty expert       # change live bots at any time
/pvpbot removeall

That is the whole loop: spawn, kit, faction, difficulty, fight.

⚔️ Combat

Bots fight with real vanilla attacks and real attack cooldowns. Nothing is faked and nothing teleports.

Footwork: sprinting, strafing, circle-strafing, W-tapping, S-tapping, bunny-hop movement
Offense: critical hits, jump resets, hit selection, P-crit, and outspacing (holding the distance where they can hit and you cannot)
Defense: shield blocking, plus axe hits to break enemy shields
Weapons: swords, axes, maces, spears, tridents, bows and crossbows, switched by the situation
Target choice: closest threat, but weighted by how hurt the enemy is, how well armored it is, and how many allies are already on it
Focus fire: a squad picks targets together and defends whoever is hit
Disengage: bots retreat when hurt, heal, then come back into the fight
Modes: hostile, neutral, assist-only, or a frozen training dummy

Difficulty

Four levels, Easy → Normal → Hard → Expert. Difficulty changes how fast a bot turns its head, how well it aims, how soon it reacts, how often it misses, what reach it has and which techniques it uses at all.

Mix them in one command. 50%easy,35%normal,15%expert rolls a difficulty for every bot spawned.

🔨 Maces, Elytras and Spears

The newer weapons get proper behavior instead of being treated as swords.

Mace smashes launched from a ledge, from a Wind Charge, from an Ender Pearl grapple, or from a full elytra dive with fireworks. A bot falling onto a crowd re-targets whoever is directly underneath it.
Breach and attribute swaps between sword and mace, and axe-then-mace combos against shields.
Spear lunges to close a gap in a hurry.
Elytra spear charge. From 16 or more blocks away, with a clear straight line to the target, a bot may take off, boost with fireworks, hold its spear out and drive through the target, piercing anyone lined up behind it. Then it glides down and lands.

❤️ Survival

Bots don't fight to the death by default. They look after themselves.

Eat food and golden apples, drink healing potions, throw splash potions
Buff with Strength, Speed, Fire Resistance, and Turtle Master when it helps
Swap totems into the offhand when health is low, and run a recovery routine after a pop
Keep a shield raised while fleeing
Escape with Ender Pearls and Wind Charges
Cut themselves out of cobwebs
Climb, pillar or dig their way out of a hole, even when there is a gravity block overhead
Restock totems, pearls, Wind Charges, XP bottles and golden apples from a shulker box they carry

Healing and fighting are decided separately, so a bot can tell when staying in the fight matters more than staying alive.

💥 Threat Awareness

Bots notice dangerous situations and respond to them.

Incoming mace smash: shield up, and an archer will shoot a slow-falling arrow at an airborne mace user
TNT minecart PvP: a rail placed nearby sets off a reaction, and depending on the situation a bot builds a wall, breaks the cart, runs, raises its shield, or pearls away
Knockback is ridden out the way a client would, including Wind Charge launches

Reaction time follows the difficulty, so an Easy bot doesn't know everything the instant it happens.

🧠 Movement and Pathfinding

Bots move through the game's own player physics.

A* pathfinding on a shared terrain cache, searched off the main thread
Live re-planning. Routes are refreshed while the bot walks, a late answer is spliced in without stopping it, and open ground gets a straight line with no search at all
Bridging, pillaring, parkour-style jumps, climbing, swimming, doors
Lethal-edge awareness: bots refuse to step off a deadly drop, and avoid lava and fire
Crowd routing: bots path around each other
Learned terrain: places the fleet keeps getting stuck are remembered, across restarts
Digging out when no route exists, but only after going around has failed

🤝 Factions, Groups and Leaders

Bots in a faction never hit each other, and they defend their own
Alliances let factions share a side
Leaders can be a real player or another bot. The squad escorts, follows and protects its leader, and regroups when the leader retreats
Groups split a faction into squads, each with its own leader
A commander bot walks up to you, nods, and then carries out a strike
faction <a> attack <b> sends one faction at another, and moveto marches one to a spot, spread out and pathing around obstacles
stopattack stands a faction down for lineups and screenshots

1 player + 20 PvP bots works the way you'd hope it would.

📐 Formations

19 shapes: grid, circle, arc, line, column, wedge, square, diamond, triangle, cross, saltire, star, spiral, echelon, double line, chevron, shield wall, skirmish and vanguard.

Instant: bots are placed immediately
Smooth: bots walk into position
Leader follow: the formation travels with the faction leader
Spacing is adjustable
Slots are fitted to the real terrain, so a formation squeezes into a corridor instead of standing inside the walls
A formation breaks automatically when any member is attacked

🌀 Portal Waves, Hunts and the Pearl Rod

Three ways to bring bots into a fight with some theater.

Portal waves open a ring of floating nether portals around you, and bots step out of them one after another.

/pvpbot portals random 10 50 red 0.5s kit diamond r100 h8

Hunts are the same thing around somebody else. Every bot that comes out is already after them.

/pvpbot hunt Steve 8 40 diamond red

The Pearl Rod gives you a plain fishing rod. Cast it and reel in: ender pearls drop out of the sky around the bobber, and a bot appears with its kit wherever each pearl lands.

/pvpbot pearlrod 25 red diamond

⛏️ Jobs and Orders

Bots can do more than fight.

Mining: lane-based tunnelling for a block type, or a shared excavation of an area, with TNT demolition when they carry it
Farming: harvest and replant a plot, check chests
Deliveries: carry a shulker box from the leader to a coordinate
Building: covered 3-wide paths and bridges, roofs over a group, and island bridges between End islands
Guard posts: hold a spot, or guard a leader
Patrol routes: hand-placed waypoint paths, walked or sprinted
Golem practice: a bot summons an iron golem, pillars up and fights it

🎙️ Voice Commands

Talk to your army. Faction leaders can give orders out loud, using the PvPBot Voice Link client mod together with Simple Voice Chat.

"Everyone, kill Steve." "Red team, push forward." "Take cover." "Mine down to me."

How it works

The leader installs the Voice Link Fabric mod, with Fabric API and Simple Voice Chat.
They run /voicelink setup once. This downloads an offline English speech model (about 40 MB for the small model up to about 2.3 GB for the biggest). /voicelink model small|medium|large|gigaspeech switches between them.
On the server they are made a faction leader: /pvpbot faction leader add <player> <faction>.
They talk. Orders reach only the bots of the factions they lead. Everyone else is ignored.

Privacy: speech recognition runs on the player's own computer and audio never leaves it. Only sentences that look like bot orders are sent to the server, and they are sent as text.

Who you are talking to

Begin a sentence with whoever should obey, or just open with the command.

address	examples
Everyone	everyone, guys, team, squad, boys, troops
A faction	red team attack blue, blue, push forward
One bot	Andy come here, Nexar Void follow me
The commander	commander kill Steve, red commander come here

Names don't have to be pronounceable. NexarVo1d works as "nexar void", Steve123 as "steve", Pinapple as "pineapple", and a misheard name is fuzzy-matched against the players and bots actually online.

What you can say

category	example phrases
Attack	kill Steve, focus Steve, take out Steve, all on Steve, Steve is our target, don't let Steve escape, kill him (whoever you're looking at), kill the closest guy, red team attack blue
Rush	push them, rush them, go get them
Stand down	hold your fire, stop fighting, cease fire, calm down, stand down
Weapons free	weapons free, fight back, engage
Regroup	come to me, get over here, regroup, stay together, rally
Follow	follow me, stay with me, stick with me
Advance	push forward, move up, move out, let's go, go go go
Hold	stay here, stay put, hold your position, don't move
Alert	watch out, behind you, they're coming, get ready, heads up
Formation	get behind me, form up, fall in, then break formation or at ease
Scatter	scatter, spread out, split up, run for your lives
Look at me	look at me, eyes on me (bots clear a 10-block ring around you, some pillar up, and everyone watches you)
Take cover	take cover, take shelter, build a roof, hide (the group builds a roof over itself, and bots further out sprint in)
Pillar to	pillar up to Steve, tower up to Steve, get to Steve
Bow	bow Steve, shoot Steve, snipe Steve (bots with bows keep range, the rest go melee)
Mine	mine the area, dig here, excavate (the area you're looking at, top-down)
Mine down to	mine down to Steve, dig down to me, tunnel to Steve
Destroy	destroy the area, blow it up, level the area (TNT if they carry it, tools if not)
Tunnel	tunnel this way, dig a tunnel (each bot digs its own tunnel in the direction you face)
Build up	build up, pillar up, get up high (each bot on its own column)
Path	make a path there, build a bridge there (covered bridge to the block you're looking at)
Island bridge	bridge to the next island (the End)
Armor	gear up, armor off, put your best armor on, put your worst armor on
Stop work	stop mining, stop digging, stop building

Every new order replaces the last one: bots drop what they were doing and take up the new task. Armor, "look at me" and "weapons free" are the exceptions, since they sit on top of whatever is running.

A few extra details:

Single words like "stop" or "wait" need an address ("everyone stop") so normal talk doesn't trigger them.
There is a short cooldown between orders to keep misheard chatter from spamming.
Server owners can turn on voice-feedback: true in config.yml to show what the bot heard on the action bar while testing.
Revoke pvpbot.voice from anyone who shouldn't be able to use it.

🎒 Kits

Save your inventory, armor and offhand as a reusable kit, then hand it to a bot, a faction or yourself.

/pvpbot kit create diamond
/pvpbot kit give diamond Steve
/pvpbot faction givekit red diamond

Random kits use weights that are normalized for you, so they don't have to add up to 100:

/pvpbot faction giverandomkit red 5%diamond,25%archer,70%anarchy

👤 Names, Skins and Bot Types

Clean names for normal play
Random "alt-account" names (x8u21wqz, 128s12uwinsok) that don't look generated
Void names with a black skin
Real skins can be pulled from accounts listed in the config
Neutral bots wander and don't fight, frozen bots are training dummies that still take damage and knockback
Quiet spawning: bots from portals, hunts and the Pearl Rod arrive without a join message each

⚙️ Customization

About 70 AI settings cover strafing, tapping, sprinting, crits, shielding, reach, aim speed, reaction time, flee and re-engage health, leash distance, mace and elytra behavior, pathfinding, restocking, pearling, team targeting and more.

/pvpbot settings opens a GUI that edits the defaults for future bots
/pvpbot set <bot|faction|all|global> <setting> <value> changes live bots, one, a whole faction, or everyone

📊 Performance

Built to keep big fights playable.

Pathfinding runs on background threads with a per-tick budget
Terrain is snapshotted once and shared by every bot instead of read separately
Quiet bots out of everyone's sight think less often, and fighting bots always get full attention
Bots keep only a few chunks loaded and don't affect mob spawning
A hardware profile lowers the limits automatically on small servers
/pvpbot performance reports tick time, the full/light AI split, pathfinder load and terrain cache hit rate

Bots survive restarts with their faction, settings, guard posts and patrol routes.

Commands

Everything is /pvpbot ... and needs pvpbot.admin (op by default). Tab completion covers all of it.

Spawning

/pvpbot spawn [kit] [faction] [difficulty]
/pvpbot spawnrandom | spawnvoid | spawnneutral | spawnfrozen      (same arguments)
/pvpbot masspawn <count> [kit] [faction] [difficulty]             (up to 50)
/pvpbot masspawnrandom | masspawnvoid | masspawnneutral | masspawnfrozen | masspawngrid
/pvpbot remove <bot>
/pvpbot removeall
/pvpbot list

Use none to skip the kit or faction slot.

Waves

/pvpbot portals <random|normal|void> <portals> <bots> [faction] [delay] [kit <name>] [r<radius>] [h<height>]
/pvpbot portals stop | close
/pvpbot hunt <target> <portals> <bots> [kit] [faction]
/pvpbot pearlrod <bots> [faction] [kit]

Kits, Settings and Difficulty

/pvpbot kit create <kit> | remove <kit> | give <kit> [bot|player]
/pvpbot give <bot|@bot> <item> [amount]
/pvpbot difficulty <bot> <Easy|Normal|Hard|Expert>
/pvpbot settings
/pvpbot set <bot|faction|all|global> <setting> <value>

Factions

/pvpbot faction list | info <faction> | create <faction> | remove <faction>
/pvpbot faction add <faction> <player|bot> | addall <faction> | addnear <radius> <faction>
/pvpbot faction leader add <player|bot> [faction] | remove <faction|player|bot> | list
/pvpbot faction commander <faction> <bot|clear>
/pvpbot faction givekit <faction|player> <kit>
/pvpbot faction giverandomkit <faction|player> <weights>
/pvpbot faction formation <faction> <shape> [smooth|instant|leader] [spacing]
/pvpbot faction <faction> moveto <x> <y> <z>
/pvpbot faction <faction> attack <faction|off>
/pvpbot faction alliance create|add|remove|delete|list
/pvpbot faction stopattack <faction> <true|false>
/pvpbot faction armor <on|off|best|worst> <faction>
/pvpbot group create <faction> <group> <amount> | disband | list | info | <group> leader add|remove

Orders and Jobs

/pvpbot attack <target|off> <bot>
/pvpbot guard <bot> [radius|here|leader|off]
/pvpbot path create <name> | point create | walk <bot|all|faction> [sprint] | stop | list
/pvpbot mine <bot> <block> <x1 y1 z1> <x2 y2 z2> <seconds>
/pvpbot faction minearea <faction> [radius] [seconds]
/pvpbot farm <bot> <x1 y1 z1> <x2 y2 z2> [seconds]
/pvpbot deliver <bot> <x> <y> <z>
/pvpbot checkchest <bot> <x> <y> <z>
/pvpbot golem <bot> fight | stop

Diagnostics

/pvpbot debug [bot] [watch [seconds]]
/pvpbot performance [on|off|reset]

Permissions

permission	default
`pvpbot.admin`	op	all `/pvpbot` commands
`pvpbot.voice`	everyone	voice orders (they still only work for faction leaders)

Requirements

Minecraft: 1.21.11
Server: Paper
Java: 21
Optional: Simple Voice Chat, so bots join voice chat and voice orders work
Optional: the PvPBot Voice Link Fabric mod on each leader's client, for voice commands

Good to Know

Bots are players with a stub connection. If an anticheat or packet plugin kicks them, exempt them; PvPBot blocks outside kicks and tells you once in the log.
Portal waves build obsidian frames in the world. /pvpbot portals close removes them.
Mining, tunnelling and building orders change blocks. Use them somewhere you can undo.
This is a PvP and testing tool, not something to leave running unattended on a survival world.

Built For PvP

Use it for:

⚔️ Large PvP battles and faction wars
🏟️ Training arenas, aim practice and shield-breaking drills
🧪 Combat and anticheat testing
🤖 AI vs AI fights
🛡️ A player and their personal bot squad
🎙️ Commanding an army with your voice
💥 Events, trailers and stress tests

Spawn them. Kit them. Split them into factions. Pick a difficulty. Form them up, drop them out of the sky, and tell them what to do. Then start the fight.

Vulkans PvPBot

Compatibility

Minecraft: Java Edition

Platforms

Tags

Creators

Details