Index
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
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. |
| 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. |
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
Index