Abuse filter log

{{infobox proglang

|image=File:Dominoscript-logo.png

|name=DominoScript

|author=[[User:Galvandi]]

|year=[[:Category:2024|2024]]

|paradigms=imperative

|memsys=[[:Category:Stack-based|Stack-based]]

|dimensions=[[:Category:Two-dimensional languages|two-dimensional]]

|class=[[:Category:Turing complete|Turing complete]]

|majorimpl=[https://github.com/andreas-schoch/dominoscript Github Repo]

|files=<code>.ds</code> recommended

}}'''DominoScript''' is a two-dimensional self-modifying [[esoteric programming language]] that uses the dots on domino pieces to represent code.

== Core Concepts ==

'''<code>Domino Pieces</code>''':

* A domino piece can be placed either horizontally or vertically.

* DominoScript by default uses Double-Six (aka <code>D6</code>) dominos to represent code. Double-six here means that each domino has 2 sides with up to 6 dots each. Essentially Base7.

* Using the [[#Base|BASE]] instruction, you can tell the interpreter to parse dominos with up to 16 dots on each side. Allowing you to represent larger numbers with fewer dominos.

'''<code>Stack-Oriented</code>''':

* There is a global data stack that all instructions operate on.

* By default, the stack size is limited to 512 items (Up to the implementation to make this configurable. The default of the reference interpreter might become significantly larger with a future version).

* At its core, DS is just another concatenative [[Postfix notation|reverse-polish]] language. The following code: <code style="border-color:gray;">0—1 0—5 0—1 0—6 1—0 0—3 1—2 5—1</code> is the same as <code style="border-color:gray;">5 6 + dup * .</code> in [[Forth]].

* Internally every item on the stack is a signed 32-bit integer.

* Strings are just null-terminated sequences of integers representing Unicode char codes.

* Floats are not supported ''(Fixed-point-arithmetic might be supported in future versions)''.

* No other data structures exist.

'''<code>Two-Dimensional</code>''':

* The code is represented on a rectangle grid of cells. The top-left cell is address 0. The bottom-right cell is address <code>cols * rows - 1</code>.

* Any implementation needs to support a grid of at least 65408 total cells to be spec compliant. That allows a square grid of up to `256x256` cols and rows or any smaller rectangular grid within the cell limit. Each cell needs to be indexable using an <code>int32</code> popped from the data stack, so well optimized implementations may support crazy amounts of cells.

* The Instruction Pointer (IP) can move in any cardinal direction. Direction changes are performed by placing dominos in a certain way (IP always moves from one half to the other half of the same domino) as well as the current Navigation Mode. See: [[#How_the_Instruction_Pointer_Moves|How the Instruction Pointer Moves]].

'''<code>Self-Modifying</code>''':

* The code can override itself somewhat similar to befunge. See [[#Get|GET]] and [[#Set|SET]] instructions.

* Getting and setting can be done using different encodings:

** '''domino''': get or set single domino

** '''unsigned number''': get or set a number within the int32 range ''(why not uint32? Because the stack only supports int32 so there is no point)''. Up to 7 dominos can be parsed per get/set.

** '''signed number''': get or set a number within the int32 range. Up to 7 dominos can be parsed per get/set. The only different to unsigned number encoding is that here the first half of the first domino is sacrificed to encode the "sign bit" (if first half is anything but 0, sign bit is on).

** '''string''': Get or set a whole string.

* Can be used as a secondary data store ''(to act somewhat similar to registers or variables)'' besides the stack.

'''<code>Multiple Files</code>''':

* You can split up DS code into multiple files and include them in the main file using the [[#Import|IMPORT]] instruction.

* Each import has its own grid of cells.

* The data stack is shared between the main and all imported files.

* Defining a label within an imported file during the import phase, allows the parent to call functions within the child. Giving the parent essentially an interface to use the imported file as a library. ''(See the [[#Label|LABEL]] instruction for more info)''.

== Text Format ==

The dots on dominos are represented using a text based format:

* The digits <code>0</code> to <code>f</code> represent the dots on half of a domino. To indicate an empty cell, use a dot <code>.</code>

* The “long hyphen” character <code>—</code> indicates a horizontal domino ''(regular hyphen <code>-</code> also accepted to make it easier to type)''. It can only appear on '''even''' columns and '''odd''' rows.

* The “pipe” character <code>|</code> indicates a vertical domino. It can only appear on '''odd''' columns and '''even''' rows.

* Any other line <ins>before</ins> and <ins>after</ins> the actual code is ignored. ''(Tip: Make use of this to add extensive comments. You will inevitable forget what your dominoscript code does, so consider including a 1:1 pseudocode implementation of the dominoscript code)''

The following DominoScript code ''(which prints "Hello world")'':

<pre style="letter-spacing:4px;line-height:1.1;display:inline-block;border-color: black;">

. . . . . . . . . . . . . . .

. . . . . . . . 0—2 1 . 0—3 .

|

. 1 0—3 2—1 4—4 . . 2 . 2 1 .

| | |

. 2 . . . . . 0 . . 0—6 1 2 .

|

. 1—6 1—2 2 . 1 6—1 . . . 1 .

| |

. . . . . 2 . . . 2 . . . 3 .

|

. 1 3—1 2—1 . . . 1 3—1 2—1 .

|

. 2 0—2 0 . . . . . . . . . .

|

. . . . 0 5—3 . . . . . . . .

</pre>

Is the equivalent of the following dominos:

<br>[[File:DominoScript-Example-003-flow.png|400px|Hello world 2d]]

The grid doesn’t have to be a square but it must have a consistent number of columns and rows, otherwise an <code>InvalidGridError</code> will be thrown before execution starts:

<table class="wikitable">

<tr><th>GOOD ✅</th><th>BAD ❌</th></tr>

<tr><td>

<pre>. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .</pre>

</td>

<td>

<pre> . . . . . . .

. . . . . . . .

. . . . .

. . . . . . .</pre>

</td>

</tr>

</table>

Connecting to a domino half which is already connected results in <code>MultiConnectionError</code>:

<table class="wikitable">

<tr><th>GOOD ✅</th><th>BAD ❌</th></tr>

<tr><td>

<pre>6—6 6—6 .

6 6—6 . .

|

6 . . . .</pre>

</td>

<td>

<pre>6—6—6—6 .

6—6 . . .

|

6 . . . .</pre>

</td>

</tr>

</table>

Having a domino half that is not connected to anything results in <code>MissingConnectionError</code>:

<table class="wikitable">

<tr><th>GOOD ✅</th><th>BAD ❌</th></tr>

<tr><td>

<pre>. . 6—6 .

. 6 . . .

|

. 6 . . .</pre>

</td>

<td>

<pre>. . 6 6 .

. 6 . . .

. 6 . . .</pre>

</td>

</tr>

</table>

Having a connection where 1 or both ends are empty results in a <code>ConnectionToEmptyCellError</code>:

<table class="wikitable">

<tr><th>GOOD ✅</th><th>BAD ❌</th></tr>

<tr><td>

<pre>6—6 . 6—6

6 . . . 6

| |

6 . . . 6</pre>

</td>

<td>

<pre>6—. . .—6

6 . . . .

| |

. . . . 6</pre>

</td>

</tr>

</table>

== How Dominos are parsed into Numbers ==

It is important to understand that '''internally''' everything in DominoScript is represented as signed 32-bit Integers and '''externally''' everything is represented by the dots on the domino pieces.

'''Every domino is part of either''':

* An opcode - decides which instruction to execute next. By default, one domino represents one opcode unless you tell the interpreter to use 2 dominos per opcode using the [[#Ext|EXT]] instruction.

* A number literal - the [[#Num|NUM]] instruction is used to push a single Integer onto the stack.

* A string literal - the [[#Str|STR]] instruction is used to push a sequence of Integers onto the stack which represent unicode char codes.

'''Furthermore, you should also be aware of the following things''':

* The number base system that is currently set influences how dots are parsed into numbers. The base can be changed using the [[#Base|BASE]] instruction. (Default: Base 7 - because double-six dominos are the most common).

* The "LiteralParseMode" tells the interpreter how many dominos will be part of a literal. It can be changed using the [[#Lit|LIT]] instruction (Default: dynamic - first half of first domino decides how many more are part of a number literal).

* Once a literal is pushed on the stack, it is your job as the developer to keep track of which items are numbers and which ones are characters of a string. You can use any instruction on characters of a “string” but only the following ones will treat them as such: [[#Str|STR]], [[#Eqlstr|EQLSTR]], [[#Strin|STRIN]], [[#Strout|STROUT]] as well as [[#Get|GET]] and [[#Set|SET]] when used with the "string" encoding type.

In examples, you might see stack items that are meant to be char codes, represented in the following way:”

<pre>[..., 1, 2, 3 'NUL', 's', 'e', 'y']</pre>

But in reality, the stack will store them as integers and look like this:

<pre>[..., 1, 2, 3, 0, 115, 101, 121]</pre>

'''What about floats?'''

Floats don’t exist in DominoScript. I’d suggest scaling up numbers by a factor of 10, 100, 1000 or whatever precision you need.

''(I know that pico-8 uses 32-bits for numbers but treats them as 16.16 fixed point numbers. I am not quite sure if that is just a convention or if pico8’s API actually treats them as fixed-point numbers. I would like to eventually add some trigonometry instructions to DominoScript but am unsure what the most practical way would be)''

== How the Instruction Pointer Moves ==

The Instruction Pointer (<code>IP</code>) keeps track of the current cell address that will be used for the next instruction. Since DominoScript is 2D, it isn’t obvious where the IP will move to without understanding the fundamental rules and the Navigation Modes.

'''Before the program starts:'''

# The interpreter will scan the grid from '''top-left to top-right''', move down and repeat until it finds the first domino.

# Upon reaching the first domino, the IP is placed at the address of the first found domino half.

# If no domino could be found, the program is considered finished.

'''During the program execution:'''<br>

The IP will adhere to the following rules:

* The IP can move in cardinal directions, never diagonally. How dominos are parsed, is all relative to that. For example, the horizontal domino <code>3—5</code> can be interpreted as the base7 number <code>35</code> (IP moves eastwards) or <code>53</code> (IP moves westwards). Same thing for vertical dominos.

* The IP will always move from one half (entry) of the same domino to the other half (exit) of the same domino.

* If the IP cannot move to a new domino, the program is considered finished.

* At the exit half of a domino, the IP will never move back to the entry half. It will always try to move to a new domino. That means, there are at most 0 to 3 potential options for the IP to move.

* When the IP needs to move to a new domino, it is possible that there are no valid moves despite there being dominos around. The [[#Navigation_Modes|Navigation Mode]] decides where the IP can and cannot move next.

'''Understanding Navigation Modes:'''<br>

Navigation Modes are predefined priority patterns which are used when the Instruction Pointer needs to decide to which domino to move to next. The [[#Navm|NAVM]] instruction can be used to change the current Navigation Mode.

Understanding the following concepts will become very important:

* '''Priority Directions''': Primary, Secondary, Tertiary

* '''Relative Directions''': Forward, Left, Right

* '''Cardinal Directions''': North, East, South, West

The Cardinal directions don’t matter much. It is all about the '''direction in relation to the exit half''' of the current domino ''(If you ever did any kind of GameDev you probably know the difference between world space and local space. It’s kind of like that)''

When the IP moves to a new domino, the half it enters to is called the “'''entry'''” while the other half is called the “'''exit'''”. Now from the perspective of the exit half, the IP can potentially move in 3 directions: Forward, Left, Right. These are the '''Relative Directions'''.

Which relative direction the IP chooses, depends on the current Navigation Mode. Below you will see the mapping of the very basic nav modes:

{| class="wikitable"

|-

! Index !! <code>Primary</code> !! <code>Secondary</code> !! <code>Tertiary</code>

|-

| 0 || Forward || Left || Right

|-

| 1 || Forward || Right || Left

|-

| 2 || Left || Forward || Right

|-

| 3 || Left || Right || Forward

|-

| 4 || Right || Forward || Left

|-

| 5 || Right || Left || Forward

|-

| ... || ... || ... || ...

|}

''The “index” here is the argument for the <code>NAVM</code>instruction.''

<br>

'''If we imagine the <code>6</code> to be the exit half, what will be the next domino the IP moves to?:'''

<table class="wikitable" style="line-height:1.1;letter-spacing:4px;">

<tr>

<th>East</th>

<th>West</th>

<th>South</th>

<th>North</th>

</tr>

<tr>

<td>

<pre>

. 2 . . .

|

. 2 . . .

5—6 1—1 .

. 3 . . .

|

. 3 . . .

</pre>

</td>

<td>

<pre>

. . . 3 .

|

. . . 3 .

. 1—1 6—5

. . . 2 .

|

. . . 2 .

</pre>

</td>

<td>

<pre>

. . 5 . .

|

3—3 6 2—2

. . 1 . .

|

. . 1 . .

. . . . .

</pre>

</td>

<td>

<pre>

. . . . .

. . 1 . .

|

. . 1 . .

2—2 6 3—3

|

. . 5 . .

</pre>

</td>

</tr>

</table>

''All 4 snippets are exactly the same code with the difference that they are all flipped differently. This is what I mean by the cardinal direction not mattering much in DominoScript.''

* When <code>index 0</code>, the IP will move to <code>1—1</code> (Primary, Forward)

* When <code>index 1</code>, the IP will move to <code>1—1</code> (Primary, Forward)

* When <code>index 2</code>, the IP will move to <code>2—2</code> (Primary, Left)

* When <code>index 3</code>, the IP will move to <code>2—2</code> (Primary, Left)

* When <code>index 4</code>, the IP will move to <code>3—3</code> (Primary, Right)

* When <code>index 5</code>, the IP will move to <code>3—3</code> (Primary, Right)

<br>

'''What if we remove the <code>1—1</code> domino? Where will the IP go to then?:'''

<table class="wikitable" style="line-height:1.1;letter-spacing:4px;">

<tr>

<th>East</th>

<th>West</th>

<th>South</th>

<th>North</th>

</tr>

<tr>

<td>

<pre>. 2 . . .

|

. 2 . . .

5—6 . . .

. 3 . . .

|

. 3 . . .</pre>

</td>

<td>

<pre>. . . 3 .

|

. . . 3 .

. . . 6—5

. . . 2 .

|

. . . 2 .</pre>

</td>

<td>

<pre>. . 5 . .

|

3—3 6 2—2

. . . . .

. . . . .

. . . . .</pre>

</td>

<td>

<pre>. . . . .

. . . . .

. . . . .

2—2 6 3—3

|

. . 5 . .</pre>

</td>

</tr>

</table>

* When <code>index 0</code>, the IP will move to <code>2—2</code> (Secondary, Left)

* When <code>index 1</code>, the IP will move to <code>3—3</code> (Secondary, Right)

* When <code>index 2</code>, the IP will move to <code>2—2</code> (Primary, Left)

* When <code>index 3</code>, the IP will move to <code>2—2</code> (Primary, Left)

* When <code>index 4</code>, the IP will move to <code>3—3</code> (Primary, Right)

* When <code>index 5</code>, the IP will move to <code>3—3</code> (Primary, Right)

<br>

'''And what if we remove both the <code>1—1</code> and the <code>2—2</code> domino?:'''

<table class="wikitable" style="line-height:1.1;letter-spacing:4px;">

<tr>

<th>East</th>

<th>West</th>

<th>South</th>

<th>North</th>

</tr>

<tr>

<td>

<pre>. . . . .

. . . . .

5—6 . . .

. 3 . . .

|

. 3 . . .</pre>

</td>

<td>

<pre>. . . 3 .

|

. . . 3 .

. . . 6—5

. . . . .

. . . . .</pre>

</td>

<td>

<pre>. . 5 . .

|

3—3 6 . .

. . . . .

. . . . .

. . . . .</pre>

</td>

<td>

<pre>. . . . .

. . . . .

. . . . .

. . 6 3—3

|

. . 5 . .</pre>

</td>

</tr>

</table>

* When <code>index 0</code>, the IP will move to <code>3—3</code> (Tertiary, Right)

* When <code>index 1</code>, the IP will move to <code>3—3</code> (Secondary, Right)

* When <code>index 2</code>, the IP will move to <code>3—3</code> (Tertiary, Right)

* When <code>index 3</code>, the IP will move to <code>3—3</code> (Secondary, Right)

* When <code>index 4</code>, the IP will move to <code>3—3</code> (Primary, Right)

* When <code>index 5</code>, the IP will move to <code>3—3</code> (Primary, Right)

<br>

These are only variations of the “Basic-Three-Way” kind of NavModes. See the [[#Navigation_Modes|Reference]] for a full list of available modes.

== Instructions ==

Instructions are mapped to opcodes behind the scenes:

* '''0-48''': Are the “core” instructions ''(2 have yet to be mapped)'' and are meant to fit within the value range a single “double-six” domino can represent.

* '''49-99''': Reserved for future extensions of the language ''(e.g. fixed-point-arithmetic, helpers for more advanced string manipulation and such)''

* '''100+''': Allow you as developer to extend the language yourself with non-standard behaviour. These opcodes are essentially alternative ways of calling by label. To learn more, see: [[#Call|CALL]], [[#Label|LABEL]] and [[#Import|IMPORT]] instructions.

To know which domino represents which opcode, you have to know the currently active [[#Base|base]]. For example, to represent opcode 48...:

* in '''base7''' you use a '''<code>6—6</code>''' domino (default)

* in '''base10''' you use a '''<code>4—8</code>''' domino

* in '''base16''' you use a '''<code>3—0</code>''' domino

<br>

The core instructions are grouped in 7 categories of 7 instructions each. Below, you will see them listed all.

''(The numbers on the right beside the instruction titles are the corresponding opcode)''

<br>

=== Stack Management ===

<span id="Pop"></span>

==== POP - 0 ====

Discards the top of the stack.

<span id="Num"></span>

==== NUM - 1 ====

Switch to “number mode”. By default, the first half of the next domino will indicate how many dominos to read as a number. Then the other halfs will all be read as base7 digits (in D6 mode) to form the number that will be pushed to the stack.

With 7 dominos, 13 out of 14 halfs are used for the number. You can theoretically represent a number much larger than the max int32 value. However, if the number exceeds the maximum int32 value, it will wrap around from the minimum value, and vice versa ''(exactly the same as when doing bitwise operations in JS –&gt; <code>(96889010406 | 0) === -1895237402</code>)''.

You might think that since internally numbers are int32s, that we parse from base7 to two’s complement. That is not the case. We simple push the decimal version of the positive base7 number to the stack

'''For example:'''

* <code>0—0</code> represents the number <code>0</code> in both decimal and base7

* <code>0—6</code> represents the number <code>6</code> in both decimal and base7

* <code>1—6 6—6</code> represents the number <code>342</code> in decimal and <code>666</code> in base7

* <code>2—6 6—6 6—6</code> represents the number <code>16,806</code> in decimal and <code>6,666</code> in base7

* <code>6—6 6—6 6—6 6—6 6—6 6—6</code> represents the number <code>1,977,326,742</code> in decimal and <code>66,666,666,666</code> in base7 (about 92.1% of the max int32 value)

* <code>6—0 1—0 4—1 3—4 2—1 1—1 6—1</code> represents the number <code>2,147,483,647</code> in decimal and <code>104,134,211,161</code> in base7 (exactly the max int32 value)

* <code>6—6 6—6 6—6 6—6 6—6 6—6 6—6</code> represents the number -1,895,237,402. '''WHY?''': The actual decimal number the dominos represent is <code>96,889,010,406</code> which is ~45x larger than the max int32 value. It wraps around about that many times before it reaches the final value.

'''What if numbers are read from the other directions?'''

* <code>1—1 1—1</code>, <code>2—2 2—2 2—2</code> for example will be exactly the same numbers (216 in decimal) eastwards and westwards.

* <code>1—2 3—1</code> when parsed backwards is <code>1—3 2—1</code> and can therefore represent different numbers if the IP moves to the east or to the west.

* <code>1—6 6—6</code> represents 666 in base7 (342 in decimal) but when parsed backwards the interpreter will raise an <code>UnexpectedEndOfNumberError</code>. Remember that the first half of the first domino indicates how many more will follow. In this case it expects to read 6 more dominos but the number ends prematurely after 1 domino.

'''What if I want to use a fixed amount of dominos for each number?'''

Use the [[#Lit|LIT]] instruction to permanently change how literals are parsed. For example with parse mode <code>2</code> it will use 2 dominos for each number. While <code>6—6 6—6</code> in default parse mode 0 results in <code>UnexpectedEndOfNumberError</code> (because it expects 6 more dominos to follow but only got 1 more), in parse mode <code>2</code> it represents the decimal number <code>2400</code>.

<span id="Str"></span>

==== STR - 2 ====

With <code>STR</code> you switch to “string mode” and can push multiple integers to the stack to represent Unicode characters.

The way the dominos are parsed to numbers is identical to <code>NUM</code>: First half of first domino indicates how many more will follow for a single number.

The difference is that it doesn’t stop with just one number. It will keep reading numbers until it encounters the NULL character represented by domino <code>0—0</code>.

Only once the interpreter does encounter the NULL character, will it push the characters to the stack in <ins>reverse</ins> order.

''(Note: I decided to parse strings like this because I wanted a single int32 based stack and, out of all options I could think of, this one felt the least annoying. If you can think of better ways, I am open for suggestions!)''

This is how you push the string <code>&quot;hi!&quot;</code> to the stack and output it:

<pre>0—2 1—2 0—6 1—2 1—0 1—0 4—5 0—0 5—3</pre>

It equals the following pseudo code: <code>STR &quot;hi!&quot; STROUT</code>

* <code>0—2</code> is the <code>STR</code> instruction

* <code>1—2 0—6</code> is the Unicode value 105 representing the character <code>h</code>

* <code>1—2 1—0</code> is the Unicode value 105 representing the character <code>i</code>

* <code>0—0 4—5</code> is the Unicode value 33 representing the character <code>!</code>

* <code>0—0</code> is the Unicode value for the NULL character which terminates the string.

* <code>5—3</code> is the [[#Strout|STROUT]] instruction. It will pop items from the stack, parse them as Unicode chars and once it encounters the NULL character, it will output the string to stdout all at once.

This is the resulting stack:

<table class="wikitable">

<tr>

<th>

Imaginative

</th>

<th>

Reality

</th>

</tr>

<tr>

<td>

<pre>[..., 'NUL', '!', 'i', 'h']</pre>

</td>

<td>

<pre>[..., 0, 33, 105, 104]</pre>

</td>

</tr>

</table>

Keep in mind that the IP can move in 4 cardinal direction so the following variations would also push the string <code>&quot;hi!&quot;</code> to the stack:

IP moves right to left:

<pre>3—5 0—0 5—4 0—1 0—1 2—1 6—0 2—1 2—0</pre>

IP moves in multiple directions:

<pre>0 . . . . 0 4—5

| |

2 . . . . 1 . 0

|

1 . . 2 1—0 . 0

| |

2 0—6 1 . . 3—5</pre>

<span id="Dupe"></span>

==== DUPE - 3 ====

Duplicate the top item on the stack.

<span id="Roll"></span>

==== ROLL - 4 ====

Pops one argument from the stack to be used as “depth”.

* With a negative depth, the item at the <ins>top</ins> is moved to the <ins>nth depth</ins>

* With a positive depth, the item at the <ins>nth depth</ins> is moved to the <ins>top</ins>

With roll you can implement common stack operations like <code>SWAP</code> and <code>ROT</code>:

{| class="wikitable"

! Roll Depth

! Equivalent to

! Stack Before

! Stack After

|-

| -3

| -

| <code>[a, b, c, d]</code>

| <code>[d, a, b, c]</code>

|-

| -2

| ROTR

| <code>[a, b, c]</code>

| <code>[c, a, b]</code>

|-

| -1

| SWAP

| <code>[a, b]</code>

| <code>[b, a]</code>

|-

| 0

| NOOP

| <code>[a]</code>

| <code>[a]</code>

|-

| 1

| SWAP

| <code>[a, b]</code>

| <code>[b, a]</code>

|-

| 2

| ROTL

| <code>[a, b, c]</code>

| <code>[b, c, a]</code>

|-

| 3

| -

| <code>[a, b, c, d]</code>

| <code>[b, c, d, a]</code>

|}

<span id="Len"></span>

==== LEN - 5 ====

Pushes the number of items on the stack.

<span id="Clr"></span>

==== CLR - 6 ====

Removes all items from the stack.

<br>

=== Arithmetic ===

<span id="Add"></span>

==== ADD - 7 ====

Pops 2 numbers from the stack. The sum is pushed to the stack.

<span id="Sub"></span>

==== SUB - 8 ====

Pops 2 numbers from the stack. The result of <code>numberA - numberB</code> is pushed to the stack.

<span id="Mult"></span>

==== MULT - 9 ====

Pops 2 numbers to multiply. The result is pushed to the stack.

<span id="Div"></span>

==== DIV - 10 ====

Pops 2 numbers. The result of the division of numberA by numberB is pushed to the stack. (Keep in mind that DominoScript is integer based and any remainder is discarded.)

<span id="Mod"></span>

==== MOD - 11 ====

Pops 2 numbers. The remainder of division of <code>numberA / numberB</code> is pushed to the stack.

Note: When numberA is positive modulo behaves identical in most languages (afaik). However, there are some differences across programming languages when numberA is negative. In DominoScript modulo behaves like in JavaScript, Java, C++ and Go and <ins>NOT</ins> like in Python or Ruby!

<span id="Neg"></span>

==== NEG - 12 ====

Negate the top of the stack.

<span id="Clamp"></span>

==== CLAMP -13 ====

Pops 3 numbers from the stack:

<pre>[..., value, min, max]</pre>

And pushes back the clamped value onto the stack.

<br>

=== Comparison &amp; Logical ===

<span id="Not"></span>

==== NOT - 14 ====

Pops the top item off the stack. If it is <code>0</code>, it pushes <code>1</code>. Otherwise it pushes <code>0</code> to the stack.

<span id="And"></span>

==== AND - 15 ====

Pops the top 2 items off the stack, performs the logical AND operation and pushes the result back onto the stack.

<span id="Or"></span>

==== OR - 16 ====

Pops the top 2 items off the stack, performs the logical OR operation and push the result back onto the stack.

<span id="Eql"></span>

==== EQL - 17 ====

Pops the top 2 items off the stack, compares them and pushes the result back onto the stack. If the items are equal, it pushes <code>1</code> to the stack, otherwise <code>0</code>.

<span id="Gtr"></span>

==== GTR - 18 ====

Pops the top 2 items off the stack, compares them and pushes the result back onto the stack. If the first item is greater than the second, it pushes <code>1</code> to the stack, otherwise <code>0</code>.

<span id="Eqlstr"></span>

==== EQLSTR -19 ====

Assumes that 2 strings are on the stack. It pops them, compares them and pushes <code>1</code> to the stack if equal, otherwise <code>0</code>.

'''<ins>For example:<ins>'''<br />

You push the strings <code>&quot;AC&quot;</code> then <code>&quot;DC&quot;</code>. They are represented on the stack as <code>[NULL, C, A, NULL, C, D]</code> (In reality it is <code>[0, 67, 65, 0, 67, 68]</code>). Since the strings are not equal, it will push <code>0</code> to the stack. It is now <code>[0]</code>.

'''<ins>Another example:<ins>'''<br />

Imagine you want to check if the user pressed arrow left. You execute the <code>KEY</code> instruction after which the stack looks like <code>[&lt;existing&gt;, 0, 68, 91, 27]</code> then you push the <ins>escape sequence</ins> which represents the left arrow key. The stack is now <code>[&lt;existing&gt;, 0, 68, 91, 27, 0, 68, 91, 27]</code>. You then execute the <code>EQLSTR</code> instruction which will pop the top 2 strings and since the strings are equal, it will push <code>1</code> to the stack. It is now <code>[&lt;existing&gt;, 1]</code> ''(See the [[#Key|KEY]] instruction for more info about escape sequences)''.

<span id="Reserved_20"></span>

==== RESERVED - 20 ====

Unmapped opcode. Will throw <code>InvalidInstructionError</code> if executed.

<br>

=== Bitwise ===

<span id="Bnot"></span>

==== BNOT - 21 ====

Bitwise NOT. Pops the top item off the stack, inverts all bits and pushes the result back onto the stack.

<span id="Band"></span>

==== BAND - 22 ====

Bitwise AND. Pops the top 2 items off the stack, performs bitwise AND and pushes the result back onto the stack.

<span id="Bor"></span>

==== BOR - 23 ====

Bitwise OR. Pops the top 2 items off the stack, performs bitwise OR and pushes the result back onto the stack.

<span id="Bxor"></span>

==== BXOR -24 ====

Bitwise XOR. Pops the top 2 items off the stack, performs bitwise XOR and pushes the result back onto the stack.

<span id="Lsl"></span>

==== LSL - 25 ====

Logical Shift Left. Performs the equivalent of <code>argA &lt;&lt; argB</code> and pushes the result back onto the stack.

<span id="Lsr"></span>

==== LSR - 26 ====

Logical Shift Right. Performs the equivalent of <code>argA &gt;&gt;&gt; argB</code> and pushes the result back onto the stack.

<span id="Asr"></span>

==== ASR - 27 ====

Arithmetic Shift Right. Performs the equivalent of <code>argA &gt;&gt; argB</code> and pushes the result back onto the stack.

<br>

=== Control Flow ===

<span id="Navm"></span>

==== NAVM - 28 ====

Changes the Navigation Mode. The default Mode is <code>0</code>.

See [[#Navigation_Modes|Navigation Modes]] to see all possible nav modes and their indexes.

If you don't know what navigation modes are and how they influence the Instruction Pointer, I'd recommend reading the relevant section in [[#How_the_Instruction_Pointer_Moves|How the Instruction Pointer Moves]].

<span id="Branch"></span>

==== BRANCH - 29 ====

Like an IF-ELSE statement.

It pops the top of the stack as a condition and then:

<pre style="letter-spacing:4px;line-height:1.1;">

. . . . . 6 . .

|

. . . . . 6 . .

0—1 0—1 4—1 . .

. . . . . 5 . .

|

. . . . . 5 . .

</pre>

* If popped value is a non-zero number: The IP will move to the relative '''LEFT''' (the <code>6-6</code>domino)

* If popped value is zero: The IP will move to the relative '''RIGHT''' (the <code>5-5</code>domino)

When using branch, the current Navigation Mode is ignored. You can always be assured that the IP will either move to the relative left or right.

<span id="Label"></span>

==== LABEL - 30 ====

Label are like a bookmarks or an alternative identifier of a specific Cell address. They can be used by the <code>JUMP</code>, <code>CALL</code>, <code>GET</code> and <code>SET</code> instructions (although these also work directly with addresses, so labels are not mandatory)

'''Labels are probably not what you expect them to be.'''

* They are '''NOT''' strings, but negative numbers.

* They are auto generated and self decrementing: <code>-1</code>, <code>-2</code>, <code>-3</code>, etc.

* You can kind of imagine them as pointers to a specific cell address.

Executing the LABEL instruction pops the address of the cell you want to label and assigns it to the next available negative number.

The negative number will '''NOT''' be pushed to the stack. First label will be <code>-1</code>, second label will be <code>-2</code> and so on. You need to keep track of them yourself.

For clarity, I’d generally recommend adding comments like the following to your source files:

<pre>

| Label | Address | Function name |

|-------|---------|---------------|

| -1 | 340 | main |

| -2 | 675 | update |

| -3 | 704 | render |

</pre>

'''About Labels in imported files:'''

DominoScript has an <code>IMPORT</code> instruction that allows source files to be imported into others. The imported functions can only be called via labels, so in that regard a label also acts like an export. If the parent file doesn’t define labels of their own, the label values will be the same in both parent and child. However if the parent file creates labels <ins>before</ins> importing a child file, the exported child labels will have a different value in the parent. For example:<br />

# Parent creates label <code>-1</code>, <code>-2</code>, <code>-3</code> and then imports the child file

# The child file defines labels <code>-1</code>, <code>-2</code>, <code>-3</code> and gives back control to parent

# The parent file will now have the labels <code>-1</code>, <code>-2</code>, <code>-3</code> and the child labels will be <code>-4</code>, <code>-5</code>, <code>-6</code>

# Now when the parent wants to call a child function which internally is labelled with <code>-1</code>, it needs to use label <code>-4</code> instead.

<span id="Jump"></span>

==== JUMP - 31 ====

Moves the IP to an address on the grid. You can either use a label or an address as an argument.

If the IP cannot move anymore, the interpreter will throw a <code>StepToEmptyCellError</code>.

If label is unknown it will throw an <code>UnknownLabelError</code>.

<span id="Call"></span>

==== CALL - 32 ====

Like the name suggests, it is similar to a function call. When The IP cannot move anymore, it will return to the address from where it was called from.

You can do recursive calls. An implementation should support a depth of at least 512 to be spec compliant.

'''Alternative way to CALL''' Instead of doing <code>ǸUM 1 NEG CALL</code> to call by label, you can just do <code>OPCODE_100</code>. Why? Because labels are mapped to opcodes 100+. So when you create the labels <code>-1</code>, <code>-2</code>, <code>-3</code>, etc. they are automatically mapped to opcodes <code>100</code>, <code>101</code>, <code>102</code>.

<span id="Import"></span>

==== IMPORT - 33 ====

Pop a “string” from the stack to indicate the file name of the source file to import.

On import the interpreter will load the file and start running it until its Instruction Pointer cannot move anymore.

Labels defined in the imported file are accessible from the file which imports it. That means you can call functions from the imported file via the <code>CALL</code> instruction.

If the importing file defined a label before the import, the labels from the imported file will have different identifiers. For example:

* <code>FileChild.ds</code> defines a label <code>-1</code>.

* <code>FileAParent.ds</code> defines labels <code>-1</code>, <code>-2</code>, then imports FileChilds.ds.s

The <ins>internal</ins> label <code>-1</code> in <code>FileChild.ds</code> will be <code>-3</code> <ins>externally</ins> in <code>FileAParent.ds</code> because labels are always auto decrementing. '''Why?''' Because it is the simplest way to avoid conflicts and be able to use labels internally and externally.

The data stack is shared between parent and all imported files. Apart from that, the parent and child imports run in their own contexts. Imported files can have imports themselves but you should avoid circular dependencies.

If you import the same file into more than one other file, it will result in multiple instances of the imported file. This is probably not a problem as long as you are aware of it ''(It might even be useful if you treat imports of the same file as "objects instances")''.

<span id="Wait"></span>

==== WAIT - 34 ====

Pops the top item off the stack and waits for that many milliseconds before continuing.

''Within DominoScript, you could simulate a delay with a ‘busy loop’ by using the TIME, GTR and BRANCH instructions within a loop. Internally an implementation is free to implement WAIT using a busy loop to avoid having to deal with asynchronous code. However, to be spec compliant it should ideally add some form of interrupt handling so the interpreter can be stopped when the user tries to exit (via e.g. Ctrl+C) even if the code is stuck in an infinite loop.''

<br>

=== Input &amp; Output ===

<span id="Numin"></span>

==== NUMIN - 35 ====

Prompt the user for a number. The user input will be pushed to the stack.

<span id="Numout"></span>

==== NUMOUT - 36 ====

Pop the top item from the stack and output it to stdout.

<span id="Strin"></span>

==== STRIN - 37 ====

Prompt the user for a string. The user input will be pushed to the stack as individual Unicode characters in reverse order.

So if the user inputs <code>&quot;yes&quot;</code>, the stack will look like this:

<pre>[..., 0, 115, 101, 121]</pre>

For convenience you might often see the stack represented But remember that in reality it just stores int32s.

<pre>[..., NUL 's', 'e', 'y']</pre>

''Note: Since each char is pushed to the stack, the max input string length is limited to the available stack space. By default, the max stack size is 512 for the reference interpreter. This limit will likely be increased to ~64k''

<span id="Strout"></span>

==== STROUT - 38 ====

Pops numbers (representing Unicode char codes) from the stack until it encounters a null terminator (number 0). It will then output the string to stdout.

<ins>

'''There is one special case:'''

</ins>

If the parser encounters the <code>Unit Separator</code> (ascii 31), it stringifies the <ins>next</ins> number instead of treating it as a unicode char code. This is very useful to generate ANSI escape sequences like <code>\x1b[15;20H[-]</code> which tells the terminal to draw <code>[-]</code> at row 15 and column 20. Without the <code>Unit Separator</code> you would have to push the char code for 1, 5 and 2, 0 individually. This is a pain if you are dealing with dynamic numbers. The [[./examples/023_input_controls_advanced.md|example_023]] uses this to create an escape sequence.

<span id="Key"></span>

==== KEY - 39 ====

Check if the user pressed a specific key since the last reset with <code>KEYRES</code>. If the key was pressed, it pushes <code>1</code> to the stack, otherwise <code>0</code>.

It pops a <ins>string sequence</ins> of the stack to represent the key you want to check for.

Unlike <code>NUMIN</code> and <code>STRIN</code> it doesn’t block the program, so you can use it in a loop to check for user input.

'''<ins>What string sequence?:</ins>''' - If a key is a printable character, the sequence is the Unicode value of the key. For example, to check if the user pressed the <code>a</code> key, you would push the string <code>a</code>. - If a key is a special key like arrow left, right etc, the sequence is an escape sequence. For example, to check if the user pressed the left arrow key, you would push the escape sequence <code>\u001b[D</code> to the stack.

'''<ins>What is an escape sequence?:</ins>'''

Escape sequences are sequences of characters that are used to represent special non-printable keyboard keys like arrow keys but can also be used to control terminal behavior, such as cursor position, text color and more. You can google them. Then just transform them to the correct domino sequence.

<span id="Keyres"></span>

==== KEYRES - 40 ====

Resets the state of all keys to “not pressed”. It is used in combination with <code>KEY</code> to check if a key was pressed since the last reset. It has no effect on the stack.

Imagine you have a game running at 20fps. Every 50ms you check if the user pressed any of the arrow keys and act accordingly. Then at the end of the frame you reset the state of all keys to “not pressed” with <code>KEYRES</code>.

<span id="Reserved_41"></span>

==== RESERVED - 41 ====

Unmapped opcode. Will throw <code>InvalidInstructionError</code> if executed.

''(Might be used as opcode for a <code>MOUSE</code> instruction which pushes the clickX and clickY position of the mouse since the last KEYRES reset)''

<br>

=== Misc ===

<span id="Get"></span>

==== GET - 42 ====

Reads data from the board and pushes it to the stack. Takes 2 arguments from the stack:

* The type Index to parse it as. It indicates the type and the direction of the data.

* The address of the first domino half

'''There are essentially 4 types you can parse it as''':

* '''Domino''': The value of the cell at the address and its connection. Essentially a single domino

* '''Unsigned Number''': A number between 0 to 2147483647 ''(Hold on! Why not 4294967295? Because the data stack uses int32 and 2147483647 is the max value you can have in the stack. “Unsigned” here doesn’t mean uint32, just that we don’t “waste” half a domino to represent the sign)''.

* '''Signed Number''': A number between -2147483648 to 2147483647 (int32 range).

* '''String''': A string is a sequence of null terminated unicode char codes.

<ins>

'''And the following directions'''

</ins>

:

* '''SingleStraightLine''': The IP moves in a straight line towards the <ins>connection direction of the cell at the address</ins>. No wrap around like in “RawIncrement” mode. If you have a 10x20 grid you can get at most 5 dominos in horizontal direction or 10 dominos in vertical direction.

* '''RawIncrement''' (to be implemented): Reads domino halfs using incrementing addresses. It disregards the grids bounds and wraps around from right edge left edge on the next line ''(Remember that addresses are essentially the indices to a 1D array of Cells which represent the Grid. Address 0 is at the top left of the grid. In a 10x10 grid, the largest address is 99 in the bottom right)''

'''Here a table of supported encoding type mappings:'''

{| class="wikitable"

! Type Index

! Type

! Direction

|-

| 0

| Domino

| connection direction

|-

| 1

| Unsigned Number

| SingleStraightLine

|-

| 2

| Signed Number

| SingleStraightLine

|-

| 3

| String

| SingleStraightLine

|-

| 4 (TODO)

| Unsigned Number

| RawIncrement

|-

| 5 (TODO)

| Signed Number

| RawIncrement

|-

| 6 (TODO)

| String

| RawIncrement

|}

<span id="Set"></span>

==== SET - 43 ====

Writes data to the board. Takes <ins>at least</ins> 2 arguments from the stack:

* The type Index to parse it as. It indicates the type and the direction of the data

* The address of the first domino half

* The data to write to the board. This can either be a single item from the stack or multiple if we write a string

<ins>

'''There are essentially 4 types you can write it as'''

</ins>

(See list under [[#Get|GET]]):

<ins>

'''And the following directions'''

</ins>

:

* '''SingleStraightLine''': The IP moves in a straight line towards the <ins>last Instruction Pointer direction</ins>. No wrap around like in “RawIncrement” mode. If you have a 10x20 grid you can set at most 5 dominos in horizontal direction or 10 dominos in vertical direction.

* '''RawIncrement''' (to be implemented): Writes domino halfs using incrementing addresses. It disregards the grids bounds and wraps around from right edge left edge on the next line ''(Remember that addresses are essentially the indices to a 1D array of Cells which represent the Grid. Address 0 is at the top left of the grid. In a 10x10 grid, the largest address is 99 in the bottom right)''

'''Here a table of supported type mappings:'''

(See table under [[#Get|GET]]):

<span id="Lit"></span>

==== LIT - 44 ====

Changes how number and string literals are parsed. It pops a number from the stack to use as the “literal parse mode”. The popped number must be between 0 to 6. If the number is out of bounds, an <code>DSInvalidLiteralParseModeError</code> is thrown.

'''If the popped argument is:'''

* <code>0</code>: Dynamic parse mode. Used by default. The first domino half of every number literal indicates how many more dominos should be parsed as part of the number. For string literals it is exactly the same but for each character.

* <code>1</code> to <code>6</code>: Static parse modes. Uses 1 to 6 dominos for each number literal or each character in a string literal.

In the following 3 examples <code>&quot;Hello world&quot;</code> is encoded in 3 different ways:

In Base7 with Literal Parse Mode 0 (default):

<pre>// Every character requires 2 dominos to be encoded on dominos

0—2 1—2 0—6 1—2 0—3 1—2 1—3 1—2 1—3 1—2 1—6 1—0 4—4 1—2 3—0 1—2 1—6 1—2 2—2 1—2 1—3 1—2 0—2 0—0</pre>

In Base 16 with Literal Parse Mode 0:

<pre>// Still every character requires 2 dominos to be encoded. Considering that we are in base 16, very wasteful!

0—2 1—0 6—8 1—0 6—5 1—0 6—c 1—0 6—c 1—0 6—f 1—0 2—0 1—0 7—7 1—0 6—f 1—0 7—2 1—0 6—c 1—0 6—4 0—0</pre>

In Base 16 with Literal Parse Mode 1:

<pre>// Every character requires 1 domino to be encoded.

// Notice how now it is pretty much just hexadecimal

0—2 6—8 6—5 6—c 6—c 6—f 2—0 7—7 6—f 7—2 6—c 6—4 0—0</pre>

As you can see, <ins>changing the default parse mode can significantly reduce the amount of dominos required to encode strings</ins>. For numbers it is less impactful but can still be significant if you are working mostly within a specific range.

<span id="Base"></span>

==== BASE - 45 ====

Pops one number from the stack to use as the “base” for future parsing of dominos (opcodes, number literals, string literals)

By default, DominoScript uses double six (D6) dominos to represent everything, so the default base is 7.

The max cell value of half of a domino is always 1 less than the Base. So in base 7, the max value is 6. In base 10, the max value is 9. In base 16, the max value is 15 (aka <code>f</code>).

If the number of dots on a domino half exceeds the max amount of possible dots for the current base, it is clamped!

For example: when you are in Base 7 and the interpreter encounters a <code>f—f</code> domino, it will be parsed as <code>6—6</code>. If you are in base 10, it will be parsed as <code>9—9</code> etc.

In below table you can see how the same domino sequence results in different decimal numbers depending on the base:

{| class="wikitable"

! Domino Sequence

! Base 7 (D6)

! Base 10 (D9)

! Base 16 (D15)

|-

| <code>0—6</code>

| 6

| 6

| 6

|-

| <code>0—9</code>

| 6

| 9

| 9

|-

| <code>0—f</code>

| 6

| 9

| 15

|-

| <code>1—6 6—6</code>

| 342

| 666

| 1638

|-

| <code>1—9 9—9</code>

| 342

| 999

| 2457

|-

| <code>1—f f—f</code>

| 342

| 999

| 4095

|-

| <code>2—6 6—6 6—6</code>

| 16806

| 66666

| 419430

|-

| <code>2—9 9—9 9—9</code>

| 16806

| 99999

| 629145

|-

| <code>2—f f—f f—f</code>

| 16806

| 99999

| 1048575

|}

With a higher Base, you have access to higher opcodes without needing to switch to extended mode.

{| class="wikitable"

! Base

! Opcode Range

|-

| 7

| 0 to 48

|-

| 10

| 0 to 99

|-

| 16

| 0 to 255

|}

While the <ins>opcode-to-instruction</ins> mapping never changes, the <ins>domino-to-opcode</ins> mapping is completely different in each base.

<span id="Ext"></span>

==== EXT - 46 ====

Toggle extended mode on or off. If extended mode is active the interpreter will use 2 dominos instead of 1 for each instruction which extends the opcode range from 0-48 to 0-2400 when using Double six dominos.

<span id="Time"></span>

==== TIME - 47 ====

Pushes the milliseconds since program start to the stack.

Useful for things like a gameloop, animations, cooldowns etc.

<span id="Noop"></span>

==== NOOP - 48 ====

No operation. The IP will move to the next domino without doing anything.

Useful to move the IP to a specific address (e.g. start of loop body) or to “reserve” space in case you think that you might need to add more instructions later on and don’t want to move dominos around.

<br>

== Navigation Modes ==

If you don't know what navigation modes are and how they influence the Instruction Pointer, I'd recommend reading the relevant section in [[#How_the_Instruction_Pointer_Moves|How the Instruction Pointer Moves]].

''(F=Forward, L=Left, R=Right)''

There are <code>49</code> total navigation modes in DominoScript. This section should reference them all.

''To be fully spec compliant an implementation should support all of them. However, when developing an interpreter, this has a rather low priority. With just the default nav mode priority (Forward, Left, Right) you can run any DS code as long as it doesn't execute the NAVM instruction to change it.''

=== Basic Three Way ===

Out of three directions, the IP will prioritize moving to the one with the highest priority.

{| class="wikitable"

! Index

! Priorities

! Domino -&gt;

|-

| 0 (Default)

| <code>Forward</code> <code>Left</code> <code>Right</code>

| <code>0—0</code>

|-

| 1

| <code>Forward</code> <code>Right</code> <code>Left</code>

| <code>0—1</code>

|-

| 2

| <code>Left</code> <code>Forward</code> <code>Right</code>

| <code>0—2</code>

|-

| 3

| <code>Left</code> <code>Right</code> <code>Forward</code>

| <code>0—3</code>

|-

| 4

| <code>Right</code> <code>Forward</code> <code>Left</code>

| <code>0—4</code>

|-

| 5

| <code>Right</code> <code>Left</code> <code>Forward</code>

| <code>0—5</code>

|-

| 6

| <code>RANDOM</code>

| <code>0—6</code>

|}

=== Basic Two Way ===

Out of two directions, the IP will prioritize moving to the one with the highest priority.

{| class="wikitable"

! Index

! Priorities

! Domino -&gt;

|-

| 7

| <code>Forward</code> <code>Left</code>

| <code>1—0</code>

|-

| 8

| <code>Forward</code> <code>Right</code>

| <code>1—1</code>

|-

| 9

| <code>Left</code> <code>Forward</code>

| <code>1—2</code>

|-

| 10

| <code>Left</code> <code>Right</code>

| <code>1—3</code>

|-

| 11

| <code>Right</code> <code>Forward</code>

| <code>1—4</code>

|-

| 12

| <code>Right</code> <code>Left</code>

| <code>1—5</code>

|-

| 13

| <code>RANDOM</code>

| <code>1—6</code>

|}

=== Basic One Way ===

IP can only move in one direction.

{| class="wikitable"

! Index

! Only Direction

! Domino -&gt;

|-

| 14

| <code>Forward</code>

| <code>2—0</code>

|-

| 15

| <code>Forward</code>

| <code>2—1</code>

|-

| 16

| <code>Left</code>

| <code>2—2</code>

|-

| 17

| <code>Left</code>

| <code>2—3</code>

|-

| 18

| <code>Right</code>

| <code>2—4</code>

|-

| 19

| <code>Right</code>

| <code>2—5</code>

|-

| 20

| <code>RANDOM</code>

| <code>2—6</code>

|}

=== Cycle Three Way ===

The direction with the highest priority becomes the least prioritized in the next cycle.

All 3 directions are available in all cycles.

{| class="wikitable"

! Index

! Cycle 1

! Cycle 2

! Cycle 3

! Domino -&gt;

|-

| 21

| <code>F</code> <code>L</code> <code>R</code>

| <code>L</code> <code>R</code> <code>F</code>

| <code>R</code> <code>F</code> <code>L</code>

| <code>3—0</code>

|-

| 22

| <code>F</code> <code>R</code> <code>L</code>

| <code>R</code> <code>F</code> <code>F</code>

| <code>L</code> <code>F</code> <code>R</code>

| <code>3—1</code>

|-

| 23

| <code>L</code> <code>F</code> <code>R</code>

| <code>F</code> <code>R</code> <code>F</code>

| <code>R</code> <code>L</code> <code>F</code>

| <code>3—2</code>

|-

| 24

| <code>L</code> <code>R</code> <code>F</code>

| <code>R</code> <code>F</code> <code>L</code>

| <code>F</code> <code>L</code> <code>R</code>

| <code>3—3</code>

|-

| 25

| <code>R</code> <code>F</code> <code>L</code>

| <code>F</code> <code>L</code> <code>R</code>

| <code>L</code> <code>R</code> <code>F</code>

| <code>3—4</code>

|-

| 26

| <code>R</code> <code>L</code> <code>F</code>

| <code>L</code> <code>F</code> <code>R</code>

| <code>F</code> <code>R</code> <code>L</code>

| <code>3—5</code>

|-

| 27

| (unmapped)

| (unmapped)

| (unmapped)

| <code>3—6</code>

|}

=== Cycle Two Way ===

The direction with the highest priority becomes the least prioritized in the next cycle.

Only 2 directions are available in a single cycle.

{| class="wikitable"

! Index

! Cycle 1

! Cycle 2

! Cycle 3

! Domino -&gt;

|-

| 28

| <code>F</code> <code>L</code>

| <code>L</code> <code>R</code>

| <code>R</code> <code>F</code>

| <code>4—0</code>

|-

| 29

| <code>F</code> <code>R</code>

| <code>R</code> <code>F</code>

| <code>L</code> <code>F</code>

| <code>4—1</code>

|-

| 30

| <code>L</code> <code>F</code>

| <code>F</code> <code>R</code>

| <code>R</code> <code>L</code>

| <code>4—2</code>

|-

| 31

| <code>L</code> <code>R</code>

| <code>R</code> <code>F</code>

| <code>F</code> <code>L</code>

| <code>4—3</code>

|-

| 32

| <code>R</code> <code>F</code>

| <code>F</code> <code>L</code>

| <code>L</code> <code>R</code>

| <code>4—4</code>

|-

| 33

| <code>R</code> <code>L</code>

| <code>L</code> <code>F</code>

| <code>F</code> <code>R</code>

| <code>4—5</code>

|-

| 34

| (unmapped)

| (unmapped)

| (unmapped)

| <code>4—6</code>

|}

=== Cycle One Way ===

The direction with the highest priority becomes the least prioritized in the next cycle.

Only 1 direction is available in a single cycle.

{| class="wikitable"

! Index

! Cycle 1

! Cycle 2

! Cycle 3

! Domino -&gt;

|-

| 35

| <code>F</code>

| <code>L</code>

| <code>R</code>

| <code>5—0</code>

|-

| 36

| <code>F</code>

| <code>R</code>

| <code>L</code>

| <code>5—1</code>

|-

| 37

| <code>L</code>

| <code>F</code>

| <code>R</code>

| <code>5—2</code>

|-

| 38

| <code>L</code>

| <code>R</code>

| <code>F</code>

| <code>5—3</code>

|-

| 39

| <code>R</code>

| <code>F</code>

| <code>L</code>

| <code>5—4</code>

|-

| 40

| <code>R</code>

| <code>L</code>

| <code>F</code>

| <code>5—5</code>

|-

| 41

| (unmapped)

| (unmapped)

| (unmapped)

| <code>5—6</code>

|}

=== Flip Flop ===

The priority flip flops between 2 primary directions.

{| class="wikitable"

! Index

! Flip

! Flop

! Domino -&gt;

|-

| 42

| <code>F</code>

| <code>L</code>

| <code>6—0</code>

|-

| 43

| <code>F</code>

| <code>R</code>

| <code>6—1</code>

|-

| 44

| <code>L</code>

| <code>F</code>

| <code>6—2</code>

|-

| 45

| <code>L</code>

| <code>R</code>

| <code>6—3</code>

|-

| 46

| <code>R</code>

| <code>F</code>

| <code>6—4</code>

|-

| 47

| <code>R</code>

| <code>L</code>

| <code>6—5</code>

|-

| 48

| (unmapped)

| (unmapped)

| <code>6—6</code>

|}

<br>

== Example: Factorial ==

<br>[[File:DominoScript-Example-Factorial-flow.png|thumb|Factorial Example with IP flow visualized]]

'''Pseudocode:'''

<pre style="overflow:auto;>

NUM 12

NUM 42 CALL

NUMOUT // prints 479001600

FUNCTION FACTORIAL: // (address 42)

DUP NUM 0 EQ

IF:

POP

NUM 1

ELSE:

DUP NUM 1 SUB

NUM 42 CALL // recursive call

MUL

</pre>

'''DominoScript:'''

<pre style="letter-spacing:4px;line-height:1.1;overflow:auto;">

0—1 . . . . . 1—0 1—0 0 . . . 2—1 4—4 0

| |

0—1 . . . . . . . . . 0 . . . . . . . 6

1 . 0—3 0—1 0—0 2—3 4—1 . . . . . . . 0

| |

5 . . . . . . . . . . 0 . . . . . . . 1

|

0—1 1—0 6—0 4—4 5—1 . 3 0—1 0—1 1—1 0—1

</pre>

== Example: WASD Controls ==

Demonstrates `WASD` keyboard inputs that move a character around on a 5x7 grid and renders it via stdout.

It could be used as a basis to build a simple game.

[[File:DominoScript-Example-WASD-Input-Example-Flow.png|thumb|WASD Controls example with IP flow visualized]]

'''Pseudocode''':

<pre style="overflow:auto;font-size:0.85em;>

NUM 16 BASE // tell interpreter to use dominos with up to 16 dots per side. Allowing you to use less dominos

// Binding addresses to labels

NUM 116 LABEL // playerX -1

NUM 122 LABEL // playerY -2

NUM 1008 LABEL // topRow = "╭──────────────╮\n" -3

NUM 1080 LABEL // middleRow = "│ │\n" -4

NUM 1152 LABEL // bottomRow = "╰──────────────╯\n" -5

NUM 72 LABEL // function main() -6

NUM 361 LABEL // function update() -7

NUM 505 LABEL // function render() -8

NUM 660 LABEL // loop body start within render() -9

NUM 6 NEG CALL // main()

FUNCTION main:

NUM 1 LIT // tell interpreter that we use exactly 1 domino for each number or character in a string

LOOP_FOREVER:

NUM 50 WAIT // wait 50ms

PUSH 7 NEG CALL // update()

PUSH 8 NEG CALL // render()

NUM 6 NEG JUMP // jump back to start of main

FUNCTION update:

STR "w" KEY IF:

NUM 1 NUM 2 NEG GET NUM 1 SUB NUM 1 NUM 2 NEG SET // y = y - 1

STR "a" KEY IF:

NUM 1 NUM 1 NEG GET NUM 2 SUB NUM 1 NUM 1 NEG SET // x = x - 2

STR "s" KEY IF:

NUM 1 NUM 2 NEG GET NUM 1 ADD NUM 1 NUM 2 NEG SET // y = y + 1

STR "d" KEY IF:

NUM 1 NUM 1 NEG GET NUM 2 ADD NUM 1 NUM 1 NEG SET // x = x + 2

NUM 1 NUM 1 NEG GET NUM 2 NUM 13 CLAMP NUM 1 NUM 1 NEG SET // x = clamp(x, 2, 13)

NUM 1 NUM 2 NEG GET NUM 2 NUM 6 CLAMP NUM 1 NUM 2 NEG SET // y = clamp(y, 2, 6)

KEYRES

FUNCTION render:

STR '\033[2J\033[H' STDOUT // clear screen and move cursor to top left

NUM 0 // iterator = 0;

LOOP:

DUPE NUM 0 EQL IF: // if (iterator === 0)

NUM 3 NUM 3 NEG NUM 2 LIT GET STROUT NUM 1 LIT // render Top row string if on row 0

DUPE NUM 8 EQL IF: // if (iterator === 8)

NUM 3 NUM 5 NEG NUM 2 LIT GET STROUT NUM 1 LIT // render Bottom row string if on row 8

DUPE DUPE NUM 2 GTR NUM 1 ROLL NUM 7 GTR NOT AND IF: // if (iterator > 2 && iterator < 7)

NUM 3 NUM 4 NEG NUM 2 LIT GET STROUT NUM 1 LIT // render Middle row string if on row 1-7

NUM 1 ADD // iterator = iterator + 1

DUPE NUM 8 EQL IF:

// Hacky way to achieve the equivalent of: stdout.write(`\033[${playerY};${playerX}H[]`)

// The string is constructed 1 char at a time in reverse order using NUM

NUM 0 NUM 93 NUM 91 NUM 72 NUM 1 NUM 1 NEG GET NUM 31 NUM 59 NUM 1 NUM 2 NEG GET NUM 31 NUM 91 NUM 27 STROUT

POP // remove iterator from stack

BREAK // exit loop if we've reached the bottom row

NUM 9 NEG JUMP // jump back to start of loop

</pre>

'''DominoScript''':

<pre style="letter-spacing:2px;line-height:1.1;overflow:auto;font-size:0.85em;">

0—1 1—0 2—2 6—3 0—1 1—0 7—4 1—e 0—1 1—0 7—a 1—e 0—1 1—3 f—0 1—e 0—1 1—4 3—8 1—e 0—1 1—4 8—0 1—e 0—1 1—0 4—8 1—e 0—1 1—1 6—9 1—e 0—1 1—2 8—8 1—e

0—1 0—1 2—c 0—1 3—2 2—2 0—1 0—7 0—c 2—0 0—1 0—8 0—c 2—0 0—1 0—6 0—c 1—f . . . . . . 0—0 0—8 . . 0—0 0—4 . . . . 0—2 c—0 6—0 1—0 e—1 4—9 2—1 1—0

0—8 0—1 0—1 0—1 0—2 0—c 2—b 3—0 3 . 0—8 0—1 0—1 0—1 0—1 0—c 2—b 3—0 3 . 0—7 0—1 0—1 0—1 0—2 0—c 2—b 3—0 3 . 0—7 0—1 0—1 0—1 0—1 0—c 2—b 3—0 3 .

| | | |

1 . . . . . . . . . . . . . . . 0 . 2 . . . . . . . . . . . . . . . 0 . 1 . . . . . . . . . . . . . . . 0 . 2 . . . . . . . . . . . . . . . 0 .

| | | |

0 1—0 a—2 c—0 2—0 1—0 1—0 1—0 d 3 . 0 1—0 a—2 c—0 1—0 1—0 1—0 1—0 d 3 . 0 1—0 a—2 c—0 2—0 1—0 1—0 1—0 d 3 . 0 1—0 a—2 c—0 1—0 1—0 1—0 1—0 d 3 .

| | | | | | | |

. 3—0 3—0 3—0 0—2 7—7 0—0 2—7 1 0 3—0 3—0 3—0 3—0 0—2 6—1 0—0 2—7 1 0 3—0 3—0 3—0 3—0 0—2 7—3 0—0 2—7 1 0 3—0 3—0 3—0 3—0 0—2 6—4 0—0 2—7 1 0 3

|

2 0—3 0—3 b—2 c—0 2—0 1—0 1—0 . . 6—0 1—0 2—0 1—0 a—2 c—0 2—0 1—0 . . 0—3 0—3 0—3 b—2 c—0 1—0 1—0 1—0 . . e—0 1—0 2—0 1—0 a—2 c—0 1—0 1—0 . . 0

|

8 . 5—b 3 . 5—b 4 . 0—1 0 . 1—0 d—0 . . 0—1 0—3 0—3 0—c 0—1 0 . 1—0 1—0 0—1 0 . . . 3—0 3—0 1 . . . 1—0 d—0 2—a 0 . 0—2 0 . 1—b 2 . . . 1—0 1—0

| | | | | | | | |

. . b . 2 . b . 8 . 6 . 0 . . 0—0 1—1 1—d 0 c—2 1—0 0—0 1—0 2 2 . 2—a 2—6 . 0 0 . 1—1 . . 0 d 0—1 . . . . . c . 1 . 1 . c . 1 . 6 . . . . . . .

| | | | | | | | | |

0—2 1 . 4—a 1 . 0—0 2 . 0—3 0—1 . . . 3—0 3 . . . . 0—1 0 6 . c 2—c . . . . . 1 . 9 . . 0 1 . . 0 . 0—1 4 . 0 . 1 . 0 . 2 . 0 . 0 . . . . . . .

| | | | | | | | |

. . . . . . . . . . . . . 1 1—1 8—0 1—0 0—3 . . . 0—3 . 4 2 a—2 2 . . 3 0—3 c—2 . 0 . 0 9 . . . 0 . b . 8 . 1 . f . 1 . a . b . 0 . . . . . . .

| | | | | | | |

. 0—3 0—3 0—3 0—3 0—3 0—3 d 0—1 0—3 0—1 0—5 3—0 . 1 . . 0—c 0—1 0 . . 0 . . 0—3 0—1 . c . . . . 0 . 5 . 0 . 0 . 0 . 0 . 0 . 5 . . . . . . . . .

| | | | |

3—0 c—2 1—0 0—0 1—0 6—2 a—2 c—2 2—0 1—0 c—0 0—3 . 0 d 3—0 3—0 3—0 3—0 0—1 . 7 . . . f—1 . . . . 1 . 1 . 1 . 1 . 1 . 1 . 1 . 1 . . . . . . . . .

| | | | | |

0—3 0—1 0—2 1—2 0—1 0—1 0—4 0—1 0—7 1—2 0—e 0—f 3—0 1 . . . . . . . . . 0—1 0 . . . . . . . . . 5—d 0 . 0—1 0 . 3—b 0 . 1—f 0 . . . . . . . . .

2—5 6—d 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 6—e 0—0 0—a 0—0 0—0

2—5 0—2 0—0 2—0 0—0 2—0 0—0 2—0 0—0 2—0 0—0 2—0 0—0 2—0 0—0 2—0 0—0 2—0 0—0 2—0 0—0 2—0 0—0 2—0 0—0 2—0 0—0 2—0 0—0 2—0 2—5 0—2 0—0 0—a 0—0 0—0

2—5 7—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 0—0 2—5 6—f 0—0 0—a 0—0 0—0

</pre>

==External resources==

* [https://dominoscript.com Website with code playground]

* [https://github.com/andreas-schoch/dominoscript GitHub Repository containing reference implementations, examples and documentations]

[[Category:Languages]]

[[Category:Stack-based]]

[[Category:Implemented]]

[[Category:Self-modifying]]

[[Category:Turing complete]]

[[Category:Low-level]]

[[Category:Thematic]]

[[Category:2024]]