Version 1.0
by Paul R. Stevens

A DSA (Designer Specified Actuator) is a new type of actuator available only in CSBwin. They use a state machine so you can accomplish anything you can imagine in the dungeon.

Contents

16-State Message Filter
Money Changer - A CSBuild DSA Example

General Description

This DSA is designed to accept inputs that affect its state. In very much the same way as the standard AND/OR actuator. But it acts as a message filter; that is it can relay (or forward) messages depending on its state. It can also be configured by changing its 'B' parameter. This is a schematic diagram of the filter:

When a message arrives, processing takes place in two sequential steps: First it is decided whether or not the message should be forwarded and then it is decided how the message will change the DSA's state. The details of these two steps:

A message arrives and can be a 'Set' , 'Clear', or 'Toggle'. And one of the four bits, 0, 1, 2, or 3, is specified.

Step 1: Decide whether or not to forward (repeat) the incoming message to the target specified by Parameter A. Two conditions must be met in order for the message to be forwarded:

1. A computation is performed using the current state of the DSA and the 'Target Value' specified by the designer. The result of this computation must be non-zero.
2. The appropriate bit must be set in the 'Transmit Mask'.

In the second of these conditions, the 'Transmit Mask' specifies which kinds of messages can be forwarded. Setting bit 0 allows messages which affect bit 0 to be forwarded, setting bit 1 allows messages that affect bit 1, and so on.

Step 2: Determine how the state of the DSA should be changed before waiting for the next message to arrive. A 'Toggle' message is converted into either a 'Set' message or a 'Clear' message so that there are only two cases to handle. The message specifies a bit to be set or cleared in the DSA's state. The designer specifies a 'Modification Mask' with four bits that specify whether each of the state's four bits can be modified. For example, if a 'Clear bit 2' message arrives then bit 2 of the 'Modification Mask' is examined. If it is set then bit 2 of the state is cleared. If bit 2 of the 'Modification Mask' is clear then the state remains unchanged.

Configuring the Filter

Parameter A is set to the location within the dungeon to which any forwarded message is to be sent. This is the 'Target' location just as for any other Actuator.

Parameter B contains the 'Modification Mask', the 'Transmit Mask', the 'Target Value', and the 'Operation Code' to be performed on the 'State' and the 'Target Value' to determine whether a message should be forwarded. Parameter B is a 16-bit value made up of four hexadeciamal digits: X1, X2, X3, and X4. X1 is the most significant. X1 contains the 'Operation Code'. X2 contains the 'Target Value'. X3 contains the 'Modification Mask'. X4 contains the 'Transmit Mask'. So the whole value looks like this:

<opcode> <value> <modification mask> <transmit mask>

with each value being expressed as a single hex digit. The opcode is encoded as an integer.

• 0 means that the value and the state must be equal in order for an incoming message to be forwarded.
• 1 means that the value and the state must be unequal.
• 2 means that the bitwise AND of the value and the state must be non-zero.
• 3 means that the bitwise AND of the value and the state must be zero.
• 4 through 15 are reserved for future needs, not yet discovered.

Example of Configuration

Suppose we set Parameter B to 0x2cc1 which is 11457 in decimal notation. The 'Operation Code' is 2 which means that a message will be forwarded if the bitwise AND of the value and the state is non-zero. The 'Value' is 'c', which is '1100' in binary. Ie: the top two bits are set. The 'Modification Mask' is also 'c' which means that the top two bits of the state can be changed by incoming messages. The 'Transmit Mask' is 1, or 0001 in binary, which means that only messages that target bit 0 (North) can be forwarded.

So messages that target bits 2 or 3 will modify the filter's state and, if either of bits 2 or 3 is set then any message targeting bit 0 will be forwarded to the target specified by Parameter A.

Further suppose that we have four pressure pads (A, B, C, and D) and a pushbutton (E). They send the following messages to the filter:

• A sends a Set Bit 3.
• B sends a Clear Bit 3.
• C sends a Set Bit 2.
• D sends a Clear Bit 2.
• E sends a Set Bit 0.

The result is that the message from the pushbutton will be forwarded if pressure pad A has been pressed more recently than pressure pad B or pressure pad C has been pressed more recently than pressure pad D. The pressure pads A and B might detect the direction of travel down a hallway, for example. This example could be accomplished with multiple standard Actuators but it would be more work and more complicated (IMHO). If you look at the diagram above you can see that this is a simple device, even if the description seems rather complicated.

A CSBuild DSA example is described here. It is a little bit complicated but it shows off a LOT of function.

The Money Changer is designed to provide a method of supplying an infinite number of objects and 'selling' them to the player in exchange for some other objects. Using it, you can create a 'Store', a 'Money Changer', or other device that you may dream up. You might exchange five silver coins for two gold coins.

It works kinda like this:

• A Cell in the dungeon that the player cannot reach contains a list of Objects that constitute the 'price'. We will call this the 'Price' Cell.
• Another Cell in the dungeon that the player cannot reach contains a list of Objects that constitute the 'merchandice'. We will call this the 'Merchandice' Cell.
• Another Cell, which the player CAN reach, contains the DSA and is the cell that will receive the 'price' and return the 'merchandice'. We will call this the 'Exchange' Cell.
• A Pushbutton or Pressure Pad triggers the Money Changer DSA.
• The DSA compares the objects in the 'Price' cell with the objects on the 'Exchange' Cell. If the Exchange Cell contains one of every such object then the exchange can continue because the 'price' has been met.
• The exchange is concluded by removing from the Exchange cell all the objects that constitute the price and replacing them with COPIES of each object in the Merchandice Cell.

The DSA is constructed from seven states:

• State 0 - The Money Changer
• State 4 - A Subroutine to drop N items from the stack
• State 5 - A Subroutine to make a list of objects in a Cell
• State 6 - A Subroutine to list the objects that constitute the 'price'
• State 7 - A Subroutine to remove an object of a particular type from a list
• State 8 - A Subroutine to remove a list of objects from a Cell
• State 9 - A Subroutine to add a list of items to a Cell