BOX-256 is a 8-bit fantasy computer, with 256 bytes of memory, 16 color 16x16 display. It is also a programming game, where the player tries to pass the graphics tests and optimize the code to perfection. The ultimate goal is to use as few CPU cycles or lines of code as possible, by employing multithreading and other optimization tricks.

Player writes the source code, executes the machine and tries to match the target output (bottom screen), with program output (top screen), with least amount of CPU cycles possible.

When the computer is not executing, the compiler tries actively to compile the source to machine code. This can be seen as memory changing, while the user is writing code. The execution can be started from the bottom using the PLAY button. It goes on forever, unless a) player stops it with STOP or STEP or b) the output screen matches the target and the level is passed.

If you want more challenge, cycle through the available levels with PREV and NEXT buttons.

Unfortunately WebGL doesn't directly support clipboard, but the game uses popup windows to give you ability to import & export code indirectly.

In the web version, clicking the SAVE button will open up a popup with your entire source code in it so you can copy it into your clipboard. In the standalone version there is no popup, but the source code is moved straight into clipboard.

Loading works similarly. In the web version you'll get a popup where you can paste your code and click load button to move it into the game. In the standalone version, clicking LOAD tries to load whatever text is in your clipboard currently.

NOTE: In the web version, drag-selecting text with mouse doesn't work. You have to use SHIFT+arrow keys to do it.

SHIFT+arrow keys lets you select code and CTRL-C & CTRL-V for copy-pasting. CTRL-Z and CTRL-Y for undo and redo. Use insert/delete/backspace/enter to move stuff around, too. For the expert players and people with weird keyboard layouts, the '@' and '*' characters can be also typed with comma (,) and period (.) hotkeys.

Hovering over memory or output screen gives you the address of the currently hovered slot.

Source code is compiled to machine code in 4 byte chunks. In other words, the machine code is based on a fixed width instruction set. However, some instructions do not use all of the 4 bytes. Clever player may use this to her advantage. Note that even with the fixed width set, it is possible to force the program counter anywhere in memory, regardless of machine code alignment.

When the execution starts, the last memory slot (FF) is used as a program counter (PC). If a second thread is started, the additional PC will be in FE, the third will be in FD and so on. Since there is no memory protection, it is possible to write into PC directly and cause execution to jump. The behaviour is identical to using JMP instruction.

It is possible to start multiple threads with THR instruction. The threads are not really simultaneous and they are executed one after another. It is counted as single cycle for score keeping purposes. The memory reads for each thread are identical and based on the memory state cached at the beginning of the cycle. For conflicting writes to same memory address, the thread that writes last is the winner.

Because of cached reads, it is generally not possible for one thread to communicate with other thread simultaneously. HOWEVER two exceptions remains: An earlier thread can write to memory address later executed by later thread. So self-modifying code is possible. An earlier thread can also write to program counter (PC) owned by a later thread to cause an immediate jump.

There are three different prefixes in source code:

0 = Constant value
@ = Address in memory
* = Address pointed by another address (a.k.a pointer)

Example:

There is no memory protection whatsoever. All executable machine code, your own variables and program counters happily co-exist in the same 00-FF memory space. You can read and write everywhere and everytime, as long as you live with the consequences :).

Creating your own level is done by using the BOX-256 computer. You need to make a program that outputs the new level into output display, and then press the URL button.

Popup will open that has an URL to the new level which is based on your current output display.

NOTE: You can pause execution during playback pressing STEP!

You can share the URL to other players. Clicking the URL opens the game with only your custom level available, titled as "CUSTOM".

In the standalone version, there is an extra button OPEN. By first copying the URL of a custom level into clipboard, and then clicking OPEN, you can open a custom level.

The language consists of 11 possible instructions. These are compiled into 120 different opcodes by the compiler. Most of the different opcodes are just different permutations of the same instruction.

MOV A B C

Sets the value A into memory address B.

The parameter C can be used as length for arrays, when multiple values are moved at once.

JMP A

Jumps the execution into A.

If A is a constant, it is an offset from current execution address, otherwise it is considered as an absolute address. It is normally a good idea to jump in multipliers of 4, because the instruction set is fixed width and the next instruction (usually) sits in the next 4 bytes.

Note that you can prefix the A with minus '-' to get negative values. They are not compiled negative in machine code, but JMP -1 compiles to JMP FF. This works, because the memory is exactly 256 bytes long and jumping FF means jumping through the entire memory and landing on to the previous memory address.

PIX A B

Outputs a pixel into index A with color B.

The screen is 16x16 consisting of 256 pixels. The index grows left to right, top to bottom. The top-left index is 0, and bottom-right is 255. The available colors are from 0 to F, but it is fine to output value bigger than that, since the palette keeps cycling through.

JEQ A B C

If A equals B, the execution jumps to C.

If C is a constant, it is an offset from current execution address, otherwise it is considered as an absolute address. It is normally a good idea to jump in multipliers of 4, because the instruction set is fixed width and the next instruction (usually) sits in the next 4 bytes.

Note that you can prefix the C with minus '-' to get negative values. They are not compiled negative in machine code, but JMP -1 compiles to JMP FF. This works, because the memory is exactly 256 bytes long and jumping FF means jumping through the entire memory and landing on to the previous memory address.

JNE A B C

If A doesn't equal B, the execution jumps to C.

If C is a constant, it is an offset from current execution address, otherwise it is considered as an absolute address. It is normally a good idea to jump in multipliers of 4, because the instruction set is fixed width and the next instruction (usually) sits in the next 4 bytes.

Note that you can prefix the C with minus '-' to get negative values. They are not compiled negative in machine code, but JMP -1 compiles to JMP FF. This works, because the memory is exactly 256 bytes long and jumping FF means jumping through the entire memory and landing on to the previous memory address.

JGR A B C

If A is greater than B, the execution jumps to C.

If C is a constant, it is an offset from current execution address, otherwise it is considered as an absolute address. It is normally a good idea to jump in multipliers of 4, because the instruction set is fixed width and the next instruction (usually) sits in the next 4 bytes.

Note that you can prefix the C with minus '-' to get negative values. They are not compiled negative in machine code, but JMP -1 compiles to JMP FF. This works, because the memory is exactly 256 bytes long and jumping FF means jumping through the entire memory and landing on to the previous memory address.

FLP A B C

Flips the values between memory address A and memory address B.

The parameter C can be used as length for arrays, when multiple values are flipped at once.

THR A

Starts a new thread from memory address A

This means that the executable machine code instruction you want the new thread to start executing is sitting in memory address A.

ADD A B C

Adds values A and B together and stores the result in C

SUB A B C

Subtracts B from A and stores the result in C

MUL A B C

Multiplies values A and B together and stores the result in C

DIV A B C

Divides A with B and stores the result in C

Division with zero (0) always evaluates to 0.

MOD A B C

Take modulo of A and B and place the result in C

Modulo with zero (0) always evaluates to 0.

The instructions in source code are compiled into machine code opcodes in the memory. These opcodes are the actual commands that the computer executes. An expert player can code programs directly by writing these values into the editor. It is also possible to change the executed memory at runtime, so everything is possible if you know what the different opcodes do.

Most of the opcodes are permutations of the same instruction. For example the ADD instruction has 8 different opcodes, depending on the 'memory depth' of the parameters.

There are three different 'depths' of parameter. Constant (0), Address (@) and pointer (*).