SBF Documentation

Scratch Binary Format is important to understand to be able to create compilers and create implementations of it.

Generally, a byte is used to refer to an instruction, but push instructions contain more.

Primary Instructions

Primary instructions are implemented simply by using a single byte.

These instructions are mapped from ScratchForth instructions to the numbers of the bytes they are represented by at https://github.com/AmazingMech2418/ScratchForth/blob/main/src/functions.js

Primary instructions use the stack to obtain parameters and return results.

Special Instructions

Special instructions are instructions 1 and 32.

69 and 87 are reserved, but not implemented. These are for the wait until and () of () blocks

Instructions 1 and 32 allow you to push strings and characters respectively. Note that both push to the stack in the same way, so a character push is a more efficient way if you have a one-character string you need to push to the stack.

pushc

pushc refers to instruction 32, which pushes a character to the stack.

pushc contains a single byte after the instruction byte, which represents the character to push.

Note that these characters are based on the Scratch charset, which can be found at https://github.com/AmazingMech2418/ScratchForth/blob/main/resources/CHARS.txt where the character "1" is represented by a number 1, as it is the first character. (this text file is a Scratch list)

For instance, if you wanted to push a lowercase letter "a" (char 44), you would use this:

00100000 00101100

pushs

pushs refers to instruction 1, which pushes a string.

While pushc only has one byte following the instruction byte, pushs has at least 1, but often more.

pushs uses a series of character bytes, terminated with 00000000. For example, "hi" (all lowercase) would be represented as this:

00000001 00110011 00110100 00000000