PvpBotdocs
Features

Factions

Who fights whom: factions, relations, leaders, coalitions and per-faction settings.

The basics

A faction is a group of members: bots and real players. Everyone is in one faction at a time; joining another means leaving the old one.

/pvpbot faction create bandits
/pvpbot faction join bandits latest
/pvpbot faction join bandits Steve
/pvpbot faction join bandits range 20
/pvpbot faction leave Steve
/pvpbot faction info bandits

join takes a name, a selector or range <blocks>, which adds every bot within that distance of you.

The "player" faction

Every real player who joins the server without a faction is put in the player faction. Anyone you put in another faction (or made a leader) stays there after reconnecting. This lets you declare war or peace on every player in one go:

/pvpbot faction hostile bandits player

Relations

RelationCommandEffect
Neutral(none)Normal behaviour: a bot with auto-target attacks anyone, as if there were no factions.
Warhostile <a> <b>They attack each other on sight. Ends any alliance or peace.
Peacepeace <a> <b>Neither side starts anything. Blasts and sweeps treat them as bystanders. A member who is hit still hits back, and the leader's call to arms still counts.
Allianceally <a> <b>The same side in everything: they don't target each other, no revenge between them, orbital strikes hold fire near an ally. Each faction keeps its own settings.

War and peace rule each other out. unally ends an alliance.

An alliance or one faction? An alliance puts bots of different calibre on the same side: bandits and elite_bandits fight together but with different skill.

Leaders

/pvpbot faction leader bandits Boss
/pvpbot faction leader bandits clear

The leader (a bot or a real player) is always a member of the faction. The whole faction joins the leader's fights: whoever the leader attacks, and whoever attacks the leader, becomes everyone's target. The hostility lasts leader-call-seconds seconds (30 by default, 0 turns it off) and doesn't survive a restart. A leader who logs out is still the leader when they come back.

Following as a group

/pvpbot faction follow bandits Boss circle
/pvpbot faction follow bandits Boss rows 4
/pvpbot faction follow bandits stop

The spacing is follow-distance. Followers fight when attacked, then fall back in. They keep up: a follower more than a few blocks off its spot sprints back; close to it, it walks at full speed while the leader walks, and it only eases in when the leader stops.

Formations

FormationLayout
behindBehind whoever they follow (default).
columnSingle file.
lineSide by side.
rowsRanks of size abreast.
triangleA wedge with the leader at the point.
wallA shield wall in front.
open_circleA ring that leaves the front clear.
square, circle, hexagon, gridLined up with the world rather than with the leader, and they hold their shape on arrival.

The first seven turn with the leader. Bots carrying an elytra form their own rank at the back. A faction keeps a standing formation with /pvpbot faction formation <faction> <shape> [size] (clear takes it off). Slots wobble a little and stragglers sprint-jump to catch up, so it looks like people, not a grid.

Marches

/pvpbot faction goto bandits 100 64 -200 wall
/pvpbot faction goto bandits Steve rows 4 then attack Steve
/pvpbot faction goto bandits status
/pvpbot faction goto bandits stop

goto sends a whole faction to a point or a player in formation. On arrival it holds there (then hold), or attacks a target (then attack <target>).

Uniforms

/pvpbot faction skin bandits SomeAccount
/pvpbot faction skin bandits stop
/pvpbot faction skin list

Puts every bot in the faction in one account's skin. It's kept in factions.yml, so it survives deaths and restarts.

Team play and armies

  • Team play: focus fire on the enemy allies are on and the weakest one; peeling off to save a nearly dead ally; splash heals thrown at allies; regearing one at a time.
  • Reaction ripple: orders and new targets reach each bot after its own moment, nearest first, so a side doesn't turn on one tick.
  • Pile-on cap: no more than three on one enemy; the rest take the next or wait at the edge.
  • Skill spread: each bot's skill sits a little above or below its faction's.
  • Morale: a side that is outnumbered and losing members breaks, the least brave first. A leader close by holds them and rallies the ones that ran.
  • Roles: archers hang back, pearl carriers flank, healers stay with the hurt.
  • Ally care: nobody shoots or sweeps through an ally.
SettingDefaultValuesWhat it does
focus-firetruetrue / falseIn a faction: goes for the enemy its allies are on, and the weakest - low, broken armour, no totem
peeltruetrue / falseLeaves its own fight to hit whoever is on a nearly dead ally
heal-alliestruetrue / falseThrows its splash healing potions at a hurt ally close by
regear-turnstruetrue / falseFaction members regear one at a time instead of all leaving the fight together
SettingDefaultValuesWhat it does
reaction-rippletruetrue / falseOrders, calls and new targets reach each bot after its own moment - nearest first, the odd one late - instead of the whole side turning on one tick
pile-cap30 – 10Most bots on one enemy; the rest go for the next or wait at the edge for a way in (0 = no cap)
skill-spread120 – 30Each bot's skill sits up to this far above or below its faction's, by its name (0 = all the same)
moraletruetrue / falseOutnumbered and losing members, the less brave run (a leader close by holds them and rallies them)
rolestruetrue / falseIn an army: archers hang back, flankers come round the side, healers stay by the hurt
loose-formationstruetrue / falseFormations wobble round their slots, each bot at its own pace, turns ripple down the column, stragglers sprint-jump to catch up
ally-caretruetrue / falseNo arrows through allies, no sword sweep into them, no standing inside each other

Per-faction settings

Any setting can be changed for one faction only. Whatever the faction doesn't set comes from the active preset or from config.yml. /pvpbot faction settings <faction> opens the faction's own settings screen, with what it changes marked, and the difficulty, playstyle and techniques have faction forms too (see Difficulty and playstyles).

/pvpbot faction set rookies skill 20
/pvpbot faction set rookies miss-chance 40
/pvpbot faction set veterans skill 90
/pvpbot faction set veterans elytra-mace true

Faction settings always beat the preset: if you change the server's preset, the factions you tuned by hand stay as you left them.

Random kits per faction

A faction can have a weighted table of kits. give rolls a random kit for each bot using those odds.

/pvpbot faction kit bandits set diamond 30
/pvpbot faction kit bandits set mace 50
/pvpbot faction kit bandits set crystal 20
/pvpbot faction kit bandits list
/pvpbot faction kit bandits give

Weights are relative (here 30%, 50%, 20%) and go from 0 to 1000. A weight of 0 removes the kit from the table, and clear empties it.

Overfactions

An overfaction is a coalition of factions. Every faction inside is automatically allied with all the others: six factions is one command, not fifteen ally calls.

/pvpbot overfaction create north
/pvpbot overfaction add north bandits
/pvpbot overfaction add north pirates
/pvpbot overfaction create south
/pvpbot overfaction add south guards
/pvpbot overfaction hostile north south
  • hostile and peace take two overfactions, or an overfaction and a single faction.
  • overfaction <name> works as a selector everywhere: you can move, retreat or kit out a whole coalition with one command.
  • leader, follow and tp work as they do for factions. An overfaction's leader doesn't join any faction and doesn't survive a restart.