CSBwin/DSA/Lesson 4
A DSA Can Speak -or- Sending Messages from a DSA
- One of the most important 'Words' that you must conquer in the DSA language is the 'Standard Message' word. Here is the entry describing it from the DSA Editor Help
standard Message
[<next state>]M[<delay>]<message type>[<target>]
This word consists of several parts, to be discussed later. Some of the parts are enclosed in broken brackets. For example, 'delay' is enclosed in broken brackets. Like this: "<delay>". This means that you are going to have to interpret the word 'delay' and write something appropriate in its place. You are NOT going to write "delay" but, in this case, a number. Some of the parts are enclosed in square brackets. For example, <delay> is enclosed in square brackets. The square brackets indicate that this part of the word is optional. You do not write the square brackets. They are there to indicate optional parameters. All optional parameters have (reasonable?) default values.
Parts and parameters of the Message Word.
Where do we start? Let us start with the 'M'. That's easy. It is not in broken brackets so you must write 'M'. It is not in square brackets so it is not optional. It is the word's name and identifies this word as a 'Standard Message' word. It means that we are going to prepare a message and send it off to some part of the dungeon.
[<delay>]
- If you look at the DSA Editor Help very closely you will see that "<delay>" is defined up near the top of the help text. Here is what it says:
<delay> default is 0 <integer> X means use first actuator parameter Y means use second actuator parameter
This part of the word specifies how long it will take for the message to be delivered. The units of time are about one-sixth second. You can write very large numbers if you wish. The default value is zero, in which case the message will be delivered before the game clock is again incremented. But the Help file says that <delay> can also be replaced with the letter 'X' or 'Y', in which case an actuator parameter is used to specify the delay. In our next lesson we will use this feature.
[<message type>]
- Again, look at the Help file to see how <message type> is defined. Here is what it says:
<message type> default is S N means do nothing S Set C Clear T Toggle
You will recognize this from our previous lesson as the 'Action' to be taken by the message's recipient. The Default is 'Set' and there is an additional possiblity of 'N' which means to do nothing! I don't know why I did that. At any rate, if you send a 'S' (or Set) message to a door, it will open. And so on and so forth.
~
[<target>]
- One more time -- look at the help file to discover the syntax of this parameter. It says:
<target> default is A A means use first actuator parameter B means use second actuator parameter * means use <location> from stack pos:2; level:6; x:5; y:5 <absolute location>
This is difficult stuff. The easy cases are the 'A' and 'B' cases. When you put a DSA into the dungeon, you can define two parameters. Here is an example of the dialog that 'plants' a DSA : 
You see the two boxes labeled "Parameter A" and "Parameter B". Both these parameters are simply 18-bit numbers. Nothing more and nothing less. The first is set to 'Integer' and the second to 'Target'. Those labels (Integer and Target) are ignored at runtime. They only affect how you enter the number and how the editor displays the DSA in the 'Map View' of the editor. If the parameter is a 'Target', then the editor can display the target arrows on the map, otherwise it ignores the parameter when drawing the map. This gets rid of a lot of arrows pointing to 0(0,0), for example.
In the example, I have set the target of parameter B to level 3, column 12, row 5, position south. Parmeter A is set to precisely the same number but it is displayed as an integer. TIP ALERT You can use this dialog box as an easy way to convert integers to/from dungeon locations. Enter a 'Target', click the 'Integer' button, and read the integer that results. And vise versa. For the curious among you, the format of the integer is given in the help file entry (see above) as "pos:2; level:6; x:5; y:5", which means that the 18 bits are allocated from most to least significant as 2 bits for position, 6 bits for level, etc. In a binary number it would look like 'PPLLLLLLXXXXXYYYYY". Another way of doing the conversion (if you prefer decimal numbers) is to evaluate the expression:
65536 ''' P + 1024 ''' L + 32 * Y + X
So now that we have defined Parameter B as a target, we can use that Parameter to send a message like this:
MSB
We have omitted several, optional, parts of the word. When it is executed, it will send a 'Set' message (the 'S') to level 3, column 12, row 5, position 2 (the 'B'). If there is a door at that location, the door will open. If there is an AND/OR actuator at that location, bit 2 will be set. So that ends the lesson of sending messages using the DSA's parameters as target designators.
A second way of designating a target for a message is to specify an absolute location within the word itself. Again, the help file is valuable because it defines the syntax of <absolute location>:
<absolute location> default is current cell <level>(column,row)~[[<position>]] default position is 0
For example, whe could have sent the message to the target designated by Parameter B like this:
MS3(12,5)S
Notice that the <position> is defined (See the Help again!) as a character 'N', 'E', 'S', or 'W', indicating 0, 1, 2, or 3 or the positions North, East, South, or West. The interpretaton of this is dependent on the recipient of the message. WARNING Designating a Target using this <absolute location> syntax buries the target information in the code of the DSA in a way that the Map Editor cannot see it. So you will get no help at the Map Editor level when you want to see what cells in the dungeon target a Pit, for example. It is MUCH better practice to use parameters to designate targets.
The last (and potentially very valuable for experts) way of designating a target is by placing an absolute location on the Stack and specifying the target as '*':
MS*
The number on the stack is computed as in the Parameter B description above. Again, the Map Editor will not be aware of this target designation. If you do this, it is probably helpful to do your computation of target location starting with one of the parameters. Something like "n cells south of Parameter A". But these are rather advanced techniques and if you understand all of this you can consider yourself an expert.
There is another Word that can be used to override the 'Position' to which a message is sent. This allows you easily use one of the parameters (A or B) but change the position associated with that parameter. You could do the same thing by putting the Target Parameter on the Stack and then manipulating it with arithmetic, but the Override Word makes it much easier. Our first example of a real DSA in the next lesson will use this Override Word to good advantage.
