Readme - Java Battle.net Bot


contents	The Java Battle.net Bot Starting the Bot Command-line Options Message System Config Files, Users, Groups and Memos Services Shape of Things to Come Unuseful Information Epilogue for American Readers
the java battle.net bot	1.0.2, don't have time to write anything new here! :-)
starting the bot	Unfortunately, running Java applications isn't as easy it should be. It depends on your Java Runtime Environment (JRE). First, to make things easier for most of you, this is one way of doing it on a Win32 platform: 1. Download the JavaSoft JRE for Win32 from: http://www.javasoft.com/products/jdk/1.2/jre/download-windows.html (Just click the "continue" button in the middle of the page) 2. Install it You know how to do that :-) 3. Run the bot Type: `java -jar bot.jar` in the directory you unzipped to. If you haven't put the JRE bin directory (like C:\Program Files\JavaSoft\JRE\1.2\bin) into your path (see readme shipped with the JRE) you'll have to type it before the java command. If you've already got a JRE installed that's 1.1 compatible, type: `jre -cp bot.jar Bot` (caps Bot correctly) Other OSes and JREs I cannot write here how to do it on every JRE (nor do I know), so you'll have to check the readme files. Some info you might need to look for is the following: First of all, javabot is a Java application, not an applet. This meens it doesn't run in a web browser, and it does more than just display nifty graphics (although the text scroller is rather impressive, if I may say so myself). It can be run on any JRE that is compatible with Java 1.1 or later. It is a Java JAR file (bot.jar), and does have a Java 1.2 main-class header. If you're not running a 1.2 compatible JRE, the main class is called "Bot" (.class), case sensitive. Javabot is not a package. Javabot uses the following standard Java packages: java.lang, java.util, java.io, java.net, java.awt, java.awt.event As I said, javabot is written in Java 1.1. I have tested it on Win 95/98/NT4, Linux 2.0/2.2 and Solaris. I am pretty sure it will run anywhere.
command-line options	-console awt Graphical, fun to use interface with chat and one hell of an about window. This is the default console :) -console text Textish console, not too fancy, no send capability. -console none Only display messages, good for running it as a background process. -timeout <time in seconds> Sets socket timeout, useful on the extremely rare occations when battle.net lags (Blizzard please hire me! :-). Default is 120 seconds. -nolog Turns off logging. -loglevel <level> Sets minimum level of messages that will be written to log file. See part about messages below. Default is 1. -msglevel <level> Sets minimum level of messages that will be sent to console. See part about messages below. Default is 2.
message system	Messages are short text strings generared on various places in the program. Every message also has a priority from 0, lowest, to 3, highest. These priorities are: 3: Errors, Exceptions, bad stuff 2: Running related things, normal messages 1: Messages related to user-generated events 0: Debug, socket input and output Don't log level 0 unless you want to exceed your quota... As noted above, the default console message level is 2, and 1 for logging. Those values have proved to be suitable (unless when debugging), that's why they're called the Default Values... :-)
config files, users, groups and memos	I'll try to explain a bit how the bot works with users and groups here, as well as explaining how it stores this information on disk. But first, let's look at the most important file that you absolutely have to edit if you want your bot to work decently. Bot.properties This file is formatted almost like an ini file. These options are available: username = <bnet username> Create this account with one of Blizzard's products. Default is "Guest". password = <bnet password> Account password. Default is blank. homeChannel = <bnet channel> This is the channel the bot hangs in. You do not need to create it with any of Blizzard's products. :-P Default is "Java Bot". hosts = <long list of bnet host names> A default list is provided so you don't have to bother about this unless you tend to like some specific servers more (like I do, that's why I placed them first in the default list :-). This list should be semi-colon separated. Default is the original list copied from my computer's registry, modified to suite me. :-P restricted = <level> Sets the original channel restriction to the following access level. Everyone with a lower level will be kicked out. welcomeMessage<level> = <welcomming message> welcomeWhisper<level> = <welcomming whisper> welcomeAction<level> = <welcomming action> This is how your bot will greet people of different levels. A message is sent publically in the channel, a whisper privately to that person, and an action is that stuff that happens when you type like "/me really, really loves Blizzard". No defaults, although some rather funny examples are provided with the included Bot.properties file. If you're not interested in modifying things by hand, you won't find anything interesting in the rest of this part. Skip it. (Gee, I whish Microsoft would have the same ideology...) users.dat and the user system If you want to hack this file this is how you should do it, if you don't want to screw up your user database. Oh, did I mention you really could mess things up if you change stuff here? No problem, just make sure you do a backup first. Each row represents one user. The format of a user (User.toString()) is as follows: (Although in the users.dat file, all spaces have to be tabs! And it has to be on one row!) `Name Group notifyMe notifyOthers channelMonitoring wins losses discs seenWhere seenWhen` Name is the Battle.net username of the user. Case sensitive. Group is the bot's group (see groups.dat). Case sensitive. notifyMe is "true" if the user wishes to be notified of other users' arrival. If the user doesn't, it is set to the text string "false". norityOthers is weather or not the user triggers a notify for other users. Can be "true" or "false". channelMonitoring tells the user when people enters or leaves the bot's home channel. "true" or "false". Note that these three settings can all be overridden by the group (see groups.dat). Darn I'm so used to programming Java I automatically end each sentence with a semi-colon... :-) wins, losses, discs speaks for themselves if you've ever been on battle.net. These are just numbers. Note that these are normal games and ladder games combined, only for the bot's ability to congratulate etc. seenWhere, seenWhen is rather speaks for themselves too. Where could be like "game "2on2 YxA!"" or "channel Brood War SWE-1"" or "the channel". When is the time in seconds since 1970-01-01 00.00 UTC. Hey, you should be glad I decided not to store it in milliseconds! :-P groups.dat and the fabulously complex groups Und jetzt, die Gruppen bitte! Eine Gruppe ist ein organisatorisch Einheit, daß... Just kidding! Anyway, groups are rather useful in the Javabot, unlike many other bots, cough wntrs cough ggdrp cough, they are not only setting the access levels, like in other bots, but are much more complex in their usage. (More features will be added in later versions.) What you can do now is, for instance, send memos only to a specific group, like if you have many clans in a channel (like in my home channel YxA). Each clan can then be given a group of their own, enabling them to not only send each other messages, but also sending challanges to other clans. In Javabot, a specific user does not have a specific access level, instead it has the group's level. 'Nough talking. The format of groups.dat is as follows: `Name level autoKick autoRemove notifyMe notifyOthers channelMonitoring overrideNotifyMe overrideNotifyOthers overrideChannelMonitoring`Name explains itself. level is a numeric value. Internally, the bot uses 0-5 for access levels, so it might be a good idea to keep it in that range. See the Services file for more on that. Can only be an integer (no decimals). autoKick is like the rest of the arguments "true" or "false". In the groups.dat file included in the zip file there is a group called enemy that has autoKick. Explains itself pretty much. notifyMe, notifyOthers, channelMonitoring is the values that the user's preferences with the same names (see users) are given if the override for this preference is enabled. overrideNotifyMe, overrideNotifyOthers, overrideChannelMonitoring is what it sounds like. Weather or not the group should decide over the user. Try not to think of it as communistic, but an organizational advantage. :-) memos.dat and the rather useful memo system Memos allows bot users (and the bot itself) to send each other memos. This is a really neat feature. It's really easy too, just send "memo <who> <what>" to the bot (see Services file). A memo is delivered to the receiver when the bot can confirm that the user is really logged on and able to receive it. This usually happens within a minute of the sending. However, the real reason to use memos isn't of course sending them to people who already are online, but to send them to people who are not online. This is where the memos.dat file comes in. Format is simple, but unlike the other files, it doesn't use single rows, so each line showed here is in fact a line in the file too. From - the sender To - the receiver Text - blah blah blah That's easy! But you won't probably ever have to edit this file (unless you like reading other people's mail :-), because of the fine memo services (see services part). Ok, so that's the important stuff. It may become clearer if you look at the files shipped with the bot. There is no necessity in changing the groups if you don't want to. Just remember, if you change name on a group, make sure you change it in every user in that group too. There will be graphical tools for doing this in the near future (see the "Things to Come" section).
services	Now, if this was a normal bot, this chapter would be called "commands". But it isn't, so it's called "services". :-) Services are things the bot does for users, on battle.net, in response to commands given by users. I had written a long list of all available services, which I intended to but in a separate file, on my Palm during a meeting yesterday. Of course I forgot the HotSync cradle at my fathers house... Anyway, you'll see more of that on the web site in a few days. Services are sent to the bot either by private whisper, or in the channel. If there are more people than you and the bot in the channel, you need to add "bot" somewhere in the text. Here are a some of the most important services: `memo who what memo online what memo all what who is who who am I who are you who has been here seen who [don't] notify me [don't] notify others [don't] monitor channel go private go public set restriction level new user name group remove user name` There are lots of more things to tell it, most of them are in plain English, so just test things out. Not all access levels are allowed to use all services, but it'll tell you, just try. As I said, a complete list of all services and levels, as well as descriptions, will be out in a few days.
unuseful information	I started programming the bot, originally called Yxabot (Swedish for Axe Bot), for personal use only (just as with mirc, and you see what happened there :-). I programmed the core of the bot during the really worst 1-2 week when battle.net was costantly "in a state of flux", as Mr Spock would put it. You can't imagine how I felt the first time it had stayed up 24 hours (which I had put up as the release date, more than a month ago). It is written in NotePad, WordPad, joe and later on a really nice shareware I found, TextPad. Some parts, like this text, is written in Memo Pad on my Palm III. Most have been done in school. Anyway, I'm watching the Miss Sweden show on tv right now and I think Miss Stockholm is the sexiest. Miss Medelpad and Miss Öland isn't bad either. I did call this "unuseful information", didn't I? Henrik Falck, javabot@swipnet.se Härnösand 99-03-27 /join YxA
shape of things to come	Well, I, and other contributors, have a lot of ideas that are not yet implemented. I'd planned to realease this months ago, so I just set a deadline on Sunday 1999-03-28. Some things are: Graphical tools for editing users and groups Lots and lots of new services Remote administration console BotNet (this would actually be rather fun to implement on bnet) More stuff... If you have any ideas please send them to javabot@swipnet.se right away and I'll add you to the contributors list! :-)
epilogue for american readers	And now, the moment you've all been waiting for! The cryptic, ununderstandable, amazingly boring... legalistics! I'm sure I've used a lot of trade marks, registered stuff and other things I don't even know about. Actually, I've just made all this up. Nothing I've said is true. I don't even remember writing this. Every word belongs to its owner. So please don't sue me, unless you'll pay my trip to the US for the trial - in that case, please sue me right away, I'm sure I'll get away with it, I'm obviously not in control of my mind. The Java Battle.net Bot is probably copyrighted to me too One thing I do care about is that no one steals the graphics, the robot picture that is, because I haven't made that myself, a friend of mine made it for me to use with this program, so please have a little respect for that. In other words, the robot picture is copyright Einar Sandström 1999. The Java Battle.net Bot is Kåppirajt (k) Henrik Falck 1999