Aqu4bot

Logo for aqu4bot.

aqu4bot, the main instance in IRC as aqu4, with the slogan "aqu4, daughter of pr0t0!" is an IRC bot originally written in C and later ported to C++ by Subsentient. She has a wide range of functionality, many of her commands being humorous and others being obscure. She has channel management capabilities, user tracking and messaging capabilities, and an extensive logging system.

Basic usage

aqu4bot can be set to respond to any prefix on a per-channel basis, but by default she responds to the dollar sign $, but will always respond to her name presented as e.g. aqu4:, followed by a space, to produce 'aqu4: commands'. An aqu4bot will not say anything if you specify an invalid command. Help is available with the 'help' command, of course accessible via $help or 'BotNameHere: help'. No prefix is required in private messages, so /msg BotNameHere help will indeed get you the help command. Likewise, the 'commands' command gives a list of available commands for the bot, but 'help' would have told you that.

Source code

aqu4bot's source code is available at https://github.com/Subsentient/aqu4bot

Bugs

Please report all bugs to Subsentient. Chat logs are helpful if they can be provided. Please provide the channel you were in, and any nicknames of users who encountered the bug, as well as any channels where the bug occurs. Case sensitivity bugs are common with aqu4bot for some reason, so please provide the correct case for nicks and channels.

Availability

aqu4bot runs as user aqu4 on irc.soylentnews.org, irc.freenode.net, and irc.ootws.ca. irc.ootws.ca can be intermittent, so the subdomain ootwsirc.universe2.us was created by Subsentient to allow better access.

Logging

aqu4bot has an extensive and capable logging system, with the logs for the 'aqu4' instance being stored at http://universe2.us/irclogz You will need to request a password from the bot maintainer, Subsentient, to get access to the logs.

Developing new commands

As aqu4bot is written in C99 and compiled into native executables, it does not support modules. Expanded features must be added by editing the existing source code. Thankfully this is less of a problem than you think, since you can simply type 'make' on UNIX systems to recompile, which takes less than 10 seconds on all but the slowest machines.

Adding commands

The source file src/commands.c and specifically the function CMD_ProcessCommand() is the bare minimum location you can add new commands for aqu4bot.

Depending on the sophistication of your new command, editing irc.c's IRC_Loop may be necessary, and depending on the sophistication, you may wish to add a new source file. You'll need to edit src/Makefile to add it to the build process. Remember to edit the help list at the top of commands.c.

aqu4bot was originally written in C89, later updated to compile as C99, and finally ported to C++ on 2016-03-20. You can write code as C with aqu4bot, provided you are willing to deal with the C++ features that are present.

SubStrings

Aqu4bot uses a small string handling library called SubStrings that is also written by Subsentient. It is by default included in aqu4bot's source tree and is compiled along with 'make'. It is platform independent. SubStrings is used to simplify the large amount of text processing done by aqu4bot, which can be a more lengthy task in C. It provides safe string copy and concatenation, string searching, line and character stepping/iteration, and much more.

libcurl

As of recent revisions, aqu4bot links against libcurl. The functionality is used for http support mostly. See curlcore.c for CurlCore_GetHTTP(). Additional libcurl features such as SMTP should be implemented by creating base functions for that functionality in curlcore.c, and calling the new functions to use them in your new command. Remember to add them to aqu4.h. You should enclose your function with #ifndef NO_LIBCURL followed by #endif /*NO_LIBCURL*/, so that if someone chooses to build aqu4bot without libcurl by using 'make USECURL=NO", their build will not fail. If you add a function to aqu4.h, it is strongly suggested you put said #ifndef macro around the prototype as well.

Bot Privileges

aqu4bot has three privilege levels. Normal users, admins, and owners. Unlike most bots that have several admins and one owner, aqu4bot can have multiple owners, all of them of equal privilege.

Admins

An admin is capable of controlling the bot's presence in channels, using 'chanctl' to manage channels with aqu4 as OP, telling her to message other users, and setting and removing user blacklist, among other things listed in the 'commands' command.

Owners

Owners are capable of all things an admin is, and everything else the owner is. These include shutting down and restarting the bot, adding temporary admins with the 'admin' command, and temporarily changing the bot's nickname.

Blacklisting

Blacklisting is a privilege for admins and owners of an aqu4bot that allows them to make the bot completely and totally blind towards any user. aqu4bot won't even log any text from a blacklisted user.

To blackist someone, use 'blackist set'. To unblacklist someone, use 'blacklist unset'. It is not possible to blacklist an admin or owner.

Syntax

'blacklist set' and 'blacklist unset' accept the format 'nick!user@host'. Up to two of the three fields may be an asterisk to denote a wildcard. You may not blacklist an admin or owner, or someone already blacklisted. An example would be '$blacklist set *!WhiteRat@unaffiliated/subsen', which would blacklist anyone with the user WhiteRat and the mask 'unaffiliated/subsen'. To delete the blacklist, simply do as you did before, replacing 'set' with 'unset'.

Viewing blacklist records

'blacklist list' is available to admins to see blacklisted users.

The 'wz' command

This command is used to list games in the Warzone 2100 game lobby, as told in 'help wz'. Warzone 2100 is an open source cross-platform RTS strategy game that Subsentient is very fond of.

The slogan

"aqu4, daughter of pr0t0!" is a homage to the predecessor of aqu4, pr0t0bot, a patchy, unstable, poorly written yet highly useful python bot based on phenny that was operated by Subsentient on freenode from 2010 to early 2014. It was designed to mimic a helpful personality, and as a result, users of pr0t0 became fond of it, including Subsentient, and to ease the feelings of loss, aqu4 was given a similar name, many similar attributes in function, and the slogan. She is often referred to as 'she' by Subsentient and his friends, as this is the 'imagined and intended' persona of the bot, just as pr0t0 before her was referred to as 'he'.

The logo

The logo for aqu4bot.

The logo is a combination of the letters P and Q. the q is for aqu4, and the p is for pr0t0. The cyan background is the color of Subsentient's homepage. The blue and green gradients are a reference to Subsentient's nationstates.net flag.

Problems

Perhaps something is wrong with aqu4, or some abuse is taking place. To remove aqu4 from a channel, you may kick her. She will register the kick and will not attempt to rejoin unless explicitly instructed to or if she is restarted. A +q quiet is preferable if possible, because Subsentient likes to keep the logs complete for all channels he considers of interest.

If this is not sufficient to resolve your problem, you may contact Subsentient here: http://universe2.us/contactinfo.html