Magsbot Help

SURVEYING AND BUILDING

Object Lists

An "object list" is a string list containing survey information. The item number of each item in the list is the object number of the object whose information is stored in that item. The information is stored in the form of a string of comma-delimited values.

Example of an Object List.

Many of the buttons below create or manipulate object lists in various ways.

An object list item contains these fields:

1 NS (Z) coordinate
2 WS (X) coordinate
3 Alt (Y) coordinate
4 Yaw
5 Tilt*
6 Roll*
7 Model
8 Description
9 Action
10 OwnerID
11 Timestamp
12 Object type**
13 Object data string**

*object list format version 3 and 4 only
**object list format version 4 only

If you're writing a script for MBot, the fields within an object list item can be accessed by assigning the item to a string named $mk and using the macros @arg and $arg. For instance @arg[1] would be the NS location, $arg[6] (or $unqarg[6] to remove the quotes) would be the description, etc. Or, you can use the @ar_ and $ar_ macros with any string name, for instance @ar_[$x,3] would be the altitude of the object, if object list item information was stored in a string named $x.

Note: because of the addition of Tilt and Roll as object attributes in more recent versions of the AW Browser, the indices of some fields in an object list may be different depending on whether or not the survey included these new attributes. Thus $arg[5] is the model field and $arg[6] is the description field in old object lists; but in lists that include tilt and roll, the model name is $arg[7] and the description field is $arg[8] instead, because @arg[5] and @arg[6] are tilt and roll. In order to simplify this, I created new macros for the fields that vary: @arg_tilt, @arg_roll, $arg_desc, $arg_model, $arg_act, @arg_owner, @arg_time, @arg_type, $arg_data. These macros will each return a different field depending on the value of @axis3, a global variable that indicates if 3d axis rotation is being used for surveys and building or not (according to the setting of the "Options/Objlist format" menu item). Therefore, if you use (for example) $arg_desc instead of $arg[6], it will be correct for either kind of object list, as long as you have "Options/Objlist format" set consistently.

You can use the $updf macro to quickly update fields within the item string. For instance, to change the description field, you would specify: $new=$updf[$old,6,"My New Description",","], where $old is the item string and $new is the changed item string. (The final argument of the $updf function allows you to specify a delimiter other than a comma, in case you want to use the $updf macro for manipulating some other kind of delimited data string.)

Magsbot uses an object list named ObjLog for logging from a survey.

Here's an example of a piece of code for scanning through an object list named "myobjlist" and replacing the "Model" field with a new model name:

reset the "nextnum" counter to the beginning of the list
resetlist myobjlist;
get the number of items in the list
@ct=@itemcount[myobjlist];

for each item in the list
for i 1 @ct {

    get the next item number
   @n=@nextnum[myobjlist];

    get that item value (a comma-delimited string)
    $mk=$litem[myobjlist,@n];

    determine which field has the model name,
    7 if 3d axis rotation is being used, otherwise 5
    @model_field=@if[@axis3,7,5];

    update the model name field
    mk=$updf[$mk,@model_field,"newmodel.rwx",","];

    save the changed list item back into the list
    setitem myobjlog @n $mk }

Note: be careful about deleting list items within a loop that uses "nextnum" or "nextitem", since removing items can cause the nextnum counter to become confused.

Create an object list:

Log Objects by Click
Log Objects by Click - Stop
Log One Object

Log from Survey
Log from World Survey
Performs a survey, locally or of the entire world, storing the information in object list "ObjLog".

Survey set relative mode
Use this button to set relative survey mode on or off. When relative mode is on, then object coordinates are adjusted relative to the bot's position. That is, object coordinates are saved as if the bot's location was "ground zero" (0n 0w). This makes it easy to survey at one location then rebuild at another location, without having to calculate an "offset," because in relative mode objects will be rebuilt as if the bot's location was ground zero. If relative mode is on when building from a survey, then the bot's location will appear as the default when you are prompted for an offset, and you should accept that.

NOTE: as of this time, this relative mode is entirely separate from the relative mode referred to on the Survey dialog. The relative mode controlled by the "Survey set relative mode" button is used for surveys done using the "Log from Survey" and "Log from World Survey" buttons, whereas the relative mode checkbox on the Survey dialog is used for surveys done from the Survey dialog. Use one or the other, but not both at the same time.

Read obj list from file
Reads a object list into memory, that was previously saved to a file. (See note under "Save obj list to file", below.)

Display an object list:

Object Log
Displays the object list named "ObjLog". (Previously all the object logging buttons stored data in this list. I've since changed most of the buttons so they will use whatever object list you specify.)

Click Log
Display the list "ClickLog." (The ClickLog list contains only NS and WE coordiates, not full object information.)

Show String List
Displays any string list you specify. (Not necessarily limited to object lists.)

Copy an object list:

Copy String List
Copies from one object list to another. Overwrites or appends at your choice.

Copy Selected from Obj list
Copies from one object list to another, only the items you specify. Use the @arg and $arg macros (see above) to specify fields of object list items, for purposes of comparison. For instance, if you wanted to copy only items containing model "walk028" you would enter @eq[$arg[5],"walk028"] for the copy conditions when prompted. (In the example, "5" is used because the model name is field 5 of the object list item.)

Change an object list:

Remove RWX extension from ObjLog items
The .rwx extension on model names is only necessary in worlds that use a registry. This button will remove the .rwx from all items in an object list and then change the actual object names in the world the bot is operating in.

Search & Replace from Obj List
This allows you to Search & Replace the model, description or action fields of all items in the object list, then change the corresponding objects in the world the bot is operating in.

Delete duplicate objects in obj list
Searchs the object list for duplicate entries and then deletes the actual duplicate object from the world the bot is operating in. Good for cleaning up if you accidentally build from propdump twice and have two of each object in the same location.

Save an object list:

Save obj list to file
Saves an object list to a file, in the quoted, comma-delimited object list format. This allows you to edit an object list as a text file, reload it into Magsbot with "Read obj list from file" and then use "Build from obj list" to rebuild the objects with the changes. (Previously there was a problem with editing an object list file using a text editor, but that problem has been resolved as of version 2.0 b1 (8/6/01). You can now use any text editor to edit an obj list file, and any object list file saved with previous versions of Magsbot should be readable.)

Save ObjLog as Propdump
Saves an object list to a file, in propdump format.

Read an object list:

Read obj list from file
Reads an object list that was saved using "Save obj list to file".

Read propdump into obj list
Reads an object list from a propdump file.

Delete an object list:

Clear obj list
Removes an object list (or any string list) from memory.

Delete entries from obj list
Allows you to select multiple object list entries for deletion from the list. (Does NOT delete the actual objects in the world.)

Delete from obj list
Deletes all the objects in the list. (Deletes the actual objects in the world the bot is operating in.)

Delete selected from obj list
Deletes selected objects in the list. (Deletes the actual objects in the world the bot is operating in.)

Build from an object list:

Build from obj list
Builds all of the objects in a list you specifiy, for instance the objlog list that was created by "Resolve Click Log".

Create selected from obj list
Builds the objects that you select from an object list.

Replace from Obj list
Changes the objects listed in the object list, using the information in list.

See "Survey set relative mode" in the Create an Object List section above.

Live logging

Log Live OFF
Log Live ON
Use these buttons to turn "Live Logging" on or off. When Live Logging is ON, then the bot will automatically update the ObjLog object list as building occurs in the bot's vicinity, adding new object information to ObjLog as objects are created and deleting object information as objects are destroyed. (Objects that are moved are actually being destroyed and recreated, so their information will be updated also.) Note: you must perform a survey (using the Log from Survey button, ideally) before turning Live Logging on, in order for it to work properly.

Other building functions

Build from Propdump
Builds all objects in a propdump file. Allows you to specify and offset for NS, WE and Alt, so that the objects can be rebuilt in a new location.

Load (build) from Propdump
The same as "Build from Propdump" except it creates the objects using the original owner ID and original timestamp, as opposed to the bot owner's ID and current time.

Log Objects by Click
When this is on, the object number and location of anything the chosen avatar clicks on will be stored in a list in memory. (The ClickLog list only contains object number, NS and WE location, not full information. You must use "Resolve from Clicklog" afterward to survey for the full information for the clicked objects.)

Log Objects by Click - Stop
Turns off "Log Objects by Click".

Resolve Click Log
Resolve Click Log - World
Scans the list of clicked objects and does a survey to find their model, description and action, and stores that information in a new list.

Dump Clicklog to file
Similar to "Resolve Click Log", except that the survey is saved to a propdump file instead of an object list in memory.

Survey for Object by Number
Survey the area and report the information only for one chosen object.

Make a Tree
Create a tree at the bot's location. (Look at the script in the button to see how to create an object programmatically.)

Instant Woods
Create 500 trees randomly around the bot's location! You probably want to be careful with this one. :) If you choose, the bot will log the trees into an object list so that they could be deleted again using the "Delete from Obj List" button.

Seed at Target Position
Creates an object at the location of a specified avatar. (Edit the button script to set the model used.)

Delete list object made
Deletes the object with the current AW_OBJECT_NUMBER at AW_OBJECT_Z, AW_OBJECT_X.