Magsbot Help

History and overview of build functions

In Magsbot version 7.0, the @objectadd, -change and -load functions have been changed. The original functions (pre version 3) didn't have the tilt and roll arguments; when AW version 3 with 3-axis rotation arrived, I added new versions of each of the object functions, that would take the new tilt and roll arguments. The version 3 function names were the same but with an underscore added, i.e. @objectadd was the pre-version 3 function and @objectadd_ was the version 3 function.

In Version 7 of Magsbot, I wanted to simplify things by consolidating these two sets of functions into one. The underscore-name functions have been removed, and the original functions updated to support tilt and roll, as well as additional optional arguments necessary to manipulate special objects available in AW version 4. In the interest of backward compatibility however, the underscore-name functions still exist as macros in the userdefs.udf file. Also, if you have any scripts that use the very old original versions of the functions without tilt and roll, (and if you don't want to bother updating to the new usage) you can simply replace the old functions with the macros @objectadd_old, @objectload_old or @objectchange_old.

In AW version 4, several new kinds of objects have become available: Zone objects, Particle Emitters, Movers and Cameras. These objects have many properties associated with them that are not defined as AW attributes. Instead, the special objects' properties are stored in several kinds of data structure that an SDK programmer must use when creating these object types with a bot. To simplify things for Magsbot programming, the special object properties can be stored in a vlist, and the vlist passed to the object building functions. Or, a string of hexidecimal characters representing the data can be sent. (This string is the same format that appears for special objects in propdump files.) The hexidecimal string can be obtained either during a survey (CELLOBJECT event) from the $objdatastr function, or by converting a vlist to a string using the $objdatafromvlist function. The new @objectaddv, @objectloadv and @objectchangev macros are used when you want to pass a vlist; the actual functions @objectadd, @objectload and @objectchange take the object properties data in the form of a hexidecimal string or an object data block (see below). See here for more information and examples of creating the new objects.

In Magsbot 7.3, the optional final argument to the @objectadd etc. function can now be either an object hex string or an object data memory block. The memory block can be created using @copydata, @objdatafromvlist or @datafromstr. Also @objectaddp macros were added that take the object data memory block pointer only.

@objectchange[@old_obj_num,@old_ns,@old_we,@owner,@ns,@we,@alt,@yaw,@tilt,@roll,$model,$desc,$action,@objtype,$datastr]
@objectchange[@old_obj_num,@old_ns,@old_we,@owner,@ns,@we,@alt,@yaw,@tilt,@roll,$model,$desc,$action,@objtype,@objdata]
@objectchangev[@old_obj_num,@old_ns,@old_we,@owner,@ns,@we,@alt,@yaw,@tilt,@roll,$model,$desc,$action,@objtype,@vproperties]
@objectchangep[@old_obj_num,@old_ns,@old_we,@owner,@ns,@we,@alt,@yaw,@tilt,@roll,$model,$desc,$action,@objtype,@objdata]
Changes an existing object and returns the new object number. Requires the current object number of the object (first argument), the current NS and WE coordinates (second and third arguments), and the object owner's citizen number (forth argument). The specified owner must be the same as the current object's owner, or someone with eminent domain in the world containing the object.