====== IRC Bot ======

===== Install =====

The IRC bot is included with Synchronet BBS, at ''exec/ircbot.js''.  Additional IRC bot modules are available in ''exec/ircbots/''.

===== Configure =====

The IRC bot configuration file is [[:config:ircbot.ini:]].

<code>
[server_ServerName]
addresses=add.ress.one, add.ress.two
nick=BotNickname
services_password=?
channels=#channelone, #channeltwo
port=6667
</code>

//Notes://
  - If you are running the Synchronet ircd, you can connect the bot to localhost, 127.0.0.1, or the specific interface that the ircd binds to as configured in [[:config:services.ini:]]
  - You may place more than one server section in [[:config:ircbot.ini:]], however connecting to multiple servers with one bot currently does not work.  Instead, you would need to run multiple instances of ircbot.js.

**Modules**
There are a number of modules available for the IRC bot, but they are not all enabled (or listed) in ''ctrl/ircbot.ini'' by default.

<code>
[module_ModuleName]
channels=#channelone <key>,!#channeltwo
dir=/sbbs/exec/ircbots/mybot/
lib=mylib.js
global=true
</code>

Looking at the ''exec/ircbots'' directory, you may see more modules that are installed but bot configured.  As of the time of this writing, the following are available:

<code>

;[module_Trivia]
;dir=/sbbs/exec/ircbots/trivia/

[module_Admin]
global=true
dir=/sbbs/exec/ircbots/admin/

[module_Antispam]
global=true
channels = #channelname
dir=/sbbs/exec/ircbots/antispam/

[module_Decider]
global=true
dir=/sbbs/exec/ircbots/decider/

[module_Dice]
global=true
dir=/sbbs/exec/ircbots/dice/

[module_Dis]
dir=/sbbs/exec/ircbots/dis/

;[module_Google]
;global=true
;dir=/sbbs/exec/ircbots/google/

[module_Ham]
dir=/sbbs/exec/ircbots/ham/

[module_Humanity]
dir=/sbbs/exec/ircbots/humanity/

[module_Info]
global=true
dir=/sbbs/exec/ircbots/info/
lib=http.js

[module_Poker]
dir=/sbbs/exec/ircbots/poker/
lib=cardlib.js

[module_Presence]
dir=/sbbs/exec/ircbots/presence/

[module_Weather]
global=true
dir=/sbbs/exec/ircbots/weather/
lib=http.js

[module_WhereIs]
global=true
dir=/sbbs/exec/ircbots/whereis/
lib=http.js

[module_RPG]
channels = #channelname
dir=/sbbs/exec/ircbots/rpgbot/
</code>

//Notes//
  - Google seems to have some missing file dependencies and doesn't execute so I have it commented out.  
  - No trivia directory although it is listed in the ini file.  
  - Add a module to a channel by adding the line channels = #channelname to the block.
  - Otherwise, by adding the modules to the ini and restarting the bot you may make these available in your ircd.

**Running the IRC Bot**

The IRC bot can be executed via [[:util:jsexec]], ''jsexec ircbot.js'', and an alternate configuration file may be specified like so: ''jsexec ircbot.js -f /some/other/ircbot.ini''.

You can also run the IRC bot via your services thread by adding an entry to [[:config:services.ini:]]:

<code>
[IRCBot]
Port=6668
Options=STATIC|LOOP
Command=ircbot.js
</code>

Note that the //Port// value must be supplied, but is irrelevant; the bot does not listen for connections.  Just pick an unused port.

You can add '' -f /some/other/ircbot.ini'' to the //Command// line to specify an alternate configuration file.

===== Use ===== 

  - See the help menu by sending **/msg <botnick> help**.
  - Some commands are restricted and will not show up in the help menu (or be usable), until you have identified yourself to the bot.  To identify, use **/msg <botnick> identify <password>**.  (Your IRC nickname must be the same as your username on the BBS for this to work.)
 
Without **IDENT** the help looks like;

<code>
Usage: HELP <module> <command> | HELP <command>
[main] help,?,ident,quote
[admin] whois,eval,lastspoke
[antispam] 
[decider] should
[dice] roll,dice
[dis] quote,dis
[ham] specs,z,geo,vhf,hf,country,callsign,contests,bands
[humanity] humanity,submit,humanity!,pick,humanity?,score
[info] def,syn,info,wtf
[poker] deal,go,fold,check,bet,call,raise,status,list,show,hole,invite,balance
[presence] nodelist
[weather] weather,forecast
[whereis] whereis
[rpg] create,classes,races,zones,login,logout,help
editor commands: set, link, unlink, move, mobs, items, exits, title, desc, goto, look
battle commands: flee, kill
item commands: drop, get, put, unlock, lock, open, close, remove, wear, equip, wield
rpg commands: score, status, move, equipment, inventory, look
for detailed command info, type 'rpg help <command>'
for help creating a characer, type 'rpg help create'
for help with the editor, type 'rpg help editor'
</code>

With **IDENT** it looks like;

<code>
Usage: HELP <module> <command> | HELP <command>
[main] reload,load,join,part,die,restart,help,?,ident,addquote,quote,greet,save,prefix,nick,module,modules,abort,ignore
[admin] whois,addmask,delmask,adduser,change,resetpass,pass,seval,eval,groups,subs,subgroups,read,finger,udpfinger,exec,say,lastspoke,force,debug,objkeys,tail,pipe
[antispam] 
[decider] should
[dice] roll,dice
[dis] quote,dis
[ham] specs,z,geo,vhf,hf,country,callsign,contests,bands
[humanity] humanity,submit,humanity!,pick,humanity?,score
[info] def,syn,info,wtf
[poker] deal,go,fold,check,bet,call,raise,status,list,show,hole,invite,balance,buyin
[presence] nodelist
[weather] weather,forecast
[whereis] whereis
[rpg] create,classes,races,zones,login,edit,logout,save,help,restore
editor commands: set, link, unlink, move, mobs, items, exits, title, desc, goto, look
battle commands: flee, kill
item commands: drop, get, put, unlock, lock, open, close, remove, wear, equip, wield
rpg commands: score, status, move, equipment, inventory, look
for detailed command info, type 'rpg help <command>'
for help creating a characer, type 'rpg help create'
for help with the editor, type 'rpg help editor'
</code>

The main module functions are contained in the ''/exec/load/ircbot_commands.js'' file.  All other modules are free standing and have separate files in their respective directories under ''/exec/ircbots/''.  The help associated with the various modules/commands is not complete.  if you choose to add/update look for the lines;

<code>
Bot_Commands["RELOAD"].usage =
	get_cmd_prefix() + "RELOAD";
Bot_Commands["RELOAD"].help = 
	"Reloads the internal bot command and function structure.  No arguments.";
</code>

This is an example from the command RELOAD.
The usage line dictates the syntax required to execute the command.
The help line contains a text description of the command's function.

**Module Main**
  * reload - Reloads the internal bot command and function structure.  No arguments. (see note below)
  * load - ??? Unconfirmed ??? I suspect this loads messages from a BBS message area but am unable to get this working.
  * join - Instructs the specified bot to JOIN a new channel. [Note: may also be specified in the [[:config:ircbot.ini:]] file as well]
  * part - Instructs the specified bot to dePART from a channel.
  * die - Causes bot to die (shut down). You don't want that, do you?
  * restart - Forces bot to restart, only works with bots running as a service.  If using JSExec the bot will DIE but not restart.
  * help - Displays helpful information about bot commands.
  * ? - This is the same as help above [Note: This is a command alias, created via //Bot_Commands["?"] = Bot_Commands["HELP"];//
  * ident - Identifies a user by alias and password. Use via private message only. [Note: create an alias for IDENT too.]
  * addquote - Adds a quote from your nick to the database.  Use QUOTE to see. [Note: quotes held in [[:config:ircbot.ini:]] file appended to bottom.]
  * quote - QUOTE returns quote assoicated with your nick, or search for a string to quote.
  * greet - Sets or clears the greeting I will display when you enter the room.
  * save - ??? Unconfirmed ??? Save some data locally?
  * prefix - Changes the bot command prefix. Default is BOT. Only needed in channels, not in private msgs.
  * nick - Change the bots nickname.
  * module - Toggle the status of modules in channels.
  * modules - Same as modules above.
  * abort - Instruct the bot to ABORT server output.
  * ignore - Tell the bot to IGNORE the specified nickname.

Note: The RELOAD command throws an error in it's default config. This should result in reloading [[:config:ircbot.ini:]] as well as all the modules, but fails with the following error;

<code>
TypeError: redeclaration of const MODULE_NAME
file: /sbbs/exec/ircbots/presence/presence.js
line: 27
</code>

You may comment out this section in the ''/exec/load/ircbot_commands.js'' file to avoid, but then you don't RELOAD modules, just the bot.

<code>
Bot_Commands["RELOAD"].command = function (target,onick,ouh,srv,lvl,cmd) {
	srv.o(target,"Reloading the bot configuration...","NOTICE");
	load("load/ircbot_commands.js");
	load("load/ircbot_functions.js");
	for(var m in Modules) {
		/* Don't reload libraries?? 
		for(var l in Modules[m].load) {
			if(Modules[m].load[l]) load(Modules[m],Modules[m].load[l]);
		} */
	}
	srv.o(target,"Reloaded.","NOTICE");
	return;
}
</code>

I'll start creating separate pages for the other modules as I work though them.

===== See Also =====
  * [[:module:|module index]]

{{tag>irc chat}}