ASMbot reference manual

ASMbot allows you to control a simple robot on a 2D grid.

ASMbot is controlled using programs written using a custom assembly-like language. This document gives an overview of the language syntax as well as all the available instructions and their behavior.

Syntax

Each line is an instruction. An instruction consists of tokens separated by spaces. The first token is a mnemonic that denotes the instruction, any remaining tokens are arguments.
Arguments can be either addresses (e.g. [123] is the memory address 123) or literals (e.g. 123 is a literal value of 123).

All values in the VM are integers. Results of computations and other values are stored in one contiguous memory space that is addressed using integer addresses. Reading from a memory address that has never been assigned to causes an error.
Note: Memory addresses can be both negative and positive. Negative addresses do not denote indexing from the end of the memory space, but are distinct memory locations.

Comment lines begin with // and are skipped when executing the program. Blank lines inside the program are forbidden.
Note: All lines, including comment lines, are counted when calculating instruction offsets for jz.

Instructions

Notation:

• (value) - The argument is interpreted as a value. For example 32 means the value 32 and [32] means the value at address 32.
• [address] - The argument is interpreted as an address. For example 32 means the address 32 and [32] means the value at address 32 as an address. Note in particular the common [target] argument: For target arguments the address that is written to is the value of the argument. For example if the value 10 is currently stored at address 32, then a target of 32 stores the result at address 32 and a target of [32] stores the result at address 10.
• <message> - The argument is interpreted as a token literal. Can be any unquoted string without whitespace e.g. a[100]:error_out_of_bounds.
• ... - Denotes varargs parameter. A varargs parameter can take a variable number of arguments (0 or more).

Note: The square, round and angle brackets around arguments are just a notation used in this reference manual. They should not be used when writing programs. (Note that square brackets are used when writing programs, but they have a different meaning.)

Available instructions:

• light (color) - Lights up the current tile that the robot is at in the color color.
  Available color values are:
  • 0 - off
  • 1 - white
  • 2 - red
  • 3 - green
  • 4 - blue
  • 5 - yellow
  • 6 - pink
  • 7 - cyan
  • 8 - orange
  • 9 - purple
• sense [target] - Detects the light of the current tile and stores it in target. The possible values detected are the same as the color argument of light.
• movex [target] (dx) - Moves the robot dx tiles in the horizontal direction. Positive dx is right and negative dx is left. Writes the number of tiles moved to target. (Note that this may differ from dx if a wall is in the way.)
• movey [target] (dy) - Moves the robot dy tiles in the vertical direction. Positive dy is down and negative dy is up. Writes the number of tiles moved to target. (Note that this may differ from dy if a wall is in the way.)
• store [target] (value) - Writes the value value to target.
• read [target] [address] - Reads the value at address address and writes it to target. Note that the address that is read from is the value of address. For example if the value 10 is stored at address 32 then read 123 [32] reads the value at address 10.
• jz (count) (value) - Jumps count instructions if value is 0. count can be positive or negative. Note that during a jump normal instruction counter incrementing doesn't happen, so jz 0 0 gets stuck in an infinite loop instead of continuing to the next instruction.
• cmp [target] (a) (b) - Compares the values of a and b and writes the result to target. The result is -1 if a < b, 0 if a == b and 1 if a > b.
• calc [target] (op) (a) (b) - Applies the binary operation op to the values of a and b and writes the result to target.
  Available operations are:
  • 0 - add
  • 1 - subtract
  • 2 - multiply
  • 3 - divide (usual integer division rules apply i.e. fractional part is truncated)
  • 4 - remainder (equivalent to JS % operator; the property a / b * b + a % b == a holds)
  • TODO: Add various bit manipulation operations?
• error <message> (arg)... - Terminates program with error message message. Additional integer arguments can be provided and will be shown together with the message.

Performance

The current VM provides no hard gurantees about performance. However, speeds of up to 5M instructions/seconds have been observed when rendering pauses are reduced to a minimum. The current VM takes comparatively frequent rendering pauses to ensure responsiveness. Because of this approximately 840k instructions/second can be executed when 5x speed is activated. (These results were obtained on a relatively modest school-provided laptop.)

Also note that because of restrictions placed on background processing by browsers the VM tends to stop/slow down dramatically when it is not visible on the screen (running in a background tab or minimized).

Some performance statistics are logged to the debug console when the VM is running. However, note that having the debug console/DevTools open while the VM is running can significantly reduce performance.