DSA - The Language
Notes:

- Every instruction listed in this table can be preceeded with an optional 'Next State'. Some of the examples show this.
- Square brackets ' [] ' delineate optional fields.
- Broken brackets ' < > ' indicate syntax elements.
- Locations are encoded as pos:2, level:6, x:5, y:5

N | Do nothing. Every Language has a NOP (No operation).
M[delay]<message type>[<target>] | Send a standard DM message.
&ADD | ( positionMask location objectID ... ) To place object in cursor use location = -1. To place object on character use location = -(100*characterOrdinal + packIndex). To place object on monster use location = -1000*monsterID. See detailed description.
&CELL@ | Fetch cell flags. See Cellflag Manipulation
&CHAR@ | (char# index n ... ) char# 0 to 3 ( or 4 to indicate the 'Lead Character' ) index = where to put result in array n = number of variables to fetch Fetch variables associated with a single party member.
See Character Fetch
&CHAR! | Exactly the same a &CHAR@ except that the values you provide are used to modify the character's attributes. Only a few of the values are actuallyu used but the format and order is the same so that you can do the &CHAR@, modify some of the variables, and then do the &CHAR!.
See the Character Fetch description to see which variable are implemented.
&CREATECLOUD | ( location type size . . . ) type FIREBALL = 0, DISPELL = 3, OPENDOOR = 4,
POISON = 7,
DEATH = 40,
FLUXCAGE = 50
&DELMON &INSMON | These words are used to delete a single monster within a group of monsters or to insert an additional montster into an existing group of monsters. You cannot delete the last monster from a group nor can you create a new group of monsters. &DELMON ( <location> index . . . )
&INSMON ( <location> position . . . )
<location> is the location of the monster group in the dungeon.
index is the index of the monster in the group. ( 0 to numberOfMonsters-1 )
position is a mask of positions that the new member can occupy. Use 15 to allow any position.
These words cannot be used in a filter. The words &%DELMON and &%INSMON are available to accomplish the task indirectly. See Indirect Actions
&GENERATORDELAY@ &GENERATOREDELAY! | ( location . . . value ) // value is the encode delay time. See below. ( value location . . . ) // value is the encode delay time. See below. Allows you to inspect the time that a Monster Generator is disabled after being triggered. It also allows you too see if a Monster Generator is positioned on a Cell of the dungeon by checking that the returned value is non-negative.
When a Monster Generator is triggered, it creates a monster and a Timer message and then disables itself. When the Timer message arrives, it turns the disabled Actuator back into a Monster Generator. So, during that time there is no Monster Generator present.
If you want a DSA at the same location as the Monster Generator to determine whether or not the generator is present then you must be sure that the DSA comes before the Monster Generator in the list of items in the Cell. Otherwise, the generator will have disabled itself ( and disappeared from view ) before the DSA has had a chance to perform its magic.
The value parameter is 8 bits in length and is encoded so as to allow for very long delays. Values of 1 through 127 are mapped to the delays of 1 through 127. The delay associated with values of 128 through 255 are determined by the function:
delay = 64 * ( value - 126 )
So that the maximum delay is 64 * (255 - 126) = 8256 = about 23 minutes.
A value of -1 is returned by &GENERATORDELAY@ if no Monster Generator is present.
If &GENERATORDELAY! is directed to a location that contains no generator then we search for an Actuator that has been disabled and, if one is found, we assume that it is a disabled Monster Generator and set its delay value. If no Monster Generator is found and not disabled Actuator is found then the function is ignored.
&GETCHARGES &SETCHARGES | ( objectID . . . charges ) ( objectID charges . .. ) Examine / set the remaining Charges in an object of type Weapon or Clothing. Get/Set the Strength of a Potion. Get/Set the Value of a Miscellaneous object.
&%INDIRECT | See Indirect Actions
&MESSAGE | (location type num delay . . .) Sends a standard message except that 32-bit parameters are included with the message. location = location in the dungeon to which the message will be sent. This MUST be a WALL cell. type is 0=set, 1=clear, 2=toggle. Same as any other message.
num is number of parameters to pass along with the message. Maximum is 29.
delay is time delay before message is delivered. Same as any other message.
Before sending a message like this you must use the &PARAM! word to set up the parameters that you wish to pass along. When the message is received the parameters can be fetched with &PARAM@.
&MONSTER@ &MONSTER ! | Get/Set information about a group of monsters. (ID index num ... ) 'ID' is the identification number of the monster group. 'index' is the address within the array where the information should be placed. 'num' is the number of words of infomation that should be retrieved.
The resulting words in the array are:

- [index + 0] Number of monsters in the group
- [index + 1] Monster type
- [index + 2] Hit points 1st in group
- [index + 3] Hit points 2nd in group
- [index + 4] Hit points 3rd in group
- [index + 5] Hit points 4th in group
- [index + 6] flags; 01=invisible; 02=drawAsSize4; 04=Unique; 08=Poisoned
- [index + 7] Alternate Graphic number

NOTE CAREFULLY!!!! The flags only work if you have 'Enabled Extended Monster Flags'
in the 'Edit/Global' dialog.
&MONSTER! cannot change the number of monsters or the monster type.
Only the HitPoints and flags will be modified.
&MONL&D | **********Used only from within a "MonsterMoving Filter" ************ Gets the moster's location and distance to the party and puts the two numbers in the Temporary Variable Array. ( index . . . ) ; Where index is the the location of two entries.
The first variable is set to the monster's location - 1024*level + 32*x + y.
The second variable is set to the distance from the party. This is defined as the x-distance plus the y-distance minus 1.
&MOVE | Moves an object from one place in the game to another. See &MOVE operation
&NEIGHBORS &THISCELL | Determine type and contents of cell's neighbors. See &NEIGHBORS &THISCELL works exactly as &NEIGHBORS except that only the single named cell is examined and only bit 0 of the result is used.
&PARTY@ | (index n ...) ; index in array; number of variables to fetch. Fetch variables associated with the party. Number of members. Group shield. Etc. See Party Fetch
&SOUND | ( soundNumber attenuation flags . . . ) Plays a custom sound for CSBgraphics.dat. The sound is a standard wave file in 8-bit mono at 11025 samples per second. soundNumber is the graphic number of the file in CSBgraphics.dat. The 'attenuation' is a divisor. Set it to 1 for full volume. Setting it to 100 makes it almost inaudible.
flags are not used and should be zero for forward compatibility.
To play the internal sounds of the game ( teleporter, etc ) you can specify the negative of the internal sound number. See Internal Sounds.
In this case, volume is 0 for low volume and 1 for high volume. This is normally used to make the sounds quieter when the source of the sound is far from the party. The global sound volume setting is always applied.
&THROW | Throw a missile, either an object or a spell. (type objectLocation launchLocation direction range damage delta ... ) If 'type' is zero then an object is fetched from 'objectLocation'. Other values of type are:

- -128 Fireball
- -127 Poison
- -126 Lightning
- -125 Dispell
- -124 Zo Spell
- -122 Poison Bolt
- -121 Poison Cloud
- -88 Monster Death (whatever that is!)

'objectLocation' includes a cell location and position
'launchLocation' includes a cell location and position
'direction' 0=N; 1=E; 2=S; 3=W
'range' is how far the missile will travel before falling
'damage' is the amount of damage done by the missile
'delta' is what is subtracted from range and damage each step.