&MOVE

The DSA operation '&MOVE' can be used to transfer an object form one location in the game to another.  The syntax is:

    &MOVE ( <source>  <destination>  . . .  )

Where <source> and <destination> have the same syntax, namely:

<source> | <destination>  =  ( locationType  objMask  positionMask  location  depth )

Therefore, ten parameters must pbe placed on the stack before attampting an &MOVE operation; five for the source and five for the destination.  The use of each of the five parameters is summarized in the following table:

locationType	objMask	positionMask	location/object	depth
1 = dungeon cell	types of objects	NESW (-1 = use location)	location of cell	depth in list
2 = Cursor	N/A	N/A	N/A	N/A
3 = Monster possession	types of objects	N/A	Object ID of Monster	depth in list
4 = Character possession	N/A	character index	possession index	N/A
5 = Chest	types of objects	N/A	ObjectID of chest	depth in list

Some discussion of the various parameter types:

• objMask - This is the mask of the object types to be considered for the move operation.  Bit numbers are (5=weapon) (6=clothing) (7=scroll) (8=potion) (9=chest) (10=miscellaneous).  More than one bit may be set.
• positionMask - When used to designate a position within a dungeon cell then bit 0=north, bit1=east, bit2=south, and bit3=west.  If more thatn one bit is set when used as a cell destination then the position of the object will be selected at random from the possibilities allowed.  If source posMask is set to negative one then it means that the postion associated with the location parameter should be used.  More than one bit may be set.  If destination posMask has no bits set then the position associated with the location parameter is used. When used as a character index it specifes which character to use; zero is the leftmost character and three is the rightmost character in the character portrait area of the playing screen.
  
• location - this is generally the location within the dungeon where the object can be found.  It can be a character index, the ID of a container, or the level, x,  y, and position coordinates of a cell in the dungeon.
• depth - When an object resides in a list such as the list of monster possessions then the depth parameter specifies which of the objects in the list is to be referenced.  When searching the list, only objects of the type specified by objMask and objects in the correct positions as specified by the positionMask are considered.  It is as if the objects not meeting these criteria were non-existent.  For example if a list contained a key, a sword, a potion, and an apple and the objMask specified only miscellaneous objects then depth zero would pick the key and depth one would pick the apple.  In the destination parameters, depth must be specified as zero.
  

Some discussion of the operation:

dungeon cell	Location is an 18-bit integer; (bits0-4 = Y) (bits5-9 = X) (bits10-15 = level) (bits16-17 = positon).  You can specify the same location as both the source and destination.  If you do, the depth parameter of the destination is interpreted after the object is removed from the dungeon cell.
cursor	This is the very simplest case.  As a source it succeeds if the cursor is full and as a destination it succeeds if the cursor is empty.  You should not specify the cursor as both the source and the destination.
monster or chest	A chest can hold only eight objects and a monster can hold any number.  You should not specify the same chest and monster as both the source and destination.
character	The location parameter specifies the location on the character's body, in his quiver, backpack, etc.  You should not specify the same location on the same character as both the source and destination.  As a source it succeeds if the location is full and as a destination it succeeds if the location is empty and will accept the object being moved.  You cannot put a helmet on a character's feet.  Sorry.

If the &MOVE fails the Timer Trace will show the status:
enum ERRORCODES
{
  SER_OK                            = 0,
  SER_UnknownLocType                = 1,
  SER_NoObjInCursor                 = 2,
  SER_IllegalCharacterIndex         = 3,
  SER_IllegalCarryLocation          = 4,
  SER_NoObjectAtCarryLocation       = 5,
  SER_InvalidCellLocation           = 6,
  SER_NoSuchObjectInCell            = 7,
  SER_IllegalMonsterID              = 8,
  SER_MonsterIsNotMonster           = 9,
  SER_NoSuchObjectOnMonster         = 10,
  SER_IllegalChestID                = 11,
  SER_ChestIsNotChest               = 12,
  SER_NoSuchObjectInChest           = 13,
  SER_ChestBelongsToCharacter       = 14,
  DER_OK                            = 0,
  DER_UnknownLocType                = -1,
  DER_IllegalCharacterIndex         = -2,
  DER_IllegalPossessionIndex        = -3,
  DER_PossessionSlotNotEmpty        = -4,
  DER_IllegalObjectForCarryLocation = -5,
  DER_CursorNotEmpty                = -6,
  DER_InvalidCellLocation           = -7,
  DER_IllegalDepth                  = -8,
  DER_IllegalChestID                = -9,
  DER_ChestIsNotAChest              = -10,
  DER_ChestBelongsToCharacter       = -11,
  DER_ChestIsFull                   = -12,
  DER_IllegalMonsterID              = -13,
  DER_MonsterIsNotAMonster          = -14
};