DSA Reference

Under construction. Last Update: 2010/11/01 22:33 +0900

TOC

Syntax (quasi BNF)

Check http://en.wikipedia.org/wiki/Backus-Naur_form for BNF meaning.

These syntaxes are used by Operations syntax and Stack Operation sections.

Operations syntax

No operation ("N")

syntax: [<next state>] "N"

standard Message ("M")

syntax: [<next state>] "M" [<delay>] <message type> [<target>]

for example, "1MSB" means, send message "Set" to location identified by parameter B of DSA actuator, and run program at state 1 in next DSA call.
summary: next state=1, delay=0, message type=S, target=B.

Copy Teleporter ("CT")

syntax: [<next state>] "CT" <from> <to>

Override ("O")

syntax: [<next state>] "O" <what> [<integer>]

<what> = P override position on next command

Gosub ("G")

syntax: [<next state>] "G" [<state>] [<column>]

Jump ("J")

syntax: [<next state>] "J" [<state>] [<column>]

Literal to Stack ("L", "L$")

syntax: [<next state>] "L" <value>
syntax: [<next state>] "L$"    ; <location> of current master cell

Store Value from Stack ("S")

syntax: [<next state>] "S" <where>

Fetch Object ID ("F")

syntax: "F"

Discussion:
If <position mask> == -1 then use position of <absolute location>. <depth> applies only to objects of the proper type at the given positions. Other objects are totally ignored-----

IfElse ("?")

"?" [( "J" | "G" ) [<column>]] [":" ("J" | "G")[<column>]]

Case

"??" "{" <case><case><case>........ "}" (n ... )

The top entry in stack is removed and compared with each case value. Control is transferred to the appropriate place if there is a match. Else control continues to next command.

for example, "??{(4,4S0)} J1": pop a value from stack, go 4S0 (column S0 at state 4) if value is "4", otherwise run "J1".

Stack Operation

LEGEND

Opcode: &+
Input : input1 input2
Output: output1

commutative operator: yes

operator &+ pops 2 values from stack and associate with input2 and input1 in order.

then, pushes output1, as a result, to stack.

next figure shows the interpretation of the code "L1 L2 &+" and returned value "3".

next figure shows how stack machine works, and logical consideration of above example DSA code "L1 L2 &+".

unary operator takes one operand. for example, "unary operator -" should be used as "-123" (such as "L123 &NEG").
binary operator takes two operands. for example, "binary operator +" should be used as "123 + 456" (such as "L456 L123 &+").

commutative for binary operators means whether you can replace 1st operand and 2nd operand to get equivalently result or not.

for example, binary operator + is commutative. both "L1 L2 &+" and "L2 L1 &+" return "3", and works equivalently.

for example, binary operator / is non-commutative. "L1 L2 &/" returns "0", and "L2 L1 &/" returns "2". they don't work equivalently.

&DROP (operator drop)

Opcode: &DROP
Input : x
Output:

erase one value from the stack

&2DROP (operator 2drop)

Opcode: &2DROP
Input : x y
Output:

erase two values from the stack

&PICK (operator pick)

Opcode: &PICK
Input : x
Output: y

Copy Nth item to top

for example: "L10 L20 L1 &PICK" returns "10"

&2PICK (operator 2pick)

Opcode: &2PICK
Input : x
Output: y

same as L2 &PICK

for example: "L10 L20 L30 &PICK" returns "10"

&POKE (operator poke)

Opcode: &POKE
Input : x y
Output:

Store at Nth item

example code "L0 L20 L10 L1 &POKE" will replace 1st value with "10" (see following figure).

&ROLL (operator roll)

Opcode: &ROLL
Input : x
Output:

Move Nth Item to top

&-ROLL (operator -roll)

Opcode: &-ROLL
Input : x
Output:

Reverse of ROLL

&ROT (operator rot)

Opcode: &ROT
Input : x y z
Output: y z x

same as L2 &ROLL

&-ROT (operator -rot)

Opcode: &-ROT
Input : x y z
Output: z x y

same as L2 &-ROLL

&! (operator !)

Opcode: &!
Input : v i
Output:

Compatibility: CSBwin98v44 or later

Store v at temporary variable[i]

&@ (operator @)

Opcode: &@
Input : i
Output: v

Compatibility: CSBwin98v44 or later

Fetch v from temporary variable[i]
for &@ and &! -- 0 <= i <= 99

&+ (binary operator +)

Opcode: &+
Input : x y
Output: x+y

commutative operator: yes

for example: "L1 L2 &+" returns "3", it means (2 + 1 → 3)

&NEG (unary operator -)

Opcode: &NEG
Input : x
Output: -x

for example: "L1 &NEG" returns "-1" (or "4294967294")

&AND (binary operator &)

Opcode: &AND
Input : x y
Output: x&y

commutative operator: yes

for example: "L3 L5 &AND" returns "1", it means (5 AND 3 → 3)

&OR (binary operator |)

Opcode: &OR
Input : x y
Output: x|y

commutative operator: yes

for example: "L3 L5 &OR" returns "5", it means (5 OR 3 → 5)

&LAND (binary operator &&)

Opcode: &LAND
Input : x y
Output: x&&y

commutative operator: yes

for example: "L0 L0 &LAND" returns "0"
for example: "L0 L1 &LAND" returns "0"
for example: "L1 L0 &LAND" returns "0"
for example: "L1 L1 &LAND" returns "1"

&LOR (binary operator ||)

Opcode: &LOR
Input : x y
Output: x||y

commutative operator: yes

for example: "L0 L0 &LOR" returns "0"
for example: "L0 L1 &LOR" returns "1"
for example: "L1 L0 &LOR" returns "1"
for example: "L1 L1 &LOR" returns "1"

&= (binary operator ==)

Opcode: &=
Input : x y
Output: x==y

commutative operator: yes

for example: "L0 L0 &=" returns "0"
for example: "L0 L3 &=" returns "0"
for example: "L3 L3 &=" returns "1"

&!= (binary operator !=)

Opcode: &!=
Input : x y
Output: x!=y

commutative operator: yes

for example: "L0 L0 &!=" returns "1"
for example: "L0 L3 &!=" returns "1"
for example: "L3 L3 &!=" returns "0"

&NOT (unary operator !)

Opcode: &NOT
Input : x
Output: !x

same as L0 &=

for example: "L0 &NOT" returns "1"
for example: "L1 &NOT" returns "0"
for example: "L3 &NOT" returns "0"

&< (signed) (binary operator <)

Opcode: &<
Input : x y
Output: x<y

commutative operator: no

for example: "L0 0 &<" returns "0", it means (0 < 0 → 0)
for example: "L1 0 &<" returns "0", it means (1 < 0 → 0)
for example: "L0 1 &<" returns "1", it means (0 < 1 → 1)

&U< (unsigned) (binary operator <)

Opcode: &U<
Input : x y
Output: x<y

Compatibility: CSBwin98v44 or later

unsigned

&SHIFT (binary operator <<)

Opcode: &SHIFT
Input : x y
Output: x<<y

y signed

commutative operator: no

for example: "L1 L0 &SHIFT" returns "1", it means (1 << 0 → 1)
for example: "L1 L1 &SHIFT" returns "2", it means (1 << 1 → 2)
for example: "L1 L2 &SHIFT" returns "4", it means (1 << 2 → 4)
1 << 0 means, 1 * 20 → 1
1 << 1 means, 1 * 21 → 1 * 2 → 2
1 << 2 means, 1 * 22 → 1 * 2 * 2 → 4

&RSHIFT (binary operator >>)

Opcode: &RSHIFT
Input : x y
Output: x>>y

y signed

commutative operator: no

for example: "L4 L0 &RSHIFT" returns "4"
for example: "L4 L1 &RSHIFT" returns "2"
for example: "L4 L2 &RSHIFT" returns "1"

&TYPE (operator type)

Opcode: &TYPE
Input : indirect index
Output: flags

like apple or dagger

it returns:

currently, it retuns unstable values.

See Also: &TYPE list

&DUP (operator dup)

Opcode: &DUP
Input : x
Output: x x

for example: "L1 &DUP" returns "1" and "1"

&1- (unary operator --)

Opcode: &1-
Input : x
Output: x-1

for example: "L1 &1-" returns "0"

&1+ (unary operator ++)

Opcode: &1+
Input : x
Output: x+1

for example: "L1 &1+" returns "2"

&SWAP (operator swap)

Opcode: &SWAP
Input : x y
Output: y x

for example: "L1 L2 &SWAP" returns "2" and "1"

&OVER (operator over)

Opcode: &OVER
Input :
Output: x

= L1 &PICK

for example: "L1 L2 L3 &OVER" returns "2"

&COMP (unary operator ~)

Opcode: &COMP
Input : x
Output: y

y is bitwise complement of x

&XOR (binary operator ^)

Opcode: &XOR
Input : x y
Output: x^y

commutative operator: yes

for example: "L0 L0 &XOR" returns "0"
for example: "L0 L1 &XOR" returns "1"
for example: "L1 L0 &XOR" returns "1"
for example: "L1 L1 &XOR" returns "0"

&2DUP (operator 2dup)

Opcode: &2DUP
Input : x y
Output: x y x y

NOT IMPLEMENTED!

for example: "L1 L2 &2DUP" returns "1" and "2"

&* (binary operator *)

Opcode: &*
Input : x y
Output: x*y

commutative operator: yes

for example: "L3 L3 &*" returns "9", it means (3 * 3 → 9)

&% (binary operator %)

Opcode: &%
Input : x y
Output: x%y

-1 2 %/ = 1

commutative operator: no

for example: "L0 L3 &%" returns "0", it means (0 % 3 → 0)
for example: "L1 L3 &%" returns "1", it means (1 % 3 → 1)
for example: "L2 L3 &%" returns "2", it means (2 % 3 → 2)
for example: "L3 L3 &%" returns "0", it means (3 % 3 → 0)
for example: "L4 L3 &%" returns "1", it means (4 % 3 → 1)
for example: "L5 L3 &%" returns "2", it means (5 % 3 → 2)

&/ (binary operator /)

Opcode: &/
Input : x y
Output: x/y

commutative operator: no

for example: "L0 L3 &/" returns "0", it means (0 ÷ 3 → 0)
for example: "L1 L3 &/" returns "0", it means (1 ÷ 3 → 0)
for example: "L2 L3 &/" returns "0", it means (2 ÷ 3 → 0)
for example: "L3 L3 &/" returns "1", it means (3 ÷ 3 → 1)
for example: "L4 L3 &/" returns "1", it means (4 ÷ 3 → 1)
for example: "L5 L3 &/" returns "1", it means (5 ÷ 3 → 1)

&LOC2ABSCOORD (operator loc2abscoord)

Opcode: &LOC2ABSCOORD
Input : location
Output: level x y pos

Break down <location> into absolute coordinates.
This includes the level offsets.

to store the location of Parameter A in DSA, use "LA &LOC2ABSCOORD"
to store the location of Parameter B in DSA, use "LB &LOC2ABSCOORD"

&SETNEWSTATE

Opcode: &SETNEWSTATE
Input : x
Output:

Sets next state of machine

&FALSEPIT (operator falsepit)

Opcode: &FALSEPIT
Input : location f
Output:

Set pits at target to false if f non-zero
else to real (non-false) if f is zero.

to disable (you cannot fall down) the pit at the DSA location Parameter A, use "LA L1 &FALSEPIT".
to enable (you can fall down) the pit at the DSA location Parameter A, use "LA L0 &FALSEPIT".

&OVERLAY (operator overlay)

Opcode: &OVERLAY
Input : p1 p2 p3 p4 overlay#
Output:

Select viewport overlay

p1: Unknown
p2: Transparency. from 0 to 100. 0 for non-transparency, 100 for full-transparency.
p3: Unknown
p4: Unknown

Next screenshot from Paul's OverlayDemo. Water weaving motion for your 1st person viewport.

The overlay# is from ID column from CSBgraphics by your "CSBgraphics.dat".
On that demo, 16 viewport overlay images are available (from 1 to 16).

Next screenshot from CSBgraphics. Displaying the contents of overlay demo's CSBgraphics.dat.

Each "Viewport Overlay" image should fix the image size to 224 by 136, otherwise your viewport will be messed up.
Also it'll accepts only 8bpp windows bitmap image file.

&DISABLESAVES (operator disablesaves)

Opcode: &DISABLESAVES
Input : d
Output:

Disable(d=1)/Enable(d=0) saves

use "L1 &DISABLESAVES" if you disable the game saving.
use "L0 &DISABLESAVES" if you enable the game saving.

Next screenshot shows saving is enabled (usual status).

Next screenshot shows saving is sealed.

&SAY

Opcode: &SAY
Input : location color
Output:

Display the text from dungeon
<location> in scrolled text area

First, add text at any wall tile on this way.

You can point the location in DSA property.

Use "LA L15 &SAY" to display the text at the location of DSA Parameter A in brightest white color.

F

Opcode: F
Input : depth location positionMask objMask
Output: indirect index

Find an exist item in dungeon. You must specify (1)what kind of object you want, (2)position mask in dungeon cell, (3)a dungeon cell you want to find and (4)depth.

Look at the next figure to check behavior of fetch operation. It assumes find (1)an misc item object, (2)at any position in dungeon cell, (3)location is specified by parameter A of DSA and (4)depth is 1.

the example code should be "L1 LA L15 L1024 F".

positionMask:

1: North (Upper left side of floor)
2: East  (Upper right side of floor)
4: South (Lower right side of floor)
8: West  (Lower left side of floor)

* specify L15 if you have no interests in position.

objMask:

    1: door
    2: teleporter
    4: text
    8: actuator
   16: monster
   32: weapon
   64: clothing
  128: scroll
  256: potion
  512: chest
 1024: misc
 2048: ?
 4096: ?
 8192: ?
16384: missile
32768: cloud

* specify L65535 if any kind of items/creatures/missiles/other objects should meet.
* specify L2016 if any possession-able kind of item (weapons, clothes, scrolls, potions, chests and misc items) should meet.
* specify L16 if any monsters should meet.

&PARAM@

Opcode: &PARAM@
Input : n i
Output:

Fetch n parameters to temporary variable[i]

Make sure you understand DSA filter capability concept well.

Acquire filter parameters from CSBwin engine. For example, you can obtain monster's type, position parameter, reason of their delete, etc while filter processing, if your DSA is designed for Delete Monster Filter.

The next figure shows association of variables among "parameters", "temporary variable[i]" and "DSA program stack". It also shows what operator transfers variable from X to Y.

* The contents of parameter are specific per filter capability.

&PARAM!

Opcode: &PARAM!
Input : n i
Output:

Store n parameters from temporary variable[i]

&MONSTER@

Opcode: &MONSTER@
Input : ID index num
Output:

Acquire monster specific information from CSBwin engine. e.g. you can get health point of a creature.
The information is specific per creature. Each creature info is independent if there are 10 mummies.

ID is object ID. Generally you can obtain ID by using operator F.

index means "i" of "temporary variable[i]". Finally you obtain the variable by using &@ operator.

num is number of variables you want to transfer. Valid number is 0 to 8 in current CSBwin.

Next figure may help to know association of "group of monster information" and "temporary variables", also include operator names to transfer between monster information and temporary variables.

* The description is very illegible because it can be referenced by CSBwin documentation site, also it may be changed in any timings.

See also: DSA - The Language (at DianneAndPaul.net)

&ADD

Opcode: &ADD
Input : positionMask location objectID
Output:

Duplicate an exist object (usually a weapon, cloth, scroll, potion, chest or a misc item), then place it anywhere you want. The item specific attribute such as charge count should be duplicated.

You can find the objectID (source item of duplication) by using F.

* The "duplication" is not "clone" technique. The duplication behaves like item generator.

See also: DSA - The Language (at DianneAndPaul.net)

&%ADD

Opcode: &#ADD
Input : positionMask location objectID
Output:

This is an indirect version of &ADD operator. You should choose &%ADD rather than &ADD if you are writing a DSA program used in filter capability.

It invokes immediately when you call &ADD.
However it is queued rather than immediate execution, when you call &%ADD. The &%ADD invokes its effect after the current DSA program exits.

&DEL