Skip to main content
Hashnode
Mohamed Gado

phBot xControl commands: run a whole party of bots from in-game chat

Updated 7 min readMarkdown
M
Mohamed Gado

xControl is a phBot plugin that turns chat into a remote control. You run it on every bot in a party, add one or more leader names to its list, and from then on any message a leader sends that matches a command is carried out by every bot that hears it. Type START in party chat and the whole party starts botting. Whisper FOLLOW to one character and only that one follows you.

It is one of the ten phBot plugins I maintain. The original was written by JellyBitz; my version adds commands, walk-script commands and a new tab. Every argument and default below is read from the source of xControl 1.9.1, not from memory.

How do I set up xControl?

  1. Download xControl.py from the plugin repo and put it in the Plugins folder inside your phBot folder.
  2. Restart phBot. The plugin gets its own tab, named xControl.
  3. On each bot, type the leader's character name into the box under Party Leaders and press Add. The list is saved per character, so you do this once.
  4. Log the leader in and type a command in chat.

Three rules decide whether a command runs:

  • Only leaders are obeyed. A message from anyone not on that bot's leader list is ignored, whoever sends it.
  • Commands are uppercase. The plugin compares text exactly, so START works and start does nothing.
  • The chat channel picks who reacts. Party chat reaches every bot in the party. A private message reaches one bot. All chat reaches every bot close enough to see it.

Arguments are separated by spaces. Below, <name> is required and [name] is optional.

Which commands start, stop and move the bots?

Command What it does
START Starts botting.
STOP Stops botting.
TRACE [player] Starts phBot's trace on a player. With no name it traces whoever sent the command.
NOTRACE Stops tracing.
FOLLOW [player] [distance] Follows a player at a distance. Defaults: the sender, at 10. FOLLOW 5 follows you at 5; FOLLOW Gado 3 follows Gado at 3.
NOFOLLOW Stops following.
MOVEON [radius] Walks to a random point within the radius, default 10. Handy for unsticking a bot.
SIT Sits down or stands up.
JUMP Plays the jump emote.
DC Disconnects the bot.

How do I change where the bots train?

Command What it does
SETPOS Sets the training position to where the bot stands now.
SETPOS <x> <y> [region] [z] Sets the training position to those coordinates.
GETPOS The bot whispers its X, Y, Z and region back to you. Use it before SETPOS with coordinates.
SETRADIUS [radius] Sets the training radius. With no number it resets to 35. A negative number is made positive.
SETAREA <name> Switches to a training area you saved in phBot, by name.
SETSCRIPT [path] Sets the training walk script. With no path it clears the script.
PROFILE [name] Loads a phBot profile. With no name it loads Default.

How do I teleport, return or revive the party?

Command What it does
TP <source> <destination> Teleports through a teleporter, naming both ends. Separate them with a space or a comma.
TP <destination> Looks for a nearby teleporter NPC that goes there and uses it.
RETURN Uses a return scroll after a random 0.5 to 2 second delay, so the party does not leave in the same tick. A dead bot revives at its return point instead.
RECALL <npc> Sets the return point at a town NPC standing nearby.
R <player> Uses a reverse return scroll to that player.
REVERSE return Reverse return scroll to the last return point.
REVERSE death Reverse return scroll to where the bot last died.
REVERSE player <name> Reverse return scroll to a player. Same as R.
REVERSE zone <name> Reverse return scroll to a zone.

Which commands help in PvP and job runs?

Command What it does
ZERK Activates Berserk.
CAPE [color] Puts on a PvP cape: red, gray, blue, white or yellow. CAPE off removes it. With no colour it picks yellow.
EQUIP <item> Equips an item from the inventory whose name contains the text, ignoring case. trader, hunter, thief and job pick the matching job suit.
UNEQUIP <item> Takes an equipped item off, matched the same way. UNEQUIP job removes the job suit.
MOUNT [pet] Mounts a horse, or a summoned pet of that phBot pet type. Default: horse.
DISMOUNT [pet] Dismounts, same defaults.
TERMINATE Dismisses the summoned pet.

EQUIP trader followed by START on a caravan party is the whole job-suit swap in two messages.

What about items, party and chat?

Command What it does
USE <item> Uses an inventory item whose name contains the text. Unlike EQUIP, this match is case-sensitive, so type the name as the game spells it.
SORT Sorts the inventory.
GETOUT Leaves the party, if the bot is in one.
CHAT <type> <message> Makes the bot speak. Types: all, party, guild, union, stall, global.
CHAT private <player> <message> Sends a private message from the bot. note takes a player the same way and sends a note.
INJECT <opcode> [true|false] <bytes...> Sends a raw packet to the server: the opcode in hex, an optional "encrypted" flag, then the data bytes in hex. For people who know the packet they want; xPacketTool is the safer way to find one.

Can xControl run from a walk script?

Yes. xControl adds five commands that phBot walk scripts (.txt) can call. They use commas, like every script command:

Script command What it does
chat,<type>,<message> Sends chat. chat,private,<name>,<message> and chat,note,<name>,<message> take a player name first.
pinvite,<name>[,<name>...] Invites each named player standing nearby to the party, creating the party if there is none.
wait_party,<count>[,<timeout ms>] Pauses the script until the party has at least that many members. The timeout defaults to 60 seconds.
use_scroll,<keyword> Uses the first item whose name contains the keyword, ignoring case. If it is in a grab pet, it moves it to the inventory first. Example: use_scroll,Random Awaken.
leaveparty Leaves the party, like GETOUT.

A script that gathers a party before a run looks like this:

pinvite,Alpha,Bravo,Charlie
wait_party,4,90000
chat,party,START

The bot that runs it sends START in party chat, and every party bot with that character in its leader list starts.

Why does a command do nothing?

Check these in order:

  • The sender is not on that bot's leader list. The list belongs to each bot. Adding the leader on one character does not add it on the others.
  • The command was typed in lowercase, or with extra text before it. The message has to start with the command.
  • The bot cannot hear the channel. A private message reaches one bot. Party chat only reaches bots in your party.
  • The item or NPC name does not match. EQUIP and USE search by part of the name; RECALL and TP <destination> need the NPC near the bot.

The phBot log shows a line for most commands, including the failures (Plugin: ...), so read it first. If you are writing your own plugin on top of this, the phBot Python API guide covers the handle_chat hook xControl is built on.

About the author

  • Mohamed Gado
    Senior Software Engineer with 6+ years building web and mobile products in React, Next.js and React Native. I build and ship Masareef and Rafiq on my own. Originals live at mohamedgado.com/writing.

Comments

Join the discussion

No comments yet. Be the first to comment.

More from this blog