Introduction

Starting with 3.0, the old Java-based GUI (graphical user interface) has been removed and replaced with a web based UI instead. Furthermore, many of the options that were earlier saved in the database have now moved to properties files (the file ending is .properties on all these files), which should make them a lot easier to modify for everyone.

Installation Guide - LucidBot 3.0

1. Getting the bot

The first step is (as always) to download the bot. Visit The Download Page to download the latest version of the bot. If you're installing it for the first time, just unzip the download wherever you want the bot to be installed. Note that the bot needs to be able to write to and create files in the folder it's in, which means that for example in Windows, you don't want to put it in "Program Files" as applications are not allowed to write or create files there. On Windows, My Documents should work fine. I assume that people who use *NIX based operating systems know about privileges and such and can figure that out on their own.

If you're not installing the bot for the first time, you don't need to replace all the existing bot files with the ones from the download. If, for example, you've made your own changes to some files, you should just keep the existing files instead of overwriting. Check the change log for each release to see which files have changed and if it's changes you want to merge into your own files.

2. Installing

When you've unzipped the bot files in the first step, go to the folder and find the bot file itself (LucidBot.jar). The .jar file is a runnable Java file, and should therefore be set to be executed by the Java Runtime Environment (JRE for short). Version 3.0 of the bot requires Java 7 to run, so make sure you have the latest Java 7 JRE installed on your computer (it's a free download, check http://java.com).

For those who are running the bot on another computer, before trying to access the installation web UI, go fix IP access in the lucidbot.properties file. Access to the web UI is controlled by IP, so make sure to add the IP you're trying to access the web UI from to Setup.Allowed.IPs.

For the most part it should be possible for people to just double click on the jar-file to run the bot, but if it isn't, make sure to set Java as the application to use to execute the file (javaw.exe from the bin-folder in your JRE installation if you're on Windows). In most modern operating systems you shouldn't have to mess around to get this to work. If you're using an OS without a GUI, you can run the file with java -jar LucidBot.jar from the terminal.

If you're in for example Windows, after running the bot file, you should see a coffee cup icon show up in the system tray (bottom right corner). If you right click the icon, you should see an option to open the setup (if you don't, wait a few seconds and try again. If that doesn't help, something's failed to start properly, so check the error logs). Clicking that option will open up a web browser and go to the setup UI. If you're not in a GUI environment, the URL to go to is http://ip:port/Setup/ where the port is specified in the lucidbot.properties file.

Choose either the easy or the advanced installation, based on your preferences and computer skills. In the advanced mode, the options are: 1. Host: the database host. If you want to use the embedded database (it saves all the data in a folder next to the bot file), the host should be the word embedded. If you'd rather use MySQL instead, simple input the URL/IP to the database in question. 2. Name: the name of the database. This can be whatever you want, as long as it doesn't clash with any database that already exists. 3. Username: the username required to use the database. If you're using the embedded database, you can input whatever you want here, and that will become the username for the bot database from this point on. If you're using MySQL, you need to supply a valid username to a user with priviliges here (for example the root user you specified while installing MySQL). 4. Password: the password corresponding to the username from the previous step. Again, with the embedded database you can choose whatever you want here, while with MySQL it must be a valid password for the specified username.

When you click install, the bot will create the database and all the necessary tables and such. It might take a while, so don't click around, just wait. You'll get a notice on the page when it's done.

After a successful installation, shut down the bot (for example using the right click option Exit on the icon in the system tray). If you want to be sure it really worked, open up the lucidbot.properties file in something like Notepad, and make sure that the database host names and such are filled in correctly.

3. Setup

Now that the bot is installed, it's time to do some setup. Do the exact same thing as in the previous step (i.e. run the bot and go to the setup UI in the browser). If the bot was successfully installed, you should now have a bunch of different tabs to select from instead of the installation tab from the previous step. The idea is to go from left to right and setup channels, bots, users and the utopia settings like races and such. The different settings pages are pretty simple and should be easy to figure out. For races and such, you can click to load the defaults into the database, which will create all the races. Then you can just check and make sure they're correct by clicking the edit button on each race. Below you can read some short descriptions of each settings page.

Another thing you might want to do is go through the .properties files (except the logging file, unless you want to specify how the bot logs things) and see if you want to change any settings there. Most of the settings should be fine as they are, but others definitely need to be changed (for example the self kd location in utopia.properties). These files have plenty of comments in them that detail what the different settings do.

Channels

This is where you setup the channels you want the bot to join. You can have as many channels as you want. Channels are simple objects:

1. Name: the name of the channel, for example #lucidbot
2. Channel Type: the type of the channel. The options are: Public, Private & Admin. In a public channel, you'll only be able to use public commands like !calc, so it's suitable for channels where non-kd-members hang. A private channel is a channel where all commands may be used, basically a channel that belongs to the kingdom and that doesn't have outsiders hanging in it. The admin channel is just like a private channel, except that whoever is in there may use admin commands in there, regardless if they're a bot admin or not. Another difference between the channel types is which announcements are made in them. For example, in a public channel, nothing is announced. In a private channel, the bot announces ticks, armies coming home and so on. The admin channel also doesn't get any announcements.

A possible setup could be like this, given a kingdom named 'Lucid':

• #lucid.public - Public
• #lucid.private - Private
• #lucid.team1 - Private
• #lucid.team2 - Private
• #lucid.team3 - Private
• #lucid.tms - Private
• #lucid.admins - Admin

But of course it might be just fine to only have a single private channel too. It really depends on your requirements.

Bots

This is where bot instances are created. You can have as many bots connecting as you want, and they will share the load of responding to commands and such, and can also be set to join different channels. This is useful because if one bot is busy responding to some spammy command (such as the help command) to some user already, another bot can pick up the slack and respond to you instead. However, there is a severe limitation that comes into play here, namely that utonet currently only allows 3 connections per IP-address. That means that if you setup 5 different bots to connect to IRC, they will just all get temp-banned. Remember that if you're running the bot on your own computer, you're already using one of the allowed connections yourself, so then there's only 2 available for the bot, max.

In practice, unless you're running on some server without ip-limitations, most kd's will probably only use a single bot instance, or at most 2. But anyway, the possibility of using more is there.

When adding a new bot instance, you'll run into the following options:

1. Bot name/nick: The nick the bot will use on IRC. This nick needs to be registered with NickServ BEFORE you try to connect the bot. You can accomplish that by simply switching to the nick you want to give the bot (/NICK LucidBot) and then message NickServ with the registration command (/MSG NickServ REGISTER password E-mail). You'll then receive an email with activation instructions you need to follow (check the spam folder if you don't get it). After that you're ready to give the bot the nick.
2. Bot password: The password you used to register the nick. This is the password the bot will use to identify with NickServ, so it needs to be correct, or the bot will have issues identifying.
3. Channels: Select which channels you want this particular bot instance to join.

Users

This is where you add users. It's generally a good idea to at least add yourself here before you connect the bot the first time, unless you have user registration enabled. Once you've added yourself you'll have access to all the commands on IRC (at least if you set yourself as admin), so you can do the rest there if you want (adding users and such).

The options you run into when adding a user should be pretty self explanatory, except maybe Owner. The Owner is basically a super-OP. It's just a regular admin apart from the fact that you can never be deleted or demoted even by other admins.

Dragons - Bonuses

These tabs are for setting up various utopia stuff. Mostly you'll just want to click Load defaults on each one and you're pretty much done, unless it's an old bot version and you need to update stuff for a new age. The only thing you need to do yourself besides loading the defaults is assigning spells to the races. Make sure to load the defaults in the Spells tab, and then go back to the Races tab and edit the races. You'll see that you can select the spells from a list of all available spells. For the most part, adding spells is irrelevant, but sometimes it's good to do. The most useful one to add is Town Watch, since it affects how the bot does calculations for defense (that is if you want Town Watch to be assumed to be on. If you expect it to be off, don't add it to the race at all). Others that are useful are Mage's Fury and Invisibility, which are used in calculations of mod tpa and wpa if they're added to the race.

When you look around you'll notice the use of "Bonuses". They're attached to spells, races and so on to let the bot know how to calculate things. For example, when it tries to calculate gains for a hit, it checks if a province has spells, buildings, race bonuses and so on that would affect gains (for example, Avian has a -10% gains bonus). The bonuses are automatically added when you load defaults for the various settings, but you can create and assign them manually if you want as well, just go to the Bonus settings page and create a bonus, then back to whatever entity you want to add the bonus for and select it from the bonus list.

Commands

This is a page where you can add information to the various bot commands. Basically what you're doing here is overwriting information on the commands. All commands have defaults, but you can choose to set another help text, or use another template and so on. The options are:

1. Command Type: This is basically just a grouping of commands. It's used by the help command in order to group commands that do similar things.
2. Access Level: Decides who has access to this command. Note that changing this setting might break some commands. For example, calling !province with no parameters is meant to just display your own province. But if you're not a registered user, the bot can't possibly identify which province is yours, so the command will not work. Only change this setting if you really know what you're doing!
3. Template File: This sets which file is responsible for formatting the output that's sent to IRC when the command has been handled. It's unlikely that this will need to be changed very often. It's more likely that you will want to edit the file itself.
4. Syntax: A description of how to use the command. If no syntax is set here, the bot will use defaults, which in many cases will be sufficient.
5. Help Text: Describes what the command does. If no text is set here, the command will have no help text at all. All commands come with a default help text, but if you change it here, it will be overridden. I.e. if you set it to empty here, it will be empty, even if the default text isn't.

Status

This is where you check the status of the bot, which includes connecting and disconnecting bot instances. Because of limitations in the framework used to create the web UI, I couldn't get this page to auto update every x seconds, so you'll need to click the Refresh button at the top of the page every now and then to get the latest info.

4. Run, Forrest. Run!

When you're all done setting things up and want to connect to IRC, go to the Status page in the setup UI. How to make a bot instance connect to IRC from there should be fairly obvious. If you don't want to have to manually make the bot connect each time you start the bot, there's a property in lucidbot.properties that will make all defined bot instances auto connect on startup if you enable it (it's disabled by default).

Make sure to give the bot appropriate OP powers in the channels before you connect it, otherwise it will fail to invite itself. As long as you give the bot @ or higher, it can invite itself, and then you don't have to tell it channel passwords or anything. Invite only channels are also no problems. www.utonet.org has a good help section that shows how to use various commands to manipulate OP and channel settings and such, so make sure to browse through it if you feel uncertain about IRC and how to use it.

Do you feel there's something missing in this guide, or that anything is hard to understand? Please let me know, so I can fix it. If you want to add something yourself, that's fine too. Just contact me on IRC in #lucidbot