_                   ___			
     | | __ ___   ____ _ / _ \ _ __     
  _  | |/ _` \ \ / / _` | | | | '_ \	
 | |_| | (_| |\ V / (_| | |_| | |_) |	
  \___/ \__,_| \_/ \__,_|\___/| .__/	
                              |_|		

• Home
  
• Introduction
• Getting Started
• Channel Moderation
• Writing Plugins
• Frequently Asked Questions
• Contributers

• Download
  
• Forum
  

Introduction

JavaOp2 is completely plugin oriented. Just about anything imaginable can be done with a plugin. Just about everything you see and use while using JavaOp2 is done by a plugin. Plugins are allowed to see, filter, and respond to packets, events, commands, errors, and more.

What software do I need?

The main software you need is the Java SDK. SDK means Software Development Kit. You need to have Java's SDK to do any kind of Java development. It can be downloaded from java.sun.com. I would recommend getting the 1.4.2 J2SE version, because that's what I use.

I strongly recommend you get the Eclipse editor. All the examples I'm giving will require Eclipse. It can be downloaded from Eclipse.org

How to get a copy of JavaOp2 source

You can get JavaOp2's source various ways:

• The best way to do this is to import it from my CVS through eclipse. To do that:
• Under the "File" menu, select "Import..."
• Choose "Checkout projects from CVS", and hit "next"
• When prompted for CVS server info, fill in the following:
• Host: www.javaop.com
• Repository Path: /src/master
• User: anonymous
• Password: [blank]
• Connection Type: pserver
• Port: default (2401)
• Save Password: [checked]
• Choose the "use an existing module" radiobutton
• You'll get a large list of projects. The important ones are:
• javaop2_pub -- The functions and definitions you'll need to create your own plugin
• javaop2 -- The base code for the JavaOp project. If you'd like to have a look at it, feel free
• web -- This website
• PluginTestHarness -- A class for testing plugins. More on it later.
• Version -- A very simple plugin, written by Warrior
• Ping -- Another simple plugin, written by me (iago)
• BNetLogin -- The plugin for logging in. Could be interesting to look at.
• AntiFlood, Autoban, ChannelList, ConsoleDisplay, Help, Moderation, SimpleEventProcess, SwingGui, and UserManagement -- Other plugins I've written, can be good examples.
• You can import more than one one if you hold control. All you need is javaop2_pub.

• You can also connect to the CVS server manually, if you'd like to. The commands are:
• $ cvs -d :pserver:anonymous@www.javaop.com:/src/master login
• (enter for blank password)
• $ cvs -d :pserver:anonymous@www.javaop.com:/src/master checkout <project>
• You can get a list of the projects in the section above.

• You can browse the source files here, it will always have the most up-to-date version. But that's the hard way to do it.

• Finally, you can download the files from the download page. The files, once extracted, will be .jar's. A .jar file is just a variation of a .zip, and can be opened by and program that supports zip files (winrar, winzip, etc). Inside you should find the .java files. You'll want to extract javaop2_pub from javaop2.jar.

Creating a project

1. Create a new project.
• Under the file menu, select "New->Project..."
• Pick "Java Project" and hit "Next"
• Give it a name
• I like to check off "Create seperate source and output folders", but that's up to you
2. Make the project depend on javaop2_pub
   • Right click on the project, and select "Properties"
   • Choose the "Java Build Path" option on the left
   • Choose the "Projects" tab
   • Check off "javaop2_pub", and hit "OK"
3. Create a new class called PluginMain, which extends GenericPluginInterface, and implements other interfaces that you want your plugin to be able to handle. See below for a list of the interfaces and what they do
• Right click on the project, pick "New->Class..."
• Name the class "PluginMain
• There should be a box for "Superclass", and on the right a "Browse..." button. Hit Browse, and set it to GenericPluginInterface.
• There should be a box for "Interfaces", and on the right an "Add..." button. Hit add, and add any interfaces you need. See the next section for more information
• Hit "Finish"
4. Fill in PluginMain with the appropriate information.
• See my examples for more details.
5. When you're ready to test it, you need to generate a .jar file. This is a little tricky in Eclipse, so I'll post some screenshots.
• Right click on your project in the "Project Explorer", and click on "export..."
• Choose "To .jar file" [screenshot]
• Check off just your plugin, and give it a name. The name you give is relative to your "workspace" folder, so if you don't specify a path it'll go to there, which isn't so bad. I personally like to put it inside a folder called "Plugins", as you can see in the screenshot. Then hit "next". [screenshot]
• You'll want to save a description of the JAR, so check that off. The path is relative work your "workspace" folder again, and I strongly recommend putting the .jardesc file in your project's folder. [screenshot]
• Finally, you'll want to save the manifest file. As usual, the path is relative to "workspace". I always put the Manifest file in my project's folder, and call it manifest.mf. [screenshot]
• That should generate the .jar file. Don't worry if there are warnings, warnings are common and generally harmless. You can now load it up in your bot and play with it!
• In the future, you can right-click on the .jardesc file and select "Create .jar" to quickly re-generate a jar file. Remember, whenever you make any changes to your plugin, you need to re-generate the .jar file before the changing will take effect.

The interfaces

When a plugin is written, the PluginMain class has to implement GenericPluginInterface, which identifies it as a plugin and lets JavaOp2's Core glean important information about it (author, version, etc.). However, if you want to be able to do anything useful, you have to implement other interfaces, which are listed below. Note that implementing one of these interfaces isn't sufficient to get notifications when the event occurs -- you also have to register the plugin. See the next section for that.

When you set up your bot, you tell Eclipse which of these interfaces you want to use. Each one is basically a series of functions that your plugin is forced to implement. These functions will be added automatically, ready for you to fill out. Remember, though, that in functions that require a return value, returning "null" or "false" will generally cancel the packet/event/whatever, and it won't go through, so make sure to actually implement them.

• BotCallback
• Your plugin can receive notifications for general bot-related activities, such as starting and stopping. The plugin is also capable of stopping a bot from shutting down if it wants to.
• CommandCallback
• Your plugin can receive notifications when a user in the channel whispers or sends a command. When you register your plugin, you're required to specify the command(s) that it recognizes, along with who is allowed to use them (the flags required) and the help for the command. I'll explain more about this in the next section.
• ConnectionCallback
• Your plugin will receive notifications about connecting and disconnecting. It can also cancel a connection or a planned disconnection.
• ErrorCallback
• Your plugin can be notified when an error occurs. Either a plugin throws an exception, or something.
• EventCallback
• Your plugin can receive events. There are quite a number of them, such as a user joining, user leaving, somebody talking, etc.
• OutgoingTextCallback
• Your plugin can register itself to see text that is being sent. This can be used for adding delays to outgoing messages (so you don't flood), for displaying outgoing messages, or for detecting outgoing commands.
• PacketCallback
• Your plugin can register itself to be notified when certain packets are sent or received. The plugin can also change or cancel packets before they're processed by other plugins or, if it's an outgoing packet, before it's sent.
• RawEventCallback
• Your plugin can receive the raw events from Battle.net. This is a username/message/code/ping/flags. The most useful feature of this is being able to change or cancel events. Floodbot filters and encryption can be done by this type of plugin.
• SystemMessageCallback
• Your plugin can see system messages that are sent by other plugins. This is useful for displaying or logging. One note that should be obvious: do NOT call out.systemMessage() from this!
• UserDatabaseCallback
• Your plugin can receive notifications when the user database is changed.
• UserErrorCallback
• Your plugin can receive notifications when a user makes a mistake. For example, using a command improperly, using a command that they aren't allowed to use, or using a command that doesn't exist.

Registering Plugins

In the plugin's activate() function, you're passed a variable called "PluginCallbackRegister register". This is what your plugin uses to register itself to receive notifications. You generally call register.registerXXXX(this, ...., null);. The actual parameters depend on which plugin. The last value is called "data", and is passed to your plugin whenever your plugin is called. It's not terribly useful, so I generally set it to null.

You can get a current list of registration functions from here. The comments provided above each function should suffice for documentation.

Public functions

When a plugin is activated, it's given an instance of PublicExposedFunctions called "out". The plugin can use "out" to communicate with other parts of the bot or with battle.net. "out" has a very large number of functions, but they're all commented and it should be clear what they do.

Examples

I haven't written any step-by-step examples, but I'll put links to a couple of my plugins here for now.

• Ping -- Responds to Battle.net's pings
• AutoBan -- Bans users with B or Z when they enter the channel, are in the channel, or have their flags updated.
• Help -- Provides the .help and .usage commands, and advises a user on proper usage of a command when they use it improperly.
• Version -- Provides the .version command which displays the (usually wrong, since I forget to update) current version. Very simple and clean, written by Warrior[x86].
• ConsoleDisplay -- Displays text in console. This won't compile alone -- pull from CVS to get all necessary files.

Advice/Comments

This is a faq-ish style section where I put any tidbits or random thoughts, as I think of them. As such, it'll probably grow on a regular basis, so check back often.

• For command plugins, leave the flag checking up to the core where possible.
• Don't use RawEventCallback unless you have to. It's much better to use the event after it's been processed, since sometimes the processing will delay or remove the event. You should wait till after all that to actually process it, unless you actually need the low level control.
• For RawEvent and Packet plugins, only register the plugin for the packets that it needs. Every plugin registered for a certain event or packet will slow it down a little.
• Starting with one of my pre-made or example plugins rather than starting from scratch could probably be very helpful.
• If you're interested in developing plugins, keep in touch with me via email or my forum. If you write anything that can be useful to others, I'll include it in my optional plugin collection.
• Throwing a PluginException if something goes wrong is fine, it will be caught later up the bot and usually get displayed.
• Throwing an IOException generally indicates that there is an error communicating with the Battle.net server. If one of them is thrown, the connection is closed up and it will attempt to reconnect. Don't throw an IOException on your own, unless you want to force an unplanned disconnect.
• Provide good help for your command, compressed into a line or two. This is generally all the documentation that a user will ever see.

All information on this page is public domain. If for any reason you want to copy/use this, feel free and have fun. All software and source directly distributed by me is public domain, and may be used in any way. Any copyrights I use (Particularely Starcraft, Brood War, Diablo, Warcraft, and Blizzard) are copyrights of their respective owners (in this case, Blizzard). Please respect all copyrights, and enjoy any public domain source code and software.