wiki:zomg

Context Navigation

close Warning: Can't synchronize with repository "(default)" (Unsupported version control system "svn": Can't find an appropriate component, maybe the corresponding plugin was not enabled? ). Look in the Trac log for more information.

Version 4 (modified by vsTerminus, 14 years ago) (diff)
--

zomg

zomg is an IRC bot written by vsTerminus for the SocialGamer? IRC network (irc.socialgamer.net:6667). Its primary function was channel moderation, but has since expanded to fill other roles as well.

If you're curious about my development patterns, please read through the Changelog at the bottom of this file!

Note: This help file does not apply to a zomg bot found on any other network, as capabilities will be severely limited in one or more areas.

Disclaimer

This section outlines a few simple terms that you must agree to if you wish to use zomg in your channel.

zomg will never invite itself into the channel. The staff will never invite zomg into your channel without your permission.
Any and all admins in your channel are able to invite zomg into you channel. Invites from users who are not channel admins will not be accepted.
zomg stores a great deal of information about the users and the server. Some of this information is publicly available through a few of the commands (including !seen). The majority of this information is available to anyone by using the /whois command from any IRC client, thus cannot be considered an invasion of privacy.
Events such as changing your nick, talking, and quitting are all stored by the bot. Channel data, however, will never be given out. Example: zomg may report that you were last seen 'Talking in a channel'.
zomg prints all information it receives to its console output window. This is viewable by the author, vsTerminus, at any time. This means I, the author, am able to 'watch' your channel through the bot's window without being there myself. I will never disclose anything I have seen through this method, and primarily only use it for testing purposes.
zomg has partial logging enabled. Certain events are logged (such as all the commands used) and may be made available to other staff members if requested.
Abuse of zomg will not be tolerated. This includes knowingly attempting to cause the bot to flood itself offline, lag out, or spam excessively. Any evidence of this will be dealt with by means of a server ban. The length of which depends on the nature of the offense.
zomg is given, by default, admin access in all channels. This is done to make your life easier, as zomg requires admin to be fully functional. Server staff has complete access to zomg, and thus will have admin access in your channel through the bot.

If you do not agree to one or more of the above terms, please DO NOT invite zomg into your chat. Please do not hesitate to send a PM to vsTerminus if you have any questions.

TOC?

Introduction

What is zomg and what can it do?

zomg is a fully automated IRC client written in Perl. It is designed to be a public interface and extension to SocialGamer?'s existing services.
zomg makes managing your channel simple. Commands are built in to change modes, track users, extend the channel topic functionality, make it easier to keep unwanted people out of your channel, and much much more.
The source code for zomg is open source and available upon request.

How can I get zomg in my channel?

It is as simple as typing a single command into your chat room. /invite zomg #yourname-chat (replace #yourname-chat with the name of your channel)
Keep in mind, you must be logged in, and an administrator in the channel you are inviting zomg to. zomg will deny invites from non-admins and users who are not logged in.

How can I control zomg?

Controlling zomg is easy. All of the commands can be issued in one simple way. You talk to the bot in the channel like any other user, but you give it commands to do. A command is always prefixed by the public command trigger. For zomg, that trigger is !
An example of giving a command would be to type: !version
This would cause the bot to display it's internal version publicly in the channel.
You can also talk to zomg by addressing it by name rather than using the command trigger.
Example: You may type something like this: zomg, whoami
The bot would then look up some information on you and display it in the channel. This is the equivalent of typing !whoami. You may use either version for any and all commands.

The Big List of Commands

The access you have to the bot at any given time is denoted by your status in the channel. When you have voice in a channel (+v, or a speaker in mibbit) you will have access to the voice commands, and everything below (the public commands). Similarly, if you are currently an op (@, or a star in mibbit) you have access to the Op commands and everything below that (Halfop, Voice, and Public).

Certain commands (such as !up) will be based on your permanent access level in the channel, as stored by ChanServ.

Public Commands

Public commands are useable by anyone in the channel, even if they do not have voice or another status level. These commands are very limited in terms of number and functionality. For all commands below, < > denotes a required parameter, [ ] denotes an optional parameter, and | denotes OR. ( ) are used to group certain items.

!version

Display the current bot version publicly
Example: !version

!help

Use this to get the latest help file available
Example: !help

!iam <description of yourself> | undefine

This command allows you to define yourself as you see fit. Others will be able to see your description by typing 'who is <yourzomgname>' in the chat.
You can remove your definition if you so wish by passing !iam the undefine argument
Example: !iam Super awesome and totally not fat
Example: !iam undefine

Who is <user>

This command will look up the definition of a user, if it exists.
This command should not be confused with !whois, which is entirely different.
This command can be used with, or without a trigger.
Example: who is vsTerminus
Example: !who is vsTerminus

Who kicked <user>

This will look up the data on the last time <user> was kicked and display it publicly
This command can be used with or without a trigger
Example: who kicked me
Example: Who kicked vsTerminus

What is <item>

This command looks up the definition of something besides a user. If a definition exists, it will be displayed publicly
Only staff members may define items here.
Example: what is op
Example: !what is halfop

!up

This command should only be used if you have permanent access in the channel already.
It will cause the bot to look up your access with ChanServ and give you the status you are supposed to have (voice, halfop, or op)
If you do not have channel access, this command will do nothing.
!up

Voice Commands

These commands will require you to have voice in the channel to use. Even if you have >= voice access in the channel according to chanserv, you must have voice currently to use these commands. That means if you purposely de-status yourself (Read the !down command), you will be unable to use these until you have restored your status level (Read the !up command). Voice commands are generally informational and have little funcionality to them.

!down

This is much the opposite of !up. It will remove any and all status you have in the channel temporarily. Next time you join, or next time you use !up, your status will be restored.
!down

!alias

This command will look up and display a list of all the nicknames the bot has seen you using.
Nicks are tracked based on an IP address, so if you have a Dynamic IP, the bot may tend to 'forget' who you are from time to time.
You cannot lookup the aliases of another user. If you require this, a staff member can do it, or you can look into a nick tracer script online.
!alias
!alias vsTerminus

!whois <user>

This command will look up information about you on the server and display it publicly.
Among the displayed information is your name, hostmask, and ChanServ access.
!whois IbitePrettyHard?

!whoami

This command is the equivalent of typing !whois <your name>
!whoami

!lastcommand

This command will display publicly the last command that was used and who issued it.
This will reflect the last attempted command, regardless of whether it succeeded.
!lastcommand

!common [user]

This command will display publicly how many channels [user] is in with the bot.
If a user is not specified, your name will be used instead.
!common
!common ChanServ

!host <user>

This command will return the host of <user> and display it publicly if it exists
!host NeGaTiVe?

!seen <user>

Seen can be used to find out when the last time the bot saw <user> was, and what they were doing.
Channel information will not be divulged, and is not logged.
!seen dho

!autobans

This will list all known autobans for the channel via PM
Example: !autobans
Example: !list bans (not yet implemented)

!idle <user>

This will look up the user's idle time and connection time and display it publicly
Example: !idle xsiick

!kickme [reason]

This command will make the bot kick you. It is a Voice command because that way voiced users can kick themselves but nobody else. A harmless loophole to usual IRC kick permissions.
If you specify a reason, it will be used. If not, a default message will be used.
Example: !kickme
Example: !kickme off to bed!

!kickcount [user]

This command can be used to display kick information about yourself, or another user.
Four items will be displayed. Your kick total in the channel and overall, as well as how many times the bot has kicked you from the current channel, and overall.
If you do not supply a user name, your own will be used.
Example: !kickcount
Example: !kickcount vsTerminus

!peak

Peak will display some info on the current channel's peak
The channel peak is the highest recorded number of users that have been there at one time
You will also see who joined to set that record, and how long ago it was set.
Example: !peak

!listcmd <command | command alias | custom command>

This command allows you to see the aliases for any given command
It also allows you to see what command an alias points to
What is an alias?
- An alias is just another name for an existing command.
- For example, !kb is an alias of !kickban and is used the same way
This command now supports custom command info as well
- Both local and global customs work.
Example: !listcmd kickban

!nowplaying [user]

This command uses the data from the !lastfm command to retrieve now playing information from http://last.fm/ and display it in the channel
- If you don't have an account, you can register for free and I recommend that you do!
You can look up another user or yourself if you leave the argument blank.
The user must link their name to a Last.FM account using the !lastfm command in order to see their now-playing info.
As of 0.8.1 this command uses the Last.FM API to retrieve your information. It is more accurate and reliable than screen scraping, and removes the need for pacing.
This command has 1 – 3 lines of output, and so is pace controlled.
- You will only be able to use this command once every 20 seconds. I may change this value without notice.
Example: !nowplaying
Example: !nowplaying vsTerminus

!ccinfo <Custom Command>

Because CustomCommand? is an admin-only command, this command has been added to allow voiced users to get info on existing custom commands in the channel
This is the same thing as typing !customcommand info <custom command>, but requires less access.
Example: !ccinfo slap

!cclist

Same idea as ccinfo, but this will list all of the existing custom commands in the channel you are in.
This is the same as typing !customcommand list, but requires less access

!gcinfo <Global Custom Command>

Same as ccinfo, but applies to global custom commands
This command was added to allow regular users access to see what global custom commands exist, since that command is limited to opers
Example: !gcinfo ccinfo

!gclist

This command will list all of the existing global commands
It was created to allow regular users to view Global Custom Commands, since that command itself is limited to opers
Example: !gclist
As a side note, it's worth mentioning that ccinfo, cclist, gclist and gcinfo are all Global Custom Commands, not hard coded commands.

!wins [user]

Display a user's current win count
Wins can only be awarded by an oper (staff member)
- Asking for them is probably a bad idea
If you do not pass a name, your own will be used.
This command will look up who [user] is logged in as, that way wins transcend nick changes.
Example: !wins
Example: !wins vsTerminus

!text [user]

Display information about how much [user] has been typing
Logging started for this on 30 April 2009, not in Feb like most of the other stats.
[user] is optional, if you do not specify your own nick will be used.
Example: !text
Example: !text vsTerminus

This will provide a top 3 list of one of several data items
nicks will give you the three users with the most aliases
kicks will be the three most kicked users
peak will be the three channels with the highest peaks
lines will give you the three users who have sent the most messages
words for the three users who have typed the most words
chars for the three users who have typed the most characters
commands will give you the three commands with the most aliases
customs will give you the three channels that have the most custom commands
Example: !top3 wins
Example: !top3 nicks
Example: !top3 kicks
Example: !top3 peak
Example: !top3 lines
Example: !top3 words
Example: !top3 chars
Example: !top3 commands
Example: !top3 customs

!uptime

This command shows the bot's connection uptime as well as the host machine's uptime
Example: !uptime

Who is banned

This works like “who is <user>” and “who kicked <user>”, except it requires voice because of the potentially large amount of output.
- A trigger is not required for this command, but may be used if you so desire.
This will read the channel's ban list, and PM you some information on each ban. This information includes
- The banned hostmask
- Up to three known aliases of that user if a match is found
- Or the number of matches found if there are many
- The time that the ban will last
- The time until the ban expires
  - These last two will only be defined (known) if the bans were places while the bot was present. Bans places while the bot is absent are never automatically removed
This command always sends results via PM to keep spam out of the channel.
Example: who is banned

!wordoftheday

This command shows the status of the Word of the Day game
Information includes how long the current word has been un-guessed for, and who guessed the previous word.
Example: !wordoftheday

!slogan <word or words>

This command displays a random slogan, with your word(s) inserted into it in often funny places.
Example: !slogan Dry Humping
Example: !slogan Fun

!lastfm <option> [args]

This command can be used to link your username to a http://www.last.fm/ account, and customize the output of the !nowplaying command.
You can look up the now-playing info of other linked users by typing !nowplaying <nick>, if they are linked. If you do not specify a nick, yours is used.
<Option> can be one of: link, unlink, currtext, lasttext, showurl
Link your account: !lastfm link <Last.FM Account>
Remove your account link: !lastfm unlink
By default, if you are currently playing a song you will see “<nick> is currently listening to <artist – title> etc”
- You can change this “is currently listening to” text to anything you like.
- !lastfm currtext <new text here>
By default if you are not listening to anything you will see “<nick> last listened to <artist – title> etc”
- You can change this “last listened to” text to anything you like
- !lastfm lasttext <new text here>
By default, the URL for your Last.FM user page is displayed when you use !nowplaying. You can change this if you don't want it showing
- !lastfm showurl <yes or no>
Example: !lastfm link RageOfOrder?
Example: !lastfm unlink
Example: !lastfm currtext is currently rocking out to
Example: !lastfm lasttext last rocked out to
Example: !lastfm showurl no

!fml

This looks up a random FML entry from FmyLife?.com
Takes no arguments yet, might in the future
Example: !fml

!wtf [is] <acronym>|<man page entry>

This command has a simple database of common acronyms and their meanins (eg. 'LOL' → Laugh Out Loud)
If also looks up man page entries for applications.
- man pages are Manual pages for Unix based oeprating systems. If you've never used one, don't worry about this part.
For the sake of natural-ish grammar, you can optionally include the word “is” after the command.
A response of 'Nothing Appropriate' generally means “I don't know”.
- Expect to see this a lot.
Example: !wtf is lol
Example: !wtf lol
Example: !wtf is ASCII
Example: !wtf blahblahblah

!weather [<Zip Code> | <City> | <Username>]

This command looks up the weather for a location using http://thefuckingweather.com
You can give it a zip code (US only)
You can give it a City (More accurate with a state or province code)
You can give it a username (More accurate if they aren't connected through a bouncer or a server)
Giving no arguments at all is equivalent to !weather <your name>
Example: !weather
Example: !weather Cleveland, OH
Example: !weather bsparks
Example: !weather 12345

!locate [<username> | <host> | <domain>]

This command can be used to look up where a specific user is located, or to find out where the server for a domain is located in the world using GeoIP
If you pass it a username it will locate where that user is connecting from. If they use a bouncer or connect through a proxy then it will only find the location of the machine they are connecting through.
You can also give it the hostmask of a user directly
This only works for North America
You can give it a doman (Such as 'google.com') and it will look up the location of (one of) the server(s) hosting that site.
Again, this only works for servers in North America. Anywhere else will not be found.
Without arguments, the bot will look up your location.
Example: !locate
Example: !locate IbitePrettyHard?
Example: !locate socialgamer.net

Halfop Commands

These commands will require Halfop in the channel to use. Halfop is denoted by a % next to your name, or a half star in Mibbit.
Halfop commands start to get interesting. They deal primarily with channel moderation, topic, and modes. The good stuff.
Again, some of these commands will have multiple aliases, or names. They will be listed in the examples.

!kick <user> [reason]

This will kick a user from the channel. Reason is optional.
Admins are un-kickable. Please keep this in mind.
<user> can also be a regex pattern
Example: !kick rockthelotus get out
Example: !k rockthelotus
Example: !boot rockthelotus

!kickban <user> [time] [reason]

Kickban will kick the user, and IP ban them.
The bot tracks users IP addresses and so you can simply give it a name to ban, and it will automatically ban the correct IP.
If you wish, you can specify an IP to ban instead and the bot will ban that.
<user> can also be a regex pattern
[time] is specified in minutes and is optional
- By default, 12 hours is used if you do not specify
- You can not set a time greater than 12 hours.
Example: !kickban azuritereaction 120 Stop spamming
Example: !kb azuritereaction 5
Example: !kb azuritereaction STOP IT!
Example: !kb azuritereaction

!stfu <user> [duration]

This command uses something called an extban, which will prevent the user from talking in the channel, but not from joining.
This does not affect voiced, halfopped or opped users at all.
This command also looks up the user's IP automatically
You can specify a time for the ban to last, in minutes, if you wish
By default, bans last 12 hours, and you cannot exceed 12 hours here either.
- If you do not specify a time, the default of 12 hours will be used.
Example: !stfu POKE-JJ
Example: !stfu POKE-JJ 45

!ban <user> [time]

This command can be used to ban a user by name, or by a hostmask if you specify one.
Time is optional, and is specified in minutes.
If you do not specify a time, or specify one too large, 12 hours will be used instead.
Example: !ban POKE-JJ
Example: !ban POKE-JJ 1.5

!unban <user>

This command will unban a user.
You may pass in a user name, or an IP hostmask to unban
Example: !unban spivs1020
Example: !ub spivs1020

!unstfu <user>

Similar to unban, but will un-mute a user
!unstfu poke-jj

!voice <user>

Give a user in the channel temporary voice status
Example: !voice Paper
Example: !v Paper

!devoice <user>

Remove voice from a user temporarily in the channel
Example: !devoice paper
Example: !dv paper

!topic <newtopic>

The topic is split into three parts: Topic, Status, and Static
This command sets the first part, Topic.
Example: !topic Check out my youtube videos!

!status <newstatus>

The topic is split into three parts: Topic, Status and Static
This is the second part, Status
Example: !status Streaming BQP – PM me to join

!static <newstatic>

The topic is split into three parts: Topic, Status and Static
This is the third part, Static
Static should ideally be used for extra information that you want to always be in your topic, no matter how often it changes.
Something like a link to your youtube, or a funny quote should go here.
Example: !static http://youtube.com/rageoforder

!mute <on|off>

Mute or unmute the channel
Mute means only users with at least voice will be able to talk
This is handy if the chat gets out of hand
Example: !mute on
Example: !mute off

!strip <on|off>

Enable or Disable color stripping
This mode allows users to send colors to the channel, but nobody else will see them.
Example: !strip on
Example: !strip off

!censor <on|off>

Enable or disable chat censoring
Example: !censor on
Example: !censor off

Op commands

These commands can only be used by channel ops, both temporary and permanent.
They involve additional modes that halfops are unable to set, as well as some extra moderation stuff that halfops are unable to do.
These commands also give you power to make the bot say stuff – Cool right?

!exempt [user]

This will set +e on [user]'s hostmask, which exempts the user from being banned.
This does not mean a user cannot be banned, it means the server will allow the user to join even if someone sets a ban on them.
If a user is not specified, your name will be used.
Example: !exempt njo823
Example: !e

!unexempt [user]

This removes exempt on [user]
If a user is not specified, your name will be used.
Example: !unexempt njo823
Example: !ue

!halfop <user>

This will give temporary halfop (%, +h) to a user in the channel
Example: !halfop toymachine
Example: !h toymachine
Example: !hop toymachine

!dehalfop <user>

This will remove halfop from a user in the channel temporarily
Example: !dehalfop toymachine
Example: !dh toymachine
Example: !dehop toymachine

!op <user>

This will give a user temporary Op in the channel
Example: !op Grinnz
Example: !o Grinnz

!deop <user>

This will remove Op from a user in the channel temporarily
Example: !deop Grinnz
Example: !do Grinnz

!say <something>

This command makes the bot talk
Text is wrapped in [ ] to prevent abuse from underprivileged users
Example: !say hi there, I am a bot

!me <something>

This command also makes the bot talk, much like !say
However, this command is the same as making the bot use /me <something>
The command “/me” on irc is generally used for actions, such as “/me enters the room, naked!”
!me uses the same syntax: “!me enters the room, naked!”
Example: !me is a bot!

!ask <user> <question>

This command will ask <user> a question.
The bot will attempt to convert your language into proper english.
You MUST use real words, spell correctly, and use proper grammar for this to work correctly.
Good Example: !ask Xyzzy if he will marry me
Bad Example: !ask someguy913 fc visions pl0x 4 me k??!

!tell <user> <statement>

This command will tell <user> your <statement>
The command will attempt to convert your text into proper english
You MUST use real words, spell correctly, and use proper grammar for this to work correctly.
Good Example: !tell Xyzzy that he is a stupid bot and needs to go die.
Bad Example: !tell someguy913 2 gtfo nub

!rr <on|off>

Choose whether users must register to chat in your channel
Useful to prevent random mibbits from talking
Example: !rr on
Example: !rr off

!nn <on|off>

Allow or disallow nick changes in your channel
This is most commonly used when the chat is muted and people decide to change nicks repeatedly to talk. Very annoying
Example: !nn on
Example: !nn off

!announce <on|off>

Announce is very different from what it was on the mIRC based zomg.
Now, it is a simple on/off switch, and rather than having the bot make your announcement, it just helps you out, so you can make it without others interrupting.
Announce on will mass de-op/halfop/voice all the users in the channel, except for you. It will then let everyone know that you have an announcement to make
When you are finished with your announcement, you can type !announce off to restore the chat
Example: !announce on
Example: !announce off

!autobans [time <seconds>|limit <kicks>]

This will display which autobans are enabled and disabled, as well as some settings if they are enabled if no args are passed
It can also be used to specify punishment for repeat offenders who continually trip the various channel protections.
This is always on, but you can set it to any values you like (within reason)
time <seconds> lets you specify how many seconds to watch for kicks within.
Limit <kicks> allows you to specify how many times the user can be kicked by an autoban before being banned for 30 minutes.
This command will not let you set any higher than 100 kicks in 3600 seconds (1 hour).
- If you do not want this to affect your channel, simply set the time to 0 seconds.
By default, this is set to 3 kicks within 5 minutes (300 seconds)
- Most users will not need to change thiscus
Example: !autobans
Example: !autobans time 500
Example: !autobans limit 10

!capsban [on|off|##|##%]

Caps ban is a form of autoban that looks for excessive caps in a users message
- There are two requirements: A minimum message length and a minimum % of caps to be found in that message.
- For example, if the minimum length is set to 30, messages with < 30 characters will be ignored, regardless of how many caps are used.
- Similarly, the % specifies how much of the message must be in capitals to trigger a ban. 85% means that most of the message has to be capitalized, but not all. Leaving room for people who accidentally let go of Shift on the last two character
This command allows you to do a number of things regarding the excess caps autoban in your chat
The first is to display its status. Simple call it without any args
The second is to enable or disable it with on or off
The third is to set a minimum length that caps ban will require
Fourth, you can specify the minimum % threshold
Example: !capsban
Example: !capsban on
Example: !capsban off
Example: !capsban 30 <--- This sets minimum length
Example: !capsban 90% <--- This sets % threshold

!spamban [on|off|##|r##]

Spamban is another type of autoban that is designed to catch spamming on a single line.
There are two kinds of spamming it looks for.
- The first is a string of characters in a row without spaces (Such as “hsuhfihfudihuehf489hf4rF”)
- The second is a string of repeated identical characters (Such as “FC!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!”)
Spamban has a minimum length for each of these, much like the minimum length for caps ban.
By typing !spamban 45 you would be setting the minimum length for the first type of spam ban (excess characters without a space) to 45 or greater. Messages shorter than this will be ignored.
By typing !spamban r25 you would be setting the repeated character threshold (Second type) to 25, and the user would have to type at least 25 of the same character without breaks to get kicked.
- Placing the r in front of the number signifies you want to specify the number of repeated chars allowed.
Example: !spamban
Example: !spamban on
Example: !spamban off
Example: !spamban 50
Example: !spamban r20

!repeatban [on|off|##]

Repeatban is a third kind of autoban that looks for users who try to spam by repeating themselves over and over.
You may specify how many repeats the bot should kick at.
If a user is kicked for repeats and then comes back, only to repeat him/herself again, the bot will kick them immediately, without waiting.
This is also a global check, so if a user posts a link in three seperate channels in a row, he/she will be kicked in the last one for repeating him/herself.
By specifying a number you tell it how many bans to kick at
Specifying on or off enabled or disables the autoban, and no args shows the status
Example: !repeatban
Example: !repeatban on
Example: !repeatban off
Example: !repeatban 3

!floodban [on|off|time <seconds>|lines <lines>]

Floodban is a limited implementation of mode +f, if you know what that is.
Basically what it does is look for <lines> messages within <seconds> seconds from any user, and kick them if they reach that limit.
- This is a good way to prevent people from flooding the room with excessive pastes, or random keyboard mashing that won't be caught by the other filters
Floodban has a limit of at most 180 seconds and at most 100 lines of text. Attempting to set values above these limits will default to these limits instead.
- This means, at most floodban can only look for 100 lines within 180 seconds (3 minutes).
Without an argument, the current status is shown
By default, all rooms are set to limit at 6 lines of text in 4 seconds from any user. Floodban is also disabled by default, so you will have to manually enable it if you want to use it. 6 in 4 is a good setting, I find. Most users will not have to modify these.
Example: !floodban on
Example: !floodban off
Example: !floodban time 6
Example: !floodban lines 4

Spamfilter is essentially a word (or pattern) filter for text in your chat.
You can configure this command to look for certain words, phrases, or patterns using the Regular Expression (regex, google it) syntax.
Upon finding a match in a non-voiced user's text, the user can be either automatically kicked, or banned from the channel.
This is useful for such things as racist words you don't want people using, filtering out links to certain or all websites, and if you know your regex, even looking for things like excessive repeated characters, or more advanced things.
There are a number of arguments this command will accept:
- on: Enable the spam filter for your channel
- off: Disable the spam filter for your channel
- kick: Set the automatic response to KICK a user only
- ban: Set the automatic response to KICKBAN the user.
- Add <regex>: Add a new filter
- Del <regex>: Delete an existing filter
- list: List the existing filters
- No argument: Display the status of the spam filter in your channel
Here is a little intro to regex:
- By default in zomg-Bot, any filter you add is case INSENSITIVE. This means that to the bot, there is no difference between banana, BANANA, baNaNa, and anything in between.
- Adding a word, such as banana, to the spam filter will search for that word ANYWHERE in the user's text. They don't simply have to say banana, and nothing else
- In regex, a period (.) will match ANY character
  - Example: the regex 'ab.d' would match abad, abbd, abcd, abdd, etc.
- In regex, a* is a little different than a usual wildcard*
  - In this case it means “0 or more of the previous character”
  - So to use* in the way you are used to, you must put a period before it
  - .* will match any number of any characters. Anything.
- ^{denotes the start of the text}
- $ denotes the end of the text
- If you wanted to filter out anything starting with the word banana, you would use the filter: ^banana
- To filter out anything ending in banana, use: banana$
- To filter out someone who says banana and nothing else, use: ^banana$
- The rest you will need to look up online. Regex is VERY complex.
Example: !spamfilter
Example: !spamfilter on
Example: !spamfilter off
Example: !spamfilter kick
Example: !spamfilter ban
Example: !spamfilter list
Example: !spamfilter add gay
Example: !spamfilter del gay

!nickfilter [on|off|list|add <regex>|del <regex>]

This command is the same thing as spamfilter, but instead of looking for filters within text, it looks for filters within usernames
The only difference to syntax is that there is no ban or kick option here, instead a 10 second ban is used automatically.
Not passing an argument will give you the current status.
Example: !nickfilter
Example: !nickfilter list
Example: !nickfilter on
Example: !nickfilter off
Example: !nickfilter add banana
Example: !nickfilter del banana

!greet [on|off|msg|pm|public|notice|<new greet message>]

Greet is used for greet messages in your channel, that will be sent automatically to users when they join.
Without a parameter, greet will give you its current status and information.
You can turn it on and off with !greet on or !greet off
- Off by default.
You can set either of three types of messages
- Notice, Public Message or Private Message (PM)
- Set notice with !greet notice
- Set PM with !greet pm
  - or !greet msg
- Set Public with !greet public
To set a new message, there is no special key word, just plain old !greet <new message here>
- There is a message by default, so you may want to change it if you enable greetings.
Example: !greet
Example: !greet on
Example: !greet off
Example: !greet notice
Example: !greet msg
Example: !greet pm
Example: !greet Hello and welcome to my chat. The rules are: #1 there are no rules, and #2 You don't talk about fight club

Admin Commands

These commands can only be used by channel admins (&, +a) in a channel.
Please remember that admin cannot be given temporarily. It must be added using ChanServ's !add command.
Also please remember that Admins have access to everything in this section, plus all of the previous command sections, and cannot be kicked by anyone but themselves.
Admin is NOT a status symbol, please do not give it out to just anyone.

!mass <command> [args]

Mass is one of my favorite commands, it's just plain cool.
Mass will call <command> once for each user in the channel, passing in a different user each time. It's the same as you calling one command over and over on each user in the channel.
Mass will check to make sure you do have access to use the command you're trying to mass.
Keep in mind this is generally pretty spammy, please do not abuse it or it will become a restricted staff-only command
Not all commands are massable. If you try to use mass on a non-massable command you will receive an error from the bot. The useable commands should be intuitive. If not, just try them.
Example: !mass say hi
- This will say “<user> hi” for every <user> in the channel
Example: !mass kick
- This will kick everyone in the room. You can specify reasons here too
Example: !mass deop
- This will de-op all the ops in the room.
Example: !mass seen
- This will look up the last-seen info for every user in the channel.

!part

This will make defiance bot leave the channel.
It will not, however, remove the channel from autojoin.
Example: !part

!leave

This will make zomg leave the channel, AND remove it from the autojoin list.
Example: !leave

!stay

This will add your channel to the autojoin list. If it already exists, you will be notified.
Example: !stay

!modelock [<modes>|off]

This will set a modelock in your channel
A modelock is a specific mode in your channel that you may want to stay on or off permanently even if someone tries to change it.
A good example of this is the mode 'G', or Censor. If you wanted your channel to be censored all the time, you could put +G in the modelock. Likewise, if you wanted your channel to never be censored, you could put -G in the modelock.
If the bot detects someone trying to change one of the locked modes, it will reset them immediately.
You can set the modelock to 'off' to disable it.
If you do not pass in new modes, or the word off, the bot will display the current existing modelock, if there is one.
Example: !modelock -G+S
Example: !ml off
Example: !modelock

!cycle

Cycle is used to have ChanServ reset every user in the channel to their added access level.
This means that users with temporary status (ops etc) who are not added to the channel's access list will be lowered back to whatever they are supposed to have.
Example: !cycle

!customcommand [add <name of your command> <access to use your comand> <existing command and args to call> | |del <custom command> | info <existing custom command>]

This is really cool
- Like, really cool
  - Like, you should really learn how to use these things. They are so cool!
Custom commands allow you to build your very own commands using any and all of zomg's existing commands.
Ever wanted a command that could, for example, kick someone with a pre-defined message so you don't have to type it out every time? CustomCommand? lets you do that, and more.
There are a number of variables available to you to aid in creating your own commands as well.
The syntax is a little complicated so here's the breakdown
To add a custom command, use !cc add
The syntax for add is <Name of your custom command> <access to use your command> <Existing command and args>
- Example: To add a command that simply says hello to the channel, you could use: !cc add hello voice say Hello to the channel!
- This could then be used by typing: !hello
- The bot would then say “Hello to the channel!”
<access> can be any status level in the channel, as well as “none” if you want anyone to be able to use it.
- Accepted levels are: none, voice, halfop, op, admin, service
- Service refers to the +q mode, which is only given to ChanServ. It would be silly of you to add a command that requires service, but I allow it anyways.
<Name of your custom command> can be anything you want, so long as it does not already exist as a hard-coded command.
- You cannot create a custom version of 'say' for example.
<Exsting command and args> is what your custom command is going to call whenever you use it.
- It should always start with a hard coded command, and be followed by the arguments you want to pass, just as if you were using it in the channel yourself!
There are some special variables that you may use when defining a custom command.
- There are optional variables, and required variables
  - Optional variables begin with a $, and if the user leaves them blank, there is no problem.
  - Required variables begin with a & and if the user leaves one of these blank, the command will fail.
- Here are the variables available to you for use in your custom commands: (For all variables below, you may use $ or & as you see fit, $ is used for this explanation)
  - $0 = The name of the command
  - $1 = The first word you pass to your command
  - $2 = The second word you pass to your command
    - This applies to all integers from 0 to infinity. Keep in mind it's very doubtful that there will ever be more than 100 parameters in any given message.
  - $1- = Everything from the first word to the end of the line
  - $2- = Everything from the second word to the end of the line
    - This applies to all integers from 0 to infinity.
  - $nick = Your nick
  - $chan = The current channel
  - $me = The bot's nick (Probably 'zomg')
  - $rnick = The nick of a random user in the channel
  - $rint = A random integer
  - $rint### = A random integer from 0 to ###.
    - Example: $rint500 picks a random integer from 0 to 500
  - $server = The server the bot is connected to
  - $unixtime = Unix time, aka the number of seconds since the Unix epoch (Jan 1, 1970)
  - $localtime = The local time (and date) of the computer the bot is running on
  - $noun = A random noun
  - $pronoun = A random pronoun
  - $verb = A random verb
  - $adverb = A random adverb
  - $preposition = A random preposition
  - $adjective = A random adjective
  - $clothing = A random article of clothing (The list is mostly made up of different kinds of hats right now)
If you would like to see more variables available to you, please let me know. I'm open to suggestions here.
Here are some examples of some simple commands you can make using CustomCommand?:
- Because there are so many things you can do, I will use a simple slap command to show you everything.
- Basic slap command:
  - !cc add slap none me slaps &1 around a bit with a large trout
    - This adds a command that you can use with “!slap <user>”. The &1 is a required parameter, which will be used as the target of the slap. If the user leaves this blank (types “!slap” without anything after it) the command will not complete, and will warn the user that they did not define a required parameter.
  - !cc add slap none me slaps &1 around a bit with a large &2-
    - This adds a similar command, that you can use with “!slap <user> <object>”. The &2 requires that the object to slap with be defined by the user. Because there is a – after the 2, it will take the second argument from the user, and the rest of the words following it. This allows the user to do something like “!slap ajanata zappy gun”. If there was no – after the 2, only one word would be supported here and the rest would be ignored.
  - !cc add slap none me slaps &1 around a bit with a large $2-
    - This does exactly the same thing as the command above, but because it's a $ instead of a & on the 2, the argument is optional and can be left blank. But we don't really want this. You'd see something like “* zomg slaps ajanata around a bit with a large” unless the user remembered to define something.
    - For this scenario, you can actually set a default value to use if an optional argument is left undefined!
  - !cc add slap none me slaps &1 around a bit with a large $2-[trout]
    - This is exactly the same as above, but the [ ] following the variable says “If the user doesn't define something, use whatever is inside the [ ] instead”. In this case, if I typed “!slap ajanata”, I would see “* zomg slaps ajanata around a bit with a large trout”
    - I could also define my own object to slap with. “!slap ajanata board” would yield “* zomg slaps ajanata around a bit with a large board”
  - !cc add slap voice me slaps &1 around a bit with a large $2-[trout]
    - The difference here is the access level required to use the command. As you can see, the previous commands were set to 'none', meaning anyone could use the command. This is not always a smart idea, so this time I have limited the command to voiced users and above. That way you can control who is able to use the commands you create.
    - Coincidentally this allows you to do something cool: circumvent the hard coded access in some commands.
For example, kick requires halfop to use by default. However, you could create a custom command that uses kick but only requires VOICE to use your custom command, thus allowing voiced users access to kick others.
Cool right?
More custom command examples:
- A !beer command to have the bot toss you (or someone else) a beer
  - !cc add beer voice me tosses $1[$nick] A BEER to chug.
    - This uses one optional argument (A username to pass the beer to)
    - If that argument is left blank, your nick will be used instead
- A !badword command to kick someone with a preset message
  - !cc add badword halfop kickban &1 30s 30 Second time-out for using a bad word! $2-
    - This uses one required argument (the name of the user to kick) and one optional argument (Any additional info you want to add to the kick reason)
    - If the optional reason is left blank, the command will still run fine and look normal, so no default value is needed here
    - The user may not need to add anything to the kick message, so it is left optional
- A !randaban command to kickban a random user for a random length of time (lol?)
  - !cc add randaban op kickban $rnick $rint You have been a victim of a random kickban!
    - This uses no input from the user, just straight “!randaban” will do it.
    - $rnick picks a random user in the channel
    - $rint picks a random number (Unless you specify, it will be between 0 and 999,999)
    - So this command kickbans a random user for a random amount of time
    - Not very practical, but kind of funny!
- A command to let people voice Xyzzy, even without being ops
  - !cc add Xyzzy voice voice Xyzzy
    - This command also uses no input from the user, and circumvents a hard-coded requirement!
    - Normally, to voice someone you would need to be a halfop or greater. However, this command only requires voice to use.
    - But! This command only voices one user: Xyzzy
    - So you could use this command to allow voiced users in your chat to voice Xyzzy (and nobody else) when the chat is dead, without needing any of the ops to do it for them.
Please talk to vsTerminus if you do not understand anything in here. I'll be happy to explain, or update this file.
Your custom commands will only work in your channel, nowhere else.
To delete a custom command, just use
- !cc del <custom command>
  - If the command does not exist, you'll get an error
  - You cannot use this to delete hard-coded commands
If you do not pass CustomCommand? any args, You will be given a list of the currently existing Custom Commands in your channel
- Example: !cc
If you want info on a specific custom command, you can use !cc info <command>
- This will give you the name, the equivalent command that it calls, and the access required to use it
- You can also get info by just passing the name of an existing command, such as !cc <command>
- Example: !cc info beer
- Example: !cc beer
That's it! I hope to see some awesome commands from some of you.
- (And I dread to think what others will create)

Staff Commands

The staff commands are essentially a superset of the User Commands, made up of existing user commands, overloaded user commands, and unique staff-only commands. In this section I will list any relevant information on the staff commands. If you are staff, you can use the '.' trigger to specify that you want to use the oper version of a command, if it exists. Similarly, addressing the bot by name will default to the oper version of a command if it exists. In both cases, a missing staff version of a command will just default back to the user version, so it is perfectly OK to use the . trigger for everything.

Extended Functionality Commands

These commands are overloaded versions of existing commands. Typically any command that performs a check on your access, or requires a certain status will be overloaded so that staff may use them at any time with or without channel access / status.
Example of this is the kick command, which would deny you access to kick an Op unless you were an Op or an Admin yourself. The staff version of this command allows you to kick anyone at any time with or without channel access.
Sometimes these commands will allow you to specify a different channel to perform the action in so you don't have to go there yourself.

.alias [user]

Allows you to look up aliases of any user, rather than just yourself

.add <user> <status>

Allows you to use ChanServ's add command without having channel access.
Useful if you have to add yourself as an op to fix a proplem, for example.
Does not check logged in as currently. You must give it a valid account name.

.up

Just gives you +ohv regardless.

.kick

Removes access checks. Kick any user at any time

.peak #chan

Optionally specify a different channel to get peak info on

.help [user]

Allows an optional user to send a help file link to.
Massable

.kickban

Removes access checks, and does not print your name in the kick message

.stfu

Regular version won't mute opers, this will.
Auto removes voice, halfop and op from the user

.wordoftheday [status|set <new word>|new]

This command can control and view the status of the Word of the Day game.
Status displays how long the word has been unguessed for
set <word> can only be done via PM to the bot, but allows an oper to set the word of the day to anything they like.
- This word will NOT be placed into regular rotation.
New just randomly picks a new word.

Oper-Only commands

These commands do not have a ! equivalent for regular users. They are primarily for controlling internal bot functions.

.mode <string>

A direct /mode command for when you just want to set some modes real quick.

.debug [on|off]

Turn debug output on or off.
Without a parameter, displays current status

.echo [on|off]

Turn standard output on or off
Without a parameter, displays current status

.quit aka .die

Quit the bot. Close the process

.join aka .j <#chan>

Join a channel. Works via PM also

.save

Writes the current database to a file. This is done automatically on quit anyways.

.nick <newnick>

Change the bot's nick

.define <item> <description>

Allows you to add/edit items in the bot's internal dictionary.

.define <user> <description>

Allows you to add/edit descriptions for users other than yourself.

.undefine <item>

Remove the definition for an item

.undefine user <user>

Remove the definition for a user

By default, the compressed output is used.
V or verbose may be specified to see the multi-line, verbose output.
Display some stats that the bot is tracking (Total/online users, kick count, etc)

.todo [newitem]

Keeps a to-do list for the bot
No args displays the current list
Note: Depreciated as of v0.8.1 as we are now using Trac for bug reports and feature requests.

.done <item#>

Just specify the matching number beside a to-do list item to remove it.

.addcmd <new command> <target command>

This allows you to define aliases for existing commands.
If you try to define an alias for another alias, the bot will automatically re-direct to the appropriate hard-coded command
Support for custom args is not there, and never will be.
The target must be a real command, and the new command cannot be an existing command.
Example: .addcmd destroy kick
- This will let you call !destroy in the same way you call !kick

.delcmd <command alias>

This allows you to remove aliases for commands
You cannot remove hard coded commands

.addchan <#channel>

Add a channel to the autojoin list

.whisperback [on/off]

Whisperback, or quiet mode, sets zomg to whisper all command output back to the person using the command instead of displaying it publicly in the channel
This will probably be moved to the regular user section as an Op command if I find people would use it.
Without args, the current status will be displayed

.timers add [chan] <repeat(s)> <length> <command> [args]

.timers del <#> .timers <#> .timers

This command control's zomg's timer system
Without args, all existing timers will be listed
If passed a number, that timer will be listed
- If a timer with that ID exists
- Example: .timers 4
Can add a timer
- .timers add [chan] <repeats> <length> <command> [args]
  - [chan] is now assumed to be the current channel if you do not specify one of your own
  - [chan] can also be a nick to send the output to instead of a channel.
  - <repeats> is the number of times you want the timer to fire
    - 0 (or less) means forever.
    - Repeats are NOT saved between sessions.
    - When zomg restarts, timers will continue as normal but will default to no repeats.
    - You will have to re-add these.
  - <length> is how long it should take the timer to fire (eg. 3600 if you want the timer to fire in one hour)
    - Feeding defiance bot a negative offset is equivalent to an offset of 0
  - <command> is parsed just like any other command. Any command that you can give to zomg with a trigger is acceptable here and uses the same syntax, except without a trigger.
  - [args] are optional, and only needed if <command> requires them.
- Example: .timers add #IBitePrettyHard-chat 1 10 tell ibiteprettyhard that he rocks
- Example: .timers add 0 120 say The rules are: You do not talk about fight club
Can remove a timer
- .timers del <#>
- Must be an existing number
- You can get the timer numbers by using .timers with no args

.disable [<command> [reason]]

Disable can be used to disable any of the regular user commands
This does not apply to oper commands, and does not prevent opers from using commands
Reason for disabling a command is optional but as always, it's a good idea to give one. Otherwise you end up answering a lot of questions.
If you don't pass any args to disable, it will list all of the currently disabled commands
A disabled command is disabled globally. This is not a per-channel thing.
Disabled commands are Re-Enabled whenever the bot restarts

.enable <command>

Enable a previously disabled command

.globalcustom

GlobalCustom? uses identical syntax to CustomCommand?, but applies to all channels, instead of just the current one.
As an oper keep in mind with both CC and GC that you can give regular users access to oper commands (or certain parts of them) by pointing a custom command at an oper-only command and setting its access to something a regular user can have (admin or less).
In the case of both an oper and a user version of a command existing, regular users will always be pointed at the user version, regardless.
For example, the global custom command, !gcinfo points at: Globalcustom info $1
- This gives regular users the ability to use .gc info <command>, which would only be accessible by opers otherwise.
- It does not give them full access to the gc command, just to the info parameter.

.award <user> <wins>

Use this to award a user any number of wins.
Only supports numbers, may be positive or negative

.restart

Use this to restart the bot

.addword <category> <word or phrase> [ : <additional word or phrase> ]

Use this to add new words to a custom variable, or create a new custom variable if it does not exist yet.
You can add multiple entries to a category with a single command, simply separate separate items with a colon (:)

.delword <category> <word or phrase>

Use this to delete a word or phrase from a custom variable category

.loadwords

This causes the bot to read and load all *.words files in its current directory and use them as custom variables.
A file named "pokemon.words" will generate the $pokemon variable

Changelog

In this section I will keep a log of changes I make with each version of zomg so you can see, quickly, what has changed since last time you read this file. Plus I think it's kind of cool to see how long features have been a part of the bot and how much I typically change/add in each revision.

Version 0.8.2 – In Progress

Added !weather
- Added GeoIP support to !weather
Added !locate
Added .addword
Added .delword
Added .loadwords
Added several new custom commands to demo new functionality
- For example, !8ball and !fight
Bot now leaves 'empty' channels and waits for a notice from ChanServ that a person has joined before coming back.
- A channel containing only the bot and ChanServ is considered 'empty'
Using !alias and .alias will now allow you to put*!*@ in front of a hostmask, just for convenience.
Converted documentation to Wiki format and moved to new location
Extended the functionality of Custom Commands considerably
Extended the functionality of Custom Variables considerably
Fixed bug where bot would not respond to custom commands if addressed by name
Fixed several command parsing bugs

Restored !wotd hint option for regular users
Moved zomg's code into a subversion repository

Version 0.8.1 – December 2nd 2009

Moved help page to static.socialgamer.net
- Updated help command to reflect this
Updated help page formatting and style
Bot no longer auto-rejoins when kicked by ChanServ
Fixed !stfu length when a time was not specified
!nowplaying now uses the Last.FM API instead of screen scraping
- Smaller output (1 line instead of 3)
- API doesn't give me the player information (yet). Sorry.
Added more functionality to !lastfm
- You can now customize your !nowplaying output
- Syntax is different now, please read the entry for it
!alias now accepts and removes*!*@ prefix on hostnames.

Version 0.8.0 – October 28th 2009

Big update, long time
- With school, working on the new SocialGamer? beta site, and other commitments it can be hard to find time to develop zomg further
Changed the database serialization (storage) system
- Previously used the XML::Dumper perl module to convert all of my hash tables, important variables and other data into a convenient XML file that could be read on startup to restore information.
  - XML::Dumper is Extremeley inefficient, and was causing me to use several hundred MB of RAM at run time! o_O
- Switched to YAML::XS (A perl module written in C) I can serialize the database into a single human-readable string of data and store that in a file
- RAM usage is now 1/10th of what it was previously
  - I can still reduce this further with optimizations to save/load and cleaning old/invalid/unnecessary data in other areas.
Added !fml
- May add an option to select a specific entry or grab the latest entry if there is interest
Added !wtf
- Uses the system wtf command, which contains definitions for common acronyms (Like 'LOL' and 'wtf') as well as man page entries for most apps
- The wtf database is not really that extensive, and a response of 'Nothing Appropriate' means 'I don't know'
Modified the now playing (!mp3) command to use Last.FM
- Renamed the !mp3 command to !nowplaying
- Added a hard-coded alias, !mp3 which redirects to the new command. Usage doesn't change.
- Command spans 1-3 lines of output, and so can only be used every 20 or so seconds to reduce spam.
Added !lastfm <last.fm-account> | none
Fixed a couple regex matches (Thanks Thierry for breaking it and Grinnz for solving it)
Added !drums
- Wrote a search function into this command, so if you can't spell it will try to help.
Added the ability to use the $ variables from custom commands in all commands (With the exception of $1,2,3 etc because that's just silly)
Added some new variables for use (They work in any command, not just customs!)
- $noun, $verb, $pronoun, $adverb, $preposition, $adjective, $clothing
Fixed default parameter parsing
Added new words to the word of the day file

Version 0.7.4 – September 1st 2009

Added uptime to restart message
Added a 10 second ban to channel protections by default
- Breaks sf ban currently, will be removing that.
Added <nick>++ or <nick>-- triggers for awarding wins to users
Added <nick>+=, -=,*= and /= as well
- eg. toymachine++ is equivalent to .award toymachine 1
- and toymachine+=5 is equivalent to .award toymachine 5
A word of the day system to award users with wins
- The word is selected at random, but can be set by an oper
- When the word is guessed, a new word is chosen (At random)
- A word un-guessed for 24 hours will expire next time anyone uses !wordoftheday
  - Might update this to use a timer system in the future
Tripping the spamfilter also removes 1 win now.
Commands via PM can now be done without a trigger
- eg. /msg zomg time
Custom Commands now support required parameters
- Variables defined with $ are optional, where as variables defined with & will be required. If a required parameter is left undefined, the command will error and ask for more input.
!listcmd now displays the access level required to use the command
Fixed glitch in !wins when look

Download in other formats:

Plain Text