AI Players
Type to search documentation.

Friends and foes

Factions

Group bots and players into teams, and decide who's a friend and who's an enemy.

A faction is a team that bots and players can join together. Factions decide who fights whom, who can give orders to which bots, and who shares a base.

Relations

Every pair of factions has a relation:

RelationWhat it means
AllyFriends. Bots protect allies under attack, and allied players can give them orders.
NeutralStrangers. Nobody attacks unprovoked, but anyone who hits a bot, or robs its base in front of it, earns a grudge. This is the default.
EnemyAt war. Bots may attack enemies on sight (depending on their play style), fight them inside their base and hunt them down. Raiding styles also go after their base’s chests.

Members of the same faction are always allies, and they can’t hurt each other. A player or bot without a faction is neutral to everyone.

Setting up factions

  1. Create the factions. Give each one an id and, optionally, a color for its members’ names:

    Commands
    /aiplayer faction create red red
    /aiplayer faction create blue blue
  2. Add members. Bots and real players join the same way:

    Commands
    /aiplayer faction join red Steve
    /aiplayer faction join red YourName

    You can also put a bot in a faction when you spawn it: /aiplayer spawn Ann aiplayers:rusher blue.

  3. Set the relation. Relations work both ways, so this makes red and blue enemies of each other:

    Command
    /aiplayer faction relation red blue enemy

Members show up with their faction’s color on their name tag and in the tab list, so you can tell at a glance who’s on which side. The locator bar follows the bots’ own rule: a member sees only its own faction’s dots, in the faction’s color, and is never sent anyone of another faction, whatever the relation. A player with no faction sees and is seen by everyone. The config key show_other_factions_on_locator_bar gives vanilla’s bar back (server configuration).

Managing factions

CommandWhat it does
/aiplayer faction listLists every faction.
/aiplayer faction leave SteveRemoves Steve (bot or player) from his faction.
/aiplayer faction relation red blue allyChanges a relation (ally, neutral or enemy).
/aiplayer faction color red dark_redChanges a faction’s color.
/aiplayer faction roles red autoLets the faction hand out its bots’ roles by its size.
/aiplayer faction remove redDeletes a faction.

What factions share

Bots in the same faction work as a team:

  • One base. They build their houses side by side in a shared base and share its chests. See Houses and bases.
  • Enemy sightings. When one bot spots an enemy, every faction mate knows where within a second.
  • Enemy base knowledge. Whatever its bots learn about enemy factions’ bases (where they are, their chests and what’s inside, their gates and golems, the traps laid there and the guard) is shared the same way, within a second of one of them seeing it. See Raiding enemy bases.
  • Villages, Nether and End structures. A village, fortress, bastion, warped forest, stronghold or end city one bot finds is known to all of them. The faction also keeps one shared record of the End: the portal room, the frames filled, the dragon, the egg, the gateway, the city and the elytra brought home.
  • Grudges and thefts. A grudge one bot earns belongs to the whole faction, and they all answer a theft noticed at the base (the counter-raid).
  • The work. They split the work so two bots don’t build the same storehouse or fence at the same time, and roles give each one a specialty.
  • Flocks and machines. The herds of animals a bot has seen grazing, for the next hunt trip, and the base’s machine yard, where every member uses any machine.
  • Help. A bot that needs backup asks the faction in team chat, and the others come.
  • The End. A bot that’s ready for the End calls the faction’s other ready bots, and they go as a party.

Faction roles

Four Turtlers left to themselves dig four mines, farm four plots and fence one base four times over. A faction can instead give each bot a role:

RoleWhat changes
minerMines twice as eagerly, builds half as much.
farmerFarms twice as eagerly, trades more, mines little.
guardFortifies twice as eagerly, hunts enemies more, never explores, and stays home. Once its house stands, it keeps to the base’s yard (and its mine beside it), fights what comes near, hunts enemies sighted within 16 blocks of the yard, works on its gear and the base, and walks back to its door after a fight.
raiderRaids twice as eagerly, explores more, mines little (only for styles that raid in the first place).
freeNo change: the bot plays its style as it is. This is the default.

A role only re-weighs what the play style already wants. Survival, fighting and the tool and armor ladder are untouched, so a farmer still gets its iron pickaxe and a guard still eats.

Set a role by hand, or let the faction hand them out by its size:

Commands
/aiplayer set Ann role guard
/aiplayer faction roles red auto

Under auto, a faction with two active bots has one guard; with three, a farmer too; with four, a miner too. Each role goes to the bot whose style cares most about that kind of work (fortify for the guard, farm for the farmer, mine for the miner). Every other bot whose style raids becomes a raider, and the rest stay free. The faction deals the roles out again whenever a bot spawns into it, leaves it for good or changes faction. Setting any member’s role by hand switches the faction back to manual roles, and /aiplayer faction list shows roles=auto or roles=manual for each faction. /aiplayer info <bot> shows the role on the faction line (faction: red, role: guard (auto)).

Calling for help

Bots in a faction talk to each other, and to you, in the faction’s team chat. A bot calls for help in four cases, and calls its mates together for the End in two more:

Team chat
<Ann> Need help at 120, 64, -80: Alice in iron, I am outmatched
<Ann> Need help at 120, 64, -80: I am raiding the blues base
<Ann> Need help at 120, 64, -80: the wall is more than a day's work alone
<Ann> Need help at 120, 64, -80: I am stuck
<Ann> Going to the End from 120, 64, -80: who is ready?
<Ann> Going to the outer islands from 120, 64, -80: who is ready?

It sends the first when it meets an enemy it would fight on sight but who outgears it, the second when its raid sets out, the third when its fortress wall still has 48 or more blocks to go, and the fourth when three of its tries to get out of a spot it’s stuck on have failed (the escape ladder), while it keeps trying. The last two go out when it’s ready for the End and wants a party. A call needs another faction member online, and a bot makes at most one call every ten minutes per reason.

A couple of seconds later, every bot of the faction within its roaming radius answers:

  • <Ben> Yes, coming if it’s free, fit and not calling itself. It then walks to the caller and waits with it.
  • <Ben> No, I am busy if it’s on an order or on a call of its own.
  • <Ben> No, I am hurt if it’s too hurt to fight.

You can answer too. Type /teammsg yes or /teammsg no (/tm works as well), or press Yes or No on the client add-on’s orders screen, and you count like a bot. You’ve “arrived” once the caller sees you within 16 blocks. The caller waits for everyone who said yes, at least five seconds and at most two minutes (half a minute for a player who hasn’t answered), then acts:

  • Outmatched: if the group is now strong enough, the caller says <Ann> We are enough: attacking Alice, and it fights that enemy together with its helpers, whatever their own odds. If not, it says <Ann> Still outmatched, standing down.
  • A raid: the caller says <Ann> Setting out for the raid. Each bot that came raids the same base with a run of its own and brings its own loot home.
  • A big job: the call ends and everyone goes back to their own work, each by its role.
  • Stuck: a helper walks to the stuck bot, which goes on trying to get free meanwhile.
  • The End: only ready bots answer yes. The others say what they still lack (<Cid> No, I still need my best tools) or No, I do not go to the End. Then the caller says <Ann> Setting out for the End, and the party follows its leader for the whole trip. Players can’t join a party yet.

Helpers follow the caller under an assist order that ends with the call (and lasts the whole trip for a party bound for the End). A restart forgets open calls. The messages only go to the faction’s team chat, not to the operators’ chat.

Free-for-all servers

Want every faction to be at war unless you say otherwise? Set default_relation to enemy in the server configuration. Factions with no explicit relation then treat each other as enemies. Setting it to ally makes everyone friends by default instead.

Technical details

Factions are scoreboard teams

Each faction is a vanilla scoreboard team whose name is the faction’s id, created with friendly fire off, “see friendly invisibles” on and the name tag color from the faction. That’s why players can also join with vanilla’s /team join <faction>, and why faction mates can’t hurt each other. A faction’s display name is its id; change it with /team modify <id> displayName <name>.

Colors

Faction colors are the same team colors vanilla’s /team modify <team> color accepts: black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, light_purple, yellow, white.

Grudges

A neutral player or bot earns a grudge when it hurts a bot, or when a base bot sees it robbing a chest, breaking a building or trampling a plot of its base (offenses). The grudge lasts for the bot’s play style grudge_minutes. It is held by the bot and its whole faction, survives restarts (it’s counted in world time) and is dropped if the target becomes an ally. While a grudge lasts, the target is treated as an enemy. /aiplayer info <bot> lists them with their cause, for example grudges: Alice (9 min) or grudges: Alice (9 min, theft).

Roles under the hood

A role is a map of multipliers over the style’s family weights, applied each time the bot refreshes its profile: miner mine ×2, build ×0.5; farmer farm ×2, trade ×1.5, mine ×0.3; guard fortify ×2, hunt ×1.5, explore ×0; raider raid ×2, explore ×1.5, mine ×0.3. A family the style leaves out counts as 1.0 before the multiplier, except raid, which a role never adds to a style that doesn’t list it. The role is saved on the bot’s roster record (role, free when absent) and the auto rule on the faction’s (auto_roles). A guard’s “yard” is the night’s safe ground: its base’s yard, a mine whose shaft top lies near it, and the walk between. A guard with no house yet plays like anyone else until it has one. /aiplayer list shows role= for each bot.

Last updated Nov 9, 2026