This documentation only covers the chat-based QmunityBot controls.


This document contains modules that deal with the different functions and commands of QmunityBot.
Each module lists the commands available within that module, with any modifiers to the command shown in red script and an explanation of what the command and modifiers will do.

All QmunityBot commands start with an exclamation point; for example, the !set command.
Any modifiers to the command are normally separated by a space; for example, !set message
In this example !set is the command and message is the modifier. A modifier may contain spaces within it, but a command may not.

If the user wants a command to prompt different responses in different circumstances they can use variables.
Variables can be used to change modifiers depending on circumstances set by the user.

All variables start with a $ and list the variable name after it in parentheses; for example $(variable_name)
If you were to use a variable within a command you could use; !set mytime Current time is $(time) This command could then take the form "Current time is 12:00:00".

To use different modifiers within a variable command you would have to place commas (,) after each modifier you want QmunityBot to pick between.
These modifiers would have to be placed within the brackets after the variable. For example $(command ABC, ...)
One example of using modifiers within a variable is creating a command to return a random number between one and ten using the $(rand) variable.
Such as !set randnum Random number is: $(rand 1, 10). This command could then take the form "Random number is: 7".

The Base module for QmunityBot, containing some essential commands and variables.
This module is always enabled, as its contents are needed for many basic functions.

Trigger Description Example
!saucebot Displays information about the bot  
!help message Notifies QmunityBot admins that you require help !help I can't set commands!
!calc expression Evaluates and displays expression mathematically !calc (pi * 5*5) / 4
!eval message Evaluatesmessage as a QmunityBot variable expression !eval Current time in Norway: $(time Europe/Oslo)
!saucetime Displays the time in the bot's timezone  
!mode modonly on Makes all commands moderator only.  
!mode modonly off Disables mod-only mode.  
!mode quiet on Makes QmunityBot only respond to moderators. Even for filters.  
!mode quiet off Disables quiet mode.  
Variable Description Example usage Example result
$(N) Returns the Nth word of the trigger message Greetings, $(1)! You are $(2)! !greet cleo awesome Greetings, cleo! You are awesome!
$(-N) Returns the Nth word to the end of the trigger message No, $(1)! You cannot $(-2)! !no cola do that No, cola! You cannot do that!
$(botname) Returns the name of the bot My name is $(botname)! My name is QmunityBot!
$(botversion) Returns the version number of the bot Running version $(botversion) Running version 3.0
$(uptime) Returns how long the bot has been online for. QmunityBot uptime $(uptime)! QmunityBot uptime: 9999days!
$(name) Returns the name of the command user You are awesome, $(name)! You are awesome, Ravn_TM!
$(channel) Returns the channel name Welcome to $(channel)'s stream! Welcome to PauseUnpause's stream!
$(rand A, B) Returns a random number between A and B Rolling the die... $(rand 1, 6)! Rolling the die... 4!
$(rand A, B, C, ...) Returns randomly one of the specified values That's $(rand great, neat, terrible, amazing)! That's amazing!
$(time) Returns the time in the bot's timezone The current time for QmunityBot is $(time) The current time for QmunityBot is 17:41:13
$(time timezone) Returns the time in the specified timezone It is currently $(time US/Eastern) EST It is currently 11:41:13 EST

The Commands module allows for the creation of custom commands that then send messages.
These messages may use the variables of any other enabled module.

Trigger Description Example
!set command message Sets !command as a trigger for message !set hello Hello there, $(name)! :)
!setmod command message Sets !command as a mod-only trigger for message !set pickuser Random user from the channel: $(users rand)
!setsub command message Sets !command as a subscriber-only trigger for message !set teamspeak The TeamSpeak3 server IP is ts.qmunity.co.uk
!unset command Unsets any commands triggered by !command !unset hello
!command Displays any messages triggered by command !hello
Variable Description Example usage Example result
$(!command) Returns the message associated with the command command Greet of the day: $(!hello) Greet of the day: Welcome to the stream!

The AutoCommercial module allows for automatic running of commercials.
Note: You need to be a Twitch partner and QmunityBot has to be set as an editor for this to work.
To make QmunityBot follow you, type !followme in chat.

Contact a QmunityBot administrator if you need help setting it up.

If the automatic commercial happens to be in the middle of something important, moderators of the chat are able to cancel it:

 QmunityBot: Commercial coming in 15 seconds!  Loneztar: !canceled  QmunityBot: Commercial canceled.
Trigger Description Example
!canceled Cancels the next AutoCommercial. You may only do this 15 seconds before it runs.
!commercial 30/60/90 Runs a commercial lasting 30, 60 or 90 seconds. Default is 30. !commercial 60
!commercial on Enables automatic commercials.
!commercial off Disables automatic commercials.
!commercial delay minutes Sets minimum time to wait between each commercial. !commercial delay 20
!commercial length 30/60/90 Sets the duration of commercials to 30, 60 or 90 seconds. Default is 30. !commercial length 90
!commercial messages messages Sets the minimum number of messages to wait for between commercials. !commercial messages 30
Variable Description Example usage Example result
$(commercial state) Returns either 'Enabled' or 'Disabled' depending on the state. Commercials are $(commercial state)! Commercials are Enabled!
$(commercial delay) Returns the delay(in minutes) set. Ad every $(commercial delay) minutes! Ad every 20 minutes!
$(commercial messages) Returns the message count set. $(commercial messages) message per ad! 45 messages per ad!

The Counters module is useful for keeping track of various counts.
When a counter is created using the !counter=... syntax, a new command, !counter, is effectively created.
This new command keeps track of a number and can take arguments to alter the current count.
You can also use variables to update the counters. This can be useful for keeping track of how many times a command has been used.

Trigger Description Example
!counter =N Creates and sets counter equal toN !deaths =0
!counter +N Increments counter byN !deaths +2
!counter -N Decrements counter byN !deaths -666
!counter unset Removes the counter counter !deaths unset
!counter Displays the value of counter counter !deaths
Variable Description Example usage Example result
$(counter name) Returns the value of the counter named name. Millbee has died $(counter deaths) times! Millbee has died 74 times!
$(add name, value) Adds value to the name-counter. I've been slapped $(add slaps,1) times! :( I've been slapped 7 times! :(
$(sub name, value) Subtracts value from the name-counter. Countdown to BOOM: $(sub boom,1) ... Countdown to BOOM: 3 ...
$(set name, value) Sets the name-counter equal to value. Deaths reset to $(set deaths,0). Deaths reset to 0.

The Filters module enables filtering on chat.
The filter types are URL filtering, basic banned word filtering, single emoticon message filtering, and ALL-CAPS filtering.
The first three filters can be customized to fit the user's needs.
Filtering can be temporarily disabled for a specific user via the !permit command.
You can also add regulars that will be ignored by the filters.

Filter actions
  1. First strike - Verbal warning
  2. Second strike - 10 minute timeout
  3. Third strike - 8 hour timeout
Note: !permit also resets strikes and unbans the target user
Trigger Description Example
!p user Makes the bot purge(1 second timeout) the user !p spambot55
!ignoresubs on/off Enables/disables subscriber-immunity for all filters !ignoresubs on
!ignoreturbo on/off Enables/disables turbo-immunity for all filters !ignoreturbo off
!clearstrikes user Clears all strikes from user. !clearstrikes havokk
!permit user Grants user filter-immunity for a few minutes (+ clears strikes) !permit ravn_tm
!regulars add user Grants user filter-immunity permanently !regulars add awesomeguy
!regulars remove user Removes user from the filter-immunity list !regulars remove notawesomeguy
   
!filter url on/ off Enables/disables the URL filter !filter url on
!filter caps on/ off Enables/disables the all-caps filter !filter caps off
!filter emotes on/ off Enables/disables the single-emote filter !filter emotes on
   
!whitelist add url Adds url to the URL whitelist !whitelist add twitch.tv
!whitelist remove url Removes url from the URL whitelist !whitelist remove justin.tv
!whitelist clear Clears the URL whitelist  
   
!blacklist add url Adds url to the URL blacklist !blacklist add bit.ly
!blacklist remove url Removes url from the URL blacklist !blacklist remove tinyurl.com
!blacklist clear Clears the URL blacklist  
   
!emotes add emote Adds emote to the bad-emote list !emotes add lol
!emotes remove emote Removes emote from the bad-emote list !emotes remove <3
!emotes clear Clears the bad-emote list  
   
!badwords add word Adds word to the badword list !badwords add noob
!badwords remove word Removes word from the badword list !badwords remove rofl
!badwords clear Clears the badword list  

The News module allows for setting of one or more periodically broadcast messages.
These messages can be configured to display when two conditions are met -
a certain amount of chat has occurred and a certain time has passed since the last news message.

Trigger Description Example
!news Displays the next news message  
!news on Enables automatic news broadcasting  
!news off Disables automatic news broadcasting  
!news add message Adds message to the news list !news add Currently playing: MineCraft!
!news clear Clears the news list  
!news seconds seconds Sets the minimum time to wait between news !news seconds 180
!news messages messages Sets the minimum number of messages to wait for between news !news messages 20

The Polls module can be used to conduct a poll of the current users.

For quick polls, use !poll run opt1 opt2 opt3 ...

Moderators can create a poll with the !poll command, and users can then each vote once for one of the specified options using the !vote command.

Trigger Description Example
!poll run [ opts ...] Runs a quick poll with the specified options !poll run north east south west
!poll name [ opts ...] Creates a named poll name with the specified options !poll direction north east south west
!poll name Starts the poll named name !poll direction
!poll results Shows the results of the active poll. !poll results
!poll end Ends the active poll and shows its results  
!vote option Casts a vote in the active poll !vote north
Variable Description Example usage Example result
$(poll results) Returns the current poll's votes Results: $(poll results) Results: opt1: 5(50%), opt2: 5(50%)
$(poll options) Returns a list of the active poll's options Current poll options: $(poll options) Current poll options: north east south west
$(poll votes) Returns the number of votes cast in the active poll The poll has $(poll votes) votes! Vote today! The poll has 3 votes! Vote today!

The Timer module provides commands for custom timers and count downs.

Time input format: (each field is optional)

#d(ays) #h(ours) #m(inutes) #s(econds)

Examples:

Input Result
5h 3m 45s 5 hours 3 minutes 45 seconds
3DAY9minutes 3 days 9 minutes
4h30M 4 hours 30 minutes

Time output format:

short/medium/normal/long/full

Examples:

D h:m:s short medium / normal long / full
1 01:01:131d1h1 day 1 hour1 day 1 hour 1 minute 13 seconds
3 00:01:013d0h3 days3 days 1 minute 1 second
0 06:50:036h50m6 hours 50 minutes6 hours 50 minutes 3 seconds
0 00:50:0350m3s50 minutes 3 seconds50 minutes 3 seconds
Trigger Description Example
!timer name Starts a named timer name !timer speedrun
!timer stop name Stops and prints the ending time for the named timer name !timer stop speedrun
!countdown name target Starts a countdown to target named name !countdown streamstart 1day 6hours 43minutes 7seconds
!countdown stop name Cancels and any countdown named name !countdown stop streamstart
Variable Description Example usage Example result
$(timer name, format) Returns the time since the last !timer name Stream began $(timer streamstart, medium) ago Stream began 1 hour 37 minutes ago
$(countdown name, format) Returns the time left for the countdown name The winners will be chosen in $(countdown, short)! The winners will be chosen in 7m45s!

The Last.fm module fetches the current song playing from the Last.fm website

Trigger Description Example
!lastfm name Lists the current song playing for name !lastfm ThePhat32
Variable Description Example usage Example result
$(lastfm username) Returns the song username is listening to I'm listening to $(lastfm cloudbro)! I'm listening to Some Artist - Some Song!

The TwitchAPI module enables access to the twitch.tv/justin.tv APIs.

Trigger Description Example
!followme Makes QmunityBot follow you on Twitch.tv. Required for AutoCommercial.  
!game Shows what game is playing (twitch.tv only)  
!viewers Shows how many people are watching the stream  
!title Shows the live stream's title  
!showhosts on Enables chat notifications of a new host in chat  
!showhosts off Disables chat notifications of a new host in chat  
!showhosts seconds seconds Configures how often to check for new hosts  
Variable Description Example usage Example result
$(jtv game) Returns the game that's being played (twitch.tv only) I am playing $(jtv game)! I am playing MineCraft!
$(jtv viewers) Returns the number of people currently watching All $(jtv viewers) of you are awesome! All 422 of you are awesome!
$(jtv title) Returns the title of the stream Topic: $(jtv title) Topic Playing Borderlands 2 with friends
$(jtv follows) Returns the number of followers Number of Followers: $(jtv follows) Number of Followers: 1158

The chat module tracks active users in the chat and allows picking of random users.

Trigger Description Example
!users clear Clears the active users list  
!pickuser Picks a random user from the active users list  
!pickusers N Picks N random users from the active users list !pickusers 3
Variable Description Example usage Example result
$(users rand) Returns a random active user since the last !users clear The winner is... $(users rand)! The winner is... Millbee
$(users count) Returns the number of active users since the last !users clear Active users: $(users count) Active users: 86

The Quote module allows for the tracking of quotes.

Trigger Description Example
!quote user Prints a random quote. If user is specified then the quote will only be from that user's quotes, if not then the quote will be from anyone.  
!quote add user quote Adds quote to user's quotes !quote add Quetzi A Condom? What am I suppose to use this for?
Variable Description Example usage Example result
$(quote user) Gives a random quote from user's quotes Daily Quote: "$(quote quetzi)" -Quetzi Daily Quote: "A Condom? What am I suppose to use this for?" -Quetzi

The Victory Monument module keeps track of the current status of the victory monument.

Trigger Description Example
!vm Lists the current blocks on the monument  
!vm block Adds block to the monument !vm light_blue
!vm remove block Removes block from the monument !vm remove diamond
!vm clear Clears the monument  
Variable Description Example usage Example result
$(vm list) Returns a list of the blocks on the monument Map completion so far: $(vm list) Map completion so far: white orange magenta
$(vm count) Returns the number of blocks on the monument I've found $(vm count) blocks! I've found 3 blocks!
$(vm remaining) Returns the number of blocks remaining I need $(vm remaining) more blocks! I need 11 more blocks
$(vm total) Returns the total number of blocks for the monument VM: $(vm count)/$(vm total) obtained VM: 3/ 19 obtained

The Jukebox Monument module keeps track of the current status of the jukebox monument.

Trigger Description Example
!jm Lists the current blocks on the monument  
!jm block Adds block to the monument !jm cat
!jm remove block Removes block from the monument !jm remove redstone
!jm clear Clears the monument  
Variable Description Example usage Example result
$(jm list) Returns a list of the blocks on the monument Map completion so far: $(jm list) Map completion so far: cat 13 mall
$(jm count) Returns the number of blocks on the monument I've found $(jm count) blocks! I've found 3 blocks!
$(jm remaining) Returns the number of blocks remaining I need $(jm remaining) more blocks! I need 11 more blocks
$(jm total) Returns the total number of blocks for the monument VM: $(jm count)/$(jm list) obtained VM: 3/ 19 obtained

QmunityBot 2015