This is the (work in progress) specification for the 1-Dimensional Stack Turtle (1DST). It is inspired from CFRS[], Uxn and brainfuck, intended for display on an adressable LED strip, such as in one of my 2023 December Adventure projects. It works by reading instruction sequences controlling a virtual stack machine which controls the turtle.
The Environment
The Machine
The virtual machine has an argument stack. Every instruction except { takes an argument N from the stack. N is an unsigned 8-bit integer, it can represent values ranging from 0 to 255.
There is no maximum stack depth, so it will depend on the implemented VM's available memory, same goes for maximum loop nesting. An instruction that tries to pop from an empty stack consistently gets a value of 0, but an error message indicationg a stack underflow occured must be emitted.
Every unrecognized instruction is ignored.
The Language
Writing an instruction's character means it will be executed when read. Writing a number in decimal between 0 and 255 will push it onto the stack. Two adjacent integer literals need to be separated with whitespace.
The language is case sensitive, F and f are seen as different. Here, a lowercase version of a turtle command will mean that command will be executed one time. For example, c is the same as 1C.
The Canvas
The color palette and canvas sizes are up to the implementer, so is the tick rate. The color palette and canvas are circular, the color and turtle wrap around when trying to go out of bounds.
The Instructions
Instruction Set Summary
The instructions that control the turtle are the following:
The instructions that define control flow are the following:
C: Change Color
This instruction pops an argument N from the stack and rotates the color palette N times. In an 8-color palette, 8C has no effect and 7C rotates the palette backwards once.
The lowercase version c only rotates the palette once.
F: Go Forward
With this command, the turtle will move one cell forward in the current direction, filling the previous cell it was on with the currently selected color.
The lowercase f only does this once.
R: Reverse Direction
The 1-dimensional equivalent of rotating the turtle is reversing its direction, or making a U-turn, if you will. By default, the turtle goes forward in the positive direction of the axis, executing r would make it go towards the negative direction.
The lowercase version r only reverses direction once. It's the most commonly used. The uppercase version can be used for a conditionnal reverse, meaning it will reverse if N is odd, and not if N is even.
S: Sleep
When encountered, this command will make the turtle wait for N frames before executing instructions that follow. As the tickrate depends on the implementation, so does sleep duration.
The lowercase s only sleeps once.
[: Loop
When encountered, a [ will pop N from the stack and run instructions between it and its matching ] N times. It can also be used as an "if": when N is zero, it skips the content of the loop, this behavior can be leveraged to write comments inside "zero loops", 0[Here is an example].
{: Loop Forever
When encountered, a { will run any instructions between it and its matching } for all eternity. It is advised to always sleep at least once inside an infinite loop, in order not to stall the turtle's process.
Examples
This section provides 1DST code bits to help programmers get an idea of how to write programs.
In this section, we assume the LED strip is 60 LEDs long, the color palette is white, black, red, yellow, green, cyan, blue, magenta, and the framerate is 50 Hz.
Example 01: All colors blink
0[Flash all colors]
{
60F
c
50S
}
Example 02: Colors sweep
0[Show all colors
in a sweeping back-and-forth pattern]
{
59[fs]
cr
}
Example 03: Light chase
0[White lights
follow each other]
{
12 [
fc
4F
7C
]
3S
f
}