PvpBotdocs
Features

Combat

How a bot picks targets, how it hits, and which techniques it uses.

A human opponent

PvpBot is built for training and recording, not for winning at all costs. No move is frame-perfect: skill (0–100, default 50) and its difficulty knobs set the speed of the reactions, the timing and the aim of every technique.

  • Mace smashes and elytra hits land a little early or late; crit hops are sometimes mistimed.
  • The axe against a shield comes after the shield is seen; the shield against a smash goes up a reaction late.
  • Weapon-swap combos fumble now and then. Practised moves, like the mace stun or the pearl launch, come off most of the time.
  • Arrows and pearls are a little off and react late to a juke.

Even at 100 there is a gap to play around. Reach is a player's (melee-range: 3.0, measured like vanilla, from the eyes to the hitbox), aim turns at a limited speed (turn-speed) and ping-millis simulates a real connection's latency.

On top of that come miss-chance (swings missed on purpose) and mistake-chance (hesitating or panicking at the decisive moment). Strafing adds at most 15 points of miss chance, so a strafing bot doesn't whiff for show.

Aim that decides hits

A swing lands where the crosshair is, the way a player's client picks what it hits, not "in reach, then a dice roll". The bot:

  • sees you a moment late (the tracking knob);
  • flicks onto you like a hand: a touch of overshoot, then it settles;
  • carries a small tremor (aim) and aims at the upper body.

It holds a ready swing until its crosshair is on you, for as long as its patience lasts. Walking a straight line or circling steadily gets you hit; a juke inside its reaction time makes it whiff. A whiff costs it the attack meter, as it does a player.

SettingDefaultValuesWhat it does
aim-hitstruetrue / falseIts swing lands where its crosshair is: it aims a moment late, flicks and settles, and whiffs a juke (off: the old in-reach-and-a-dice-roll hit)
aim-height7030 – 95Where on the body it aims, percent of height from the feet - each bot a little higher or lower

Picking a target

  • auto-target: the bot looks for the nearest enemy within max-target-distance by itself. target-players and target-passive-mobs decide whether players and passive mobs count.
  • revenge: it hits back at whoever hits it. bot-vs-bot: bots attack each other without orders.
  • Factions decide who is an enemy, an ally or at peace.
  • priority-hp-target: at equal priority it prefers the target with the least health.

Detection

With detection on, a bot only knows about a target if:

  • it can see it;
  • it is very close (detection-touch-radius);
  • or it was told about it by an order.

After losing sight it remembers the target for detection-memory-ticks. Crouching, being invisible or wearing no armour shortens the distance you're noticed at.

Senses

  • View cone: someone behind a bot isn't seen until they're heard or they hit it.
  • Hearing: sprinting (walking at half the range, crouching silent), fighting, a totem going off, eating and pearls make it stop and turn to look. A pursuer it is already fighting is tracked by ear.
  • Blindness and Darkness blind it: it only notices someone within touching distance, though it remembers who it was fighting.
SettingDefaultValuesWhat it does
fov12030 – 360How wide it sees, in degrees: someone behind it is not seen until heard or felt (360 = all round)
hearing160 – 32Blocks it hears sprinting, fighting, eating and pearls from, and turns to look (0 = deaf)

It doesn't attack at once

A new bot leaves players alone for spawn-grace seconds. When it notices a player by itself, it sizes them up for reaction-ticks before attacking. A hit, an order or a faction war is answered at once. The opening walk-in comes after that.

Melee

Swords, axes and spears. The bot keeps a fighting distance (melee-standoff) instead of walking into you, and swings every attack-cooldown ticks.

The techniques, each switchable on its own:

SettingTechnique
crits, crit-chainCrits from a real jump, back to back if wanted.
cooldown-trickSwings at 92% cooldown: sooner than a full charge, but still past the 90% vanilla needs for a crit, sprint knockback and a sweep, so it combos properly.
hit-selectWaits for a favourable angle and spacing.
d-tapSideways sprint reset after a hit.
mirror-punishHits back mid-air off your own knockback.
sweep-hitSweep attack when 2 or more enemies are on it.
shield-disableSwitches to an axe against a raised shield (shield-disable-chance of the time).
shield-read-windupRaises the shield when it reads your crit windup.

The shield goes up only when you can actually hit it right now, not in every gap between the bot's own swings.

Fighting smarter

  • Hotbar only: in a fight it uses its hotbar and off-hand. Anything in the bag means opening the inventory: it stands still, can't swing, and moves the item over. That takes about 0.2–0.45 s for a good bot and 0.7 s for a weak one, with the odd fumble, and with you close it backs off a few blocks first. Between fights it refills its hotbar the way its kit laid it out.
  • Damage model: it ranks weapons by the damage they do through your armour (toughness, Breach, Protection, Resistance, crits) and times heals by how fast it's losing health. It backs off sooner when losing the trade and stays in when winning.
  • Reads you: how often you shield, jump-reset and strafe each way, when you pearl, how many totems and gapples you use. A shield player gets the axe every time, a jump-resetter gets crits, a pearl gets followed, and low with no totem showing means all in.
  • Shield game: it drops its shield to a charged axe instead of feeding it, goes all out while yours is down, and keeps out of reach while its own is.
  • Edges: it walks round to knock you toward the void, lava or a drop, and keeps its own back off edges.
  • UHC tools (off by default, because they change blocks): lava at your feet taken straight back, fire under you, a couple of blocks to hide behind while it heals.
  • Looks at what it uses: it looks at the block before it places water or a block, scoops water back, or breaks something, and its arm swings like a click.
SettingDefaultValuesWhat it does
hotbar-onlytruetrue / falseIn a fight it uses its hotbar and off-hand; anything in the bag means opening the inventory - standing still for a moment - and it refills its hotbar between fights
damage-modeltruetrue / falsePicks weapons by the damage they do through your armour, and fights, heals and backs off by who is winning the trade and how fast it is losing health
read-opponenttruetrue / falseLearns your habits in a fight: axes a shield player every time, crits a jump-resetter, follows your pearls, goes all in when you are low with no totem up
shield-gametruetrue / falseLowers its shield to an axe about to land, punishes the five seconds your shield is down, and keeps its distance while its own is
edge-playtruetrue / falseLines its hits up to knock you toward the void, lava or a drop, and keeps its own back off edges
lava-playfalsetrue / falseUHC: pours lava on you and takes it back, and lights fire at your feet (needs a lava bucket / flint and steel; changes blocks)
block-offfalsetrue / falseWalls itself off with a couple of blocks while it heals (needs blocks; changes blocks)

Mace

With mace on, the bot uses the mace with tactics, not at every chance. The individual moves (swaps, dashes, stun slams, finishers) are on Mace and spear techniques.

  • Launch and smash: it launches with a wind charge or a jump only when the smash can land: close enough, shield down, target not running, and a few seconds between launches.
  • Pearl launch (mace-pearl-launch): throws a pearl and pops a wind charge on it mid-flight, going far higher.
  • Not always the mace: special-weapon-melee-chance of the time it fights with an ordinary weapon.
  • Wind Burst: a smash with a Wind Burst mace throws it back up for the next one (jump-reset chains smashes).
  • Defence: against an incoming smash it raises a shield (mace-defence-shield), gets out of the way (mace-defence-flee) or takes it. Alone under a mace player it holds its ground near the landing spot, ready to shield, and a dodge is a late sidestep. mace-totem-chance of the time it keeps a totem in the offhand instead of a shield, and with a smash about to land it may take a totem in the main hand.

Elytra mace

With elytra-mace (needs elytra, rockets and a mace) the bot:

  1. climbs on rockets above the fight, to elytra-mace-height blocks;
  2. dives at where you're heading;
  3. smashes without landing: it drops the glide for the swing and picks it up again straight after, as a player does;
  4. climbs back up for another pass.

Rocket-speed dives often overshoot, whatever the skill, and turn wider; a last-moment sidestep gets out of the way. With rockets it makes two passes a flight at most and rests 9 to 14 seconds after one. Coming down is a steep spiral and a short drop, so bots don't glide on until they hit the ground. With elytra-chain a Wind Burst smash chains straight into the next pass (see techniques).

With no rockets it builds a real smash from whatever height it has: if Wind Burst, a wind charge, a pearl or a drop takes it up high, it glides toward you, then closes its wings and drops once a fall would land on you, so every block counts. A Wind Burst hit throws it up for another go, three at most.

Against someone on an elytra

A bot on the ground watches the glider and reads the dive from how they fly, not from what's in their hand. It gets under a roof if there's one close, and otherwise keeps moving. It shoots you while you climb. When you dive, it puts its shield up facing you or sprints across your line once you're committed. It heals in the gap between dives and drops a bite when a dive is coming. When you land, it fights you normally.

Cart PvP

With cart-pvp (needs a Flame bow, arrows, rails and TNT minecarts) the bot:

  1. draws the bow and looses;
  2. puts a rail and a TNT minecart in the arrow's path;
  3. the arrow sets the cart off at your feet.

Before doing it, it works out the damage with vanilla's own explosion formula (distance, blocks in the way, armour, Protection, difficulty). It only goes ahead if:

  • the trade favours it;
  • its average damage taken is under cart-max-self-damage;
  • not even the worst roll can kill it (unless it holds a totem);
  • no ally is in the blast.

The bow only comes up once there's a spot that works, so it doesn't stand there with a drawn bow. When shooting first would hurt it too much it sets and pops: rail and cart down next to you, out of its own blast, then a quick arrow while you're still on it.

Weapon swapping

attribute-swap is the master switch for three techniques:

  • breach-swap: hits with a sword carrying the mace's Breach/Density enchantments;
  • mace-stun: an axe to break the shield, then the mace straight after;
  • spear-lunge: chained spear jabs to close distance (needs Lunge).

The rate limit is swap-cooldown. The newer swaps are on Mace and spear techniques.

Bows and crossbows

  • Holds ranged-optimal-range and switches to melee under ranged-min-range.
  • With arrow-prediction it leads moving targets.
  • Fires in volleys (ranged-volley-size), then stops for ranged-rest-ticks and closes in.
  • Against mace users: if it saw you holding a mace in the last few seconds, it loads a Slow Falling arrow first.

More items

Each one only when it's on the hotbar: a fishing rod to reel a runner in, the trident (thrown, or ridden with Riptide), splash potions of Weakness, Slowness, Harming and Poison, firework crossbow ammo, the spear charge, and block clutches (slime, hay, cobweb, powder snow) when there's no water.

SettingDefaultValuesWhat it does
fishing-rodtruetrue / falseHooks you with a fishing rod and reels you in - off a ledge, toward lava, back from running
tridenttruetrue / falseThrows its trident (and waits for Loyalty to bring it back), rides Riptide in rain or water
crossbow-ammotruetrue / falseLoads firework rockets from its off-hand into a crossbow for burst damage
throw-potionstruetrue / falseThrows Weakness, Slowness, Harming and Poison at you
spear-chargefalsetrue / falseHolds use with a spear as it runs in - the charged spear attack (check it on your version)
block-clutchtruetrue / falseWithout water, clutches a fall with a slime block, hay bale, cobweb or powder snow

Survival

  • Totems (auto-totem): into the hand under totem-health, after a short pause (totem-delay-ticks). The off-hand can prefer a totem, a shield or pick for itself.
  • Food, shield, potions: eats without waste (at three hunger bars), blocks when hurt, drinks healing potions and eats golden apples. It won't use an enchanted apple while it has a plain one. Buff potions (buff-potions) only when there's actually a fight.
  • No starving on golden apples: bots keep golden apples for healing, but with nothing else to eat a bot eats a plain one at three hunger bars, and an enchanted one only at one bar.
  • Healing: it buys a gap before it heals (a knockback hit, a web on you, or a short pearl) instead of eating in your face; healing: old brings back the plain behaviour. While a gapple or potion is up it eases back facing you, strafing from side to side, and each heal starts at a slightly different health.
  • Retreat (retreat): backs off when low, along the open ground rather than a straight line: the most open way out that still leads away from you (never into a wall or off a drop). It runs a few blocks on a weaving line, glances back and heals on the move, circles at a distance if it has to wait, and comes back once the heal has taken. Cornered, it turns and fights instead of pressing into the wall.
  • Answers to combos: it reacts to being comboed instead of eating every hit.
  • Pearls (pearls): to escape when nearly dead or to chase someone running away.
  • Water: an MLG bucket on long falls (water-clutch), looking where it places it, and scoops up the water you place (drain).
  • Repair (auto-repair): mends gear with Mending by collecting XP.
  • Enemy stashes (break-stashes): breaks the shulker box or ender chest you place mid-fight.
  • Shields against explosions: when lit TNT, a TNT minecart, a creeper about to blow or an end crystal next to an enemy is close, the bot turns to it, puts its shield up just before it goes off and stays still until it does. A shield blocks a blast from the front completely: in our test, TNT three blocks away did 15 damage without a shield and under 1 with it.
  • Running low: it regears from its ender chest or a shulker box.
SettingDefaultValuesWhat it does
healingadvancedadvanced / oldHow it heals under pressure: advanced buys a gap first (knockback hit, web or short pearl), old just heals where it stands or runs
offhandautoauto / totem / shieldWhat it keeps in its off-hand: auto (shield while healthy, totem when low), totem, or shield
offhand-totem-hearts4.00.5 – 10Hearts at which a shield off-hand gives way to a totem (offhand: shield only)
mace-totemtruetrue / falseA totem in its main hand while a mace is about to land on it and its off-hand has none
combo-answerstruetrue / falseBeing combo'd gets an answer: a crit back instead of a flat trade, a pearl out once it is clearly lost
hunger-stoptruetrue / falseStops to eat at three hunger bars whatever it is doing, taking its best plain food

Cobwebs

With cobwebs on, webs are held out, looked at and swung, not a block appearing in a sword hand. They can predict where you walk, web your head against a wall, or knock you back and web where you land. cobweb-global-cooldown stops a squad from chain-webbing you.

Cutting out of a web: shears first (keeping the web), then water, a pearl, then a sword.

SettingDefaultValuesWhat it does
web-predictionfalsetrue / falseWebs the ground an opponent closing in is about to walk onto, not the ground they are on
head-webfalsetrue / falseWith a wall behind the opponent, hits them into it and webs the block their head rises into
hit-webfalsetrue / falseHalf its webs: a knockback hit first, then the web where they land
web-drain-chance1000 – 100Percent of chances it takes to scoop up someone's escape water
web-cuttruetrue / falseCuts itself out of a web: shears first (keeping the web), a sword when it has no bucket or pearl

Escapes

Chorus fruit when webbed and boxed in, and water on its own feet when burning.

SettingDefaultValuesWhat it does
chorus-escapefalsetrue / falseWebbed and boxed in, it eats a chorus fruit to teleport out
fire-escapefalsetrue / falseBurning with no fire resistance, it pours water on its own feet and takes the water back

Orbital Strike Cannon

With orbital on, a bot carrying the datapack's rods uses them without blowing itself up. It works with the V8 rods (nukes from 5 to 31 charges, stabs from 50 to 275, normal or infinite) as well as the old ones.

V8 doesn't drop the strike where the bobber lands, it drops it wherever the bot is looking, on the first solid block. So before firing, the bot checks that same spot, and keeps checking until the strike goes off. If a wall or a tree is in the way and the strike would come down on top of it, it doesn't fire.

It only fires from outside the blast. We measured the blasts on a server: a 5-charge nuke reaches about 10 blocks, 10 charges about 60, 15 about 95, 20 about 135, and 25 or more goes past 150. A stab is a column roughly 5 blocks wide. The bot stays that far away plus a bit extra, and runs after firing anyway. It won't fire if a teammate or a faction it's at peace with is in range, and it never uses an orbital rod to reel someone in like a normal fishing rod, since casting one fires it. The datapack's double-click setting can be on or off.

Big nukes need a server setting On Spigot's default max-tnt-per-tick: 100 in spigot.yml, nukes of 10 charges or more just hang in the air and never land. Set it to something like 5000 and restart.

Stasis

stasis (off by default) blocks a killing hit and pulls the bot away like a pearl, healing it to half health. It's used per faction (/pvpbot faction set bosses stasis true) for characters that must not die.