backIndex

Xelagot action script

Events: (3.5) User List

Refer to Events for general information about events, and to Topics: Trivia for information about trivia.

Requires xelagot 3.603 or higher.

User Lists were introduced in 3.5 universe servers. Normally, only universe caretakers (Number One) have access to this list, but in some universes, all users can access it. See below IfUserLister.

This page has three sections: user list events, user list statements and user list examples

User List events

Installers:

OnUserListBeginEvent <eventlabel>
Event type: 10400
is triggered when the bot starts a QueryUserList or FullQueryUserList

OnUserAddEvent <eventlabel>
Event type: 10410
is triggered when the universe server sends a new user information

OnUserChangeEvent <eventlabel>
Event type: 10411
is triggered when the universe server sends new information for a user

OnUserDeleteEvent <eventlabel>
Event type: 10412
is triggered when the universe server notifies that a user has logged off

OnUserListCompleteEvent <eventlabel>
Event type: 10401
is triggered when the universe server has no more information to send

Specific statements (must be inside the event handler):

GetEventType %a stores the event type code in variable %a
GetEventResult %a stores the event result code in variable %a. 0 means success, other positive codes are equivalent to the rc codes of the SDK and the Windows codes. See SDK Error Codes.

 

 

User List statements

IfUserLister statement1
Else statement2


IfNotUserLister statement1
Else statement2
xelagot 3.603
Test the ability of the bot to query the universe server for a user list. The universe must be 3.5 or higher, and the bot must either be logged in as citizen 1 (universe caretaker, can always query), or the user list must be enabled for all users (most universes will not allow this). Universe owners can enable the user list for all by editing the universed.ini and restarting the universe server:
[misc]
user_list=1
QueryUserList
xelagot 3.603
Starts a user list query. If the query starts OK, then this will trigger OnUserListBeginEvent, followed by OnUserAddEvent, OnUserChangeEvent, OnUserDeleteEvent for events sent by the universe server, and as last OnUserListCompleteEvent.

Note: this statement forces the universe server to send changes (add, change or delete) to what it previously sent. If you wish to have the full set of users, call FullQueryUserList: this is always necesary when you first query from a script, next calls can be done with QueryUserList if you have stored user data in e.g. a string list.
FullQueryUserList
xelagot 3.603
Starts a user list query, as previous statement. But just after triggering the OnUserListBeginEvent, it first scans it's internal user list and triggers an OnUserAdd event for each user there. After that, it may trigger OnUserAddEvent, OnUserChangeEvent, OnUserDeleteEvent for events sent by the universe server, followed finally by OnUserListCompleteEvent.
GetUser %id %st $name $world %cit %privs $ip $email xelagot 3.603
Retrieve the individual data of a user. Universe caretaker bots may retrieve all the data, other bots (if allowed to query) do not get %privs, $ip or $email, so these last 3 parameters may be omitted.

%id is a unique number per user, it can be used as name in a name=value pair to identify the user.
%st is the status, it is 0 when a user logs off (OnUserDeleteEvent), and not 0 for others. The usual value is 1.
$name is the name of the user. It is unique for citizens and tourists, but not for bots!
$world is the name of the world where the user is. Bots do not show the name of the world.
%cit is the citizen number of the user, for tourists it is 0, and bots will show the citizen number of their owners (note: the SDK sends 0, but xelagots change this).
%privs is the citizen number used as privilege by the user (privs). For bots, it is the citizen number of their owners. When a citizen is not wearing privs, the SDK sends a 0, but xelagots change this to match the citizen number of the user.
$ip is the dotted IP of the user.
$email is the email of the user, as recorded in the universe database. At present, this information is not being sent.

Note: universe caretaker bots get the full set, other bots (if allowed to query) do not get %privs, %ip or $email. Moreover, only universe caretaker bots get information about bots.

Applies to:
OnUserAddEvent
OnUserChangeEvent
OnUserDeleteEvent
GetUserList /s_myList xelagot 3.603
Copies the full user list to a string list in new database format. Each record is a name=value pair, and strings (name, world, ip, email) are DBEncoded; id, state, citnum, privs are integers.
id=state,name,world,citnum,privs,ip,email


Applies properly to:
OnUserListCompleteEvent
but may be called at any moment
IfIsBotName $name statement1
Else statement2
xelagot 3.603
Tests for the square brackets surrounding bot names.
IfIsTouristName $name statement1
Else statement2
xelagot 3.603
Tests for the double quotes surrounding tourist names.
IfIsCitizenName $name statement1
Else statement2
xelagot 3.603
Tests for the absence of square brackets and double quotes surrounding names.
UserListCount %c

UserListUsers %c
xelagot 3.603
Both these statements count the total number of users in the bot's User List.
UserListBots %c
xelagot 3.603
Counts the total number of bots in the User List.
UserListTourists %c
xelagot 3.603
Counts the total number of tourists in the User List.
UserListCitizens %c
xelagot 3.603
Counts the total number of citizens in the User List.

 

 

User List examples

This very simple example, which can only be used with X1, triggers a refresh of the user list every 60 seconds. If your bot is allowed to query the user list, open your X1's Universe Attributes screen, select the User List tab, and run this script:

[Head]
Type=Script
Version=2.0

[Settings]
Origin=0.000n 0.000w 0.00a 0.0

[Script]
  OnTimeoutEvent TOE
  SetTimeout !t
Label Loop
  Goto Loop
End

Event TOE
  QueryUserList
  GetDateTime !t
  AddSeconds !t !t 60
  SetTimeout !t
EndEvent

 

This next script is a bit more complex, and uses almost all of the new statements. Test it with X1, as it uses SecretConcat. Notice that it calls FullQueryUserList the first time, and then only QueryUserList to see the changes.

[Head]
Type=Script
Version=2.0

[Settings]
Origin=0.000n 0.000w 0.00a 0.0

[Script]
var /s_UL
  OnTimeoutEvent TOE
  OnUserListBeginEvent ULBegin
  OnUserListCompleteEvent ULComplete
  OnUserAddEvent UAdd
  OnUserDeleteEvent UDelete
  OnUserChangeEvent UChange

  FullQueryUserList
  GetDateTime !t
  AddSeconds !t !t 60
  SetTimeout !t
Label Loop
  Goto Loop
End

Event TOE
  QueryUserList
  GetDateTime !t
  AddSeconds !t !t 60
  SetTimeout !t
EndEvent

Event ULBegin
  SecretConcat "user list begin"
EndEvent

Event ULComplete
  SecretConcat "user list complete"
  GetUserList /s_UL
  SListCount /s_UL %c
  DBAddField /s_UL 2 $a
  SecretConcat "list has " %c " users: " $a
  UserListBots %b
  UserListTourists %t
  UserListCitizens %c
  UserListUsers %u
  SecretConcat "users " %u " = bots " %b " + tourists " %t " + citizens " %c
EndEvent

Event UAdd
  GetUser %i %s $n $w %c %p $p $e
  IfString $w = "" $w = "unknown world"
  SecretConcat "add user " %i " state=" %s ", " $n " in " $w " #" %c " (" %p "), ip " $p ", email " $e
EndEvent

Event UDelete
  GetUser %i %s $n $w %c %p $p $e
  IfString $w = "" $w = "unknown world"
  SecretConcat "delete user " %i " state=" %s ", " $n " in " $w " #" %c " (" %p "), ip " $p ", email " $e
EndEvent

Event UChange
  GetUser %i %s $n $w %c %p $p $e
  IfString $w = "" $w = "unknown world"
  SecretConcat "change user " %i " state=" %s ", " $n " in " $w " #" %c " (" %p "), ip " $p ", email " $e
EndEvent


backIndex