Xelagot action script

Surveying, building... and the Lists

Object manipulation is usually aimed at changing the virtual environment in one way or another. The action script provides a series of tools to help you achieve this.

The first step is learning how to use object variables. This is explained in Object variables and operations. In that section you will also find statements for building, modifying and deleting individual objects.

Next, you may want to read the section on Events and especially Events: ObjectCreate, ObjectResult. When you build, objects are created and receive a special ID number: the object number. This number is needed if you wish to modify an object or delete it, and is automatically provided to your object variable when the command to create a new object is sent to the world server, a short while after your script statement is executed: there is a delay between both actions. The safest way to know when this number has been assigned is in the event handler ObjectCreate. There is one exception: if your statement is in the main part of the script, or in a Sub called from there, the bot interrupts the execution of the script to send the object and retrieve the object number inmediately, provided no projects are being built by the bot at that moment (i.e. the send queue must be empty) and that the statement is not in a Suspend-Do block. The event handler ObjectResult returns the world server's veredict: success or failure in creating, modifying or deleteing an object.

To find existing objects, you must learn how to survey property by querying the world server: queried objects are kept in the Survey collection of objects. Two events are associated to this: event QueryBegin and event QueryComplete. When the survey is complete, use filters to narrow your search and retrieve the result of your search in the Result (Res) collection. This is explained in Filters and searching for objects.

In 3.1 worlds (world server 28 or higher) the Cell buffer contains the objects of a specific cell, obtained by issuing GetCellAt @a statement, and waiting for the CellContents event.

You can manipulate collections of objects as well as individual objects. See Projects for a list of statements to make, save, load and manipulate these collections or Projects, and Events: ProjectComplete for an associated event handler.

All these actions are recorded by the bot, and the state of affairs is kept in lists, which are also collections of objects. Here is how this happens...

When you send a command to build an object, this object is put on a queue in a list called the ToDo list. The same applies to objects being modified or deleted.

Next, the program sends these objects to the world server: at that precise moment, new objects receive the Object Number which identifies them as unique, and the object is passed from the ToDo list to the AddUnconfirmed or DeleteUnconfirmed list. Adding to the AddUnconfirmed list triggers the ObjectCreate event.

They will stay on these lists until the world server acknowledges receipt of the command, and returns a code signifying success or failure. If the command succeeded, the object is passed to either the AddSuccess or DeleteSuccess list. If the command failed, the object is moved to the AddFailed or DeleteFailed list. The ObjectResult event is triggered at this moment.

What happens if the world server fails to confirm a command? This is the case when the connection fails: waiting for server. Well, the object stays on the Unconfirmed list forever... you won't know what happened to it. The only way to find out is to survey the area and look for the object in question.

Individual manipulation of objects on these lists is not (yet) possible through scripting, but you can count the objects on these lists, save and clear the lists. You must clear the lists yourself if you build and do not need to keep the results, because otherwise these lists keep on growing. Also, if you plan to build something (a Project, for instance), clear the lists beforehand so that, after building, you will have a clear picture through these lists of what happened: the Project should be empty, the Success list should have all the objects which were in the Project, with their brand new object number. You can save this Success list with SaveListAS and, if you need to delete the same objects, reload it as a Project with ProjectLoad, clear the lists again and destroy. See Projects for project statements, and here below for the list statements.

The corresponding statements are:

CountLists %as %af %au %ds %df %du %td stores the amount of objects in each list in variables:
  • AddSuccess stores in %as
  • AddFailed in %af
  • AddUnconfirmed in %au
  • DeleteSuccess in %ds
  • DeleteFailed in %df
  • DeleteUnconfirmed in %du
  • ToDo in %td
You may not omit a variable if it is placed before the variable you need to know, but you may use bogus variables or even words to replace unwanted data. For example, if you only want to know the DeleteSuccess count, you may write:
CountLists x x x %c x x x
or even:
CountLists x x x %c

xelagot 3.607
Clears the corresponding list, ClearLists clearing them all. See Managing memory usage when building.

xelagot 3.607
adds ClearConfirmedLists, that clears AddSuccess, AddFailed, DeleteSuccess and DeleteFailed. See Managing memory usage when building.
  • AS is AddSuccess
  • AF is AddFailed
  • AU is AddUnconfirmed
  • DS is DeleteSuccess
  • DF is DeleteFailed
  • DU is DeleteUnconfirmed
  • TD is ToDo
SaveListAS $f [%r]
SaveListAF $f [%r]
SaveListAU $f [%r]
SaveListDS $f [%r]
SaveListDF $f [%r]
SaveListDU $f [%r]
SaveListTD $f [%r]
  • AS is AddSuccess
  • AF is AddFailed
  • AU is AddUnconfirmed
  • DS is DeleteSuccess
  • DF is DeleteFailed
  • DU is DeleteUnconfirmed
  • TD is ToDo

Saves the corresponding list in file $f. If successful, optionally stores 0 in %r, otherwise -1.

xelagot 3.607 or newer
The filename convention is explained in the section Filenames. If the destination path and folder does not exist, it will be created to accommodate the file.

xelagot 3.606 or older
The path defaults to the path of the current script file. A full drive + path may also be specified, see Program paths.

Copies the objects in the corresponding list to the Project buffer.
  • AS is AddSuccess
  • AF is AddFailed
  • AU is AddUnconfirmed
  • DS is DeleteSuccess
  • DF is DeleteFailed
  • DU is DeleteUnconfirmed
  • TD is ToDo

The program uses a few buffers which can contain collections of objects:

All these collections have methods for saving their contents to file and clearing them.