Perlbot Plugins =============== Table of Contents ----------------- 1) Introduction and description of what a plugin is 2) Layout of plugin directory 3) Installing a plugin 4) Disabling a plugin 5) Dynamically loading a plugin 1) Introduction and description of what a plugin is --------------------------------------------------- Everyone who runs an IRC bot has a different set of requirements. There will always be someone who feels that a given set of features is too much or too little for their purposes. This is why we decided to keep the core perlbot functionality limited to a small set of things that nearly *everyone* will want in a bot, and added a 'plugin' feature to accommodate all the extras. A plugin is a small package which adds some small bit of functionality to your perlbot. It is meant to easily 'plug in' to an existing perlbot installation with little or no effort. Here are some examples of what a plugin could do: - add an interface to pull the most recent headlines from a given news website - add an interface to a web search engine or other form-based webpage - allow IRC users to play interactive games with the bot, such as a trivia or quiz game - add an interface to a specific unix utility or other program, such as ispell (spell checker) or bc (calculator) - provide protection for channels, to prevent takeovers, flooding and other abuses 2) Layout of plugin directory ----------------------------- All plugins reside in a subdirectory under your perlbot directory (we'll refer to the perlbot directory as "perlbot/" here) called "Plugins". You can change this location if you want, by changing the bot.plugindir option in the main perlbot configuration file, but we'll always refer to it as "Plugins" here. Under this directory, plugins are classified by type. "Core" plugins are the core bot functionality, you probably should leave these alone. "Basic" plugins are some basic services expected from IRC bots. "Misc" contains miscellaneous plugins. Other directories may contain other types of plugins. Each plugin resides completely in its own directory under "perlbot/Plugins/(something)/PluginName", and the directory is simply the name of the plugin. So if you had a plugin called "Foo", it would reside in the directory "perlbot/Plugins/Misc/Foo", for example. 3) Installing a plugin ---------------------- A plugin will come as a .tar.gz or possibly .zip archive. To install it, go to your perlbot plugins directory and extract the archive. The archive should expand into a directory which has the same name as the plugin, as described above in Section 2. Read the README file in that directory, if there is one. If the README instructs you to modify your main perlbot configuration file or the plugin's configuration file, make the necessary modifications. Now just start perlbot (if it's already running, make sure to stop it first) and your shiny new plugin will be enabled. 4) Disabling a plugin --------------------- To prevent perlbot from automatically loading a plugin when it starts, add a line to the 'bot' section of your config file with the word 'noload' followed by the name of the plugin that you wish to disable. For example, if you want to prevent the "Foo" plugin from being loaded, you would add the line "Foo". The plugin will not be immediately unloaded from your perlbot, but it will not be loaded at the next startup. 5) Dynamically loading a plugin ------------------------------- You can even tell your perlbot to load a plugin that is currently not loaded. Simply message the bot "#plugins load PluginName" where PluginName is the name of the plugin you want to load. You can also use "start" instead of "load" if that's easier to remember. If the plugin you loaded is one of the "noload" plugins (see section 4) then it will still be prevented from loading the next time you start perlbot. If you want the plugin to automatically start up, you'll have to remove the appropriate "noload" line from your config file. In addition, you can msg the bot "#plugins unload PluginName" (or "stop") to dynamically reload a plugin, and "#plugins reload Pluginname" (or "restart") to reload the plugin. Reload is generally useful to plugin developers. (See plugins-authoring.txt if you're interested.)