Index

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:

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

• the Survey usually contains 1 zone at a time, and is made by querying or scanning that zone in a world. Surveys can be initiated through verbal commands, scripts or user interface (Survey Manager).
• the Project can contain any collection: you may load objects from file, you may get the objects from the survey (optionally using a filter), or you may add them individually. You may do this with a script or through the user interface (Survey Manager).
• the Lists mentioned previously contain objects which are sent to the server to build or destroy, either individual objects or objects from the project. Also objects seeded by the bot go through these lists (verbal commands), as well as those sent through the user interface (Survey Manager).
• the Res is specific for scripts: it contains the result of searches using a filter on the Survey or Project collections. You can recover individual objects in the Res with script statements.
• in 3.1 worlds, the Cell contains the objects of a specific cell, obtaines with GetCellAt @a. Objects can be copied to the Res and to the Project.

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

Index