Built in commands

This page is assuming you are using the default command prefix of "!". This is totally customizable e.g. to "Lietu sucks ". If you have done such a customization, please change the commands appropriately, so e.g. "!quote" would become "Lietu sucks quote".

The built in commands are:

• !reg add <username>
• !reg del <username>
• !addquote <text>
• !delquote <quote id>
• !quote
• !blacklist [--banTime=1h] <phrase>
• !unblacklist <blacklist ID>
• !whitelist <phrase>
• !unwhitelist <whitelist ID>
• !def [--user_level=userlevel] [--cooldown=seconds] [--args=something] [--want_user] [--quoted] <command name> <command Lua code>
• !com [--user_level=userlevel] [--cooldown=seconds] <command name> <response text>

Managing regulars

These commands require moderator or owner user level.

To add lietu as a regular, run the following command:

!reg add lietu

To remove lietu from regulars, run the following command:

!reg del lietu

Quotes

These commands are for regular users or higher.

To add a quote, run the following command:

!addquote The streamer said this.

To delete a quote, get the ID for the quote you want to delete (displayed when shown with !quote) and delete it e.g. as:

!delquote 1

To show a random quote from the database:

!quote

There is an auto-generated quote suffix (configurable in settings.py), which defaults to "[Streamer Name / YYYY]" where YYYY is the year the quote was saved in the database. So e.g. the above example when saved for "The Duke" on 2014 it would say: The streamer said this. [The Duke / 2014]

This suffix and streamer name can be changed later on in the config without having to update the database.

Phrase blacklist and whitelist

The bot can automatically time out people using blacklisted phrases. These are generally URLs, or derogatory phrases that you don't want on your chat.

E.g.:

!blacklist http://google.com/
!blacklist --banTime=1w rape

The --banTime argument can be abbreviated to -b. The value given to --banTime is in the following format: <number><period>[<number><period>]...

The periods are fairly self-explanatory, w(eeks), d(ays), h(ours), m(inutes), s(econds). So these are all valid: 1w1d1h1m1s, 1h30m, 30s, 1w

The default --banTime is 10 minutes.

To complement this, a whitelisting feature also exists, since sometimes there are exceptions you want.

!whitelist grape
!whitelist grapes

Simple custom commands

These commands require moderator or owner user level.

The "simple commands" are simply capable of returning some text to the channel and not doing anything more complex than that. They can take arguments, and they always get the username of the caller as an argument.

The required user level for calling the function can be defined with --user_level= or -ul=, where is one of the following:

• user (normal users)
• reg (regulars)
• mod (moderators)
• owner (owners only, set in settings.py)

You can specify a cooldown with the --cooldown=seconds argument. After the command has been called once, any consecutive calls during the cooldown period will be ignored.

To define a custom command use the following syntax:

!com [--user_level=<userlevel>] [--cooldown=seconds] <command name> Some text.

To clear a custom command, just redefine it with no response text:

!com <command name>

For arguments, you can use tags for positional arguments starting from {0} and going up until infinity. The special tag {user} is always the calling user's name.

So e.g.:

!com gift Here {0}, a free {1} given was given to you by {user}.
!gift lietu cookie

``

Custom Lua commands

These commands require moderator or owner user level.

When the simple commands are not enough, or you want to integrate to the included Lua modules, you need the more powerful Lua commands. These commands will be able to do practically anything imaginable, especially when combined with Lua modules.

To define a new command:

!def [--user_level=userlevel] [--cooldown=seconds] [--args=something] [--want_user] [--quoted] <command name> <command Lua code>

Internally the function will be created with a name prefix of __chat__ so you CAN call other functions defined from chat, but you need to be aware of this. So e.g. if you define function "foo", and try and call it from another function "bar", you'll have to call __chat__foo().

For example to add a command to create strawpolls with the bundled strawpoll module:

!def --quoted --user_level=mod --args=title,... poll local sp = require("strawpoll"); sp.create(title, unpack(arg))
!poll "My new poll" "First option" "Second option" "Third option"

To clear a previously set command just create an empty function in it's place:

!def poll

The --want_user -option makes the defined function receive the calling user's name as the an argument called "user" (the first argument).

The --quoted -option changes how arguments are processed, so it is possible to give arguments with multiple words in them, for e.g. Strawpoll creation. This works so that "quoted strings" count only for a single argument. Both single- (') and double quotes (") work.

The short versions of argument names are:

• --user_level = -ul
• --args = -a
• --want_user = -w
• --quoted = -q

Any value returned by the function will be output back in chat by the bot.

So you can e.g. create a function that greets people on the channel:

!def -ul=mod -a=user hello return "Hi, " .. user

And you'd call that function e.g. !hello lietu.

The user levels and cooldowns work the same as for simple commands.

You can define what arguments your function accepts from the chat using -a= or --args=, "..." is a lua magic argument that gives all the given arguments in a variable called "arg", and it works fine with this bot.

!def --args=user,gift gift return user .. ", please accept this " .. gift

The functions will automatically be persisted to the sqlite database.