Overview

Plugins provide bMotion with its interactivity.

There are several kinds of plugins:

• Simple plugins: Match a text pattern and respond with some output
• Complex plugins: Match a text pattern and call a TCL function (which may generate some output, but doesn't have to)
• Output plugins: Process output generated by simple and complex plugins (and bMotion's internal modules) to do things like add typos, or correct common errors caused by gluing sentences together
• IRC event plugins: Handle things like joins, parts and quits
• Management plugins: Provide management commands (.bmotion ...)

Simple and complex plugins also come in two varieties: normal and action. The former handle normal text said on IRC and the latter handle actions done with /me.

When some text is said on IRC (or used in an action), bMotion first processes all the simple plugins and then the complex ones. Plugins are processed in alphabetical order by name.

Simple Plugins

Simple plugins (both regular and action - they both work the same but trigger on different types of events) specify a regular expression to match against, and a probability (0 = never, 100 = always). They also give a list of possible outputs.

If the text said on IRC matches the regexp, and bMotion thinks of a number between 0 and 100 that's higher than the probability, then the plugin fires.

If the plugin files, bMotion picks a random item from the list of possible outputs and sends it back to the channel.

The same simple plugin cannot trigger twice in a row. If the output generated is the same as the trigger text then the output is dumped (to stop bMotion going :) in response to someone else going :)).

If a simple plugin fires, bMotion stops and does not evaluate any more plugins of either type.

Complex Plugins

Complex plugins (of buth types) specify a regular expression to match against, and a probability. They also specify a TCL function.

If the text said on IRC matches the regexp and bMotion thinks of a number between 0 and 100 that's higher than the probability, then the TCL function is called. The parameters to the callback are always the same: nick host handle channel text.

bMotion first makes a list of all the callbacks to execute, and then calls them in order (alphabetically by plugin name).

Callbacks can return a value to tell bMotion what to do next:

• 0: Continue with other callbacks. Use this if your plugin does nothing. bMotion does not increment the user's flood counter.
• 1: Stop processing other callbacks. Use this if your plugin generates output. bMotion increments the user's flood counter appropriately and does not call any more callbacks.
• 2: Stop processing other callbacks, no flood: Use this to stop bMotion from incrementing the user's flood counter and also prevent any other plugins firing.

It is entirely optional if a plugin generates any output or not; some of the standard bMotion plugins trigger on text and generate no output as their purpose is just to collect words.

Output Plugins

Output plugins are unique in that they can be disabled and enabled. They specify their starting state, so some will be enabled after a restart/rehash, and others will not.

Output plugins are called in alphabetical order once per individual line of output sent to IRC by bMotion (just before it's added to the output queue).

An output plugin does not have a probability or regexp and is always called.

The text returned from each output plugin is the text passed to the next one (and from the last one to the queue). If an output plugin returns "" (the empty string) then bMotion abandons the line.

Standard enabled plugins include the typos plugin and the "english" plugin, which make typos and try to straighten out English errors respectively.

Standard disabled plugins include the Welsh output plugin, which tries to make everything look Welsh.

IRC event plugins

Event plugins are called when users join/leave channels, change nicks, etc. They register which type of event they are interested in along with a callback. bMotion executes each plugin in alphabetical order until one of them returns 0.

Management plugins

Management plugins add commands to the .bmotion command used to control the script.

They specify a regexp to match (immediately after .bmotion), the eggdrop flag(s) needed by a user to use the command, a callback, and optionally another callback which provides help.

When the user issues a matching .bmotion command, the callback is called with the rest of the command. The callback can use the bMotion_putadmin function to send output back to the user. This function automatically sends output to the right place, as users can use the .bmotion commands from a channel, a query, or the partyline. Management plugins should avoid unexpectedly sending the user large amounts of output as if the command is used on a channel or in a query, eggdrop will throttle the output to avoid Excess Flooding itself off IRC, and it'll take forever :)

If the user issues .bmotion help followed by the command's regexp, the second callback is executed and should give the user a summary of using that command.