An AI Script for eggdrop bots

This manual is © James Seward 2002/3james@jamesoff.net

http://bmotion.sourceforge.nethttp://www.bmotion.net

2

Welcome to bMotionHi there!

bMotion is a kind of AI script for eggdrop bots. It is written in a different style to things like ELIZA and the MegaHAL module. Those trigger on keywords and attempt to have a conversation.

bMotion started as a hobby of mine during my fi nal year at University. It was something I’d pondered writ-ing, and I wanted to try to learn some TCL (the scripting language supported by eggdrop). It started out very simple, but one thing lead to another, and now roughly 18 months later it’s 12100 lines of code.

It is designed to become a member of the channel. It’ll laugh with you, it’ll comfort you when you’re upset, and best of all it’ll sprout random (hopefully amusing) stuff like “cabbages.” You can try to have a conversa-tion with it, but you might die trying.

bMotion represents a considerable investment in my own personal time, and also that of my friends, who have not only put up with broken code, bad ideas, and poor jokes from me at 2 am, but have encouraged me, offered suggestions/coding help/coffee, and grown to love the bots. (I hope.) It has been an interesting exercise in coding and also interaction. Many times I added a feature to the bot and invited people to try it, only for them to immeidately do something I hadn’t thought to handle. Giving the bot the ability to deal with all kinds of input has taught me a lot about the English language and processing it.

I’ve also learned that less is defi nitely more. The most natural assumption would be that for something like this, the more output you can generate, the better. Wrong. Studies* have shown that the less often something happens, the more people will accept it. This is especially true in bMotion’s case where it’s generating out-put from a fairly fi nite list of things, so is prone to repeating itself if you’re not careful. I think that I’ve got the balance right now.

Because of the complexity of bMotion, it can be daunting and perhaps diffi cult to setup and use. I’ve been writing this software for a long time now, and it’s surprisingly hard to write documentation for something like that — to make sure you get all the details down on paper and so on. If you fi nd it tricky or confusing to operate, give it some time... it at least deserves it doesn’t it? :)

Also, because this has been my hobby and mainly operating in a channel of friends, bughunting hasn’t been my highest priority. That’s where you, the Open Source Software User comes in. Please, feel free to report bugs in the proper direction (SourceForge’s bugtracker for this project is the best place). If you’re so in-clined, have a go at writing your own plugins; I’d love to see what people do with my work. Finally, excuse the documentation, I’m working on it :D

Most importantly, have fun! (Great, now I sound like a SuSE motd fi le.)

* Ok, one study. Of #exeter. And that’s more annecdotal evidence than an offi cial study.

3

Installing bMotionSo you want to install bMotion?

Good.

You’ll need the following:

• bMotion’s code• An eggdrop, already set up and working. (If you don’t know how to do this, or what I’m talking about, stop reading right here.)• A cup of coffee

Version requirements:• eggdrop 1.6.x (where x is reasonably high)• TCL 8.3 or better

(bMotion may work to a varying degree on older versions, but you’ll get errors probably. If you’re using older versions (check .status) then I strongly recommend you upgrade.)

To get the latest bMotion release source, download it from www.bmotion.net.

If you’re feeling daring, you can run the CVS code. The CVS version is always the latest version, but it may have half-complete features and may even crash your bot (however, I’m not in the habit of knowingly com-miting code that kills eggdrop to CVS... after all, it’s what my bot runs).

You can get bMotion by anonymous CVS from SourceForge.

cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/bmotion login

(at the password prompt press enter)

cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/bmotion co bmotion

(bMotion will try to load customised versions of certain fi les (see the manual for more on customising), and the settings fi le is one of them. For easier upgrades, copy modules/settings.tcl to modules/settings_BOTNETNICK.tcl (where BOTNETNICK is the value from the ‘set botnetnick ...’ line in your eggdrop’s confi g). Edit that fi le instead of settings.tcl below.)

4 5

Installing the files

Once you have your bMotion code, eggdrop, and coffee do the following:

Put the bmotion...tar.gz file in your eggdrop’s scripts directory (usually .../scripts).Run tar zxvf bmotion...tar.gz (substituting the proper filename). This extracts the bMotion code to .../scripts/bmotion/.If you want to move the code somewhere else, do so now.Change into the bmotion directory, and edit bMotion.tcl with your favourite editor. The first two lines of code should look like this:

set bMotionModules “scripts/bmotion/modules”set bMotionPlugins “scripts/bmotion/plugins”

If you put bmotion somewhere else, edit these two variables to match. Close and save the file.

Now change into the modules directory. Fire up your editor and open settings.tclThis file contains (brace yourself) all the settings for bMotion. You WILL want to change these, so pay at-tention:

set bMotionInfo(gender) “male”This sets the bot’s gender. Choose from “male” or “female”

set bMotionInfo(balefire) 1A somewhat traditionally-named setting. This determines if the bot responds to things not directly addressed to it that you wouldn’t want more than one bot to answer. If you have only one bMotion bot on a channel, set it to 1, else set it to 0 on all but one of the bots.

set bMotionInfo(randomChannels) { “#molsoft” “#ags” “#exeter” “#namcoarcade” “#star-trek” }This is the list of the channels bMotion should be active on. If the bot’s on a channel not listed here, it will ignore all bMotion commands/events there. Putting a channel in here that the bot isn’t on will likely cause TCL to strop, so get it right.Remember, bMotion can be annoying, so only put it in channels where you have the right to, and where it will be welcome.

set bMotionInfo(orientation) “straight”Set the bot’s sexual orientation. Choose “straight”, “bi”, “gay”, or “lesbian”

set bMotionSettings(needI) 1Set this to one to require users to have the global I (that’s capital i) flag for most of bMotion to respond to them. This flag isn’t used much now anyway. Set it to 0 to have the bot treat all users equally.

set bMotionSettings(melMode) 0Set this to 1 to make the bot ignore its morals and sleep with anyone, regardless of gender or orientation.

set bMotionSettings(botnicks) “nt|bots|the bots”This is an important one. It defines the names your bot understands as referring to itself. (My bot is called NoTopic, so the first field is nt). List all the names it should respond to, separating them with a | (shift-\ on my keyboard). Case doesn’t matter. Don’t use parentheses — ( and ). You don’t need to include the bot’s IRC nick, it will always respond to that.

4 5

set bMotionSettings(typos) 7A factor affecting how many typos the bot should make. 100 will make the bot make typos almost continu-ously, 0 will stop it. (This is used by the output_typos plugin. See the section on Managing bMotion for more information about turning plugins on and off.)

set bMotionSettings(colloq) 10A factor affecting how much the bot will use (English) colloquialisms (common expressions). Values are 0 to 100 as above.

set bMotionSettings(noPlugin) “simple:huk,complex:wb”If you don’t want bMotion to load a plugin ever, but don’t want to delete the file, list them here using <type>:<name>. You can list more than one by separating them with commas. See the Managing bMotion chapter for more information.

set bMotionInfo(minRandomDelay) 20set bMotionInfo(maxRandomDelay) 120These two settings control how often the bot does random things (like going “lalala” and stuff). The first sets the minimum length of the gap between events, and the latter sets the longest delay. bMotion will pick a value between the two. These values are both in minutes.

set bMotionInfo(maxIdleGap) 45This setting stops the bot talking to itself. During bMotion’s early days, it was common for it to chatter (“lalala”) to itself overnight even though everyone else in the channel was idle. If there has been no activity on a channel for more than this many minutes, bMotion will keep quiet (or set itself away until people start talking again).

set bMotionInfo(brigDelay) 30This is the number of seconds someone should be kept in the brig before being tried by the courtmartial plugin.

set bMotionSettings(leetRandom) 0.5How often the bot should say something in 1337-speak randomly. Values are 0-100.

set bMotionSettings(languages) “en,nl”set bMotionInfo(language) “en”Choose the languages bMotion thinks it can speak. Changing these won’t actually make the bot speak a dif-ferent language; they change which plugins it loads. Currently, bMotion ships with just English plugins (and about 2 Dutch ones). Don’t change this unless you know you have other languages available. See the Man-aging bMotion chapter for more information.

Save and close settings.tcl

Back up to your eggdrop directory and open your bot’s config file. Scroll to the end section where the source ... statements are to load scripts, and add:

source scripts/bmotion/bMotion.tcl

(If you put bMotion somewhere else, adjust this.)

Save and close the configuration file.

Optional

6 7

bMotion saves some information about users in the userfile, and you may want to set/edit these directly (in-deed, you’ll need to make this change in order to take advantage of the feature in bMotion).

Change to your scripts directory, and open userinfo.tcl (the filename may be slightly different).

Find the line that looks like this:set userinfo-fields “URL BF GF IRL EMAIL DOB PHONE ICQ”

Add “GENDER IRL” to the list. Save the file.(End optional section).

Ok. Now for the important bit.Rehash your bot (/msg <botnick> rehash <password>, or .rehash on the partyline).If all goes well, you should see something like:

[21:13] bMotion v 1.19 2002/11/19 19:54:55 james AI online (randoms file: $Id: abstracts.tcl,v 1.25 2002/11/18 23:28:58 james Exp $)

...as your bot starts up.

If you get an error, refer to the currently non-existent Troubleshooting section. (Sorry, until I get feedback on what goes wrong for people I can’t really write that bit.)

If you do require assistance, try me in #bmotion on EFNet. Don’t ask for help in any of my other channels because I shall taunt you.

To check it’s working, try typing .bmadmin status on the partyline.

Drink the coffee.

Linking bMotion Bots

bMotion bots can make each other talk in the channel, which can increase the “human” effect by making them react to each other. They don’t actually react, but command each other to do stuff. More details on exactly how this process works can be found in the Developers Guide.

Before going any further, make sure your bots can see each other on the botnet. They don’t need to be di-rectly linked, but if they can’t see each other on the ‘net, they’re not going to get very far.

In order to get the best results with linked bMotion bots, you should set their gender and IRL values for each other (after all, you did do the optional section above, didn’t you?). You can do this on the partyline with “.chgender <bot> female” and “.chirl <bot> emma”.

To make them aware of each other, give them the K flag on the relavent channels, with “.chat-tr <bot> |+K #channel”. Global +K doesn’t count. If you don’t want them to talk to each other in a particular channel, don’t set them +K for it. Remember you need to have the channel included in the random-

6 7

Channels setting in the config file too.

That’s it, they should be happy to talk now. If you want to test, type the following in a channel where they’re both active and +K:

!bmadmin <botnick> parse hello%|%BOT[hello there]

This should result in something like:

<JamesOff> !bmadmin notopic parse hello%|%BOT[hello there]<NoTopic> hello<MonicaOff> hello there

as NoTopic has made Monica talk. You can have more than two bMotion bots in a channel interacting with each other, but remember that might get annoying with that many copies of bMotion responding to people all the time.

User meta-informationbMotion makes use of meta-information on users as stored in the eggdrop userfile. It will use the gender and IRL fields as it can (which is why you should add them to the userinfo.tcl script so that you and your bots users can set their information).

User’s IRL names should be stored as a space-separated list of names. If the user wants to have a name with a space in it, that entire name should be enclosed in quotes. bMotion will pick a random name from the list when it needs it. If the user doesn’t have that information set, it will use their IRC nickname, trying to strip any characters such as [, ], _, |, etc.

Users can check their IRL names by saying, “<botname> say my names”. If it responds with, “Ah, you must be <their nick>” then it doesn’t have any entries on record for them. It will /NOTICE them instructions on how to set their names. If it says, “Your IRL name(s) are: ...” then it does have the information (it still /NOTICEs them).

If you want to set the information manually for them (e.g. when you add them to the bot), you can do it with .chirl <nick> <names>. You can also set their gender with .chgender <nick> male|female

A user can set their own IRL names by either using “.irl <names>” on the partyline (and .gender), or by msg’ing the bot with “IRL <names>” and “GENDER male|female”. Genders other than male or female are not currently supported as there seems to be no need for them. It’s possible to set the gender field to anything, but it may cause unexpected results or errors with bMotion.

The user’s gender is used in determining the bots reaction to things like hugging and so on. The decision looks something like:

If the bot is bisexual, that’s okIf the bot is straight, and the user is the opposite gender to the bot, that’s ok.If the bot is not, and the user is the same gender, that’s ok.

IRC users not in the bot’s userfile are rejected by default unless the bot is stoned or horny enough. bMotion also rejects immediately any user with a sufficiently low friendship rating. (See the Managing bMotion section for more details on friendships.)

8 9

Personalising Your BotbMotion has spent all of its existence (about two and a half years now) living in #exeter on EFNet, and has really become part of the family. The reason for this is mainly that the script has been tuned to respond to things unique to our channel, and also respond with expressions that we use a lot.

While most of the stuff bMotion says and does probably makes sense (or at least is amusing) to everyone, there are some things that won’t. (Like, “blblbl.” I’m not even going to try explaining that to you.)

The answer, then, is to customise the bot yourself.

There are three main things to customise for bMotion. Firstly the abstracts file, which contains most of the generic stuff the bot says. Secondly, the abstacts stored in plugins. Finally, you can customise the plugins themselves. Most people should be happy with the first two.

What are abstracts?

Abstracts are lists of similar phrases, for example a list of words/expressions meaning “hello.” When bMotion needs to say hello, it will pick a random abstract from the “hello” list and say it. This keeps the code clean by not having every possible variant of “hello” stored in the code (possibly in multiple places), and also makes interbot communication much more advanced (more on that later).

Abstracts almost have a programming language to let you do special things with them. They consist of a percent symbol % followed by something. This table lists most of them:

%% The nick of the person the bot is talking to%pronoun “himself” or “herself”%himherself “himself” or “herself”%me The bot’s name%noun A random noun (depricated)%colen Random shifted-symbols, like “(*$&£$”%hishers “his” or “hers”%heshe “he” or “she”%hisher “his” or “her”%2 Special use for more text%% Percent symbol%ruser A random nick from the channel%rbot A random bot’s nick from the channel

There are also some special use commands:

%VAR{name} A random entry from the name abstract list%OWNER[text] Convert to ownership%NUMBER{maximum} English-text version of a random number up to the

given maximum%SETTING{plugin,setting,channel,nick} Replaced with the given setting name (advanced)

8 9

%BOT[text] Send command to another bot%bot[chance,text] Send command to another bot with chance% chance%PICKBOT[conditions] Change the bot to use (%BOT and %rbot)%PICKUSER[conditions] Change the user to use (%ruser)

Finally two commands that affect the output of the line:

/text (at start of element) Turns the text into an actione.g. “/says hello” is turned into “/me says hello”

%| Split element (i.e. start a new line)The pipe symbol is Shift-\ on my keyboard.

So for example, to make the bot say on IRC:

<botnick> hi there!* botnick waves

You would use “hi there!%|/waves”

Making/editing abstracts

Unless you’re writing your own plugins, you won’t need to make your own abstracts. If that’s what you want to do, refer to the Developers’ Guide section of the manual.

The abstracts are defined as TCL lists. This means each one is a list of things to say in curly braces { }, with each thing enclosed in double quotes, and separated by spaces or line breaks. Here’s an example abstract:

set mingreplies { “not as much as you though” “yeah? well you ming more” “so? you’re my role model” “oh no b-” “you bitch” “you suck like a dustbuster”}

This list of abstracts is used when the bot is told it’s minging. This is a fairly simple example as each item is only one element and doesn’t use any of the commands. However, let’s say you wanted to remove the “oh no b-” entry because you don’t understand it (that’s an expression that you’d have to be in #exeter, or have gone to school with me, to understand).

All you need to do is open modules/abstracts.tcl in your favourite text editor, and delete “oh no b-” from it. Rehash the bot, and it’ll vanish from the list of things bMotion will say. If you want to put your own line in, just add it inside the curly braces.

If you find a whole abstract you don’t want the bot to use at all, don’t just delete it from abstracts .tcl; I’ll cover that shortly.

One problem with editing abstracts.tcl is that when you unpack a new version of bMotion, it’ll get overwritten with the distribution version. The best solution here is to create, in the modules directory, a file called “abstracts_BOTNETNICK.tcl” where BOTNETNICK is taken from the “set botnetnick” line of

10 11

your eggdrop’s config file. (This is used instead of the bot’s nick because the bot’s nick is undefined when eggdrop first launches [because it hasn’t connected to IRC yet], and because the bot’s nick can change.)

bMotion reads the abstracts.tcl file first and then, if one exists, loads the abstracts_BOTNETNICK.tcl file. There are two types of entry you can put in the second file:

set abstract_name { “abstract” ... }

and

append abstract_name { “abstract” ... }

The first will override the value from the main file with your version. The second will add your values onto the values from the main file. This means if you want to delete some of the entries in the main version then you’ll have to override it with a copy from the mail file, minus the lines you don’t want.

For example, to delete the “oh no b-” line above, using the second file, put this in it:

set mingreplies { “not as much as you though” “yeah? well you ming more” “so? you’re my role model” “you bitch” “you suck like a dustbuster”}

If you want to add “that’s not very nice to it” instead, do this:

append mingreplies { “that’s not very nice”}

Note: Escape important characters for TCL with a backslash (\). This means mainly $, [, and ]. If you don’t something will go horribly wrong.

Editing plugins stored in plugins

bMotion is still in a state of migration (from having all the code in one big file to having many small plugins). Quite a few of the abstracts it uses which are used only by one plugin (i.e. not smilies, etc) are stored in the plugin file itself. This makes it easier to manage the abstracts associated with it.

In order to avoid having your changes to plugins’ abstracts overwritten on an upgrade, you can put the changes (using set or append, as above) in the bot’s own abstracts file.

Customising the plugins

Customising the plugins themselves gives you ultimate control over what bMotion responds to, and how it does so. For more information on how the plugins work, see the Developers’ section of the manual.

10 11

Linking two bMotion botsbMotion works best when there’s another bMotion bot in the channel with it (or more). The bots can interact and become much more entertaining. They can also end up seeming to develop their own character traits. By customising their abstracts files, you really can make them two distinct personalities.

(This is why abstracts are so powerful; instead of one bot asking the other to say a particular line, it requests the bot say a particular abstract... and since each bot can have its own unique abstracts, the other bot will respond with something from its own personality. Hurrah!)

In order to get this working, you will need:

• Two (or more) bMotion bots, already fully configured and working in a channel.• Those bots to be on a botnet together. Userfile sharing is not required, but it will mean information like gender and IRL name can be shared.

bMotion uses the K flag to identify a bot it can talk with on a particular channel. You cannot set it globally (currently).

Once your bots are setup and on a botnet together, give them the K flag for each other (i.e. on both bots) for each channel they’re going to talk together in:

For example:

(On NoTopic).chattr MonicaOff |+K #molsoft

(On MonicaOff).chattr NoTopic |+K #molsoft

Once you’ve made the changes, test in the channel by asking one of the bots to make the other talk:

!bmadmin <botnick1> parse %BOT[hello]

Which should make the second bot say hello. You can even make the bots use abstracts:!bmadmin <botnick1> parse %BOT[¬VAR{greetings}]

You may also want to set IRL and gender settings for the bots on each other for best results.

Help! I don’t have bots linked and I’m getting ALERTs on the partyline :(

Regardless of if bMotion’s linked to another bot or not, it may still try to use an abstract with needs one. If it realises it’s parsing a line that needs another bot but one isn’t available, it will drop the whole output to avoid looking silly by having a one-sided or incomplete conversation. When it does this, it will generate an ALERT on the party line that looks like this:“ALERT! While trying to say !...! to #channel couldn’t find another bot to talk to. Lost entire output.” An ALERT from bMotion isn’t critical and can be safely ignored. If you want to avoid

“¬”? WTF?

You may not have this symbol on your keyboard. Try Alt+0172 to get it.

bMotion uses it as a “parse on other bot” marker. If you used %VAR inside a %BOT, then the first bot would parse it and then send it to the second bot.

12

this then you can edit the abstracts file(s) to remove any entry that uses %BOT.

13

Managing bMotionbMotion should pretty much look after itself once you’ve got it set up right (see previous section on how to do that). Should the need arise, or if you’re just curious to see what’s going on inside, bMotion offers quite a few commands to change and view its status.

bMotion uses plugins to provide its admin functionality, so if a command in the manual doesn’t work, then it’s possible the plugin isn’t loaded. Type “.bmadmin plugins” at the partyline to see which ones are loaded. If you get “What? You need .bmhelp” in response to that, you’ve got problems as the plugin to manage plugins isn’t loaded...

Using .bmadmin.bmadmin is the command used to access bMotion’s admin plugins. bmadmin itself only takes one parameter - the name of the plugin to call. The plugin itself may require additional parameters afterwards, usually a command and then optional fi elds like a user’s handle.

If you try to call a plugin that isn’t loaded, bMotion will respond (in keeping with eggdrop’s own unhelpful error message ;) respond with “What? You need .bmhelp!”. .bmhelp will list all the loaded admin plugins, but is unable to offer any assistance with using them. Telling you how a plugin works is left up to the plugin itself.

Here’s an example showing the usual admin plugins:

Note “some may not be accessible by you.” Plugins can restrict their use to people with certain eggdrop global fl ags, usually “n” (owner). This is because they can radically alter

2255.43 Commands available: (Some may not be accessible by you)2255.43 lang friends rehash queue codesize test unbind votes parse fl ood status plugin

settings_clear

14 15

the behaviour of the bot in some cases. In brief, the functions of these plugins (in the order above) is:

lang Change the language bMotion is runningfriends View friendship informationrehash Safe code reloadqueue View and manage the bMotion (not the eggdrop) output queue.codesize Display the size of the bMotion codetest A test admin plugin :)unbind votes Unbinds the vote binds for courtmartialingparse Makes the bot parse the text for outputfood View and manage bMotion’s fl ood protectionstatus Report information about bMotionplugin Manage pluginssettings_clear Delete all bMotion settings (as saved by plugins, not the confi guration)

Details of each plugin follows in this section.

14 15

Default Plugins ReferenceIn no particular order...

pluginThis is one of the more important plugins, as it manages all the others. You should always have it set to load.

.bmadmin plugin ““|remove|info|enable|disable <type> <name>

““Calling this plugin with no parameters will give a grouped listing of all the installed plugins, totals for each section, and a grand total. Output plugins are followed by [on] or [off] to show if they are enabled or not. Output plugins are the only ones that can be loaded but inactive.

remove <type> <name>Use the remove command to unload a plugin. bMotion will delete it from memory, and you can’t get it back unless you rehash the bot or reload the fi le it lives in. (An add command to make bMotion load the plugin for you is on the todo list.) Type is one of admin, output, complex, simple, action_complex, or action_simple.

info <type> <name>This command dumps out bMotion’s internal information about the plugin, and probably won’t mean much to you unless you’ve poked around the plugins module. The developers’ guide may explain further, if I feel like explaining it then :P Types of plugin are as for remove.

enable <type> <name> and disable <type> <name>These two commands enable and disable plugins which can be loaded yet inactive. Currently the only plugin type to support this is the output plugin, so <type> must always be output.

16 17

lang

Displays the loaded and active languages, and allows you to switch the active one.

.bmadmin lang [<language>]

With no parameters, this plugin displays a list of the loaded languages, and also tells you which one is active. This refers to the fact that each plugin is assocated with a particular language. Only plugins matching the current active language are used, although plugins can bind to the language “any” and will run regardless of bMotion’s language (a good example of this would be the smiley plugin. Note also that the admin plugins should generally be language-free!)

<language>If this optional parameter is given, bMotion will attempt to switch the the given language. This takes effect immediately.

See the Developers’ Guide for more information on languages and plugins.

friends

Reports the status of bMotion’s friendships.

.bmadmin friends [<handle>]

With no parameters, this plugin dumps to the party line the handles of all the people it has friendships for (or has had to lookup friendships for, in which case they get set to 50). Friendships range from 0 (absolute hate) to 100 (awww). All friendships are initialised to 50, and currently do not drift. The only way for a user to change their friendship rating is to do things to the bot that are nice or nasty. Plugins can use the friendship information to change their behaviour.

<handle>Passing an optional handle (not a nick, bMotion uses the handle matching the user’s userfile entry... unless they don’t have a userfile entry, in which case the nick is used) makes bMotion report the friendship for just that one user.

16 17

rehash

Reload code in an orderly fashion

.bmadmin rehash

This plugin takes no parameters. It attempts to validate the bMotion code to make sure it won’t crash the bot, and if it’s safe will reload it. If the code isn’t safe, it reports the TCL error encountered that prevented it from working. It’s not able to report the file the error occurred in. This is the equivalent of typing “<botnick> rehash” on IRC (on IRC, the bot will /notice you the error message). To bypass this, use the normal eggdrop command .rehash.

queue

Display and modify the bMotion output queue.

.bmadmin queue [flush]

Use this to view and, if necessary, flush the bMotion queue. bMotion has an internal queue of what it’s going to say on IRC (or push to another bot). This queue is processed in a FIFO fashion, with the delay between elements being a coefficient of the length of the text (i.e. it takes bMotion longer to type a long line). This command reports the number of elements still in the queue, and then displays them in the order they will be processed.

flush(Synonyms: clear, delete, reset)Use this command to immedately clear the remaining queue. Some processed elements may be in eggdrop’s own output queue, but typically bMotion sends output slower than eggdrop sends it to IRC. Using this command will result in a warning a few seconds later, as it will attempt to process the queue only to find there isn’t one. You can safely ignore this warning if you have recently (seconds, not minutes) cleared the queue.

codesize

Display the size of the bMotion code in lines

.bmadmin codesize

Displays the size of the bMotion code. This plugin calls the external shell script codesize, which needs to be in the eggdrop directory and have the executable bit set. The reply is broken down into the size of the bMotion loader, the size of all the modules, and the size of

18 19

all the plugins. A final total is also given.

parse

Makes the bot parse text for output

.bmadmin parse <channel> <text>

Used for testing bMotion’s output routines. It’s the bMotion equivalent of eggdrop’s .say command. You can put any bMotion commands (%VAR{} and so on) in the text and the bot will parse them just as though it had generated the output itself.

This command is also avilable directly from IRC to the owner by saying:

!bmadmin <botnick> parse <text>

in the channel.

status

Show some status information about bMotion

..bmadmin status

bMotion will dump, to the partyline, various status information about itself:

This information is:

• The version of bMotion running• The version of the randoms file in use• The bot’s gender and orientation

I am running bMotion v 1.15 2002/09/27 16:02:47 jamesUsing randoms file v 1.21 2002/09/29 14:21:25 jamesMy gender is male, and I am straightRespond to everything is 1 (1 = on)Current pokemon is pikachuRandom stuff happens at least every 20, at most every 120, and not if chan-nel quiet for more than 45 (mins)My botnicks are (NoTopic|nt|bots|the bots) ? (‘.bmotion redo botnicks’ to update)melMode 0 (1 = on)needI 1 (1 = on)

Current queue size is 0

18 19

• The value of the “balefire” setting• The current pokemon• The timings for the random stuff occurence• The botnicks it will respond to• melMode setting (1 = bypass the gender check on users)• needI setting (1 = only respond to users with the I flag globally)• The number of items in the output queue (see .bmadmin queue)

20

21

Interacting with bMotionThis section of the bMotion manual will explain how interaction with bMotion works.

You should be aware I view this section in the same way I do documents that tell me how the next Star Trek fi lm unfolds (i.e. spoilers). Half the fun of bMotion is discovering random triggers you didn’t know were there (or in my case, forgot). Obviously not all the triggers are random and will only happen if you trigger them on purpose, which is where this document will help.

I shall thus divide this chapter into two parts - the “you have to know to make it happen” part, and the “happens during the normal course of converstation” part. I strongly urge you to not read the second part unless you really, really want to.

This section will be presented by plugin rather than by text/response, so that owners know which plugins are responsible for which responses. To disable a plugin, permanently or otherwise, see the Managing bMotion chapter.

You-Need-To-Know-Them TriggersOr, Commands, if you will.

simple:pokemon_returnReturns the bot to your pokeball

bot return* bot returns to user’s pokeball

simple:transformMakes the bot transform and roll out, Transformers-style

bot transform and roll out* bot transforms into <something> and rolls out

complex:replicate (and complex:replicate2)Activate replicators and generate stuff

bot [please] replicate|make|send|create someone something

22 23

bot [please] replicate|make|send|create something for|to someone* bot replicates something and hands it to someone

bot make it something for user* bot makes it something for user

(Try make it so)

complex:tauntBe rude with zero effort

!taunt targetbot target: you are taunt

This plugin will attempt to use the plural where required.

complex:st-courtmartialPunish people for being bad (or good)

The user will be thrown in the brig for a pre-defined time (default is 30 seconds), before being charged with two random things. The user will then be found innocent or guilty, and sentenced if necessary.

The username given MUST be on the channel with the bot. You may encounter problems with users with nicks longer than 9 characters, in which case an upgrade of eggdrop may help.

bot courtmartial user* bot throws user in the brig to await charges<bot> user, you are charged with plotting with a proton, and putting several female Maquis crewmembers into suspended animation

<bot> You have been found innocent, have a nice day.

In England (and some other countries), there’s a TV show called Banzai, which is a spoof Japanese programme, where the audience is invited to bet on the outcome of stupid things (e.g. electric wheelchair racing with old people, and how many helium balloons make a chicken float). bMotion can handle this too, and if you add “with banzai” to the end of the courtmartial request, it will change modes.

bot courtmartial user with banzai<bot> user’s Prison Poser!<bot> Rules simple. Simply decide if you think I’ll find user innocent.

<bot> Place bets now!

(After this line, users in the channel can use !vote innocent or !vote guilty to cast their votes. This is betting, not a democracy - the voting does not affect the outcome. Each user can only bet once.)

* bot throws user in the brig to await charges<bot> bet bet bet!<bot> Betting ends!<bot> user, you are charged with plotting with a proton, and putting several female Maquis crewmembers into suspended animation

<bot> You have been found innocent, have a nice day.

Afterwards, the bot will announce the nicks of the winners (i.e. the people who voted for the outcome).

22 23

Don’t complain about broken English in the banzai mode; remember the game is supposed to be Japanese :)

complex:eatMake the bot consume things

bot eat something* bot eats something

No, he won’t eat himself.

complex:st-cloak and complex:st-decloakIt’s a starship!

bot cloak* bot shimmers and disappears from view...

bot decloak* bot shifts back into view

Being cloaked or uncloaked has no effect on the operation of the bot, except for the following plugin.

complex:st-fireIt’s a starship with guns!

bot fire phasers|torpedos|quantum torpedos|photon torpedos at something* bot swoops in on something

* bot fires phasers at something

The bot will decloak on the way if it is currently cloaked, and recloak afterwards. (Remember, firing weapons requires that the ship decloaks, this isn’t Star Trek VI you know.)

The actual “fires” line changes depending on the weapon chosen, and the bot will sometimes have a failure too.

You can also attempt to fire weapons that don’t exist, but it won’t work very well.

complex:sportInvent a sport

!sport [adult]

The bot will invent a sport. Adding “adult” after the command seeds the random lists with adult words too (although it’s possible that it won’t be a very adult response still). Example sports include reverse handicapped line dancing, and Swedish husband web surfing.

This is a conversion of the random sport generator from my webpage.

24

complex:handHand something over

bot hand|give something something* bot gives someone something

Just like the replicate handler.

complex:abbrRandom abbreviation generator

!abbr [adult]

Generates a random TLA. Add “adult” to the command to seed the random lists with adult terms. Examples include “SHH: Starchy-Holding-Hole” and “HPW: Horny-plowing-wesley”The idea for this plugin came from lectique :)

complex:chooseyouMore pokemon stuff

blah blah

complex:attackMore pokemon stuff

blah blah

complex:scrapGenerate a random device

!scrap [adult] [silly]

In the UK we have a show called “Scrapheap Challenge” in which two teams are dumped in a junkyard and asked to build a device to e.g. catapult a ball to the moon, only from the junk. This plugin generates random challenges. Add “adult” to seed the lists with adult terms, and “silly” to make it (even more) silly. You can also use adult and silly together. Examples include “An alien spring loaded digger” and “A bizarre steam powered postcard”

25

Developers’ GuideWelcome to the bMotion Developers Manual. This section is designed for people who want to tinker with the bot’s inner workings (so to speak). This is not required reading for normal use of bMotion. Before you embark on reading this, you should be familiar with TCL and the TCL interface to eggdrop. Information on TCL can be found in the 3tcl series manpages (on Debian at least; for some distros I’ve encountered it’s been the n series) or on http://www.tcl.tk. Details of the functions eggdrop exposes to TCL can be found in the fi le /docs/tcl-commands.doc from your eggdrop’s install directory. If you’ve never touched either before, a good grounding in script-type languages like PHP and Perl will probably enable you to pick up TCL as you go (like I did when I started on this project), and a good understanding of all IRC terms and how IRC works will make eggdrop easy to understand. This document itself won’t make any particular attempt to explain either of these concepts.

bMotion provides what I hope is a powerful yet easy-to-use architecture for extending its functionality. The code can be divided up into two main groups: plugins and modules.

Modules are the core of bMotion’s functionality, and are required for it to function. They include things like output processing (queuing, interpolation, etc), fl ood checking, interbot communication, event triggering, and so on. The modules live in scripts/modules/. They are loaded by the main bMotion script (scripts/bMotion.tcl). In some cases the order they are loaded is important, as latter scripts’ initialisation relies on variables or functions defi ned by earlier scripts. If you edit bMotion.tcl, be sure to keep the core modules in the order they are in already. If you want to add modules, the best place to do so is at the bottom of the script before the fi nal initialisation.

Plugins are what make bMotion smart (or not). They use the functions exposed by the core modules to control the bot. A simple overview is that plugins match text the bot sees on the channel, and then make the bot say something (with additional processing if required). There are quite a few different types of plugin, and each type is divided (mostly) into two parts: simple and complex. A simple plugin simply makes the bot say something back to the channel. A complex plugin is one that executes a TCL function, allowing more processing to be done. Send text back to the channel is optional with a complex plugin – what goes on inside the TCL function doesn’t matter. Mostly they send text back of course, because that’s the main thing that bMotion does.

Most people are going to be writing plugins, although there’s nothing to stop you writing a new module, or editing an existing one. One example of why you may want to write your own version of a module is (something I’ve been thinking about but never really been bothered to implement) a version of the interbot module, which is responsible for helping two or more bMotion bots in a channel coordinate themselves. Currently, it operates using eggdrop’s botnet, but linking two bots isn’t always possible or convenient. As long as interbot.tcl always exposes the same API, there’s no reason why it couldn’t use PRIVMSG over IRC to communicate with other bots…

26 27

PluginsPlugins in bMotion fall into a couple of categories:

• Simple plugins: Match text on a channel and make the bot say something.• Complex plugins: Match text on a channel and make the bot run a callback.• Output plugins: Once the bot is going to say something, all (active) output plugins are given a chance to process the line before it goes to IRC. Examples include the plugin to make the bot make typos, and one to make it speak l33t.• Action plugins (complex and simple): Match ACTION events instead of plain text.• Admin plugins: Provide commands for managing bMotion through the .bmadmin command on the partyline.

Plugins are also associated with a language so that bMotion can switch languages on the fl y. There is an “any” language supported for plugins that don’t associate with any language (for example, the admin plugins).

Plugins are stored in fi les in scripts/plugins/language/ where language is commonly a two letter abbreviation, for example “en” for English and “nl” for Dutch.

bMotion loads plugins in batches depending on type, as determined by the fi lename. However, you don’t have to include just complex plugins in a fi le named to show it’s for them — it’s just to help organise things.

The pattern of fi lenames bMotion looks for is as follows:

Filename Typeadmin_*.tcl Adminaction_complex_*.tcl Complex actionsaction_simple_*.tcl Simple actionscomplex_*.tcl Complexsimple_*.tcl Simpleoutput_*.tcl Output

You can put as many plugins as you wish in each fi le, and they don’t all have to be the same type either. For example, if you had a plugin which translated English to Dutch, and you wanted to use the same code to handle on-the-fl y translation for the bot (i.e. an output plugin) as well as offering people a !nl command, you can put both plugins in one fi le. bMotion also allows you to declare a “null” plugin, which doesn’t respond to anything, but allows you to inform bMotion it’s loaded. This is important because other plugins can check

26 27

to see if it’s loaded or not. You don’t want the Dutch output plugin loading if the actual translation function isn’t available.

Plugins are loaded in the order they’re listed exposed to bMotion by TCL. bMotion uses TCL’s glob command to select the fi les it wants (using the wildcards in the table above). Furthermore, TCL’s hashing for indexed arrays seems to be wild, so there’s no guarantee that plugins are executed in any particular order (fi lename order or alphabetic by plugin name). The order bMotion executes them in may be investigated by using the .bmadmin plugins command, which will show the loaded plugins.

Defi ning Plugins

Adding a plugin to bMotion consists of two steps. (Or sometimes one.) First, write the function that will run when the plugin is called, and second write the line to add the plugin to bMotion. Simple plugins (action and regular) only require the second step. They pick a random element from the list of responses, and use that.

Simple Plugins

Easy, these. Here’s an example.

bMotion_plugin_add_simple “foo” “^foo$” 30 “bar” “en”

bMotion_plugin_add_simple is the function to add a simple plugin. The fi rst parameter is the name of the plugin. This is what’s displayed in the list above. The second is the regular expression this plugin matches. If that regular expression returns 1 when matched against a line of text said on IRC, the plugin is passed. The next parameter is a number from 0 to 100, and is the percentage chance of the plugin running if it matches. This plugin matches 30% of the time, for example. 30-40% is a good range for things you don’t want to run all the time. It has been my experience that over-talkative bots are the annoying ones, and a 30-40% response rate for random events (such as this one where the bot isn’t being directly addressed) provide a

2321.50 Installed bMotion plugins:2321.50 (one moment...)2321.50 simple: question-have, shocked, alors, dude, :(, didn’t!,2321.50 moo, here, arebot, littlebit, pokemon_return, sweet,2321.50 oops, kansloos, list-1, sneeze, url-gen, rules, list-2,2321.50 wassup, transform, bored, foo, url-img, ali g, bar,2321.50 notbot, ow, ick, bof (30)2321.502321.50 complex: noun-catch, sorry1, dutchify, opme, sorry2, stupid,2321.50 eat, sex-oral, replicate2, taunt, kill, fuckoff, bhar,2321.50 st-cloak, love, chooseyou, mmm-catch, st-decloak, test,2321.50 sport, attack, thanks, unf, replicate, st-readings,2321.50 want-catch, test2, st-fi re, st-courtmartial, hand,2321.50 blbl, techsup, hug, hello, sex-oral2, hello2, supermarkets,2321.50 watchout, snicker (39)2321.502321.50 output: leet[off], colloq[on], english[on], typos[on] (4)2321.502321.50 admin: lang, friends, rehash, queue, codesize, test, unbind votes,2321.50 parse, fl ood, status, plugin, settings_clear (12)2321.502321.50 action_simple: sneeze, moo (2)2321.502321.50 action_complex: light, back, hands, away,2321.50 waves, hugs, attacks (7)2321.502321.50 Total plugins: 94

28 29

good medium. The next parameter is the list of things to respond with; in this case it’s a list of one item, the string “bar”. The final parameter is the language this plugin should run with. If this plugin is language-free, it should have the language “any”.

Let’s look at a more complex example:

bMotion_plugin_add_simple “moo” “^mooo*!*$” 40 [list “moo”

“mooo” “m000”] “en”

This one matches a line starting with moo followed by zero or more os, and then by zero or more !s, and then the end of the line. It has a 40% chance of firing if the regexp matches, but this plugin has three different responses defined. bMotion will automatically pick a random one (different each time the plugin is called) and use that.

bMotion offers a powerful feature called variable interpolation (also known as expandos to some people. Whatever you call them, they’re bits of text which, when processed by the bot, become something else. One of the more powerful ones offered by bMotion is %VAR{}. If you define a global variable and then put the name of it inside the braces, bMotion will insert the contents of it in place of the %VAR bit. If the variable is a list, bMotion picks a random element from it and uses that. And even better, if the variable contains other %VAR{}s, they’re expanded too in a recursive fashion. These variables are known as abstracts because they allow you to use concepts in your plugins, and give each bot a personality by given them a different set of strings for the abstract to expand to.

Hopefully simple plugins don’t look too bad - after all, they’re supposed to be simple.

Complex Plugins

Now let’s look at a complex plugin:

bMotion_plugin_add_complex “test” “^%botnicks: test$” 100 \“bMotion_plugin_complex_test” “en”

proc bMotion_plugin_complex_test { nick host handle channel text } { bMotionDoAction $channel $nick “%VAR{hellos}” bMotion_plugins_settings_set “complex:test” “blah” $channel “” $nick return 0

}

This is the first ever complex plugin I ever wrote so it can’t be that hard to follow :P

The first line (note it’s wrapped) looks a lot like the simple plugin definition. It adds a plugin known by the tag “test”, matching the regexp “^%botnicks: text$”. It matches 100% of the time. The key difference is that instead of a list of responses, it has the name of a function as the final parameter. This is called a callback. When bMotion matches the regexp against the incoming text, it runs the callback function.

The callback is declared just like any other TCL function, and takes the parameters nick, host, handle, channel, and text. These are the exact same parameters passed to a msg bind by eggdrop, so you can use code for plugins that you would use in a bind proc. (If you didn’t follow that, read the tcl-commands.doc described in the introduction.) Without covering the contents of the callback in too much depth (the functions used will be explained properly later), this callback does the following: send a random element of the “hellos” abstract back to the channel, save an internal setting in bMotion, and then returns 0. This return

A note on “random”

Remember “random” on a compu-ter is only ever pseudorandom, and TCL’s random number generator does seem particularlly good at pick-ing the same number several times in a row.

Code Wrapping

I’m using the “\-at-end-of-line syntax” to show a wrapped line in the manu-al. I don’t know if TCL supports it but I suspect not :)

28 29

value is important. Returning 0 from a callback will allow other plugins to run, if any others match the text too. Returning 1 will stop any other plugins from running (although previous plugins may have already run). If you want to ensure the bot responds only once to a particular event then the plugin that matches it should return 1.

You may have noticed in the regexp used to declare this plugin that “%botnicks” was used. This is another expando bMotion uses, and only works in the regexps for plugin definitions (not inside plugins themselves). This expands to the $botnicks variable, with additional bits to make sure there are no problems matching. The $botnicks variable matches all names by which your bot expects to be called, and is defined in the settings file. See the Configuration manual for more information (when I write it).

The effect of this plugin is:

You can put any code you want inside a callback function, and bMotion provides quite a few functions to help you out. bMotionDoAction is one of the ones you’ll use most, and it makes bMotion dump text to IRC with some pre-processing. The exact syntax will be explained later in this manual.

Action Plugins

Simple and complex action plugins work in an identical fashion to simple and complex regular plugins, but the function used to define them changes name. All the other parameters remain the same.

bMotion_plugin_add_action_simple name regexp %-chance response(s) language

bMotion_plugin_add_action_complex name regexp %-chance callback langauge

Output Plugins

Output plugins run against every line of text that bMotion outputs (via bMotionDoAction). They give the opportunity to adjust the contents of the line before it goes to IRC. An example of this is the typos plugin (aka TyposEngine) which makes the bot make human-like errors as if it was typing at a keyboard. Output plugins can be enabled and disabled from the partyline, as well as (just like all other plugins) completely unloaded. They also have an language to which they apply, so that a plugin making English colloquial errors (“should have” to “should of” for example) doesn’t try to run when the bot is outputting Dutch.

Output plugins use callbacks, and are passed two parameters: the text to process and the channel it will go to. They must return the processed text (if they return nothing, the bot will lose the output).

if [bMotion_plugin_check_depend “complex:dutchify”] { bMotion_plugin_add_output “dutch” bMotion_plugin_output_dutch 0 “en”}

proc bMotion_plugin_output_dutch { channel text } { catch { set text [bMotion_plugin_complex_dutchify_makeDutch $text] } return $text

}

This is the Dutchify output plugin, which makes the bot have a go at (somewhat comedy) translations to Dutch on the fly. Note that the plugin definition is wrapped in an if statement. bMotion_plugin_check_

1247.49 [ JamesOff] notopic: test

1247.51 [@NoTopic] hey

30

depend is a bMotion function that returns true if the given plugin(s) are loaded, and false if they are not. The actual function that does the Dutchification resides in another plugin (the one that provides the !nl command), so this plugin reuses that code. If that plugin is not loaded, this one won’t load either.