Download JBot User Guide

JBot User Guide
A Java IRC Bot
Home Page: https://jbot.dev.java.net/
IRC: EFNet #java
i
1
Introduction .......................................................................................................................... 1-1
1.1
2
Why Another Bot Implementation? ............................................................................. 1-1
Deployment .......................................................................................................................... 2-1
2.1
Compiling JBot ............................................................................................................ 2-1
2.2
Configuring JBot .......................................................................................................... 2-1
2.3
Running JBot ............................................................................................................... 2-3
2.4
Configuring Plugins ..................................................................................................... 2-4
2.4.1
2.4.2
2.4.3
2.4.4
2.4.5
2.4.6
2.4.7
2.4.8
2.4.9
2.4.10
2.4.11
2.4.12
2.4.13
2.4.14
Bullshit .................................................................................................................... 2-4
Command ............................................................................................................... 2-4
Ebonify .................................................................................................................... 2-4
Factoid .................................................................................................................... 2-4
Google .................................................................................................................... 2-4
Idle .......................................................................................................................... 2-4
Insult........................................................................................................................ 2-4
Javadoc ................................................................................................................... 2-4
Karma...................................................................................................................... 2-4
Nickometer .............................................................................................................. 2-4
Regex ...................................................................................................................... 2-5
Seen ........................................................................................................................ 2-5
Statistics .................................................................................................................. 2-5
Time ........................................................................................................................ 2-5
ii
1
Introduction
JBot is a Java-based IRC robot that provides functionality through dynamically loadable plugin
modules. The core kernel of JBot supplies IRC connectivity, event management, plugin
management, user management, and response handling.
1.1
Why Another Bot Implementation?
A while ago, EFNet #java used to be entertained by an Infobot (http://www.infobot.org/) named
“jjava”. Infobot is written in Perl and provides a fun feature called factoids. The bot would key in
on phrases of the form, key phrase + (is|are) + value phrase. For example: “Java is fun”. It
would store the key and value phrases and when some said something like, “What is Java?” the
bot would respond with “Java is fun”.
The problem with Infobot was that is wasn’t very modular – its components were fairly tightly
coupled – and it was written in Perl. After trying to coax Infobot to perform features it wasn’t
designed to handle (such as permission-based factoid management), I decided to write my own
bot implementation. Additionally the tight coupling made it difficult to easily add or remove
functionality. This theme of tightly coupled feature sets continued with every bot implementation I
saw.
After some discussion on #java, I chose to base the first version on Pircbot
(http://www.jibble.org/pircbot.php) and implement a loosely coupled plugin architecture where
feature sets could be added or removed by the bot owner based on their needs. The first feature
sets I added were a time plugin (which acted as a “hello world” example plugin), a factoid plugin
to provide the same features as Infobot, a karma plugin to track user karma, and a command
plugin to provide permission-based command handling from users to bot via the IRC channel.
Soon other #java users authored additional plugins from the Google search plugin to the
politically incorrect ebonify (English to Ebonics translator) plugin.
2
Deployment
This guide will attempt to explain everything necessary to compile, configure, and run JBot.
2.1
Compiling JBot
JBot is compiled by running ant (http://ant.apache.org/) in the base directory of the project. The
build.xml ant script details the various build tasks, but running ant without a specific task
invokes the ‘all’ task which builds everything including the distribution zip file.
2.2
Configuring JBot
JBot is configured by modifying the etc/jbot.properties file. The following sections
describe all the currently supported JBot properties.
irc.proxy.class = jbot.proxy.PircbotProxy
The irc.proxy.class property declares which IRC implementation to instantiate to
communicate with the IRC server. Use a fully qualified class name which can be found via the
CLASSPATH used when invoking JBot.
2-1
irc.servers = irc.choopa.net:6667 irc.blessed.net:6667 \
irc.he.net
The irc.servers property declares which IRC servers to attempt to use to connect to IRC.
Each server is delimited by spaces and can be continued on following lines by using the property
file continuation character (‘\’) as the last character on the preceding line. IRC servers are
defined using the format:
servername[:port[:password]]
One server is connected to at a time. If a connection cannot be established or if disconnected,
JBot will move to the next server in the list and try to connect to it. If the last server is reached,
the connection manager starts again at the beginning of the list.
irc.name = jbotv2
The irc.name property declares the IRC nickname by which this bot will be known.
irc.login = jbotuser
The irc.login property is the login name by which this bot will be known. This is typically the
user name of the user that is running the bot.
irc.channels = #jbottest2 #jbottest3
The irc.channels property declares one or more channels that JBot will attempt to join upon
connecting with an IRC server. Channel names are space-delimited and may span multiple lines
as long as the properties file continuation character (‘\’) is the last character on the preceding line.
irc.connection.failures = 5
The irc.connection.failures property defines the number of times JBot will attempt to
connect before aborting. A value of zero means JBot will never abort and will continuously cycle
through the list of IRC servers attempting to connect. This number should be at least as large as
the number of servers or else JBot won’t attempt to connect to all of the servers. Server
connections are attempted one time before moving on to the next server.
addressing.mode = 1
The addressing.mode property defines the default method in which plugins will react to a public
message. If 0, the default plugin behavior will be to process every message it receives whether
or not the bot has been addressed. If the bot has not been addressed and its nickname does not
appear anywhere in the message, then only plugins with an addressing mode of 0 will process
2-2
this message. A value of 1 indicates that a plugin should only respond if directly addressed.
Direct addressing appears as follows:
fate-sg> jbotv2, time
This snippet shows IRC user “fate-sg” asking the bot (nickname “jbotv2”) what time it is. Plugins
with addressing modes of 0, 1, or 2 will respond to it. If addressing.mode is 2 then the bot will
respond if its nickname appears anywhere in a public message. For example,
joeblow_gt>I think this jbotv2 code is competent
When this message is received by JBot, plugins with addressing mode of 0 or 2 will respond to it.
Note that, typically, plugins will override the addressing.mode property.
plugins.directory = plugins
The plugins.directory defines the subdirectory from the JBot root directory (from which JBot
is executed) where the plugin manager will look for plugins.
# Plugin overrides
The method in which plugins are loaded allows properties defined in the plugin’s jbotplugin.properties file to be overridden by identically named properties in the
jbot.properties files. This way, jbot.properties, is the only properties file a user need
change when deploying their own JBot. This section is typically empty in a default JBot
installation. Below is an example of overridden plugin properties:
statistics.database.driver
= org.postgresql.Driver
statistics.database.class
= jbot.plugin.statistics.StatisticsJDBC
statistics.database.url
= jdbc:postgresql://localhost/jjava
statistics.database.username = statistics
statistics.database.password = jBot314
statistics.collection.period = 15
statistics.ignore=joeblowgt
statistics.alias.1=tdrury joeblowg_ joeblowgg
The above example shows how the statistics plugin does not use the default Mckoi embedded
database to store user and channel statistics, but, instead uses a PostgreSQL database to store
the statistics. The collection period has been reduced from the default 30 minutes to 15 minutes
and an alias has been defined. The statistics for nickname “tdrury” will be combined with the
statistics from nicknames “joeblowg_” and “joeblowgg” under the nickname “tdrury”. The
nickname “joeblowgt” will be ignored by the statistics plugin. (Note: the ignore and alias features
came about from some asshat hijacking my long used nickname, “joeblowgt”)
2.3
Running JBot
A sample Windows command script has been supplied to show all that is needed to run JBot.
set CP=lib/jbot.jar;lib/pircbot.jar;etc
java -cp %CP% -Djava.util.logging.config.file=etc/logging.properties \
2-3
jbot.JBotImpl
The variable CP is used to define the JBot CLASSPATH. The jbot.jar obviously must be
included. Since we’ve defined the Pircbot proxy to provide IRC connectivity, the pircbot.jar
file must also be included. Lastly, the etc/ subdirectory is included which allows JBot to find its
jbot.properties file and the logging.properties file.
2.4
Configuring Plugins
Each plugin has its own properties file defined in the plugin jar in a file named META-INF/jbotplugin.properties. Typically, these properties will never change. If they should be modified,
it is recommended they be overridden by defining the same property name in the JBot properties
file, jbot.properties and assigning the new value to it there.
2.4.1
Bullshit
tbd
2.4.2
Command
tbd
2.4.3
Ebonify
tbd
2.4.4
Factoid
tbd
2.4.5
Google
tbd
2.4.6
Idle
tbd
2.4.7
Insult
tbd
2.4.8
Javadoc
tbd
2.4.9
Karma
tbd
2.4.10 Nickometer
tbd
2-4
2.4.11 Regex
tbd
2.4.12 Seen
tbd
2.4.13 Statistics
tbd
2.4.14 Time
tbd
2-5