CamfrogBot Owner Guide

Getting started

Camfrog Bot is created to help you operate your Camfrog Video Chat Room, log chat room events so that nothing important passes you by, entertain your chat visitors and more. You may also add custom functionality to Camfrog Bot by writing your plug-in modules.

Camfrog Bot can do the following administrative actions for you.

  1. Kick or punish users for bad words automatically.
  2. Perform administrative actions on demand.
  3. Help you to find out who banned a particular user.
  4. Log all the administrative actions that happen in your chat room.
  5. Send announcements to your room.

You may also save your chat room log in the HTML format, post RSS feeds and run a Trivia game to entertain your visitors.

Follow these steps to get started.

  1. Download Camfrog Bot from http://download.camfrog.com and install it.
  2. Run Camfrog Bot.
  3. Create your bot profile.
  4. Connect the bot to your room.
  5. Set up Camfrog Bot to make it do what you want the way you want.

Plug-In Descriptions

Overview

Camfrog Bot extends its functionality with plug-in modules. There are several modules that come with the Camfrog Bot installation pack.

The bad words kicker module allows you to kick users from a room for bad words automatically. The HTML log module writes a chat room log to an .html file. The IM control module allows you to control your bot via instant messages. The messenger module sends announcements to a room. The Trivia game module allows running a Trivia game in a room. The "Who banned" module helps you to operate your room. The RSS reader module allows you to post RSS feeds to a chat room.

Note. Camfrog Bot 3.94 or earlier plug-in modules are not compatible with Camfrog Bot 5.0 and higher.

8 Ball

Full list of bot commands

8 Ball is an entertaining plug-in, which answers users' Yes/No questions in the form of pseudo-random generation.

Localization

The 8 Ball plug-in module can be localized. You may want to translate the warning messages to your native language. All warning messages are stored in 8ball_messages.txt. This file must be in the same directory as 8ball.conf. See also Camfrog Bot Configurations File. Here is an example of this file.

# This is a localization sample file for the "8 ball" plug-in.

#

# Copy this file to %appdata%\Camfrog Bot\\

# and modify it as you need (in Windows OS)

#

# NOTE:

# 1. '%' is a reserved symbol. Use it carefully

# 2. The file must be saved in the UTF-8 encoding

value1=Type %1% to ask 8 ball

Value1 message offers to play the 8 Ball game on plug-in startup or when a user connects to the chat room.

%1% - 8 Ball name, which can be specified in the plug-in settings.

Bad Words Kicker

Full list of bot commands

The sample file badwords_message.txt is stored in \plugins\localization-sample\. Modify this file and copy it to %appdata%\Camfrog Bot\\.

The Bad Words Kicker can kick or punish users for typing bad words. The bot scans users' chat text in a room and finds matches with the rules you set. If the given quantity of matches is found, the bot performs the action you have set, for example, kicking the user from the room or banning them.

There are two ways you can set rules. If regular expressions are off, then the bot will try to find words that match the list of words you give it (case sensitive).

If regular expressions are turned on, the chat room text will be checked for matching by mask. An example of a mask is below.

Wor.d World, Worsd, Wor d, Wor.d
Wo*rd Wrd, Word, Wooord
Wo+rd Word, Wooord
Wo?rd Word, Wrd
Word{2,4} Wordd, Worddd, Wordddd
Wor(d|k) Word, Work
Wor[a-z] Wora, Worb, : , Worz
[cba] a, b, c
.*word.* All strings with substring 'word'

The bad Word Kicker can punish or kick users from a room. You may want to define a reason that is shown to the user when the bot is taking action. You can also define the number of violations; it must be 1-10.

Localization

The bad words kicker module can be localized. You may want to translate the warning messages to your native language. All warning messages are stored in badwords_message.txt. This file must be in the same directory as badwords.conf. See also Camfrog Bot Configurations File. Here is an example of this file.

#

# Badwords plugin. Room message file

#

# These are the warning messages. You can translate them to your native language

value1=%1% you are using a forbidden word %2% time(s), %3% time(s) left

value2=%1% you are using a forbidden word '%2%' %3% time(s), %4% time(s) left

Note.

Value1 warning is shown to the user if regular expressions are on.

%1% - user nickname;

%2% - number of violations;

%3% - violations left;

Value2 warning is shown to the user if regular expressions are off.

%1% - user nickname;

%2% - word;

%3% - number of violations;

%4% - violations left;

The sample file badwords_message.txt is stored in \plugins\localization-sample\. Modify and copy this file to %appdata%\Camfrog Bot\\.

Greeter

Full list of bot commands

The Greeter module sends greeting messages when a user joins a chat room. All users are divided into several groups by sex and role. So the bot owner can create a list of greeting messages for each group of users or their combinations, for example, male or female users, owner females, friend males and so on.

Lists of greeting messages are stored in %appdata%\Camfrog Bot\\greeter\ as simple text files. Names of these files consist of two parts, which determine the role and sex of users to whom these messages are displayed. If for some reason these files do not exist, the plug-in will recreate them automatically.

Localization

Greeting messages can be localized. All messages are in English by default, but you may want to translate them into your native language. Please keep in mind that these files should be saved in the UTF-8 encoding.

HTML Log

Full list of bot commands

The HTML Log module writes down all room events such as user chat, log in and log out notifications, administrative actions, and more.

The log file name is composed of the chat room name and current date, e.g. "CamfrogHelp_chatlog_20090604.html". In case the room name contains restricted characters (\, /, :, *, ?, ", <, >, |), a hash value will be used instead of the room name.

Log file encoding is UTF-16. The module can gather room statistics every hour. In this case the bot must have the OWNER role in the room.

IM Control

This module allows the user to control the bot and configure plug-in modules by instant messaging. You must be the bot owner for the bot to execute your commands. The bot owners list can be edited in imcontrol.conf, the module settings or by instant messages.

Full list of bot commands

Instant message control plug-in commands (imcontrol.dll/libimcontrol.so) - CSLLCIMC

/pause - pause the bot (the bot disconnects from the room, but the bot is still online)

/resume - resume the bot (connects to the last room)

/shutdown - shut down the bot

/imrefresh - reload the instant message control configuration file

/help - show help

/addowner - add a user to the owners list

/delowner - remove an owner from the owners list

/owners - show the bot owners list

/postmsg - post a message to the chat

/kickuser - kick a user from the chat room

/punishuser - punish a user in the chat room

/unpunishuser - unpunish a user

/modules - list of currently active modules

Trivia plug-in commands (trivia.dll/libtrivia.so) - CSLLCTRV

/trvplay - turn the Trivia game on/off

/trvstart - start a Trivia game

/trvstop - stop a Trivia game

/trvclear - clear the records

/trvrefresh - reload the trivia configuration file

Messenger plug-in commands (messenger.dll/libmessenger.so) - CSLLCMGR

/msgrtime - set the interval of message posting

/msgrclear - clear the message list

/msgradd - add a message to the message list

/msgrdisable - disable the messenger plug-in

/msgrrefresh - reload the messenger configuration file

Bad words kicker plug-in commands (badwords.dll/libbadwords.so) - CSLLCBWD

/bexpr - turn the bad expressions catcher on/off

/bekick - select to kick for bad expressions

/bepunish - select to punish for bad expressions

/bereason - set the reason for kicking/punishment

/becount - set the forbidden words counter

/bewords - select the regular expressions/words mode

/beclear - clear the bad expressions list

/beadd - add an expression to the rule list

/berefresh - reload the bad words module configuration file

WhoBanned plugin commands (whobanned.dll/libwhobanned.so) - CSLLCWBN

/whobanned - check who banned the given user

/whounbanned - check who unbanned the given user

/whokicked - check who kicked the given user

/whopunished - check who punished the given user

/whounpunished - check who unpunished the given user

/whooped - check who oped nickname

/whodeoped - check who deoped nickname

HTMLLog plugin commands (htmllog.dll/libhtmllog.so) - CSLLCHTM

/hlogdisable - disable the html log plug-in

/hlogrefresh - reload the html log module configuration file

RSS reader plugin commands (rssreader.dll/librssreader.so) - CSLLCRSS

/rsstimerfeed - change the feed update time interval

/rsstimerpublish - change the news publishing time interval

/rssrefresh - reload the rssreader configuration file

8 Ball plugin commands (8ball.dll/lib8ball.so) - CSLLC8BL

/8disable - disable the 8 Ball plugin

/8name - change the 8 Ball name

/8refresh - reload the plugin configuration

Greeter plugin commands (greeter.dll/libgreeter.so) - CSLLCGRT

/grtdisable - disable the Greeter plugin

/grtnoroles - disable roles checking

/grtnosexup - disable sex checking

Math Trivia plugin commands (math_trivia.dll/libmath_trivia.so) - CSLLCMTR

/mtrplay - turn the Math Trivia game on/off

/mtrstart - start a Math Trivia game

/mtrstop - stop a Math Trivia game

/mtrclear - clear the records

/mtrrefresh - reload the Math Trvia configuration file

Word Trivia plugin commands (word_trivia.dll/libword_trivia.so) - CSLLCWTR

/wtrplay - turn the Word Trivia game on/off

/wtrstart - start a Word Trivia game

/wtrstop - stop a Word Trivia game

/wtrclear - clear the records

/wtrrefresh - reload the Word Trvia configuration file

Math Trivia

Full list of bot commands

Math Trivia is an entertaining module, which generates simple math equations and posts them over a user-defined time interval. If a user solves the equation correctly, he or she will gain a point.

The rating table is stored in %appdata%\Camfrog Bot\\math\. The rating file name depends on the name of the chat room where the game was started. If you launch the game in the room "SomeRoom1", the rating file name will be "SomeRoom1_records.dbu". Please keep in mind that if the room name contains restricted characters (\, /, :, *, ?, ", <, >, |), the rating file name will contain some hash value, for example, B0B4DD05B629387BC3A005039EE27B8A_records.dbu.

Any room visitor can execute Math Trivia commands. Here is the list of these public commands:

!math help - sends a private help message;

!math - starts the game;

!mq - repeats the current question;

!math top - shows the top 10 game leaders.

Localization

The math trivia game module can be localized into any language. You may want to translate the notification messages into your native language. All the notification messages are stored in math_trivia_message.txt. This file must be in the same directory as math_trivia.conf. See also Camfrog Bot Configurations File. Here is an example of this file.

# This is a localization sample file for the "Math trivia game" plug-in.

#

# Copy this file to %appdata%\Camfrog Bot\\

# and modify it as you need (in Windows OS)

#

# NOTE:

# 1. '%' is a reserved symbol. Use it carefully

# 2. The file must be saved in the UTF-8 encoding

value1=Math Trivia game is not active. To start the game type !MATH

value2=<b>Math Trivia Game help</b>\n\n<b>!MATH HELP</b> - this help screen\n<b>!MATH TOP</b> - top scores\n<b>!MQ</b> - current question

value3=Game started by %1%! Get ready!

value4=<b>Top 10 list:</b>

value5=Correct answer is %1%, answered by %2%, total %3% points

value6=%1% seconds remaining...

value7=Not answered!

value8=Not answered! Correct answer was %1%

value9=Math Trivia game is disabled.

value10=[list empty]

Notes

Value3:

%1% - user nickname;

Value5:

%1% -correct answer;

%2% - user nickname;

%3% - user points;

Value6:

%1% - time left;

Value8:

%1% - correct answer;

Value10:

This message stands for the private message when the top 10 leaders list is empty.

Messenger

Full list of bot commands

This module posts messages in the chat room after every fixed time interval. You can change the time interval from 30 to 30000 seconds. It is possible to add, remove, or modify messages by editing the messenger.conf file, messenger module settings or by instant messages. The module chooses a message to post from the message list randomly.

RSS Reader Plug-In

This module allows you to post RSS feeds of your choice to your chat room. To add a feed to the list, enter its URL in the "Feeds" field and click the "Add" button. To edit a previously added feed URL, double-click the feed in the feeds list. To remove a feed from the list, select the feed and press the "delete" button on your keyboard.

You can also define how often the module will update the news and post them to the chat room.

Click the "Apply" button for the changes to take effect or "Cancel" to discard them.

Any room visitor can execute RSS reader commands. Here is the list of all public commands.

!news - sends all news heads and their URLs;

!feeds - sends the list of feeds and its ID;

!feednews - sends the list of news of the chosen feed.

The information is then sent as a private message.

Trivia

Full list of bot commands

This module runs a Trivia game in the chat room. The bot asks questions and users who answer get positive ratings points that are reported by the bot.

The question database is stored in the %appdata%\Camfrog Bot\\trivia\questions.du file. The rating table is stored in the same directory. The rating file name depends on the name of the chat room where Trivia is launched. If you launch Trivia in the room with the name "SomeRoom1" and after that launch Trivia in the room with the name "SomeRoom2", then the rating file names will be "SomeRoom1_records.dbu" and "SomeRoom2_records.dbu". Please keep in mind that if the room name contains restricted characters (\, /, :, *, ?, ", <, >, |), the rating file name will contain some hash value, for example, B0B4DD05B629387BC3A005039EE27B8A_records.dbu.

Edit the questions.du file to fill it with your own questions. Preserve the file format for the bot to understand it.

An example question template is below:

Q:What is the name of our planet?

A:Earth

Please note: The default question pack is located in \plugins\trivia. You must put your own questions pack to a separate location in %appdata%\Camfog Bot\\trivia\.

You can also enable hints, correct answer alerts, and notify room visitors how to start the game.

Any room visitor can execute the Trivia commands. Here is the list of these public Trivia commands.

!stat - get a private message with the game stats;

!help - get a private message with a trivia help message;

!play - starts the game;

!q - repeats the current question;

!top - shows the top 10 game leaders.

Localization

The trivia game module can be localized into any language. You may want to translate the notification messages to your native language. All notification messages are stored in the trivia_message.txt file. This file must be in the same directory as trivia.conf. See also Camfrog Bot Configurations File. Here is an example of this file.

#

# Trivia plugin messages

# You can translate these messages to your native language

value1=Trivia game is not active. To start the game type !PLAY

value2=<b>Trivia Game stat</b>\n\n%1% question(s) loaded\n%2% question(s) displayed\n%3% question(s) answered\n%4% question(s) cached in buffer

value3=<b>Trivia Game help</b>\n\n<b>!HELP</b> - this help screen\n<b>!TOP</b> - top scores\n<b>!Q</b> - current question\n<b>!STAT</b> - game stats

value4=Game started by %1%! Get ready!

value5=<b>Top 10 list:</b>

value6=Correct answer is %1%, answered by %2%, total %3% points

value7=%1% seconds remaining... First letter is %2%

value8=%1% seconds remaining...

value9=%1% seconds remaining... Last letter is %2%

value10=Not answered!

value11=Not answered! Correct answer was %1%

value12=Trivia game is disabled.

value13=[list empty]

Notes.

Value2:

%1% - number of questions;

%2% - displayed questions;

%3% - answered questions;

%4% - questions left.

Value4:

%1% - user nickname;

Value6:

%1% -correct answer;

%2% - user nickname;

%3% - user points;

Value7:

%1% - time left;

%2% - first letter (if hints turned on);

Value9:

%1% - time left;

%2% - last letter (if hints turned on);

Value13:

This message stands for the private message when the top 10 leaders list is empty.

Who Banned Plug-In

Full list of bot commands

This module is compatible with Camfrog Chat Room Server 5.0 and higher.

This module gathers statistics about any chat room server options changes, user kicking, punishing, banning, microphone blocking and unblocking, status changing events. The module writes logs in UTF-16.

The default log directory is %appdata%\Camfrog Bot\\whobanned\. The log file name depends on the room name.

You can also receive administrative action statistics by instant messages. Statistics will be lost if the bot is restarted or the module is turned off. Statistics records are also removed after the given time interval which can be defined in the settings or in the configuration file.

If you request the latest ban statistics and nothing is found, the module returns only the last 20 records. This feature may be turned off in the settings.

Word Trivia

Full list of bot commands

Word Trivia game asks users to guess the encrypted word whose letters are rearranged. The module also offers a short tip specifying the area the word is related to.

A user can gain a point by giving a correct answer. The top rated user list is saved to a file located in %appdata%\Camfrog Bot\\words\. The name of the rating file depends on the room name, where the game was launched and basically has the following view: "SomeRoom_records.dbu" if the room name is "SomeRoom", but if the room name contains some restricted characters (\, /, :, *, ?, ", <, >, |), the rating file name will contain a hash value, for example, B0B4DD05B629387BC3A005039EE27B8A_records.dbu.

The default question pack is located in \plugins\words. When the plug-in is started up for the first time, the question pack is automatically copied to %appdata%\Camfrog Bot\\words\.

Any room visitor can execute Word Trivia commands. Here is the list of these public commands:

!words help - sends a private help message;

!words - starts the game;

!wq - repeats the current question;

!words top - shows the top 10 game leaders;

!stat - sends a private message with the game stats.

Localization

The word trivia game module can be localized into any language. You may want to translate the notification messages into your native language. All notification messages are stored in word_trivia_message.txt. This file must be in the same directory as word_trivia.conf. See also Camfrog Bot Configurations File. Here is an example of this file.

# This is a localization sample file for the "Word Trivia game" plugin.

#

# Copy this file to %appdata%\Camfrog Bot\\

# and modify it as you need (in Windows OS)

#

# NOTE:

# 1. '%' is a reserved symbol. Use it carefully

# 2. File must be saved in the UTF-8 encoding

value1=Words Trivia game is not active. To start the game type !WORDS

value2=<b>Words Trivia Game stat</b>\n\n%1% question(s) loaded\n%2% question(s) displayed\n%3% question(s) answered\n%4% question(s) cached in buffer

value3=<b>Words Trivia Game help</b>\n\n<b>!WORDS HELP</b> - this help screen\n<b>!WORDS TOP</b> - top scores\n<b>!WQ</b> - current question\n<b>!WORDS STAT</b> - game stats

value4=Game started by %1%! Get ready!

value5=<b>Top 10 list:</b>

value6=Correct answer is %1%, answered by %2%, total %3% points

value7=%1% seconds remaining... First letter is %2%

value8=%1% seconds remaining...

value9=%1% seconds remaining... Last letter is %2%

value10=Not answered!

value11=Not answered! Correct answer was %1%

value12=Words Trivia game is disabled.

value13=[list empty]

Notes.

Value2:

%1% - number of questions;

%2% - displayed questions;

%3% - answered questions;

%4% - questions left.

Value4:

%1% - user nickname;

Value6:

%1% -correct answer;

%2% - user nickname;

%3% - user points;

Value7:

%1% - time left;

%2% - first letter (if hints turned on);

Value9:

%1% - time left;

%2% - last letter (if hints turned on);

Value13:

This message stands for the private message when the top 10 leaders list is empty.

Version (Sample Plug-In)

This module is distributed with open source code to help developers understand the plug-in architecture. Its reaction to an instant message /ver command to the bot is "Camfrog Bot 5.1 version plug-in". The module's settings tab contains a field where you can type additional text to be displayed after the version message (the text will be displayed in brackets).

For more information look at the sample plug-in sources which are located in < Camfrog Bot installation folder>\plugins\sample-src\.

To build the sample project we used Microsoft Visual Studio 2008.