Crowd Bot for ActiveWorlds

Description

Description

The main purpose of the CrowdBot is to populate your world with active avatars giving a living atmosphere to it. Imagine having birds, cars, ghosts and other creatures constantly moving around (sometimes even talking)!

What can the bot do?

Record a visitor's all movement and gestures (together with his.her chat) to a movement file.
Playing back any movement file up to 32 bots parallel.
Any individual Crowd can be configured to act like a well behaved car: it will not collide with your visitors but politely waits for them (for a limited time:)

What the bot can NOT do? Brewing your coffee and much more :)

The bot comes for Linux and Windows OS and it supports the ActiveWorlds technology's V3.6 and V4.1 version. It can be licensed to a single world or to a universe.

All flavors of the bot reads its configuration parameters from an ini file and it accepts commands through the chat interface inworld.
The Windows version has some limited GUI where you can start or stop the crowd and initiate the recording. This version can fill some basic parameters for the ini file.

To run the bot, the owner citizen number has to have sufficient bot rights in the universe and preferably Caretaker Right in the world.

Whats are the basic information the bot needs to run

The universe authentication parameters (Uniserver's URL, Port, Owner's citizen number, privilege password and the world it runs)
The individual Crowd bot's movement sequence and the number of Crowd bots you want to run at once (limited to 32 bots)
The list of Bosses who can control the bot (the Owner is a boss by default). The robot doesn't accept any command from anyone else!
The Control bot's mode: Global or regular bot (the later one doesn't need CT rights but has limited hearing distance of 200 meter radius).

How does the bot works:

Recording (start it with the /record or /talkrecord commands or click on the Record button in the GUI version):

When you instruct the bot to record a visitor, it creates the movement file, presets the bot name to the visitor's name and sets the recording unit to 100 millisecond increment.
From that point on, each avatar related event (enter,exit,change or chat) is compared to that particular visitor name and if a match found, the avatar's state is recorded together with the time elapsed since the previous similar event. The visitor can change his avatar, use the gestures and if enabled, his chat is recorded to the movement file too.
When you think the recording is sufficient, just issue the /endrecord command or click on the Stop button. The bot then saves the file and it is ready for playback.

Playback (starts with the /reload command or clicking on the StartCrowd menu item)

Based on the command parameters, the bot reloads the movement file(s) for the Crowd bot and creates and appropriate bot inworld. This newly created bot is visible to all visitors and it will replay all those events the movement file contains. (It can enter or exit from the world , can replay the gestures or even talk). By default all playback is looped but you can override it by modifying the movement file. It can be suspended and resumed by a chat command or you can terminate/destroy any or all bots. If a movement file specifies the script as a "car" (and "Car behavior" enabled) then wen the bot comes too close to a visitor, it will stop and wait for the visitor to move away from its path. The car can be impatient and honk if the visitor doesn't move. After 15 seconds the car will move on and overrun the obstructing avatar.

Creating movement file from Tracker's SQL recordings

The bot can read the MySQL database where the Tracker bot records the visitor's movement. This feature let you replay some events occured long time ago or just now. The bot doesn't distinguish between tourists, so it can only use citizen numbers for the movement file. The movement has to be occured within the same world, it would be strange to playing back a movement sequence occured in a different world :)

Interpreting the commands:

Commands can be delivered to the Control bot by chatting in the chat window (the only way to send it to the bot if it is invisible) or whispering to it when the bot is visible.
All command should start with a "/" character. Those commands which has parameters, should end with a ":" (semicolon) character followed by the parameters.

Command descriptions

/crowdhelp

Lists all commands for the user with brief explanation.

/reload:[botnum] [movement file]

Reloads the given bot's movement and starts immediately the playback.
Both parameters are optional and they have default values.

If botnum is missing or 0 it reloads all default movements assigned to each bot.
When botnum is specified, only that particular bot is loaded with the given movement file.
If the movement file is missing then the bot assumes the default movement file associated with this bot.

/record:visitorname[,filename]

Creates new movement file based on recording a visitor's move.
In the event you want to record a tourist's move, you should use the " quotation around his name. Visitorname is not case sensitive for matching but recorded in the movement file as typed (minus the " characters if exists).
If no file name is given, assume visitorname.ini.

/talkrecord:visitorname[,filename]

Creates new movement based on recording a visitor's move AND his/her chat. The command behaves exactly like /record: except it puts the visitor's chat text to the movement file too. Those chats can be played back later if enabled.
If no file name is given, assume visitorname.ini.

/endrecord

Finishes the recording and closes the movement file. The movement file is immediately available for playback now.

/suspend[:elevation]

Suspends the Crowd playback and sends them up to the air.
Elevation is optional and it has to be in centimeter. If the elevation value is given, it changes the INI file settings too, so the next suspend request can use it without providing the value.
When the elevation value is less than -200 meter (-20,000) then the crwod will be suspended but not sent to the desired elevation.

/resume

Resumes the Crowd playback.
Warning: suspend and playback is executed during the next step of the movement script. If the duration of the current step is long, the command will be delayed till that duration finishes for the given Crowd bot.

/speedset:botnumber speeddivisor

Sets the bot speed divisor (must be a float value e.g.: 2.0 for half speed)
You can experiment with different speed settings for the bot. The given divisor will be used to divide all the palyback durations, rounded to the next 100 ms value and limited to the minimum of 100 ms.

/number:numberofcrowd

Sets the maximum number of crowdbots can be started at once to numberofcrowd (minimum 1, maximum 32)

/save:botnum movementfile

Assigns the movementfile to the botnum crowdbot permanently in the INI file.

/stop:botnumber

Destroys the botnumber crowdbot.
If botnumber is 0 then ALL crowdbots will be destroyed!

/talk:botnumber

Toggles the right to speak of the botnumber crowdbot.
If botnumber is 0 then ALL Crowd bots toggled!

/cars

Toggles car bot behavior.
When the crowdbot is a car and it comes too close to a visitor, it tries to avoid a collision with him/her by waiting for a while.

/honk

Toggles car's honking behavior.
If the car behavior is enabled and the bot encounters a possible collision with a visitor, it will say "beep... beep... beep..." after 5 seconds and will say "HONK!! HONK!! HONK!!" after 10 seconds. 15 seconds later the bot will continue the playback regardless of the visitor's position.

/details

Toggles the bot verbose logging.
The bot can log detailed events which is usefult for debugging the movement file

/getsql:citnum,botname,movementfilename,datetimefrom,datetimeuntil

This command will query the MySQL server for the citizen number and the same world where the bot is located for all movement records which occured between datetimefrom and datetimeuntil. The datetime format is (as MySQL uses it): yyyy-mm-dd hh:mm:ss (e.g. 2008-08-24 12:18:32). Later you can assign this newly created movement file to a bot even permanently.

Movement file syntax

In the movement file, all values are in centimeter, 0.1 degrees and 100 milliseconds!

First line: [BotMove]

Actually ignored

Bot naming line

It should start with the # character. Only the last occurance is recorded!

This line renames the bot to the given one. It should contain the for: string right in front of the bot name.
There are two modifier can be added to that line right after the # sign but before the for: string:

Declare the avatar as a car so you can use the car behavior on it (no avatar collision will occure) by using the car string with space before and after
If you want this move file played only once then use the noloop string with space before and after non-looping palybacks should be restarted manually.

E.g.:
# for:Marionett

The bot will act as a regular avatar and will have the name: [Marionett]

# car for:audi3

This bot can act as a car and it will be called [audi3]

# noloop for:SpaceWalker

This bot will play back its script only once

# noloop car for:Ambulance

You can command this [Ambulance] car once manually if there is a need for it :)

RecordModifier line

This line contains offsets to the original recorded file. The line starts with the + character and it has 8 integer and one float value and ends with an equal sign. You can use those modifiers to change each movement location without manually editing each line.
Format: + Xoffset Yoffset Zoffset YAWoffset PITCHoffset AVATAR GESTURE DURATIONoffset DURATIONmultiplier =
Xoffset Yoffset Zoffset YAWoffset PITCHoffset - adds those values to all of the move addresses (Z is North-South, X is West-East and Y is the elevation element) . PITCH offset is not implemented yet.
AVATAR - overrides the recorded avatar number with this one,
GESTURE - not used (it kept by compatibility reason)
DURATIONoffset - this value added to each duration unit
DURATIONmultiplier - each resulted duration multiplied with this value.
E.g. We want to use only avatar number 5 for this move and elevate the bot 3 meters above the original level(note the duration multiplier is set to 1!):
+0 300 0 0 0 5 0 0 1 =

Move sequence line

The actual move sequence has 10 integer values and ends with an equal sign. The optional chat string is after the equal sign and it is left trimmed from the spaces.
format: X Y Z YAW PITCH AVATAR GESTURE DURATION ACTION =[Optional chat string]

action=-2 - Avatar exit (the bot will actually exit from the world)
action= -1 - Avatar enter
action=256 -Avatar will talk the optional chat message. (the chat right is disabled by default)
action=257 - Regular movement action but a marker will be sent to the log file if detailed log enabled

anything else is actual move to the specified address

DURATION is in 100 millisecond units! Maximum value is 6000, which is 10 minutes. This limitaion can be overridden by the ini file.

E.g.:
Move the avatar to 15.353N 7.307E 1.11a 162 with avatar #5 and no new gesture and stay there for 10 seconds:
7307 1110 15353 -1621 0 5 0 100 0 =

The duration value shouldn't be too small because it could consume high bandwidht and the visitors will not see it at all.
General rule of thumb: use the minimum value as ½ of the world server's avatar update speed (default is 1 per second, so the smallest number should be around 4 or 5).

INI file values:

[License]

LicenseKey=xxxx-xxxx          # Your licence key for the bot

[Universe]

Host=auth.activeworlds.com    # uniserver URL  (replace with the dotted decimal IP address if it can't be resolved)

Port=5670            # uniserver port

World=AW            # the world you run the bot

[Bot]

BotName=CrowdControl        # default name for the invisible control bot

CitNum=1            # Citizen number the bots are running under

PrivPass=secret            # Owner's privilege password

LogFileName=crowd.log        # log file name

LogFileSize=1000000        # log file size in bytes

GlobalBot=1            # Must be a caretaker to be able to communicate with the bot

AutoStartCrowd=0        # starts all crowd automatically after the bot is started

AutoStartBot=0            # starts the control bot automatically (if not running, you can't command it from chat!)

VerboseLog=1            # detailed logs to crowd.log

CarsEnabled=0            # enable car-like behavior

HonkEnabled=0            # enable Honking when a visitor stops the car bot

Visible=0            # set the bot visibility

X=0                # W-E location of the bot (in centimeter)

Y=0                # the bot's elevation

Z=0                # N-S location

YAW=0                # the bot's orientation in 1/10th of degree

Avatar=0            # the avatar number the bot has

[CrowdMove]

CrowdNumber=4            # maximum number of crowd bots started when AutoStartCrowd=1 or /reload:0 issued

SuspendElevation=3000        # which elevation the bots should be suspended (default is 30 meter)

MaxDuration=6000        # the limit of the playback single element

CrowdName1=Crowd        # default bot name (move file can override it!)

MoveFile1=botmove1.ini        # bot move file for the 1st Crowd Bot

CrowdName2=Crowd

MoveFile2=botmove2.ini

CrowdName3=crowd

MoveFile3=botmove3.ini

CrowdName4=crowd

MoveFile4=botmove4.ini

[Controllers] # list of citizens who can control the bot

Boss0=1                # set to your Citizen number

[MySQL] MySQL server parameters where the bot can access the Tracker generated location table

UseServer=1

SQLServerURL=            #set to your MySQL server's Location

SQLPort=3306

SQLTablename=Storage_Location    #set your tracker's Location database table

SQLDatabase=TrackerDB            # set your database name

SQLPassword=xxxxxxxxxx

SQLUser=yourusername

SQLSocket=/var/lib/mysql/mysql.sock    # only use it if the Server URL is localhost

Tips

Set the world "Avatar Refresh per second" option to 4-5 when recording a move to get smooth playback. Don't forget to set it back to 1 or 2 when finished because it can put a stress on the network traffic!
You can omit the ControlBot if you don't want to commandeer it from the chat interface by not autostarting or starting it.Your crowds are still operational but it can not act as a car. This method will greatly reduce the internet traffic too!
Quick start (Windows):
Start the bot, fill in the credentials in the Bot Parameters dialog box but don't check the "AutoCrowdStart" checkbox.
Leave the MoveFile names grid empty.
Put your name into the "User Name to Record" field and click on Record.
Walk around your world, use the gestures, change your avatar as you wish then Stop the recording that will result a move file.
Restart the bot and put the newly created move file's name into the grid. Start the Crowd and check if you like itJ
When you first start the bot, it will pop up the Bot parameter settings dialog box, where you have to specify/modify the default parameters.
Don't forget to put your License Key in place unaltered!
The bot name is for the Crowd Control bot, which is invisible for the visitors and should have Caretaker privilege to operate.
This bot can receive commands through the chat interface, so you can control the bot on a remote computer too.
You have to have sufficient bot rights to create your crowd inworld (at least N+1 where N is the number of moving avatar inworld
The bot responds only to it's authorized users where the bot owner is always added by default.
You can add more authorized user by editing the crowd.ini file and adding BossXX=citnum lines to the [Controller] section where XX is a sequence number between 1 and 99 but it is renumbered to a proper sequence every time you start the bot.
Please use only Notepad kind of editors!

GUI Screenshots

Parameter dialog:

File menu

Change Log

V 2.1 - first release 12/31/2006

V 2.2 - 1/2/2007
Fixes/mods:
    Changed the /help to /crowdhelp.

    Added /stop:n command to destroy individual crowd bots. If n=0, all crowdbots are destroyed.

    Modified /record:visitorname[,filename] - if no filename given, the bot will record it under visitorname.ini (of course the tourist's " characters are stripped:).

    Changed log file handling. One can specify different file name for the log. The log file size is limited now to 1000000 which can be changed through the inifile. The bot now does a simple log rotate.

V 2.3 - 1/2/2007
    Replaced synchronous enter,logins with async one to make it more responsive
    Added Center bot Visible feature (answers now with whisper)
    Added /visible command to toggle the bot visibility but it only changes in the INI file. The bot has to be restarted!

V 2.4 - 1/3/2007 - Linux, Windows
    Moved help message to timer to avoid chat flooding
    Added talking capability to the crowd. Use sparingly because it can flood the chat window!
    Added /talkrecord: command where the bot will record not only the visitor's movement but all of his/her chat
    Added /talk: command where the boss can toggle individual (or all) crowd's talking right. Talking is disbled by default!
    Added suspend command's elevation value to the INI file and it can be modified by the /suspend:elevation command.
        If the value is less than -20000 , the bot will stay where he is.
    Added marker to the movement script (257 as action) for recording into the log file.
    Added MaxDuration to the ini file to override the buil-in 10 minutes maximum limit

V 2.5 - 1/4/2007 - Linux, Windows   - Works with 4.2 universe too!
    Fixed strange playback timing behavior
    Fixed Windows version time resolution

V 2.7 - 8/24/2008
    Added creating movement file from Tracker's database

V 2.9 - 11/18/2008 - Linux, Windows
    Rebuilt with AW SDK 75 for Universe version 4.2

This page visited since 2007 Jan. 2.: