Magsbot Help

Special Objects

Some special types of objects are now available in AW version 4.1. They are: Zone objects*, Particle Emitters, Movers and Cameras. When creating these objects with Magsbot using the @objectaddv, @objectloadv, @objectchangev, @objectidaddv, @objectidloadv or @objectidchangev functions, the properties that you want to give the object are stored in a vlist that is passed to the function. (You can also create special objects using @objectadd, @objectload, @objectidadd, @objectidload, specifying the special properties in a hae string or object data block. Using a vlist however gives you the ability to set or change the object properties in your Magsbot script.)

Below is a list of properties available for each object type.

Besides the other properties, each object has a @flags property that defines certain characteristics. A flag usually refers to a variable that is either 0 or 1, true or false. Multiple flags can be combined into a single variable if each bit of the variable is used to represent one of the flags. For example, a 16-bit number could hold 16 possible flags, with each bit of the number representing a flag. Normally you would set a flag using the "or" operator and a bitwise mask, for example to set bit 7, you would do @flag=@flag|2^7, etc., but to simplify this process, Magsbot provides some macros that take flag names as input and return the value to use for the @flags variable.

For example, if you were creating a mover, you could put:

@flags=@moverflags["CLICK_START,CLICK_PAUSE,LOCK_POSITION,LOCK_YAW,LOCK_PITCH,SINGLE_RIDER"];

...to deterimine the @flags value to use if you wanted to set those flags on the mover you were creating.

The macros to use for converting a list of flag names into a number are

@moverflags[$flaglist]
@zoneobjflags[$flaglist]
@particleflags[$flaglist]
@cameraflags[$flaglist]

and to convert a flag value into a list of flag names:

$moverflags[@flags]
$zoneobjflags[@flags]
$particleflags[@flags]
$cameraflags[@flags]

(The above macros call corresponding buttons on the root . tab of the Actions panel.)

New in Magsbot 7.3:
You can create special objects more quickly by using an object data memory block instead of a hex string. The optional $objdata (hex string) argument used with the basic object creation functions @objectadd, @objectload, @objectchange, @objectidadd, @objectidload, @objectidchange can now be @objdata (memory pointer) instead. To obtain an pointer to an object data memory block, use the @copydata function or the @objdatafromvlist function. Those two functions return object data in the same form as @atr[object_data] within a CELLOBJECT event. Remember to use FREEOBJDATA to free a memory block created using @copydata or @objdatafromvlist once you no longer need the data, but do NOT use FREEOBJDATA on @atr[object_data], which is freed automatically after the CELLOBJECT event is done.

Macro functions @objectaddp, @objectloadp, @objectchangep, @objectidaddp, @objectidloadp, @objectidchangep have also been added. (The "p" is for "pointer".) Use those functions the same way @objectaddv etc., except substitute an @objdata block in place of a vlist. For example, create a vlist containing the object properties as shown below, but instead of calling @objectaddv using the vlist, you would call @objectaddp using a memory block created with @objdatafromvlist.

* To avoid confusing the new zone objects with the zones that can be defined in Magsbot using the various ZONE commands, I will always refer to the AW 4.1 zones as Zone Objects.

EXAMPLE: Creating a particle emitter.

Here's an example of creating a particle emitter at the bot's location. Note that you don't need to include properties that you want to set to 0 (or blank for a string property).

@v=@vlist;

STORE_ @v speed_min_z=-0.5;
STORE_ @v speed_min_x=-0.5;
STORE_ @v speed_min_y=2;
STORE_ @v speed_max_z=0.5;
STORE_ @v speed_max_x=0.5;
STORE_ @v speed_max_y=5;
STORE_ @v size_min_z=1;
STORE_ @v size_max_z=2;
STORE_ @v size_min_x=1;
STORE_ @v size_max_x=2;
STORE_ @v size_min_y=1;
STORE_ @v size_max_y=2;
STORE_ @v release_min=10;
STORE_ @v release_max=100;
STORE_ @v release_size=4;
STORE_ @v lifespan=2000;

REM the colors of this PE run from hot pink (FF0080)
    to blue (0080CD), but note that the usual byte order
    of colors must be reversed when used as an object property!
    that is, color ABCDEF becomes EFCDAB (the first two
    digits and the last two digits are swapped).
    (i have no idea why it was done this way in the SDK!)
    so in this case ff0080 must be given as 8000ff and
           0080cd must be given as cd8000;
STORE_ @v color_start=@dec["8000ff"];
STORE_ @v color_end=@dec["cd8000"];

STORE_ @v opacity=0.5;

rem render style is 0=normal, 1=bright, 2=glow;
STORE_ @v render_style=2;

REM actually this PE looks better with flags=0, but
        i wanted to show an example of using the @particleflags macro;
STORE_ @v flags=@particleflags["INTERPOLATE|GRAVITY"];

STORE @v asset_list="c_soft1";

REM note that there is no model, description or action for a PE,
         so those arguments are left blank.
        also note that you use @objectaddv not @objectadd;
@new_obj=@objectaddv[@ns,@we,@alt,@yaw,0,0,"","","",3,@v];

REM If you plan to create the same special object many times (but in different places), you could save the vlist and just call @objectaddv each time (i.e. you don't have to recreate the vlist each time). Even better, you could covert the vlist to a hex string ($objdata=$objdatafromvlist[@v]) and then call @objectadd[...,$objdata] each time you want to create the object.

REM In Magsbot 7.3, you can improve on this even more by using a pointer to object data instead of a hex string, which is faster. In that case, you could fill the vlist, then convert the vlist to object data using @objdata=@objdatafromvlist[@v], then create the object each time using @objectadd[...,@objdata] or @objectaddp[...,@objdata] .

REPORT $fmt["new object number=%s",@new_obj];

REM be sure to free the vlist after using it, if you aren't going to be using it again;
FREEVLIST @v

REM If using @objdata, be sure to free it after using it, if you aren't going to be using it again;
FREEOBJDATA @objdata;

Zone objects

@flags

WATER
BLOCK_PARTICLES
BLOCK_LIGHTS
BLOCK_WORLD_LIGHT
BLOCK_CHAT
VISIBLE

@size_z
@size_x
@size_y
@shape
@priority
@gravity
@friction
@color
@fog_min
@fog_max
$footstep
$ambient
$camera

Particle emitters

@flags

INTERPOLATE
GRAVITY
COLLIDE_ZONES
ZONE_EXCLUSIVE
CAMERA_EMIT
MOVER_LINK

@size_min_z
@size_min_x
@size_min_y
@size_max_z
@size_max_x
@size_max_y
@volume_min_z
@volume_min_x
@volume_min_y
@volume_max_z
@volume_max_x
@volume_max_y
@speed_min_z
@speed_min_x
@speed_min_y
@speed_max_z
@speed_max_x
@speed_max_y
@accel_min_z
@accel_min_x
@accel_min_y
@accel_max_z
@accel_max_x
@accel_max_y
@angle_min_z
@angle_min_x
@angle_min_y
@angle_max_z
@angle_max_x
@angle_max_y
@release_min
@release_max
@release_size
@lifespan
@emitter_lifespan
@fade_in
@fade_out
@color_start
@color_end
@opacity

@render_style

0=NORMAL 1=BRIGHT 2=GLOW

$name
$asset_list

Movers
(Note: currently, mover creation isn't working quite right. The mover is created, but the properties are messed up. I believe this is a problem in the SDK.)

@flags

LOOP
USE_OBJTAG
BUMP_ADD
CLICK_START
CLICK_PAUSE
LOCK_POSITION
LOCK_YAW
LOCK_PITCH
SINGLE_RIDER
NO_AUTO_YAW
EMPTY_RESET
DISABLE_FLYING
KEEP_ON_WATER
DISABLE_UPWARDS
INVISIBLE_AV
EXIT_EJECT_UP
EXIT_NON_SOLID
AV_APPLY_TILT_X
AV_APPLY_TILT_Z
OBJECT_LINK
DISABLE_MOVE
TILT_BY_TERRAIN
DISABLE_EXPL_SEQS
DISABLE_TURN_ON_PLACE
DISABLE_TELEPORTS
DETACH_ON_TELEPORT

@otype

0=PASSIVE 1=ACTIVE

@locked_pos_z
@locked_pos_x
@locked_pos_y
@locked_pos_yaw
@locked_pos_pitch
@glide_factor
@speed_factor
@friction_factor
@accel_tilt_z
@accel_tilt_x
@turn_factor

$waypoint1, $waypoint2 ...

note: each waypoint is a comma-delimted string, containing "X,Y,Z,yaw,pitch,roll,speed(ms),pause(sec),flag",
e.g. "100,34,1800,0,0,10,.5,0"

$name
$seq
$script
$sound
$bump_name

Cameras

@flags

TRACK_USER

@zoom

$name