ChuckleBot Plugin Development System
The
ChuckleBot plugin system is designed to be easily understood by both non-native perl programmers and those just getting into programming.
Main Code
The main code section is located at the top of the file. Here you can use any modules or libraries your module wants.
Notice that the package name and file name are the same. You Must do this, its how the plugin identifies with itself.
package test;
use LWP::
Simple;
my @array;
The Configuration Hash
The configuration hash is is where you set up the plugin.
The hash is located at the top of the plugin.
%settings = (
trigger => '!billsucks',
event => '1',
timer => '1',
timer_is_hidden => '1',
timer_output => 'both',
);
The Trigger Event Class
The trigger event class gets triggered whenever somebody says your
preset trigger in a channel the bot is currently in.
The sub is only enabled when
trigger => is set.
The event contains all the information you need from irc for a basic trigger event plugin and is labled clearly in the code:
sub main { my ( $plug, $chan, $nick, $host, $text ) = @_;
if ($nick =~ /wildbill/i) { chucklebot->privmsg($nick, "You cannot use this command punk"); }
elsif ($text eq 'null') { chucklebot->privmsg($chan, "Why yes, he does!!!", "and so does WBB!!!"); }
elsif ($text =~ /^really bad/i) { chucklebot->privmsg($chan, "How bad is really bad?"); }
elsif ($text =~ /^worse than a cow farm/i) { chucklebot->privmsg($chan, "Wow! Thats pretty bad!"); }
}
$plug is the name of the plugin.
$chan is the channel in which the trigger was called.
$nick is the nickname that typed the plugins trigger.
$host is the hostname of the user that typped the trigger.
$text is any text typed after the trigger.
View the
output formating to see how to communicate with irc.
The Event Class
The event class is called whenever an event in irc occurs.
The sub is only enabled when
event => '1' is set.
sub event
{ my $self =
shift;
my %info =
@_;
if (($info{event
} eq
'msg') &&
($info{nick
} =~ /wildbill/i
)) {
foreach my $chan (chucklebot::
%names) {
chucklebot->
privmsg($chan,
"Eww, Bill messaged me.");
, chucklebot->
privmsg($chan,
"What a perv!");
}
chucklebot->
notice($info{nick
},
"Do you love me or something?");
}
}
%info is the info from the event.
$info{event} is the event that occured.
$info{chan} is the channel in the event.
$info{nick} is the nickname involved with the event.
$info{knick} is the nickname that was kicked in the kick event.
$info{host} is the hostname of $info{nick}.
$info{text} is the text from the event if there was any.
$info{raw_line} is the raw line from irc if the line isnt automatically parsed and isn't in $info{event}.
$info{event} can contain any of the following:
public a channel message
msg a private message
join a user joins
quit a user quits
notice a notice
kick a user is kicked
part a user parted
mode a channel mode is set
userhost a user's host is requested
oper the bot opered
nick a nick has changed, (the users new nick is in $info{text})
View the
output formating to see how to communicate with irc.
The Timer Event Class
The timer event is called when it is
enabled in the config and a
a certain amount of time has passed.
An intialize option is passed to the sub once when the bot first starts up, this is useful to gather information needed to prevent the plugin from outputing anything not necessary when the first timer strikes.
$initialize will be 1 when the bot is first started, after that it will always be 0.
sub timer
{ my ($self,
$initialize) =
@_;
if ($initialize) { @array =
("PRIVMSG Bill sucks.");
}
return(@array);
}
Output Formatting For Timers
Outputs for the
timer plugin are set up with three options:
message will message channels.
notice will notice channels.
both will message and notice channels.
If a channel has the timer enabled, the timer section will automatically add the channel information to your outputs.
If the output is "message", the returned
@array must be formatted as:
@array = ('A line of text', 'Another line of text');
If the output is "notice", the returned
@array must be formatted as:
@array = ('A line of noticed text', 'A second line of noticed text');
If the output is "both", the returned
@array must be formatted as:
@array = ('PRIVMSG A line of text', 'NOTICE A line of noticed text');
Alternatively you can work with any of the bot's
global variables to establish your own custom timer system.
The possibilities are limitless, as long as youre willing to write your own code and not use the bot's defaults.
Output Formating
The bot has many default ways to communicate with irc.
Any and all irc communications can be made with the bot.
To send a message to a channel or nickname use:
chucklebot->privmsg('chan/nick', 'A line of messaged text');
To send a notice to a channel or nickname use:
chucklebot->notice('chan/nick', 'A line of noticed text');
To kick a user from a channel use:
chucklebot->kick('channel', 'nickname', 'optional kick text');
To perform a /me "act" command use:
chucklebot->act('chan/nick', 'A line of acted text');
To change a mode in a channel use:
chucklebot->mode('channel', '+o nickname');
To join a channel use:
chucklebot->join('channel');
To part a channel use:
chucklebot->part('channel', 'optional part text');
To send a raw command to irc use:
chucklebot->raw('raw line sent to server');
The bot has two useful ban functions for the plugin creator if need be.
To ban a nick's hostname in a channel use:
chucklebot->ban('channel', 'nickname');
To kick and ban a user and his/her hostmask from a channel use:
chucklebot->kickban('channel', 'nickname', 'optional kick text');
Chucklebot Global Variables
Chucklebot has several very helpful variables for you to work with in your plugin.
%chucklebot::switch Plugin on/off information per channel.
%switch is set up as:
%switch = (
bot => (
all => (
#channel1 => 1
#channel2 => 2
)
)
trigger => (
!help => (
#channel1 => 1
#channel2 => 1
)
!rw => (
#channel1 => 1
#channel2 => 1
)
)
timer => (
help => (
#channel1 => 1
#channel2 => 1
)
)
If a channel is located in $switch{bot}{all} or $switch{trigger}{"trigger"} it has been
disabled
for that channel.
If a channel is located in $switch{timer}{"plugin"} then it has been
enabled
for that channel.
Holds user, user status, and currently joined channels.
%names is set up as:
%names = (
#channel1 => (
nickname1 => 1
nickname2 => 4
)
#channel2 => (
nickname1 => 2
nickname2 => 3
)
the numbers represent a user's status in the channel. 1 is simple user access, 2 is a voiced user (+v), 3 is a user with halfop (+%), 4 is op (+o), 5 is protected (+a), and 6 is owner (+q)
spam checking information for nicknames.
%val_nick is set up as:
%val_nick = (
nickname1 => (
banned => 0
ban_expire => 0
uses => 3
use_expire => 111111111
)
nickname2 => (
banned => 1
ban_expire => 11111111
uses => 0
use_expire => 0
)
If a user calls a trigger, his or her nick will be put through the nick validation sub, the sub then adds the user to this hash for evaluation.
Holds information on each loaded plugin.
%plugin is set up as:
%plugin = (
);
The settings from the
configuration hash in each plugin is stored in here for easy search and access.
set to 1 if the bot if oppered, 0 if not.
%chucklebot::config holds configuration information.
%config is set up as:
%config = (
server => irc.server.com
...
);
There are no comments on this page. [Add comment]