All of the above are plugins and can be runtime disabled or compiled out. It is modular and easily extensible.

Current limitations:

the dmd and ldc compilers may segfault if building in anything other than debug mode (bug #18026).

the stable release of the gdc compiler doesn't yet support static foreach and thus cannot be used to build this bot. The development release based on D version 2.081 doesn't work yet either, segfaulting upon compiling (bug #307).

Windows may need a registry fix to display terminal colours properly; see the known issues section.

Use on networks without services (NickServ/Q/AuthServ/...) may be difficult, since the bot identifies people by their account names. You will probably want to register yourself with such, where available.

Note that while IRC is standardised, servers still come in many flavours, some of which outright conflict with others. If something doesn't immediately work, generally it's because we simply haven't encountered that type of event before, and so no rules for how to parse it have yet been written.

Testing is primarily done on freenode and on Twitch servers, so support and coverage is best there.

Getting started

Prerequisites

You need a D compiler and the dub package manager. There are three compilers available; see here for an overview. You need one based on D version 2.076 or later (September 2017). You will also need more than 4 Gb of free memory to build all features (Linux debug, excluding tests).

kameloso can be built using the reference compiler dmd and the LLVM-based ldc. The stable release of the GCC-based gdc is currently too old to be used.

Downloading

$ git clone https://github.com/zorael/kameloso.git
$ cd kameloso

Compiling

$ dub build

This will compile the bot in the default debug mode, which adds some extra code and debugging symbols.

You can automatically skip these and add some optimisations by building it in release mode with dub build -b release. Mind that build times will increase. Refer to the output of dub build --help for more build types.

The above might currently not work, as the compiler may crash on some build configurations under anything other than debug mode. (bug #18026)

polyglot, development build equalling everything available, including things like more error messages

List them with dub build --print-configs. You can specify which to compile with the -c switch. Not supplying one will make it build the default for your operating system.

$ dub build -c twitch

How to use

Configuration

The bot needs the services account name of one or more administrators of the bot, and/or one or more home channels to operate in. To define these you can either specify them on the command-line, or generate a configuration file and enter them there.

$ ./kameloso --writeconfig

A new kameloso.conf will be created in a directory dependent on your platform.

Command-line arguments

You can override some configured settings with arguments on the command line, listed by calling the program with --help. If you specify some and also add --writeconfig it will apply these changes to the configuration file, without having to manually edit it.

Later invocations of --writeconfig will only regenerate the file. It will never overwrite custom settings, only complement them with new ones. Mind however that it will delete any lines not corresponding to a currently valid setting, so settings that relate to plugins that are currently not built in are silently removed, as are comments.

Display settings

If you have compiled in colours and you have bright terminal background, the colours may be hard to see and the text difficult to read. If so, make sure to pass the --bright argument, and/or modify the configuration file; brightTerminal under [Core]. The bot uses the full range of 8-colour ANSI, so if one or more colours are too dark or bright even with the right brightTerminal setting, please see to your terminal appearance settings. This is not uncommon, especially with backgrounds that are not fully black or white. (read: Monokai, Breeze, Solaris, ...)

If you are on Windows and you're seeing \033[92m-like characters instead of colours, see the known issues section for a permanent fix.

Other files

More server-specific resource files will be created the first time you connect to a server. These include users.json, in which you whitelist which accounts get to access the bot's features. Where these are stored also depends on platform; in the case of OSX and Windows they will be put in subdirectories of the same directory as the configuration file, listed above. On Linux, under ~/.local/share/kameloso (or wherever $XDG_DATA_HOME points). As before it falls back to the working directory on other unknown platforms.

Example use

Mind that you need to authorise yourself with services as an account listed as an administrator in the configuration file to make it listen to you. Before allowing anyone to trigger any restricted functionality it will look them up and compare their accounts with the white- and blacklists. Refer to the admins field in the configuration file, as well as your users.json.

Online help and commands

Send help to the bot in a private message for a summary of available bot commands, and help [plugin] [command] for a brief description of a specific one. Mind that commands defined as regular expressions cannot be shown, due to technical reasons.

The prefix character (here !) is configurable; refer to your generated configuration file. Common alternatives are . and ~, making it .note and ~quote respectively.

[Core]
prefix "!"

It can technically be any string and not just one character. It may include spaces, like "please " (making it please note, please quote, ...). Prefixing commands with the bot's nickname also works (and in some cases only works, like kameloso: sudo [...] in the example above).

Twitch

To connect to Twitch servers you must supply an OAuth tokenpass (not password). Generate one here, then add it to your kameloso.conf in the pass field.

Twitch bot

The streamer bot plugin is opt-in, both during compilation and at runtime. Build the twitch configuration to compile it, and enable it in the configuration file under the [TwitchBot] section. If the section doesn't exist, regenerate the file after having compiled a build configuration that includes the bot. (Configuration file sections will not show up when generating the file if the corresponding plugin is not compiled in.)

Feel free to copy these and drop them into your own project. Examples of parsing results can be found in the test files in tests/. Look up the structs IRCBot and IRCParser to get started. See the versioning at the top of irc/common.d. It can be slimmed down further if support for only one server network is required.

Further help

Known issues

Windows

Web URL lookup, including the web titles and bash.org quotes plugins, will not work out of the box with secure HTTPS connections due to missing libraries. Download a "light" installer from slproweb.com and install to system libraries, and it should no longer warn on program start.

Terminal colours may also not work, requiring a registry edit to make it display properly. This works for at least Windows 10.

In regedit under HKEY_CURRENT_USER\Console, create a DWORD named VirtualTerminalLevel and give it a value of 1.

Otherwise use the --monochrome setting to disable colours, or compile a non-colours configuration.

When run in Cygwin/mintty terminals, the bot will not gracefully shut down upon hitting Ctrl+C, instead terminating abruptly. Any changes to configuration will thus have to be otherwise saved prior to forcefully exiting like that, such as with the Admin plugin's save command.

Posix

If the pipeline FIFO is removed while the program is running, it will hang upon exiting, requiring manual interruption with Ctrl+C. This is a tricky problem to solve as it requires figuring out how to do non-blocking reads. Help wanted.