MC5000
MC5000 is a Craftbook IC that is programmable using Perlstone language.
Details

Unlike other ICs, MC5000 doesn't take any arguments from its sign, instead it tries to retrieve Perlstone code from two possible sources
- Written Book
- MC5000 expects chest directly above or below itself with single written book in it that contains Perlstone code. If there is chest both above and below the one that is above will be used. It is usually preferred for the chest to be above, as that way it can be locked by placing block on top of it to prevent anyone from stealing the book.
- Sign Column
- MC5000 expects that on the same X, Z position as itself there exist column of signs with sign that has
[Code Block]on its 2nd line on the very top of that column, the Perlstone code is then being read from top to bottom starting from the first sign below[Code Block]sign and ending on the first block that isn't a sign. As relative Y distance between MC5000 and[Code Block]sign doesn't matter, this method can be used to create many MC5000 ICs that all take code from the same source.
MC5000 operates on 3 inputs and has 1 output, anytime any of its input changes Perlstone code gets executed and output pin gets set according to user defined code.
Perlstone
Perlstone is a stack based programming language that's used in MC5000, it operates solely on boolean values.
Stack
The most essential part of Perlstone is its execution stack that is used by almost every single instruction. Stack is a data structure that primarily uses two operations: push to put value on top of the stack and pop to remove the value on top of the stack (the one that was most recently pushed). Huge chunk of Perlstone instructions are dedicated solely for manipulating values on the stack and evaluating boolean expressions, these are:
+and-for pushing true and false values on top of the stack.pfor popping value from top of the stack.|,&,^and=for performing OR, AND, XOR and XNOR operations on two topmost values of the stack.dfor duplicating the value on top of the stack andvfollowed by a digit n to duplicate value that is n values deep down the stack.xfor swapping top two values of the stack with each other.!for inverting value on top of the stack.
Input/Output
Every time MC5000 gets triggered (i.e. any of its input changes) the first function in the user defined code gets run,
in that code its possible to check if each of the 3 inputs are powered by using A B and C instructions,
each one of those instructions push value that correspond to the input onto the stack. The MC5000 output is simply the return value of the first function
that was called by MC5000.
Variable Tables
Key feature of Perlstone are variable tables which allow storing values outside of the stack, those values can be loaded using L instruction and stored using S instruction, there are 3 types of variable tables
- Persistent Table referenced by
P - Values in this table persist across different executions (but are unique for each MC5000) and are global - meaning that the same table can be used from any function.
- Temporary Table referenced by
T - Values in this table are global, but aren't persistent - meaning every time MC5000 calls first function those values get initialized to false.
- Local Table referenced by
L - Values in this table only exist in the context of currently running function - meaning that when another function is called new table gets created and the previous table become inaccessible (until the execution is returned to the previous function)
- Shifted Tables referenced by
p,tandl - Additionally there exist mirrored versions of those tables referenced by their lowercase counterparts, they represent exactly the same values but positions of those values are shifted through the use of
<and>instructions and reset usingeinstruction, those shifting offsets aren't persistent and are only local to the current function.
Positions in the tables are indexed by digits 0-9 and letters a-v, allowing for up to 32 variables per table.
Function Calls
Perlstone code can be split into multiple functions by separating them with : character. Functions can be called using c instruction, it requires 2 digit function index (the index starts at zero therefore first function would be 00) and 1 digit argument count. When function is called specified number of values are popped (specified by argument count) from the stack and new execution stack is constructed and populated by the popped values then the execution resumes at the specified function. Returning from functions can be done using s instruction that returns with no return value or using r which pops value off the stack and returns it, execution is then returned to the call site and return value is pushed onto the original stack (if one was returned).
Additionally there exists another way of calling functions using the tail call instruction t, this instruction works the same way as c instruction, with one caveat - it doesn't preserve call site and original stack, meaning that when MC5000 calls function 00 and that function tail calls function 01 and that function returns true value, the execution isn't continued at function 00 but rather its treated as if the return instruction happened inside function 00, and since that function was called by MC5000 the execution gets finished and return value is used to set output pin.
Conditional Branching and Loops
All conditional execution in Perlstone is done through
[ and ] instructions, those instructions work in pairs meaning opening bracket requires closing bracket and each closing bracket requires opening bracket, they can be thought from higher level as programming statement that encloses code block inside them, however each of those instructions perform slightly different operation. When Perlstone interpreter encounters [ instruction it pops value of the stack and if that value is false it jumps to the corresponding closing bracket (outside ]) effectively skipping any code inside the code block, if its true it enters that code block. When it encounters ] instruction it pops value of the stack and if that value is true it jumps to the corresponding closing bracket (inside the code block) effectively creating a loop, if that value were false it would exit the current code block.
Perlstone functionality of
A[...B]
can be better understood by equivalent statement in Java.
if (A) {
do {
...
} while (B)
}
- It can be deduced that:
- If
Bis always false the statement effectively becomes if statement. - If
Ais always true the statement effectively becomes do while loop. - If
AandBare the same expression the statement effectively becomes while loop. - If
AandBare always true the statement effectively becomes infinite loop.
Perlstone instruction reference table
| Instruction | Operands | Description | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Stack | |||||||||||||||||
| + | Pushes true value on the stack. | ||||||||||||||||
| - | Pushes false value on the stack. | ||||||||||||||||
| d | Duplicates value on top of the stack. | ||||||||||||||||
| v | n | Peeks stack n values deep and pushes that value on top of the stack. | |||||||||||||||
| x | Swaps two values on top of the stack. | ||||||||||||||||
| p | Pops value off the stack. | ||||||||||||||||
| ! | Inverts the value on top of the stack. | ||||||||||||||||
| | | Pops two value off the stack and performs OR operation on them and pushes the result. | ||||||||||||||||
| = | Pops two value off the stack and performs XNOR operation on them and pushes the result. | ||||||||||||||||
| & | Pops two value off the stack and performs AND operation on them and pushes the result. | ||||||||||||||||
| ^ | Pops two value off the stack and performs XOR operation on them and pushes the result. | ||||||||||||||||
| . | abcd | Pops X and Y off the stack and pushes value according to the following truth table:
abcd can composed of | |||||||||||||||
| Input | |||||||||||||||||
| A | Pushes value of middle input as boolean value. | ||||||||||||||||
| B | Pushes value of left input as boolean value. | ||||||||||||||||
| C | Pushes value of right input as boolean value. | ||||||||||||||||
| Table | |||||||||||||||||
| S | t i | Pops value off the stack and stores it in table t at the index i. | |||||||||||||||
| L | t i | Pushes value from table t at the index i on the stack. | |||||||||||||||
| < | t | Shifts table t by 1 to the left. | |||||||||||||||
| > | t | Shifts table t by 1 to the right. | |||||||||||||||
| e | t | Resets t's table shift. | |||||||||||||||
| Control Flow | |||||||||||||||||
| c | ff n | Pops n values off the stack and calls function ff with the popped values as arguments. | |||||||||||||||
| t | ff n | Pops n values off the stack and tail calls function ff with the popped values as arguments. | |||||||||||||||
| r | Pops value off the stack and returns from the current function using that value as return value. | ||||||||||||||||
| s | Returns from the current function with no return value. | ||||||||||||||||
| [ | Pops value off the stack if its false jumps to its closing bracket ].
| ||||||||||||||||
| ] | Pops value off the stack if its true jumps to its opening bracket [.
| ||||||||||||||||
| : | Marks the end of a function. | ||||||||||||||||
Examples
2 input AND/OR Circuit that switches between being either AND or OR depending on its middle input.
BC| A! & BC& A & | r
Circuit that becomes OR gate when all its input are ON and becomes AND gate when all its inputs are OFF.
c010 c020 r : A B & C & [ + SP0 -] A! B! & C! & [ - SP0 -] s : LP0 [ A B | C | r ] A B & C & r
Function that clears entire persistent table.
+ Sl0 + [ - Sp0 <p <l Ll0!]
Function that calls function at index 04 with no arguments 5 times (assuming no return value).
- + + + + + [c040]
Function that returns True if calling function at index 04 returns with value (i.e. r is used as opposed to s)
- + c040 p r