Terminus-Bot: The IRC Bot to End All Others

terminus-bot.net

chat.freenode.net #Terminus-Bot

Join the chat at https://gitter.im/Terminus-Project/Terminus-Bot

About the Bot

Terminus-Bot is an IRC bot written in Ruby under the MIT license. Its purpose is to completely avoid the problems of other bots.

The authors of the project are long-time IRC bot users and know how things can go badly or be confusing. Hopefully, we can address all of the problems we have encountered, as well as all of those everyone else tells us about.

Requirements

How to use Terminus-Bot

Installation and Configuration

See doc/GettingStarted.md.

After that, if you are interested in running Terminus-Bot in a Docker container, see doc/Dockerizing.md.

Code Documentation and Guides

Documentation, including most internal and scripting APIs, is hosted at http://terminus-project.org/terminus-bot/doc/index.html. These docs are a work in progress; contributions are welcome!

You may also generate these docs by running yard from the project root (this requires the yard and redcarpet gems).

Scripts

This is a complete list of all official scripts that are distributed with the bot. Commands provided by each script are listed here. For more complete information on what a command does and how to use it, you should view the on-IRC help for the command by using the help script's HELP command.

In these examples, the command prefix used is @. When using the bot, be sure to use whichever command prefix you set in the core configuration block.

Account

Create and log in to bot accounts. This script is required if you want access to administrative functions.

Commands:

Admin

Manage the bot's core functionality.

Commands:

Away

Announce away status in channel when users are highlighted. This is pretty annoying, but some archaic IRC clients don't know how to mark away users in the nick list, so this can be useful.

Commands:

Backspace

React to ^H, ^W, ^U, and ^Y by displaying the resulting text.

Base

Convert a number from one numeric base to another.

Commands:

Battle

Facilitate PRNG-based role-play battle games. No turn-based enforcement is done, so it is up to the users how to use this. Once a battle is started, interaction is done with IRC actions (/me). For example:

<@Kabaka> @battle start
<Terminus-Bot> Kabaka has started a battle!
<Terminus-Bot> To attack other players, use /me attacks TARGET with ITEM
<Terminus-Bot> You may check the health of active players by using the HEALTH command.
* Kabaka attacks aji with Hammer of Thor
<Terminus-Bot> Kabaka's Hammer of Thor hits aji for 12 damage.
<Terminus-Bot> aji has 88 health remaining.
* aji attacks Kabaka with pointy sticks
<Terminus-Bot> Kabaka absorbs the hit and gains 20 health!
<Terminus-Bot> Kabaka has 120 health remaining.

Starting health, the amount of damage that is possible, and the chance of hits being ineffective is all configurable in terminus-bot.conf. Any players in the channel may join in at any time. In large channels, this can get incredibly hectic, so it is strongly recommended that this script only be used in smaller channels.

Commands:

Chanlog

Log channel activity to disk. To disable logging for a specific channel, use the bot's script flags to disable the script in those channels. Logs are written to var/terminus-bot/chanlog/ with the file name format server.channel.log.

This script is still experimental and will be subject to extensive changes before beta.

Channels

Join and part channels, and maintain the list of channels the bot tries to occupy. Without this script loaded, the bot will not attempt to join any channels and will not rejoin channels the next time it starts.

Commands:

Choose

Lets the bot make decisions for you. There are two types of questions you may ask the bot: Yes/no questions and questions with multiple answers.

To ask a question, begin your message with the bot's commmand prefix followed by a space. For example:

<Kabaka> @ Should I go to bed?
<Terminus-Bot> Kabaka: No

<Kabaka> @ Ruby, Python, or C?
<Terminus-Bot> Kabaka: Ruby

Cipher

Encode and decode text using basic ciphers.

Commands:

CTCP

Give the bot the ability to respond to some CTCP requests. Without this, the bot will not be able to respond to things like CTCP PING and CTCP VERSION.

Available CTCPs:

Derpibooru

Search for and look up images on Derpibooru. Search syntax is identical to that on the web site.

Commands:

DNS

Perform DNS look-ups.

Commands:

DuckDuckGo

Query DuckDuckGo.com.

Commands:

e621

Search for and look up iamges on e621. Search syntax is identical to that on the site.

Commands:

Eval

Commands:

Exchange

Get up-to-date exchange rates from openexhangerates.org. Requires an API key. Sign up free: https://openexchangerates.org/signup/free

Commands:

Factoids

Remember and recall short "factoids." Factoids are short blocks of text. For example:

<Kabaka> @remember Ruby is the best programming language
<Terminus-Bot> I will remember that factoid. To recall it, use FACTOID. To delete, use FORGET.
<Kabaka> @factoid Ruby
<Terminus-Bot> ruby is the best programming language
<Kabaka> @forget ruby
<Terminus-Bot> Factoid forgotten.

Commands:

Flags

Manage the bot's script flags table.

This script is experimental and will be subject to change before beta.

Terminus-Bot allows you to enable or disable scripts per-channel. This is done using script "flags." Flags can be on or off for any script in any channel on any server.

When accessing or modifying the flags table, wildcards are supported.

For example, if we want to disable all scripts on the Freenode network:

<Kabaka> @disable freenode * *

If we want to see what scripts are enabled in the #Terminus-Bot channel on StaticBox:

<Kabaka> @flags freenode #Terminus-Bot *

Commands:

Flist

Interact with F-list.net.

Note: for access to character information, the character owner must have enabled API access in their account settings.

Commands:

FOAAS

Interact with the FOAAS service at foaas.herokuapp.com.

Commands:

Games

Provides a few basic gaming commands.

Commands:

Gizoogle

"Translate" text using Gizoogle.

Note: Gizoogle has no API as of the time of writing, so this script scrapes the web page. Because of this, it may be prone to breakage.

Commands:

Google

Search the Internet with Google.

Commands:

Help

Provide on-IRC help for bot commands and scripts.

Commands:

ICNDB

Get jokes from the Internet Chuck Norris Database.

Commands:

IdleRPG

Allows the bot to play Idle RPG and/or interface with an XML API to look-up information about other players.

Commands:

Ignore

Manage the bot's ignore list. Ignores are wildcard-matched strings in the format nick!user@host.

Commands:

IsUp

Check the availability and responsiveness of web services.

URI syntax is the usual protocol://hostname:port. If no port is given and the protocol has a default port, it is used.

Supported protocols are currently:

Commands:

Karma

Track user "karma" based on observed nick++ and nick-- messages.

Commands:

LastFM

Access information on last.fm.

Script script is experimental and will be subject to change before beta.

Commands:

Lorem

Retrieve Lorem Ipsum placeholder text from loripsum.net.

Commands:

LMGTFY

Generate "Let Me Google That For You" links.

Commands:

Lograw

Log all messages the bot sees. Messages are logged to the core logger, so information is in var/terminus-bot.log. This script is primarily intended for developer use and will not be helpful to most users.

Markov

Create Markov chains based on word statistics collected by the bot.

This script is experimental and will be subject to change before beta.

If you are in a low-memory environment, do not use this script!

Commands:

MPD

Interface with a Music Player Daemon script and optionally announce status changes to an IRC channel (useful for Internet radio stations).

Commands:

Nato

Convert text to the NATO phonetic alphabet.

Commands:

Netutils

Provides access to network tools such as ping and mtr.

The ping and mtr utilities must be installed on the host system and accessible to whatever user started the bot. For IPv6 commands to work, the host system must have IPv6 connectivity.

Commands:

Networks

Show information about the networks to which the bot is connected.

Commands:

Numbers

Retrieve interesting number facts from numbersapi.com.

Commands:

Ping

Allows users to check the round-trip time for a CTCP PING with the bot.

Commands:

Pong

Reply to server PINGs. Without this script loaded, the bot will frequently disconnect due to ping timeouts.

Potassium

Track user K intake.

Comands:

Rainbows

Make text more colorful.

Recent messages are searched by regular expression with r//. Please your search expression between the slashes. You may include one of the following flags after the last slash:

Raw

Commands:

Reddit

Handle reddit URLs and interact with reddit.

Commands:

Regex

Perform regular expression substitutions and searches on recent messages.

Substitutions are done with sed-like message syntax: s/regex/replacement/flags

Searches are done with: g/regex/flags

For example:

<Kabaka> I'm writting documentation for Terminus-Bot!
<Kabaka> s/writting/writing/
<Terminus-Bot> <Kabaka> I'm writing documentation for Terminus-Bot!

<Kabaka> This is a test.
<Kabaka> s/[aeiou]//g
<Terminus-Bot> <Kabaka> Ths s  tst.

Relay

Relay chat between two or more channels on one or more networks.

This script is highly experimental is will be subject to change before beta. There are multiple known problems with this script, so production use is not recommended.

Commands:

Roulette

Russian Roulette for IRC.

If the bot is a channel operator when a user loses, the bot will kick the user. If not, it will just announce it as a channel message.

Commands:

RPN

Reverse Polish notation (postfix) calculator.

Commands:

Operators for RPN command:

RSS

Automatically check RSS and ATOM feeds and post updates to channels.

Commands:

Seen

Tracks when the bot has last seen a nick speaking.

Commands:

SoFurry

Retrieve submission information and other data from sofurry.com.

Source

Provides a link to the bot's home page.

Commands:

Speak

Allows bot admins to use the bot to speak and perform actions.

Commands:

Tell

Leave messages for inactive users. This is basically an in-channel MemoServ. If MemoServ is available, it is almost definitely a better solution, as this script has some privacy and abuse concerns.

Commands:

Time

Commands:

Title

Display the titles of web pages when the bot sees links in channels.

In addition to basic title retrieval, the bot handles several special cases:

More sites may be added later.

Translate

Provides an interface to glosbe.com.

Commands:

UPC

Look up UPC codes on upcdatabase.org.

Commands:

Uptime

Commands:

Urbandict

Look up words on urbandictionary.com.

Uses the new (unannounced?) JSON API.

Commands:

Weather

Look up weather on wunderground.com.

Locations can be specified in many ways for this script. For instance, you can give a zip code, city/state, or a weather station identifier.

Commands:

WHOIS

Look up domain registration information.

Commands:

Wikipedia

Look up information and pages on Wikipedia. Queries are searches, so it isn't important that you provide an exact page title.

Commands:

Xbox

Look up information on Xbox Live players and games.

Commands:

Modules

Modules are files that augment the bot's core code. They cannot be unloaded or reloaded. Some are required by some scripts.

buffer

A short-term, in-memory message history. This is used by the regex script for quick searching of recent messages for subtitution, and can easily be used by other scripts.

caps

Client capability negotiation. With this module loaded, the bot can use modern IRC features such as multi-prefix and SASL to help improve security and reduce bandwidth usage. Loading this module is strongly recommended.

http_client

Simplifies HTTP access for scripts. This module handles redirects, timeouts, and headers.

ignores

Allows the bot to ignore other users. This is managed by the ignore script.

regex_handler

Provides an easy-to-use way for scripts to act on messages matching regular expressions.

For usage examples, see the Reddit script and others.

url_handler

Provides an easy-to-use way for scripts to react to URLs the bot sees in chat.

For usage examples, see the title script, Wikipedia script, and others.

First Run

After you've completed configuration of the bot, type ./terminus-bot in the bot's directory. The bot will load all files and then disappear into the background. It should then connect to IRC.

Since it won't join any channels until you tell it to, you'll have to manually open a query with it by typing /query Terminus-Bot (replacing "Terminus-Bot" with whatever nick you gave the bot).

From here, you'll need to register an account with the bot. When writing the configuration file, you should have specified at least one level 10 account in the admins block. Use that account name to register your new account using the register command in the account script.

The bot should inform you that you've been logged in. Go ahead and have it join a channel using the channel script's join command.

Remember, you can use the help script's help command to get a list of commands and help with specific commands.

Reporting Problems

Remember, Terminus-Bot is not yet done, so some things may not work correctly. If you get stuck, or if something just isn't working, make sure you read the relevant help and make sure you are not making a mistake. Once you're sure there is a problem with your Terminus-Bot, head to the IRC channel at the top of this document and ask one of the channel operators what to do. If there is a bug, we'll probably need you to reproduce it with debug logging enabled so that we can get a backtrace.