Xelagot action script

WriteToBot commands

The WriteToBot command series is used by different interfaces and script statements:

by script statements sent to bots in the same application, using the WriteToBot statement
by script statements sent by bots connected to a Xelagot server (if they have MASTER protocol) to other bots connected to the server, using the CLWriteToBot statement
by the Av99Bot and SrvcXlgBot applications when they read command files from their DB2Bot folder

These commands are executed by the destination bot directly, whether it is running a script or not. The Hear and Message commands may trigger a reply through the Answer and Message channels, any other command which requires a reply tiggers one through the Confirm channel. It can spawn the destination bot, change its name, log it in, move it, make it talk... and void it. It can even manipulate the sending bot: both sending and receiving bots can be one and the same bot.

Bots in the same program as the destination bot can use the following script statements, where $botname and &bot refer to the destination bot:

WriteToBot $botname $command
WriteToBot &bot $command

AnyWriteToBot $botname $command

Bots connected through a Bot Client (if they have a master protocol) use these statements, where $login refers to the login name of the destination bot:
CLWriteToBot $login $command
AnyWriteToBot $login $command

The Av99Bot and the SrvcXlgBot also use these commands: they read them from files dropped into their DB2Bot folder. In those files, each line can contain a command, preceded by the bot's name and a separating comma. For example, one line in the file could be (assuming there is a bot called Moishele):
Moishele,enter
'enter' is a write to bot command to enter the universe and world, or to re-enter the world. The general formula for this is: botname,command

$command (or command for the DB2Bot command file) is in a special command format, as specified below:

Hear,string literal
the destination bot interprets the string literal as a verbal command, using the language file codes. It will answer back as in normal chat, using the same Hear command. For example, bot Harry sends through scripting the following statement:
WriteToBot "Pauline" "Hear,citnum Freddy"
this statement reaches bot Pauline through the language interface: citnum Freddy
Pauline sends Harry the following statement:
"Looking for the number of Freddy ...
(Harry hears it in its BotAnswer event handler: Looking for the number of Freddy ...")
followed a few seconds later by
"Freddy is citizen number 3456"
(Harry's BotAnswer event handler hears: Freddy is citizen number 3456)

What Pauline sends back is not in her script, it is generated directly by the language interface verbal command processor as a response to the Hear command it received. If Harry has a BotAnswer event handler installed, it will trap these answers. Pauline does not need a BotHear event handler (but may have one) to handle what Harry sent: Harry's request is formulated as a verbal command Pauline can process directly; if Pauline has a BotHear event handler, it can 'tap' the conversation, but can not prevent the verbal command processor from answering Harry's request.
If the destination bot of a Hear command has BotHear, DBHear (not applicable for regular Xelagots) or CLHear event handlers installed, what it hears will first go to the script event handler as chatlines and then will get processed by the Verbal Command processor. The event handler needed to trap this event depends on the way this event was sent. If sent by a script to a bot in the same program using WriteToBot or AnyWriteToBot statement (command Hear), triggers a BotHear event. If sent through the DB interface (not available in the regular Xelagot) triggers a DBHear event. If sent by a Central Client or a Bot Client (script statement CLWriteToBot or AnyWriteToBot with Hear command) and received by a Bot Client, triggers a CLHear event.

sending bot	channel	destination bot
sends a verbal command to a bot in the same program with WriteToBot "Hear" or to a BotClient on a server with CLWriteToBot "Hear"	hear	receives in OnBotHear or OnCLHear event handler if installed and in verbal command processor.
may receive an answer in OnBotAnswer or OnCLAnswer event handler.	answer	may send back an answer with WriteToBot "Answer" (or CLWriteToBot "Answer" if the bot has Master protocol) - this option is not fully implemented. The recommended way is to answer with MessageToBot and CLMessageToBot. See the event handler BotMessage verbal command processor may trigger an action and/or answer, answers get sent back through an answer channel.

Notice: The destination bot does not need to have the master protocol to for the Verbal Command processor to answer to a CLWriteToBot or AnyWriteToBot Hear command, through its BotClient: it is sent through a different CLAnswer channel (version 2.999984 upwards).

Answer,string literal
Used primarily by the automatic replies of the Verbal Command processor to answer WriteToBot Hear and DBWriteToBot Hear commands. CLWriteToBot Hear commands get answered by the Verbal Command processor through a special channel. CLWriterToBot Answer could be used by bots having Master protocol. Requires that destination bot has BotAnswer or CLAnswer event handlers.

Message,string literal
triggers a BotMessage, DBMessage or CLMessage event in the destination bot's script, passing the string literal, to which the receiving bot's script can attach any meaning: this string is not passed on to the Verbal Command processor. The event triggered depends on the way this command is sent. If sent by a script to a bot in the same program using WriteToBot or AnyWriteToBot statement (command Message), triggers a BotMessage event. If sent through the DB interface (not available in the regular Xelagot) triggers a DBMessage event. If sent by a Central Client or a Bot Client (script statement CLWriteToBot or AnyWriteToBot with Message command) and received by a Bot Client, triggers a CLMessage event.

sending bot	channel	destination bot
sends a message to a bot in the same program with WriteToBot "Message" or to a BotClient on a server with CLWriteToBot "Message"	message	receives in OnBotMessage or OnCLMessage event handler if installed
may receive a message in OnBotMessage or OnCLMessage event handler.	message	may send back a message using WriteToBot "Message" or CLWriteToBot "Message" may also send MessageToBot or CLWrite

Notice: WriteToBot &bot "Message,I like potatoes" and WriteToBot $botname "Message,I like potatoes" is equivalent to MessageToBot &bot "I like potatoes" and MessageToBot $botname "I like potatoes". CLWriteToBot $Login "Message, I hate broccoli" is equivalent to CLWrite $Login "I hate broccoli": the statement CLWriteToBot requires a "master" protocol, ClWrite does not require this.

Say,string literal
Say the string literal aloud. Example:

# get position and name of the sending bot
GetPosition @p
GetName $n
# make the command string $a for $bot2, the destination bot
Concat $b $n " is at position " @p
Concat $a "Say," $b
#send the command string
WriteToBot $bot2 $a

Whisper,string literal
Whisper to all the string litteral

Avatar,number
Change avatar

Gesture,number or gesture sequence
Do gesture number or sequence as specified in Customising

Pitch,integer number (in deci-degrees)
Sets the 3.4 Pitch of the bot in a range from -900 to +900 decidegrees (i.e. -90 to +90 degrees). A positive value is 'look down'.

AvatarState,string
Sets the 3.4 AvatarState according to one of the following strings (case is not important): walking, running, flying, swimming, falling, jumping, warping.

URL,Url URL,Url,FrameName
Requires caretaker abilities in the destination bot. Pushes a URL, optionally in a second frame

Exit
Expel from world

Void
Expel from universe

Enter
Enter universe and world

Warp,posZ,posX,posY,Rotation[,world]
Warp,coordinates A warp command in cm and decidegrees with optional world (comma separated) or in coordinates with optional world (no commas allowed in the coordinates + world string). May be used instead of the Enter command. Example:

Concat $a "Warp," @p
WriteToBot $Bot2 $a
# or
Concat $a "Warp," @p " mars"
WriteToBot $Bot2 $a

BotName,name
Change the name of the bot. May only be used when the bot is outside a universe (after the Void command)

UniverseData,UniverseName,UniverseHost,UniversePort
UniverseHost,UniverseHost
UniversePort,UniversePort
When bot is outside the universe (voided), the universe data may be set. Setting the universe name invalidates the Citizen data of the bot, see next command.

CitizenData,CitizenNumber,CitizenName,UncodedPrivilegePassword
Changes the Citizen data of the bot. Must be used after setting the universe name.

Owners,comma separated list of citizen numbers
OwnersAdd,comma separated list of citizen numbers
'Owners' changes the list of first bosses - besides the login boss, who is automatically first boss. 'OwnersAdd' adds numbers to an existing list.

LoadScript,filename
LoadScript
Loads and runs a script. Filename may have a full path specification. If it hasn't, the current script directory is searched. If no filename is specified, the current script is reloaded and run

EndScript
Ends the execution of a script

StartChatLog
SaveChatLog
StopChatLog
StartTecLog
SaveTecLog
StopTecLog
StartFulLog
SaveFulLog
StopFulLog
Starts logging, saves log (happens anyway), stops logging

Any combination of the following statements:
WorldTitle,string
WelcomeMessage,string
WorldEntryPoint,string
(AW 3.3), coordinates in AW standard notation
WorldKeyWords,string
(AW 3.3), comma-separated list of words
WelcomeMessage,string
Homepage,string
Backdrop,string
Ground,string
SkyBox,string
(AW 3.2)
ObjectPath,string

ObjectRefresh,integer
valid: 0 to .... (abs applied)
RestrictedRadius,integer
valid: 0 to .... (abs applied)
CellLimit,integer
valid: 0, 1, 2
Rating,integer
up to 3.3 worlds valid: 0, 1, 2, 3 (modulo applied)
as from 3.4 worlds valid: 0, 1, 2, 3, 4 (modulo applied)
MinimumVisibility,integer
(AW 3.2) valid: 30, 40, 50, 60, 70, 80, 90, 100
MaxLightRadius,integer
(AW 3.1) valid: 0 to 1000 (abs applied)
AvatarRefreshRate,integer
(AW 3.4) valid: 1 to 15 (abs applied)
BackdropColor,red,green,blue
replaced in 3.4 by
FogColor,red,green,blue
valid integers: 0 to 255 (modulo applied)
FogRed,red
replacing BackdropRed,red
valid integer: 0 to 255 (modulo applied)
FogGreen,green
replacing BackdropGreen,green
valid integer: 0 to 255 (modulo applied)
FogBlue,blue
replacing BackdropBlue,blue
valid integer: 0 to 255 (modulo applied)

AllowCreateURL,string
valid: On or Off
AllowPassthru,string
valid: On or Off
AllowTouristWhisper,string
valid: On or Off
AllowFlying,string
valid: On or Off
AllowTeleport,string
valid: On or Off
AllowObjectSelect,string
valid: On or Off
AvatarsInScene,string
valid: On or Off deprecated
AllowAvatarCollision,string
(AW 3.0) valid: On or Off
RepeatingGround,string
(AW 3.2) valid: On or Off
Allow3AxisRotation,string
(AW 3.3) valid: On or Off
EnableTerrain,string
(AW 3.3) valid: On or Off
AllowCitizenWhisper,string
(3.4) valid: On or Off
DisableChat,string
(3.4) valid: On or Off
AlwaysShowNames,string
(3.4) valid: On or Off
DisableAvatarList,string
(3.4) valid: On or Off
AllowTouristBuild,string
(3.4) valid: On or Off
DisableMultipleMedia,string
(3.6, xelagot 3.601) valid: On or Off

BotsRight,comma separated list
BuildRight,comma separated list
EminentDomainRight,comma separated list
EjectRight,comma separated list
EnterRight,comma separated list
PublicSpeakerRight,comma separated list
SpeakRight,comma separated list
SpecialCommandsRight,comma separated list
SpecialObjectsRight,comma separated list

DirectPolarH,azimuth,elevation
(AW 3.0) Azimuth is 0 = North, positive anticlockwise (towards West), negative values change the direction, you can use then 0.0 to 360 degree notation as well; elevation is negative below the ground, range is -90.0 to 90.0
DirectX,float
(AW 3.0)
DirectY,float
(AW 3.0)
DirectZ,float
(AW 3.0)
DirectColor,red,green,blue
(AW 3.0) valid integers: 0 to 255 (modulo applied)
DirectRed,red
(AW 3.0) valid integer: 0 to 255 (modulo applied)
DirectGreen,green
(AW 3.0) valid integer: 0 to 255 (modulo applied)
DirectBlue,blue
(AW 3.0) valid integer: 0 to 255 (modulo applied)
AmbientColor,red,green,blue
(AW 3.0) valid integers: 0 to 255 (modulo applied)
AmbientRed,red
(AW 3.0) valid integer: 0 to 255 (modulo applied)
AmbientGreen,green
(AW 3.0) valid integer: 0 to 255 (modulo applied)
AmbientBlue,blue
(AW 3.0) valid integer: 0 to 255 (modulo applied)
FogEnable,string
(AW 3.0) valid: On or Off
FogMinimum,integer
(AW 3.0) valid integer: 0 to ...?
FogMaximum,integer
(AW 3.0) valid integer: 0 to ...?

SkyNColor,red,green,blue
(AW 3.4) for the Northern sky (valid integer values: 0 to 255)
SkyNRed,red
(AW 3.4) for the Northern sky (valid integer value: 0 to 255)
SkyNGreen,green
(AW 3.4) for the Northern sky (valid integer value: 0 to 255)
SkyNBlue,blue
(AW 3.4) for the Northern sky (valid integer value: 0 to 255)
for the other skies, substitute SkyN with SkyW (west), SkyS (south), SkyE (east), SkyT (top), SkyB (bottom), for example:
SkyTColor,red,green,blue
for the top sky

Clouds1Texture,string
(AW 3.4) for the Texture of the 1st cloud level
Clouds1Mask,string
(AW 3.4) for the Mask of the 1st cloud level
Clouds1Opacity,integer
(AW 3.4) for the opacity of the 1st cloud level (valid integer values: 0 to 255)
Clouds1SpeedX,float
(AW 3.4) for the west-east speed of the 1st cloud level (float number)
Clouds1SpeedZ,float
(AW 3.4) for the north-south speed of the 1st cloud level (float number)
Clouds1Tile,float
(AW 3.4) for the tiling value of the first cloud level (float number)
for levels 2 and 3, substitute Clouds1 with Clouds2 or Clouds3

EnableWater,string
(AW 3.4) on or off, sets water rendering on or off
WaterUnderTerrain,string
(AW 3.5) on or off, enables water rendering under terrain on or off
WaterTopTexture,string
(AW 3.4) for the Texture of the top layer of water
WaterTopMask,string
(AW 3.4) for the mask of the Texture of the top layer of water
WaterBottomTexture,string
(AW 3.4) for the texture of the bootom layer of water
WaterBottomMask,string
(AW 3.4) for the mask of the Texture of the bottom layer of water
WaterOpacity,integer
(AW 3.4) for the opacity of water (0 to 255)
WaterColor,red,green,blue
(AW 3.4) for the red, green and blue components of water
WaterRed,integer
(AW 3.4) for the red component of water
WaterGreen,integer
(AW 3.4) for the green component of water
WaterBlue,integer
(AW 3.4) for the blue component of water
WaterLevel,float
(AW 3.4) altitude of the water surface (in metres, the AW browser uses decametres)
WaterSurfaceMove,float
(AW 3.4) for the movement of the surface (float)
WaterWaveMove,float
(AW 3.4) for the movement of the waves (float)
WaterSpeed,float
(AW 3.4) for the speed of water (float)
WaterVisibility,integer
(AW 3.4) for the under-water visibility (metres)
WaterBuoyancy,float
(AW 3.4) for the buoyancy of water (float)

WorldLightTexture,string
(AW 3.4) for the Texture of the world light (sun)
WorldLightMask,string
(AW 3.4) for its mask
WorldLightDrawSize,integer
(AW 3.4) for its size (integer)
WorldLightDrawBright,string
(AW 3.4) on or off, for enabling or disabling glow
WorldLightDrawFront,string
(AW 3.4) on or off, for setting (or not) the world light in front of the clouds

Gravity,float
(AW 3.4) world gravity in dm/sec (1 is like on Earth)
TerrainAmbient,float
(AW 3.4) ambient coefficient of terrain tiles (0.0 to 1.0)
TerrainDiffuse,float
(AW 3.4) diffuse coefficient of terrain tiles (0.0 to 1.0)
TerrainOffset,float
(AW 3.5) sets vertical offset of terrain origin in metres (-320 to 320)

SoundFootstep,string
(AW 3.4) filename of sound
SoundWaterEnter,string
(AW 3.4) filename of sound
SoundWaterExit,string
(AW 3.4) filename of sound
SoundAmbient,string
(AW 3.6, xelagot 3.601) filename of sound

Followed by:
ChangeAttributes

Changes world attributes if destination bot is caretaker. Example using a script statement WriteToBot:

WriteToBot $bot2 "WelcomeMessage,Welcome to this games world! Game has started..."
WriteToBot $bot2 "AllowTeleport,Off"
WriteToBot $bot2 "AvatarsInScene,On"
WriteToBot $bot2 "ChangeAttributes"

Strings sent to the world server may not exceed 255 characters, so for instance the Welcome message Welcome to this games world! Game has started... has to remain within these limits.

WriteToBot,botname,message
commands the destination bot to forward the command in message to a bot (in the same program) named botname. Useful when using the BotClient software, example:

# Larry is a bot logged into
# the same remote server as the sending bot's BotClient
$n = "Larry"
# Mary is a bot in Larry's program,
# but is not connected to the same remote server
$m = "Mary"
Concat $a "WriteToBot," $m ",Warp," @p " " "mars"
CLWriteToBot $n $a

Larry receives the message for Mary, forwards it, and Mary warps (if all goes well).

Notice: this is a WriteToBot command inside another WriteToBot command

CLWriteToBot,login name,message
commands the destination bot to forward through its BotClient the command in message to a bot logged in as login name on the server the BotClient of the destination bot is connected to. See previous example. Another example:

# Peter is a bot in the same program as the sending bot,
# but its BotClient is logged into a different server 
# as the sending bot's BotClient
$n = "Peter"
# Mary is a bot 
# connected to the same remote server as Peter
$m = "Mary"
Concat $a "CLWriteToBot," $m ",Warp," @p " " "mars"
WriteToBot $n $a

Peter, a bot in the sending bot's program, receives the message for Mary, forwards it through its BotClient, and Mary warps (if all goes well).

Notice: this is a WriteToBot command inside another WriteToBot command

AnyWriteToBot,botname or login name,message
commands the destination bot to try first to forward the command in message to a bot (in the same program) named botname. If that fails, commands the destination bot to forward through its BotClient the command in message to a bot logged in as login name on the server the BotClient of the destination bot is connected to. Example:

# Larry is a bot logged into
# the same remote server as the sending bot's BotClient
$n = "Larry"
# Mary is a bot in Larry's program
# or it is connected to the same remote server as Larry
$m = "Mary"
Concat $a "AnyWriteToBot," $m ",Warp," @p " " "mars"
CLWriteToBot $n $a

Larry, a bot connected to the sending bot through a BotClient connection, receives the message for Mary, searches its own program for Mary or, if not found, its BotClient connections for a bot logged in as Mary, forwards it, and Mary warps (if all goes well). Obviously, Larry must in some way be able to reach Mary, otherwise the command will fail.

Notice: this is a WriteToBot command inside another WriteToBot command

ServerPort,port number
sets the port of the server of the destination bot's program

ServerConnect,port number
ServerConnect
attempts to connect the server of the destination bot's program

ServerDisconnect
disconnects the server of the destination bot's program

ClientHost,address
ClientPort,port number
ClientLogin,login name
ClientPassword,uncoded password
set the data of the destination bot's CentralClient.

ClientConnect,address,port, login,password
ClientConnect
attempts to connect the destination bot's CentralClient.

ClientDisconnect
disconnects the destination bot's CentralClient.

CLHost,address
CLPort,port number
CLLogin,login name
CLPassword,uncoded password
sets the data of the destination bot's BotClient.

CLConnect,address,port, login,password
CLConnect
attempts to connect the destination bot's BotClient.

CLDisconnect
disconnects the destination bot's BotClient.

The following commands trigger a confirmation or answer from the destination bot. This reply can be trapped by the sending bot (the one that sent the original command) in the BotAnswer event handler for destination bots in the same program, and in the CLAnswer event handler for commands set throught the Bot Client.

sending bot	channel	destination bot
sends a verbal command to a bot in the same program with WriteToBot command or to a BotClient on a server with CLWriteToBot command		receives and executes the command directly (not through a script) if necessary, sends a confirmation or reply back
may receive an answer in OnBotAnswer or OnCLAnswer event handler.	confirm

Download,url,filename
Download,url
requests the destination bot to download a file from internet (http) as specified in the url, and to save it to a file called filename. Filename may contain a full path and filename, but it can also contain just a filename - in this case, the file will be downloaded to the Downloads folder. If the filename is omitted, the destination bot will use the filename in the url. See also Topics: Downloading files.
Confirmation: DownloadComplete,result,url,filename,filelength[, error_message]
result = 0 if everything goes ok

How to parse a Confirmation.

Supposing the bot issued to a bot called Johnny in the same program:
OnBotCAnswerEvent Confirm
WriteToBot "Johnny" "Download,http://www.myserver.com/blues.mid"
it could have this in its script:

Event Confirm
  GetChatname $b
  GetChatline $a
  Split $c $d $a ","
  # $c contains the Confirmation code
  # $d contains the rest
  IfString $c = "Download" Gosub ParseDownload
EndEvent

Sub ParseDownload
  Split $e $d $d ","
  %e = $e
  # %e has the result code, $d has the rest
  Split $u $d $d ","
  # $c has the url, $d has the rest
  Split $f $d $d ","
  # $f has the filename, $d has the rest
  Split $L $d $d ","
  %L = $L
  # %L has the length of file
  # $d has the error code (if any)
  
  # notify the user through the GUI
  Concat $z " url " $u " as file " $f " length " $L " bytes"
  IfInt %e <> 0 Concat $z $z ". Error: " $d
  IfInt %e = 0 SecretConcat $b " downloaded " $z
  Else SecretConcat $b " failed to download " $z
EndSub

Index