ChatBot
documentation
last revised May 11, 2009

Any comments or questions should be directed to magine@turtleflight.com.
DO NOT SEND ME TELEGRAMS! Grrr!

Overview

This Magsbot script filters all chat in the world(s) in which the bot is run.

Commands (any chat beginning with a / slash or a : colon) are not echoed except to the speaker, and any chat that begins with a ' single quote is echoed throughout all worlds that the bots are running in, but only to people on the controller list. Chat beginning with an exclamation ! is echoed to everyone in every world that the bots are running in. Chat beginning with a # pound sign is displayed in boldface. (Only controllers can use the ' and ! and # features.) Normal chat "fades" with distance. Chat zones can be defined in which chat is limited to people within the zone. An optional list of banned words can be specified that will be replaced with "****" when spoken.

Optionally the chatbot can operate in "global" or "univeral" modes, echoing all chat throughout each world, or throughout all worlds, respectively.

The bot's privilege ID must belong to a world caretaker.

Installation

As with all Magsbot scripts, it is recommended that you create a separate folder for each project. Install Magsbot if you haven't already, and unzip the chatbot files into a separate folder. Also copy magsbot.ini, userdefs.udf, behavior.beh and buttons.btn from the Magsbot folder to the chatbot folder. Then right-click and drag MBot.exe from the Magsbot folder to the chatbot folder, and choose "Create a Shortcut" from the popup menu that appears when you drop the file. Then right-click the newly-created shortcut, choose "Properties", and change the "Start In" box so that it contains the path to the chatbot folder, rather than the Magsbot folder. Now when you want to run the chatbot you can click on the shortcut. If you wish, you can copy the shortcut to your desktop or anywhere else.

Before running the chatbot, use notepad to add these lines to the userdefs.udf file in the chatbot folder:

; console message colors*
@defclr=26214
@zclr=32960
@cmdclr=34816
@xclr=32832
@erclr=16711680
@iclr=10625217 @gcclr=0 @aclr=16711935

; @wind and @ind combined, for searching inventory strings
@ind_[$,$]=@if[@asn[x_,@wind[$cat[~1,":*"],~2,","]],@x_,@ind[~1,~2,","]]

$extract[$,$]=$ftn["(ChatBot)/[TakeFromStr]",~1,~2]
$combine[$,$]=$ftn["(ChatBot)/[AddToStr]",~1,~2]
$censordelims=$cat[$chatdelims,"'",$asc[34],$LF,$tab]

(*You can change the console message colors if you wish. They are the decimal equivalents of the familiar hex color values used in the AW browser, e.g. FF0000 for red, etc. You can use the Magsbot @dec function here instead of decimal values, for example @defclr=@dec["008843"], or you can use the @dec function in Magbot's built-in calculator (F3) to determine the decimal values and put those in the userdefs.udf file.)

Now run the bot (Connection/New Instance) and use the File/Action Buttons/Merge Action Buttons... menu to merge the chatbot.btn file. Press F7 to save the merged files. Next use File/Behavior/Open Behaviors... to load the chatbot behavior file. (It's also possible to merge the standard Magsbot behavior.beh file after loading the chatbot.beh file, but in this case it is not recommended because you want the chatbot to run with all possible speed, and adding the standard behavior increases the processing that Magsbot has to do for each event.)

Once you have all the chatbot instances running that you want, you can click the Create MultiInstance Button on the . tab of the Magsbot Action panel to create a new button that can be used to start all the bot instances again in the future.

When running the chatbot, you should have chat disabled in your world. To disable chat, either use your AW Browser (check "Hide Chat" in the Options/World/Features/Options menu), or you can click the disable chat button on the (Chatbot) tab of the Magsbot Action panel, when the bot is in your world.

Chat Relay

The chatbot automatically echoes chat spoken by a controller that begins with a ' single quote, to controllers in all worlds that have a chatbot instance running in them. (Of course each instance must have caretaker privs in the world it's in.)

To add another chatbot instance, just start it normally (Connection/New Instance) and move it (using the Magsbot Location panel) to the world you want it in. To start an instance in a different universe, simply enter the port and host address on the New Instance dialog when starting the instance.

Chat Modes

There are three modes of operation that can be chosen for the chatbot, using the Set mode button.

The normal mode, "local" mode, is what is described elsewhere in this document: chat is echoed to other persons who are near the speaker, and fades with distance.

In "global" mode, chat is echoed throughout the world that the chatbot is in. If there are several instances of the chatbot, then chat is echoed throughout each world individually, but chat is not transmitted from one world to the others (except by controllers using the relay function, see below).

In "universal" mode, chat is echoed throughout all the worlds that have chatbot instances running in them. In this mode, all chat is treated the same as when a controller uses the relay function.

Regardless of mode, chat within a specific zone (see below) will only be heard by other people in that zone.

Zones

Zones are created and deleted using the zone commands (see below). You can also manage zones from the Magsbot root . tab of the Actions panel, using buttons SetZoneN, SetZoneS, SetZoneW, SetZoneE, SetZoneB, SetZoneT, SetZoneActive, ZoneSetPriority, save zone list, load zone list and ZoneInfo.

Once a chat zone is created, anything spoken within the zone can be heard only by others within the zone. Zones must be rectangular, and aligned on the world grid (i.e., they can't be rotated, the sides must run directly north-south and west-east). Zones can overlap if you give them a different priority, using the ZoneSetPriority button.

IMPORTANT NOTE: When running chatbot instances in multiple worlds, in order for the "ZoneEnter" and "ZoneExit" messages to be properly displayed when someone enters or leaves a zone, each zone's group name must be the world's name.

Censor

If your world is "G-rated" then you might want to censor inappropriate language. To use the chatbot censor feature, first create a text file in the chatbot folder, named "wordlist.txt" and containing the prohibited words, one to a line. If a word in the list has an asterisk * at the end, then any word beginning with that word will match, e.g. "foobar*" in the list would match (and censor) "foobaring" in chat. The list will automatically be loaded when chatbot starts, or you can click Load word list on the (ChatBot) tab of the Magsbot Actions panel if Magsbot is already started.

To activate censoring, you must also click the Censor ON button on the (Chatbot) tab of the Magsbot Actions panel. To deactivate censoring, click the Censor OFF button. The chatbot will remember this setting between sessions.

Optimizing

To help speed up the chatbot's response, it's recommended that you disable some handlers that it doesn't need anyway. To do this, open the Handlers dialog (Options/Handlers...) and uncheck AvatarClick, ObjectAdd, ObjectDelete, ObjectClick, ObjectSelect, ToolbarClick and BotGram. Chatbot doesn't use any of these, but if the handlers are enabled they will generate extra, unnecessary messages from the world server. (The other handlers either are needed, or handle events that are rare or infrequent and so won't cause a problem.)

Controllers

Some chatbot commands (see below) can be used only by world controllers. Use the add controller, remove controller and list controllers buttons on the . tab of the Magsbot Action panel to manage the list of controllers. Press F8 to save changes after adding or removing controllers.

Chat Commands

Anyone:

/who all
Lists people in all worlds that the chatbots are in. If the optional "all" is specified, then bots are also listed.
(Note: if you are using the chatbot in the same world as the RPGBot II, you might want to change this command to "whom" to avoid conflict with the RPGBot's own /who command. Do this by editing the chatbot behavior table row that has HEAR @cmd_[who] in the Event column, changing it to HEAR @cmd_[whom].)
/present
Lists people in the same zone as the speaker.

/mute avname
/unmute avname
Mute or unmute a person so you won't hear their chat.

Controllers only:

' anything
The chat is echoed only to other controllers, in all worlds that have chatbot instances running in them.
! anything
The chat is echoed in all worlds that have chatbot instances running in them.

# anything
The chat is echoed in boldface.

/zone zonename
Create a new zone.

/unzone zonename
Delete a zone.

/zonelist
see a list of zone names

/zoneinfo zonename
See the boundaries for one or all zones.

/zoneactive zonename 0 or /zoneactive zonename 1
Turn a zone off or on. When you first create a new zone, it is off by default, so you need to use this command to activate it.

/zoneN zonename
/zoneS zonename
/zoneW zonename
/zoneE zonename
/zoneB zonename
/zoneT zonename
Set the boundaries for a zone, taken from your current location. For example, stand at the north boundary and say /zoneN. The /zoneB sets the bottom of the zone and /zoneT sets the top of the zone; if they are not given then the zone will have no vertical boundaries. You must say /zoneactive zonename 1 to turn the zone on after setting the boundaries.

/gag avname
/ungag avname
Mute or unmute a person so no one will hear their chat.

/newchat worldname
Start a new chatbot in the specified world.

/die
Shut down the chatbot in the world you're in.

/do magsbot_command_sequence
Perform any command or sequence of commands in the Magsbot programming language (see the Programming section of Magsbot help). NOTE: This command is potentially hazardous, and so it is turned off by default. To turn it on, press Alt-B to open the behavior table, and on the very last row (with the Event HEAR @cmd[do]) double-click the leftmost column so that it changes from Off to On. Press F6 to save the change. Unless you completely trust the people whom you designate as controllers, it's recommended that you leave this command turned off since it could allow any controller to change objects in your world or even run files on your computer!