README for dicebot.rb
=====================

dicebot.rb is a Jabber (XMPP) chat bot, which rolls virtual dice for roleplaying games such as Dungeons & Dragons.

The latest version of dicebot.rb is available from http://paulgorman.org/software/dicebot/

REQUIREMENTS, INSTALLATION
==========================

1. Ruby

If you're running Linux or Mac OS X, there's a very good chance that the Ruby scripting language is already installed. You can check by opening a command prompt/terminal, and typing:

    ruby --version

If it comes back with a response like "ruby 1.8.7 (2010-06-23 patchlevel 299)" then you already have Ruby installed. If it comes back with a response like "command not found" then you need to get Ruby from http://www.ruby-lang.org.

2. Ruby Gems

To test if you already have Gems installed, open a command prompt/terminal and type:

    gem --version

If it comes back with something like "1.3.7" then you're good. Otherwise, get Gems from http:rubygems.org, and install it.

3. xmpp4r

dicebot.rb uses the library xmpp4r. The easiest way to install it is using Gem:

    sudo gem install xmpp4r

4. The dicebot.rb script

Put the dicebot.rb script in a convenient location, such as /home/me/scripts/dicebot.rb.

5. A Jabber/XMPP account for the dicebot.rb script

The dicebot will need its own instant messaging account. Create a new account for it, like "MyDiceBot999@example.com".


USE OF DICEBOT.RB
=================

1. Use your instant messaging client to start a multi-user chat on a Jabber chat server. How to do this varies slightly depending on your IM client. Either your client will get a room number for you, or you can choose it. If you're using the groupchat.google.com server, the room numbers look something like "private-chat-00000000-0000-0000-0000-000000000123".

2. Invite the dicebot user account to your chat. The script may not have permission to connect until you invite it.

3. Run the dicebot. Open a command propmt/terminal, and type:

    ruby /home/me/scripts/dicebot.rb botUserName botPassword private-chat-room-1234@groupchat.example.com/DiceRoller

(Obviously, it's not super-secure to type the password on the command-line, so don't use the same password you use for your banking.)

4. The bot should then join your chat. In chat, send the bot commands like:

    :roll 3d6+1

or

    :roll help

or

    :roll d8 poison damage

5. When you're done with the bot, just kill the process (usually CTRL-C in the command prompt/terminal).


LICENSE AND DISCLAIMERS
=======================

This script is copyright Paul Gorman 2010, and licensed under the GPL. See http://www.gnu.org/licenses/gpl.html for details.

Dungeons & Dragons is a trademark of Wizards of the Coast. dicebot.rb is not associated with Wizards of the Coast.