IRC bot in D
To use this package, run the following command in your project's root directory:
Put the following dependency into your project's dependences section:
kameloso sits in your channels and listens to commands and events, like bots generally do.
A variety of features comes bundled in the form of compile-time plugins, including some examples and proofs of concepts. It's easily extensible, API documentation is available online. Any and all ideas for inclusion welcome.
IRC is standardised but servers still come in many flavours, some of which outright conflict with others. If something doesn't immediately work, usually it's because we simply haven't encountered that type of event before, and so no rules for how to parse it have been written yet. Once discovered it's generally not a difficult thing to do.
Please report bugs. Unreported bugs can only be fixed by accident.
Current functionality includes:
- bedazzling coloured terminal output like it's the 90s
- automatic mode sets (eg. auto
+oon join for op)
- looking up titles of pasted web URLs
sed-replacement of the last message sent (
notesto offline users that get played back when they come online
seenplugin; reporting when a user was last seen, written as a rough example plugin
- Twitch chat support, including basic streamer bot (default disabled); see notes on connecting below
- piping text from the terminal to the server (Linux/OSX and other Posix platforms only)
- mIRC colour coding and text effects (bold, underlined, ...), mapped to ANSI terminal formatting (extra step needed for Windows)
- SASL authentication (
- configuration stored on file; create one and edit it to get an idea of the settings available
If nothing else it makes for a good lurkbot.
- missing good how-to-use guide. Use the source, Luke! Also the wiki.
- the dmd and ldc compilers may segfault if building in anything other than
debugmode (bug #18026).
- Windows may need a registry fix to display terminal colours properly; see the known issues section.
- the stable release of the gdc compiler doesn't yet support
static foreachand 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).
- IRC servers that have not been tested against may exhibit weird behaviour if parsing goes awry. Need concrete examples to fix; please report errors and abnormalities.
Use on networks without services (
AuthServ/...) may be difficult, since the bot identifies people by their account names. You will probably want to register yourself with such, where available.
Testing is primarily done on freenode and on Twitch, so support and coverage is best there.
-n --nickname Nickname -s --server Server address [irc.freenode.net] -P --port Server port  -A --account Services account name -p --password Services account password --admins Administrators' services accounts, comma-separated -H --homes Home channels to operate in, comma-separated -C --channels Non-home channels to idle in, comma-separated -w --writeconfig Write configuration to file A dash (-) clears, so -C- translates to no channels, -A- to no account name, etc.
Table of contents
- Getting started
- How to use
- Example use
- Use as a library
- Known issues
- Built with
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 (released September 2017). You will also need some 4 Gb of RAM to build all features (Linux, 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.
$ git clone https://github.com/zorael/kameloso.git $ cd kameloso
Note: do not use
dub fetch until we have released v1.0.0. It will download an ancient version.
$ 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
dub build -b release. Mind that build times will increase. Refer to the output of
dub build --helpfor 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)
Unit tests are built into the language, but you need to compile the project in
unittest mode to include them. Tests are run at the start of the program, not during compilation. Test builds will only run the unit tests and immediately exit.
$ dub test
There are several configurations in which the bot may be built.
vanilla, builds without any specific extras
colours, compiles in terminal colours
web, compiles in plugins with web lookup (
full, includes both of the above
twitch, everything so far, plus the Twitch bot
posix, default on Posix-like systems (Linux, OSX, ...), equals
windows, default on Windows, also equals
fullbut with extra code needed for running under the default Cygwin terminal (mintty)
cygwinbut with the Twitch bot
polyglot, equals everything available, including things like more error messages and the Admin plugin being able to see Twitch users (more of a development build)
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 cygwin
How to use
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
kameloso.conf will be created in a directory dependent on your platform.
- Other unexpected platforms: fallback to current working directory
Open the file in a text editor and fill in the fields.
You can override some settings with arguments on the command line, listed by calling the program with
--help. If you specify some and also add
--writeconfig it will save these changes to the file so you don't have to repeat them, without having to manually edit the configuration file.
$ ./kameloso \ --server irc.freenode.net \ --nickname "kameloso" \ --admins "you,friend,thatguy" \ --homes "#channel,#elsewhere" \ --channels "#d,##networking" \ --writeconfig Configuration file written to /home/user/.config/kameloso/kameloso.conf
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 valid setting, so settings that relate to plugins that are currently not built in are removed, as well as comments.
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;
[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 weird
\033[92m-like characters instead of colours, see the known issues section for a permanent fix.
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.
Mind that you need to authorise yourself with services with an account listed as an administrator in the configuration file to make it listen to you. Before allowing anyone to trigger any 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 generated
you joined #channel kameloso sets mode +o you you | I am a fish you | s/fish/snek/ kameloso | you | I am a snek you | !addquote you This is a quote kameloso | Quote saved. (1 on record) you | !quote you kameloso | you | This is a quote you | !note OfflinePerson Why so offline? kameloso | Note added. you | !seen OfflinePerson kameloso | I last saw OfflinePerson 1 hour and 34 minutes ago. you | kameloso: sudo PRIVMSG #channel :this is a raw IRC command kameloso | this is a raw IRC command you | https://www.youtube.com/watch?v=s-mOy8VUEBk kameloso | [youtube.com] Danish language (uploaded by snurre)
Online help and commands
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
~, making it
[Core] prefix !
It can technically be any string and not just one character. Enquote it if you want any spaces as part of the prefix, like
"please " (making it
please quote, ...).
To connect to Twitch servers you must supply an OAuth token pass. Generate one here, then add it to your
kameloso.conf in the
[IRCBot] nickname twitchaccount pass oauth:the50letteroauthstringgoeshere homes #twitchaccount channels #streamer1,#streamer2,#streamer3 [IRCServer] address irc.chat.twitch.tv port 6667
See the wiki for more information.
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 with the bot included. (It will not show up when generating the file if the plugin is not compiled in.)
$ dub build -c twitch $ ./kameloso --set twitchbot.enabled=true --writeconfig
Assuming a prefix of
!, commands to test are:
NOTE: a dot
. prefix will not work on Twitch, as it conflicts with Twitch's own commands.
Again, refer to the wiki.
Use as a library
The IRC event parsing is largely decoupled from the bot parts of the program, needing only some common non-bot-oriented helper modules.
Feel free to copy these and drop them into your own project. Examples of parsing results can be found in
tests/events.d. Look up the structs
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; inquire within.
Web URL lookup, including the web titles and Reddit 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.
HKEY_CURRENT_USER\Console, create a
VirtualTerminalLeveland give it a value of
- Alternatively in Powershell:
Set-ItemProperty HKCU:\Console VirtualTerminalLevel -Type DWORD 1
- Alternatively in
reg add HKCU\Console /v VirtualTerminalLevel /t REG_DWORD /d 1
Otherwise use the
--monochrome setting to disable colours, or compile a non-
Terminal output will be broken in Cygwin terminals without compiling the aforementioned
cygwin configuration. Powershell and
cmd consoles are unaffected.
When run in such Cygwin terminals, the bot will not gracefully shut down upon hitting Ctrl+C. Any changes to configuration will thus have to be otherwise saved prior to forcefully terminating like that.
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.
- pipedream zero: no compiler segfaults
- pipedream: DCC
- pipedream two:
seendoing what? channel-split?
- non-blocking FIFO
- more pairs of eyes
This project is licensed under the MIT license - see the LICENSE file for details.
- kameloso for obvious reasons
- ikod for
- Adam D. Ruppe for
- IRC Definition Files and
- Registered by JR
- 1.0.0-rc.5 released 4 years ago
- Copyright © 2018, JR
3.9.0 2023-Feb-22 3.8.0 2023-Feb-01 3.7.1 2023-Jan-14 3.7.0 2023-Jan-09 3.6.0 2022-Nov-21
- Download Stats:
0 downloads today
0 downloads this week
0 downloads this month
144 downloads total
- Short URL: