CSBwin/DSA/Lesson 5

DSA Lesson 5 - An ~InterLevel/Long Delay Relay

The standard Actuators are not capable of sending messages between levels of the dungeon. This causes us to transport Rocks and Screamer Slices in order to push a button on level 3 which activates a teleporter on level 3 which transports a Rock to a ~PressurePad on level 4 which causes a Pit on level 4 to open. Ugly! The standard Actuators also allow for only short delays, commonly about 2-1/2 seconds. Constraining! A simple, standard DSA can be used to work around these restrictions. We will build one right here before your eyes. If you can bring yourself to understand HOW it works then you will have mastered all the basics of the DSA and will be ready to begin to learn the hundreds of details that can make a DSA do something a lot more interesting.

---

Here is a sample dungeon with the relay in action

There are a lot of steps involved to get this DSA installed and working in a real dungeon.

Step 1 - Write the code for the DSA

Initiatiate the editor by clicking on the DSA control on the toolbar.

The "Select DSA" dialog will appear. Click on one of the unused DSA numbers and click on "Edit Selected DSA". If you are looking at the sample dungeon, then select the DSA numbered 000 with the description Inter-Level, Long-Delay Relay A=Target B=delay" and click on "Edit Selected DSA". Here is the contents of our example :

What is supposed to do? We want a DSA that will relay ( or repeat ) whatever message is sent to it. We want that message to be sent to an arbitrary place on any level of the dungeon with an arbitrary delay. Our solution to this problem is a DSA that uses its parameters to specify the target and the delay. In particular, parameter A will specify the target and parameter B will specify the delay.

The DSA can receive 12 different messages:

• Set North -or- Set 0 -or- S0
• Clear North -or- Clear 0 -or- C0
• ....
• Clear West -or- Clear 3 -or- C3
• Toggle West -or- Toggle 3 -or- T3

If a message of type "Toggle East" is received, for example, then the words on the line labeled "T1" will be executed. On that line you will find the words "OP1 MYT". Ignore the "OP1" for a moment and concentrate on the "MYT". The first letter designates the action to be performed. A quick look at the 'Help' will reveal the following:

standard Message
[<next state>]M[<delay>]<message type>[<target>]

A standard message begins with an optional <next state>. The help defines <next state> as:

<next state>    default is current state
integer

Well, "MYT" clearly does not begin with an integer so this part of the word must have been omitted. The next part is the "M" which designates this as a word that sends a standard message. That is what we wanted to do, this seems reasonable. The next part of the word is the optional <delay>. The help defines <delay> as:

<delay>    default is 0
<integer>
X means use first actuator parameter
Y means use second actuator parameter

What we see in the word is a 'Y' and therefore the delay of the message will be whatever we set the second parameter, parameter B, when we create an instance of this DSA in the dungeon. Next in the definition of a standard message word is the required <message type>. In our example, we see a 'T'. This is reasonable, too. We received a 'T1' message (toggle) and so we want to send a 'T' message. Lastly in the definition is the optional <target>. <target is defined in the help as:

<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>

There is no target specified in our example so the default will be used. The default is the first parameter, parameter A. And there you have it. Every line in the DSA sends a message of the same type as it received, with the delay specified by parameter B and the target specified by parameter A.

But we have a problem. Parameter A specifies a cell in the dungeon by its level, X coordinate, and Y coordinate. Parameter A also specifies the position within that cell (0, 1, 2, 3 or North, East, South, West). But the messages we receive do not all have the same position. We need to override the position specified by parameter A, depending on the position specified in the message we received. That is the purpose of the 'OP' word that preceeds each 'Standard Message' word. The help defines this as:

Override
[<next state>]O<what>[<integer>]
<what>  P  override position on next command

On our case we specified the <what> portion of the word as 'P' (Actually the only option right now) which means to override the position specified in the next word encountered. The next word is the 'Standard Message' word, so the 'OP1' will cause that message to have a position of 1, which is the same as the position in the message we received. As you see, each line of the DSA overrides the position with the same position as the message received so that the message we send will be an exact duplicate of the message we received except for the target and the delay.

Step 2 - List the DSA for use on a level

Each level of the dungeon has a list of up to 32 DSAs that can be used on that level. This is similar to the list of Wall Decorations that can be used on a level. From the Map Editor you select menu "Edit / Level Info". Select the level in the upper left of the "Edit Level Information" dialog and click on the "Edit DSA List" button. The 32 DSAs that are allowed on that level are listed. Select one of the empty selections and click on the "Replace Selected DSA button". The "Select DSA" dialog will appear with a list of the 256 possible DSAs. Select the one you want to make available on the level (in this case the "Inter-Level Long-Delay") and press the OK button. You will return to the "Edit DSA List for Level" dialog and you will see that the DSA has been added to the list of allowed DSAs for the level. Press "Exit".

Step 3 - Plant an instance of our DSA in the dungeon.

Putting a DSA in the dungeon on any particular level is exactly analogous to putting any other Actuator in the dungeon. You right-click on a cell and click "New" for one of the allowed positions within that cell. You select the "Actuator" radio button and choose "Designer-Specified Actuator" (DSA) from the drop-down list of possible Actuator types and press "OK". The "Edit DSA Actuator" dialog will appear.

The "DSA Type" field will contain the name of the first DSA type allowed on the level. You can press "Select New DSA Type" if you would like to put a different kind of DSA in the cell.

Parameter A is going to be the target of our "Message Repeater" and so it is best to select "Target" rather than "Integer" for parameter A. This actually makes no difference except to help you as you edit the dungeon. Then we press "Browse" for Parameter A and locate the cell to which our messages will be sent. Exactly like any other Actuator except that now we can send the message to any level of the dungeon. We can also choose a 'Position' to which the messages will be sent but, as we learned in Step 1 of this lesson, the position specified by Parameter A will be overridden when the DSA is executed.

Parameter B is going to be the delay. Again, it will be helpful to you to properly designate Parameter B as an 'Integer' so that the editor will not try to interpret it as a target and so that you will not have to enter the delay as if it were a target. Enter the delay in the "value" box.

The 'State' box contains the initial state of the DSA. Make sure it is zero for our example (When we wrote the DSA, we put all the instructions in state 0).

Press OK. Press OK. And you are back to the map editor with a new DSA in your dungeon. Any messages you send to that DSA will be forwarded (repeated - relayed) to a different place in the dungeon with a different delay.

This concludes Lesson 005. If you downloaded the example, you can run it, fetch and eat the apple, and see our DSA in action.

FAQ

Q - The "DSA Type" field will contain the name of the first DSA type allowed* on the level

A It is probably worth mentioning again that you have to add DSA's to the level.

Otherwise you cannot select any to place in the dungeon

Q - What do you mean when you say that "The messages we receive do not all have the same position"?

A DSA receives all messages targeted to a dungeon cell regardless of the DSA's position within the cell or the 'position' indicated by the message. We can receive twelve different messages. For example, we could receive a (Toggle,East) message or we could receive a (Toggle,South) message or ten other messages. 'East' and 'South' are different positions. (Toggle,East) and (Toggle,South) are examples of two messages that we can receive that do not have the same position.

Q - What happens with (Toggle, East) and (Toggle, South) when it reaches the DSA in our example without the OP?

A - It sends the position of Parameter A (e.g. North.) because you did not 'override' that position with the 'OP' word.

Q - But where would the Toggle, Clear, Set come from? There is no info in Parameter A. it would either lack the Toggle or the south. There is only one North and no Set, Clear or Toggle anywhere to be found. Is that part missing or does it come from the original signal from the actuator?

A - The message sent to the DSA has a position. The position is 0, 1, 2, or 3. (or North, East, South, West). The position in that message to the DSA determines which line of code is executed in the DSA. For example, a (Clear, West) message will cause the line labeled C3 to be executed. That line of code creates a duplicate message by specifying a message type of 'Clear' (the letter 'C' in 'MYC') and by specifying a position of 'West' (the digit '3' in the 'OP3' word). So the message that is sent is a (Clear, West) message, exactly like the message received.

Q - It does not matter for a pit to receive a (Toggle, East) or a (Toggle, South) message. So why worry about it?

A - We could make a simpler DSA if we KNEW that the target did not care about the position. But some targets DO care. Then we would have to write two DSAs....one for targets that care and one for targets that don't care. I think it is easier to write one DSA rather than two. But you are right. The sample dungeon would have worked with a simpler DSA. An example where the position is important will come in a future lesson.

There is currently no info here on the wiki to see what results the different messages would have on a door or a pit? I know there is some on dianne and paul net In the future we should add basic things, how doors react to messages to the wiki as well, a short reference page, probably to print or so...(Adamo, do you read this?) Thanks for the patience so far

Q - two things that were new to me- "when we create an instance of this DSA in the dungeon". In the above download example are 2 different cells with the same DSA.(instances) This I did not expect. I was convinced we have merely "one" DSA for a task, not that we add it just like apples to the dungeon. but it makes sense. ====

A - A DSA is an Actuator just as Counter is an Actuator. A Counter is an Actuator that counts. Certainly, you might expect a dungeon to have more than one Counter. But a Counter can only count to 15. You could make a DSA that counts very big numbers. It is certainly possible that, like counters, you might want to do this in more than one place in the dungeon.

Q - this is the second point- We create an instance of the DSA at the cell that contains e.g. the pushbutton. But not necessarily - I guess to keep things tidy - it is in the same cell. We only need one instance at each level? Could be that the messages get mixed up in the queue, so not sure if it would be good practice to have as many instances of this DSA as there are interlevel messages..

A - Our sample DSA forwards messages to the place specified by Parameter A. Let us assume that an instance of the DSA has Parameter A pointing to a door on another level. Any messages sent to that instance of the DSA will be sent to that same door. If you want to send a message to a different door, perhaps on a different level, then you will need a different Parameter A. That means you will need another instance of the DSA.