RedChu

iRCbot Plug-in Writing Guide

May 18th, 2011
113
0
Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
text 12.85 KB | None | 0 0
  1. ***************************************
  2. * iRCbot Plug-in Writing Guide *
  3. * *
  4. * last updated *
  5. * may 18 2011 *
  6. ***************************************
  7.  
  8.  
  9.  
  10. ==============================
  11. VERSION HISTORY
  12. ==============================
  13.  
  14. v 1 - may 18 2011
  15. ----- Finished writing the guide. It's all here, everything I
  16. could think of to include. All variables currently
  17. defined, arrays, functions, etc... it should help those
  18. who wish to create a plug-in for iRCbot to do so.
  19.  
  20. I even included templates to help you get started.
  21.  
  22.  
  23.  
  24.  
  25. ==============================
  26. Table of Contents
  27. ==============================
  28.  
  29. 1. Introduction
  30. 1.1 How iRCbot works
  31. 1.2 Commands and parameters
  32. 2. Core features
  33. 2.1 Variables
  34. 2.2 Arrays
  35. 3. Making a plug-in
  36. 3.1 Help parameter
  37. 3.2 Requiring a certain level
  38. 3.3 Relaying errors
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48. --------------------------------------------------------------------------------------------
  49. 1. Introduction
  50. --------------------------------------------------------------------------------------------
  51.  
  52. 1.1 How iRCbot Works
  53.  
  54. iRCbot is a modular IRC bot written in PHP. iRCbot uses plug-ins
  55. which extend upon it's core functionality. This guide is meant to
  56. explain how to create plug-ins for iRCbot, but first we must know
  57. how iRCbot works.
  58.  
  59. It is assumed that you have an understanding of PHP as all
  60. plug-ins must be written in it. It is not required that you be an
  61. expert with it, as long as you have a decent understanding of
  62. how to use it for what you want to achieve with it in your
  63. plug-in.
  64.  
  65. iRCbot is essentially a one piece program, meaning that it is
  66. perfectly capable of running on its own. Plug-ins extend the
  67. functionality of iRCbot by providing it with more capabilities
  68. than just idling in a channel and stalking the users.
  69.  
  70. Basically, iRCbot alone can only connect to the server, join the
  71. default channels and then idle. All other functionality is provided
  72. through plug-ins which are executed by commands that users
  73. send to iRCbot through a PRIVMSG, which if you're unfamiliar
  74. with IRC, is either a query to iRCbot or a message sent in a
  75. channel which iRCbot is present.
  76.  
  77. 1.2 Commands and parameters
  78.  
  79. All commands are recognized by a ~ (tiled). The command must
  80. be started at the beginning of a PRIVMSG for it to be recognized
  81. by iRCbot.
  82.  
  83. All commands use the file name of the plug-in in the plug-in
  84. directory where iRCbot is stored. You cannot change the name of
  85. a command unless the plug-in file's name is changed as well,
  86. at least at this time.
  87.  
  88. Sample command:
  89.  
  90. ~test donkey kong
  91.  
  92. In the above sample, we have the command (~test) and two
  93. parameters (donkey, kong).
  94.  
  95. Parameters do not always have to be required for a command.
  96. If a plug-in requires two parameters, then two parameters should
  97. be returned, ignoring others unless otherwise specified.
  98.  
  99. Some plug-ins, such as say, use an infinite amount of parameters,
  100. not one of which are required but the first.
  101.  
  102. It's a bit difficult to explain without seeing an already made plug-in,
  103. but we'll get to that point later in this guide.
  104.  
  105. So far, you know that a command is what executes a plug-in and
  106. that they share the same name, and that plug-ins may have up to
  107. any number of parameters depending on the circumstances.
  108.  
  109. Let's say you want to add a user to a list... let's use the adduser
  110. plug-in as a reference:
  111.  
  112. You want to add a user to the list along with a numeric value for
  113. the user's level. You create a plug-in that will be executed by the
  114. command ~adduser. You need to get the nick of the user as well
  115. as the level you want to add the user as having, so you require
  116. two parameters to ~adduser:
  117.  
  118. ~adduser <nick> <level>
  119.  
  120. Parameter <nick> will contain the nickname of the user, and
  121. parameter <level> will contain the numeric value for the level.
  122.  
  123. Now that you know how plug-ins are executed, let's learn how
  124. to make the most of them!
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134. --------------------------------------------------------------------------------------------
  135. 2. Core features
  136. --------------------------------------------------------------------------------------------
  137.  
  138. 2.1 Functions
  139.  
  140. iRCbot contains a number of ready made functions that make
  141. the life of an iRCbot plug-in creator easier. Gone are the worries
  142. of meddling with the IRC protocol, as difficult and daunting a
  143. task that it isn't.
  144.  
  145. The functions that you will likely be using the most is the privmsg()
  146. function, which is what iRCbot uses to send messages to a
  147. channel or nick (whichever works).
  148.  
  149. All functions must be used in this fashion:
  150.  
  151. $this->functionnamehere();
  152.  
  153. The reason for this is because of the way iRCbot is designed. As
  154. a plug-in, you are directly adding to iRCbot's class. iRCbot is
  155. in a continuous loop state until a command is thrown its way,
  156. which then if the plug-in exists, it executes the plug-in until the
  157. end and then it goes back into its loop state.
  158.  
  159. $this-> signifies that it is part of the class. iRCbot is an object
  160. so to speak, and since the functions are defined within
  161. the object, you have to signify that you want to use them in
  162. this object... I might be wrong as I'm fairly new to object
  163. oriented programming, but that's how I would explain it
  164. and that's how I did!
  165.  
  166. Anyway, here's a list of the currently available functions and
  167. how to use them:
  168.  
  169. privmsg($channel, $message)
  170. Sends $message to $channel. $channel can be either a
  171. channel name or a nick.
  172.  
  173. action($channel, $message)
  174. Sends an action command containing $message to
  175. $channel. An action command is essentially a /me
  176. command.
  177.  
  178. nick($name)
  179. Changes the nick of iRCbot to $name if it is not already
  180. in use.
  181.  
  182. kick($nick, $message = null)
  183. Kicks $nick out of the channel it's called from. $message
  184. is an optional parameter, but if used will use a custom
  185. kick message instead of the default one.
  186.  
  187. join($channel)
  188. Joins $channel. If $channel is an array, it joins all of the
  189. channels in the array... if possible, that is.
  190.  
  191. part($channel)
  192. Leaves (or parts) $channel. If no channel is specified, it
  193. parts the channel from which it was called.
  194.  
  195. quit($message)
  196. Disconnects from the server with an optional custom quit
  197. $message. iRCbot's default quit message is "My time has
  198. come...".
  199.  
  200. notice($nick, $message)
  201. Sends a notice containing $message to $nick. $nick can
  202. also be a channel instead.
  203.  
  204. send($type, $param = null)
  205. Sends raw data to the server. Basically useful if you want
  206. to do something that a function can't or when there is
  207. no function that does what you want to do. $type is the
  208. IRC command, such as PRIVMSG or something similar,
  209. and $param is an optional parameter. As it is optional,
  210. $param doesn't have to be used and $type can be the
  211. only parameter used.
  212.  
  213. 2.1 Variables
  214.  
  215. iRCbot contains a number of variables and arrays that contain
  216. data from the server to make your life easier. Most variables and
  217. arrays contain specific data that has been parsed from the main
  218. buffer to make it easier on plug-in creators to create plug-ins, so
  219. they don't have to know how to get the information themselves
  220. from the raw buffer data.
  221.  
  222. Unlike functions, no variables require $this-> prior to the variable
  223. name. Here's a sample variable call:
  224.  
  225. $channel
  226.  
  227. It's obvious and easy, and all of the variables have self-explanatory
  228. names so you'll know what they contain.
  229.  
  230. Here is the list of pre-defined variables and what they contain:
  231.  
  232. $channel
  233. Contains the channel which the command was received. If it
  234. was received via query to iRCbot, it returns iRCbot's current
  235. nickname. The functions privmsg and action take this into
  236. account so it is not necessary to check for this if using those
  237. functions.
  238.  
  239. $nick
  240. Contains the nick of the person that used a command.
  241.  
  242. $name
  243. Contains the username of the person that used a command.
  244.  
  245. $host
  246. Contains the hostmask of the person that used a command,
  247. but does not include the nick or username portions of of the
  248. hostmask, and only that after @.
  249.  
  250. $level
  251. Contains the level of the user that used a command. Returns
  252. nothing if the user is not in the user list.
  253.  
  254. $call_help
  255. Indicates whether the -help parameter was used. Returns 1 if
  256. so, otherwise returns 0.
  257.  
  258. $data
  259. The buffer. Contains raw data received from the socket with a
  260. maximum size of 512 bytes.
  261.  
  262. 2.2 Arrays
  263.  
  264. Arrays have the same use as variables, but some arrays do indeed
  265. use $this->. However, all of the arrays that have been made to make
  266. your job easier do not require $this->. Here's an example of calling an
  267. array:
  268.  
  269. $parameter[0]
  270.  
  271. As you should already know, arrays start at 0 increase in value by 1
  272. for each value within the array.
  273.  
  274. Here is the list of pre-defined arrays and the information they contain:
  275.  
  276. $command
  277. Contains the command called. Value starts at 1 rather than 0.
  278.  
  279. $parameter
  280. Contains the parameter(s) after a command. Value starts at 0.
  281. Pretty much contains everything that is said after a command.
  282.  
  283. $default_chan
  284. Contains the list of channels that iRCbot joins on startup.
  285.  
  286. $plugins
  287. Contains the list of loaded plug-ins. Is automatically updated
  288. when a plug-in is loaded.
  289.  
  290. $users
  291. Contains the list of users and their levels. In the array, value 0
  292. is the user and value 1 is the level. It follows this pattern for all
  293. users in the list.
  294.  
  295. $ignored
  296. Contains the list of users currently being ignored by iRCbot.
  297.  
  298. $this->full_data
  299. Contains the data from the buffer, but is exploded by whitespace.
  300. Not necessary unless wanting to achieve something that iRCbot's
  301. core functionality cannot.
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311. --------------------------------------------------------------------------------------------
  312. 3. Making a plug-in
  313. --------------------------------------------------------------------------------------------
  314.  
  315. 3.1 Help parameter
  316.  
  317. It is not required for a plug-in to respond to a -help parameter,
  318. but it is good if it does as users who want to know what it does
  319. and how to use it will be able to find out by using it.
  320.  
  321. A help parameter is used like so:
  322.  
  323. ~command -help
  324.  
  325. iRCbot checks whether the parameter is used before if executes
  326. the plug-in, and it is not recognized if not used as the only
  327. parameter.
  328.  
  329. When the -help parameter is used, it sets the variable $call_help
  330. to 1 before the plug-in is executed. It is up to the plug-in to check
  331. if $call_help is true (1 is true, 0 is false) and then act accordingly.
  332.  
  333. If you wish to acknowledge the help parameter, you may do so
  334. however you like, but it is encouraged that you use (or at least
  335. follow) this basic template:
  336.  
  337. <?php
  338.  
  339. $usage = "Use: ~command <parameter>";
  340. $info = "This is information on what the plug-in does and how it works.";
  341.  
  342. if($call_help)
  343. {
  344. $this->privmsg($channel, $usage);
  345. $this->privmsg($channel, $info);
  346. }
  347. else
  348. {
  349. // Plug-in code goes here
  350. }
  351.  
  352. ?>
  353.  
  354. 3.2 Requiring a certain level
  355.  
  356. Some plug-ins, depending on what it does, might be best if use
  357. is restricted to users with a certain minimum level. Users that are
  358. not on the user list or whose level is less than the minimum
  359. required level will not be able to use it. This is good if the plug-in
  360. does something that you don't want everyone to be able to do,
  361. such as changing the topic of a channel, kicking a user, etc...
  362.  
  363. As there is no limit to the level one can have, it is best if you
  364. check if a user's level is greater than or equal to the desired
  365. minimum level, rather than just equal to. This allows users with
  366. a higher level than the required level to use the plug-in. I hope
  367. that you already knew that, though.
  368.  
  369. Here is a template that you can use for a plug-in which requires
  370. the minimum level of 150.
  371.  
  372. <?php
  373.  
  374. $usage = "Use: ~command <parameter>";
  375. $info = "This is information on what the plug-in does and how it works.";
  376.  
  377. if($call_help)
  378. {
  379. $this->privmsg($channel, $usage);
  380. $this->privmsg($channel, $info);
  381. }
  382. elseif($level >= 150)
  383. {
  384. // Plug-in code goes here
  385. }
  386. else
  387. {
  388. $this->privmsg($channel, "Can't let you do that, $nick.");
  389. }
  390.  
  391. ?>
  392.  
  393. 3.3 Relaying errors
  394.  
  395. Sometimes a user won't use a plug-in properly, but if it doesn't
  396. say what's wrong, they won't know! It's not required that you
  397. relay messages telling the user what they did wrong, but it
  398. providesa better user experience and also helps for debugging
  399. your plug-in.
  400.  
  401. It's best to check to make sure that parameters are not empty,
  402. or at least the parameters required. You can relay specific
  403. messages to the user when one is empty so they know what
  404. it was they did wrong. This is just an example of when to relay
  405. a message containing an error or what happened that was
  406. wrong.
Advertisement
Add Comment
Please, Sign In to add comment