Gammaplex Programming Language v0.34

By Lode Vandevenne

The Gammaplex programming language is an esoteric programming language that, unlike most esoteric programming languages, has graphical output and mouse input. It also has much more commands. Unlike some esoteric programming languages, Gammaplex doesn't try to be obfuscated or hard to use. But that doesn't make it un-esoteric, on the contrary!

Like many esoteric programming languages, inspired by Befunge, gammaplex has a 2-dimensional instruction array, and the instruction pointer can move in the directions North, East, South or East. It's also Turing complete (if it would have an infinite instruction array). Every instruction is a single character.

The gammaplex interpreter (available both for Windows and Linux), its source code, and a few examples are available to download:

gammaplex.zip.

The interpreter is written in C++ and uses SDL. The .zip file includes:

• The C++ source code (it compiles with g++ *.cpp -lSDL -O3)
• a .dev file for bloodshed DevC++ to compile it in Windows (done really fast by installing bloodshed DevC++ with compiler, SDL for it, and then opening the .dev file and pressing F9)
• this .html file + the images for it
• a series of gammaplex examples in .txt files (mandelbrot, pong, paint, ...)
• a compiled ELF binary for Linux
• and a compiled .exe binary + the needed SDL.dll for Windows, that can run the examples.

The interpreter is recently (31 oktober 2007) updated to have somewhat cleaner code and run faster. The Mandelbrot demo is now done in a few seconds, instead of after minutes. This should make Gammaplex a bit more usable (ha ha). I even had to mess with the code of tron3k's Pong game, because it didn't use a time anchor or any other system to control the time and went way too fast on the new interpreter, to the point of being unplayable. Now it is a nice demonstration of time anchors :).

Index

• The Interpreter
• Using the Interpreter
• How to make Code Files
• The Debug Modes
• The Gammaplex Virtual Machine
• The Instructions
  • Basic Instructions
  • Extended Instructions
  • Decimal Numbers
  • Strings
• Graphical Styles
• Examples
• Tips
• Challenges
• Known Bugs
• Contact Information

The Interpreter

Using the Interpreter

This section explains how to use the official Gammaplex interpreter to run your code files.

The interpreter uses SDL, a multiplatform library for multimedia, so you need the newest SDL.DLL (included in the zip) for Windows, or install SDL in your Linux if you're using Linux.

If you start the interpreter, it'll try to load the code file "gamma.txt", and if it doesn't find that file, load an empty program and allow you to load another file by going to the menu. You can also let the interpreter start with another file, if you start it from a console and give the filename as parameter. For example, if you want it to use the file "sierpinski.txt" in Windows, start gammaplex with "gammaplex.exe sierpinski.txt" from the console.

To exit the interpreter, press the "close" button of the window (always works) or press escape and then press 2 (only works if the program isn't in "sleep" mode)

The Linux version of the interpreter is included in the same .zip file that contains the windows executable, and is called "gammaplex" without file extension. To make sure the program can open files relative to it's program path, open it from a console with "./gammaplex" while being in the folder of gammaplex.

If you press escape in the interpreter, a menu will show up. To choose one of the options, simply press the number of the option on your keyboard. You have the following options:

• 1. Continue: will go back to the program
• 2. Exit: quits the interpreter (you can also press the close button with the mouse for this)
• 3. Load Code File: this option will ask you to type in the filename of the code file you want to load. The code file path is relative to the interpreter executable.
• 4. Memory Editor: allows you to edit instructions, register and stack values, etc... See below for more help on this.
• 5. Debugging Options: allows you to set the debug mode
• 6. Execute Command: allows you to execute a single command that you type. It executes that command and thus changes the program state, but doesn't move the IP (unless the command itself moves the IP of course). You can choose if you want to enter the command as a character (press a single key on the keyboard) or number (type in the ascii value of the command). When entering commands as a character, type E to stop the command entering mode (shift + e).
• 9. About...: shows version number of the interpreter and language

The "Memory Editor" options are the following:

• 0. Continue: don't do anything, continue the program
• 1. Show Info: shows instruction array width (iw), instruction array height (ih), instruction pointer position (ix and iy) and direction (id).
• 2. Modify Register: allows you to change a value of any of the registers: first type the address, then the new value.
• 3. Pop Stack: pops the top value off the stack
• 4. Push Stack: pushes a value to the stack, it'll ask you to type in the number (you can type floating point numbers but you only see the point if you place something non zero behind the point)
• 5. Modify Instruction: allows you to modify an instruction: first asks x and y coordinate (0, 0 is the top left one), then asks the new instruction value.
• 6. Modify Instruction Array: allows you to change the width and height of the instruction array
• 7. Modify IP: allows you to change x and y coordinate and direction of the Instruction Pointer. For the direction, 0 = north, 1 = east, 2 = south, 3 = west.

Note that the menu might look messed up if the screen is smaller than 256x256 pixels because there isn't enough space for all the text.

Note: input always keyboard layout depends on SDL on your platform.

How to make Code Files

The code file has to be a plain text file, interpreted as a 2D grid of characters. Every line has to be exactly as long. The width of the first line determinates the width of the instruction array, and the number of lines determinates the height of the instruction array.

Do make sure that every line of the text file is as long! The interpreter ignores endline characters and assumes every line is as long as the first line. The first line has to be terminated with any ascii character smaller than 32 (so an "enter" will do), after that it simply reads all the other characters of the file, ignoring values smaller than 32, and adds them to the instruction array with the width given by the length of the first line. It doesn't matter what ascii code(s) your text editor uses for "enter".

Every instruction is a single character with an ascii value higher than 31 and smaller than 128. A list of each instruction follows below. The program will start with the top left character (0, 0), or at the last '@' character in the file.

Here's an example of a codefile, edited in Notepad. See further inthis document for more examples:

The Debug Modes

• 0: no debug enabled
• 1: prints the info described bolow to the screen
• 2: prints the info described below to the screen, AND refreshes the screen so that you can actually see the printed info
• 3: does the above, AND pauses after EVERY SINGLE COMMAND, you have to press a key each time to execute the next one

The 'U' command cycles between these modes, and initially it's 0. With 'XU' you can set it back to 0.

You can also set the debug mode by pressing escape, then 5, then the number of the debug mode.

It prints the following info:

In White:

• ix: instruction pointer x coordinate (leftmost characters of the code have x coordinate 0)
• iy: instruction pointer y coordinate (top line of the code has y coordinate 0)
• id: instruction pointer direction: 0=north, 1=east, 2=south, 3=west
• instr: current instruction as a character (so you'll see the same symbol as in the source text file)
• im: instructionMode: 0=normal, 1=extended, 2=string mode, 3=string command mode
• ticks: the number of commands executed so far
• dc: the decimal counter

In Red:

• Register 0 to register 12 (i.e. the 13 named registers, the top 2 red values are "position A", the bottom red value is "style", etc...)

In Green:

• The top 12 stack values (the topmost one printed is also the top of the stack)

This screenshot contains an example of the enabled debugging mode:

The Gammaplex Virtual Machine

Gammaplex allows you to use both a stack and random access memory to store your variables. The random access memory units are called registers.

The official version of Gammaplex puts some memory limitations. Gammaplex has 1048576 registers and a stack of 1048576 values. All of those are floating point numbers. If a certain parameter or calculation requires integers, it converts it to integer, then does the calculation, then converts it back to float (for example for the '&' binary AND command). The first 16 register values are the parameters for some functions. These are the named registers:

register[0]: x
register[1]: y
register[2]: R
register[3]: G
register[4]: B
register[5]: radius
register[6]: x2
register[7]: y2
register[8]: R2
register[9]: G2
register[10]: B2
register[11]: transparency (0 = opaque, 128 = semitransparent, 255 = invisible); note that this is the opposite of "opacity" where 0 means invisible and 255 means opaque.
register[12]: style

Registers [0] and [1] together form "position A"
Registers [6] and [7] together form "position B"
Registers [2], [3] and [4] together form "color", and is set to 255, 255, 255 by default at the start
Registers[8], [9] and [10] together form "color2"

The first 8 registers are used as input and output for functions like C (circle, uses x, y as position, radius as radius, and RGB as color), etc... The next 5 registers are used for the graphics styles. The other registers can be used as memory, but the stack can be used for that as well.

Please don't use registers up to register[15] for your own variables, they might get a meaning later.

The stack is a typical LIFO stack: you push() values on top of it, and pop() values again from the top. The stack is for example used for mathematical functions, for example to add two values: push the first value on the stack, then push the second value from the stack, then use the "+" command, and the two top values will be popped from the stack (i.e. they're removed from it), and their sum is added to the stack again.

Here's a full list of all parameters of the virtual machine:

Unless mentioned otherwise, all the parameters of the virtual machine are set to 0 at start. An exception is color A which is set to white, and the IP which is set to the location of the last '@' in your code if there is one.

The Instructions

Basic Instructions

The Gammaplex programming language has a lot of official instructions. Each instruction is a single ascii character, that the IP will read while traveling through the text file containing the instructions. The history of these instructions is a bit messy. As a result, the set of inctructions contains some inconsistensies here and there. Effort was made to give each instruction an as memorable character as possible.

Instructions are case sensitive! Each instruction has an ascii value between 31 and 128.

In the table of inctructions, "pop" means: the top stack value is read, and removed. "pop, pop", means that two parameters from the stack are used, each pop is a different value. For example this explains how to read the explanation of the '?' command.

Extended Instructions

Because there are more instructions than there are possible ascii values between 31 and 128, not all instructions can be a single character. Extended instructions are placed after the X command.

Some instructions are interpreted as basic after an X, here are some rules about extended instructions:

• The following commands behind an X do the same as when they're not behind an X and make the next command not-extended: #
• The following commands behind an X do the same as when they're not behind an X, but make the next command extended as if that one was placed after an 'X': v, ^, <, >, /, \, (space), @
• The official extended commands is given in the table below.
• There exist String commands, placed after a " in a string.
• Non existing extended instructions after an X are ignored, but might be used later if new features are added so please never use an unused extended instruction as NOP.
  

Decimal Numbers

You can easily type decimal numbers in your code, these will be pushed to the stack. Each character of the decimal number is actually a command, and the commands are designed so that you can type them normally. It works as follows:

To be able to do this, a Decimal Counter is used, which is initially 1. Any command, except the ones in the following list, sets the DC back to 1:

0123456789.\/@; <>^v

Please note that "space" is also in that list, while '#' is not, so '#' can be used to separate two decimal numbers, while space, 'v', ... can be used to continue typing the decimal number.

The decimal number commands (0-9) do the following:

• If DC is equal to 1, push n to the stack (i.e. create a new value on the stack, rather than modifying an existing one), and set DC to 0
• If DC is 0, it multiplies the top stack value with 10, and adds n to it (e.g. if the value on the stack was 5, and now you do the command '4', the value on the stack becomes 54)
• If DC is not 0 and not 1 but something between those, it adds DC * n to the top stack value, and then divide DC through 10. For example if DC is 0.1, and the top stack value is 54, and you do the command '8', the top stack value will now become 54.8, and the DC will become 0.01.

So the DC is equal to 0 when pushing digits before the point, and is 0.1, 0.01, ... when pushing digits after the point. It's 1 when not pushing any digits.

The '.' or decimal point command will set the DC to 0.1, and if DC was 1 (i.e. you used a point as initial digit of the number, like .445), will push a zero to the stack (this is the zero before the point and creates your new value you're entering). For example if you want to push "256.23" to the stack, you have to give the following commands in the following order, this is the same order as when you normally write down a decimal number:

256.23

That is, if the IP is moving to the east. If the IP is going in another direction, you have to type the commands in the other direction, for example if it goes to the west, to add 256.23, you have to type 32.652 in your code instead.

To add two values to the stack, 256.23 and 255, use for example

256.23#255

The # command sets the DC back to 1 so that the next decimal command will push a new value to the stack. With a space: 256.23 552, you will NOT be adding two values to the stack, but only one value namely 256.23552, because space is in the list of commands that doesn't set the DC back to 1.

You can output (print) numbers to the screen with 'i' or 'f'.

Trigonometry

The 'XT' command can do trigonometric and hyperbolic functions and their inverses, plus a few extra mathematical functions.

• First, XT pops a value from the stack that represents which function it has to do.
• Then, it pops a second value from the stack, called "u" here, which is the value it'll perform the calculation on.
• A few functions, which have a number higher than 63, take 2 arguments and thus pop a third value, "v" (the second parameter for the function).
• After performing the calculation, it pushes the result.
  

Here are the numbers of the functions it can perform:

0.  0: the zero function

1.  sin(u): sine
2.  cos(u): cosine
3.  tan(u): tangent
4.  sec(u): secant
5.  csc(u): cosecant
6.  cot(u): cotangent

7.  asin(u): inverse sine
8.  acos(u): inverse cosine
9.  atan(u): inverse tangent
10. asec(u): inverse secant
11. acsc(u): inverse cosecant
12. acot(u): inverse cotangent

13. sinh(u): hyperbolic sine
14. cosh(u): hyperbolic cosine
15. tanh(u): hyperbolic tangent
16. sech(u): hyperbolic secant
17. csch(u): hyperbolic cosecant
18. coth(u): hyperbolic cotangent

19. asinh(u): inverse hyperbolic sine
20. acosh(u): inverse hyperbolic cosine
21. atanh(u): inverse hyperbolic tangent
22. asech(u): inverse hyperbolic secant
23. acsch(u): inverse hyperbolic cosecant
24. acoth(u): inverse hyperbolic cotangent

25. exp(u): exponential: e^u
26. ln(u): natural logarithm (base e)
27. exp(-(u * u)): standard normal distribution 
28. sign(u): returns -1, 0 or 1 (the sign of u)

64. atan2(v, u): computes the principal value of the arc tangent of v/u, using the signs of both arguments to determine the quadrant of the return value
65. log_u(v): base u logarithm of v, that is: ln(v)/ln(u)

For example to put the hyperbolic secant of 0.5 on the stack, use 0.5#16XT

Strings

With the instruction X" (extended ") you can make strings in your code. When in string mode, every character the pointer walks over will be pushed as an ascii value to the stack instead of executed. A string starts with X" and ends with "X. The end-X doesn't make the next character extended. To push a " symbol to the stack, use "".

Inside a string, you can still execute commands, if you put the command after a " character. Such a command inside a string is called a string command. There are only a few commands that work as a string command. The following commands are enabled as string command and do the same as what they do as normal command:

"> "v "< "^ "\ "/ "; "(space)    "# "@ "+ "- "* ":

The following string commands do something different:

"X: end the string
"": push a " character to the stack
"2: the next two characters will be executed as normal command, so this command is used to extend the lifespan of the string command mode, e.g. if you need to go through a few 'v', '<', etc...

Other string commands do nothing in this version of Gammaplex.

For example:

0X"""hell";+o world"""XXS

Will first push a 0 to the stack, this is the string termination character. Then it'll push the following characters to the stack: '"' 'h' 'e' 'l' 'l' 'o' ' ' 'w' 'o' 'r' 'l' 'd' '"'. The ';' character is executed as a command to jump over the '+'. The '+' is never executed and never pushed to the stack. After pushing the string, it'll mirror it with 'XS', because when pushing a string to the stack this way the topmost character of the stack is the last character of the string, which'll make it being printed the wrong way (mirrored).

Graphical Styles

Graphical shapes are drawn with the positions and color of the named registers. With the extended style registers you can enable more drawing options.

R2, G2 and B2 together form a second color used for some styles.

Transparency is the transparency value used if the transparency style is enabled. Transparency 0 means no transparency (opaque), 128 means semi transparent (50%), 255 means 100% transparent (invisible). You cna also pick any value in between.

Style, register[10], is used to enable the special styles. Style is a binary number where each bit enables or disables a different style option. The sum of the numbers of the following options is the style value to have these options enabled:

• 0: no special style.
• 1: enable transparency (using register[11] for transparency value)
• 2: multiply blending
• 4: make underlying pixels negative color (effect visible if transparency or blending is used)
• 8: do not draw over pixels with color2
• 16: only draw over pixels with color2
• 32: pattern 1: 50% dots
• 64: pattern 2: less dots
• 128: pattern 3: horizontal lines =
• 256: pattern 4: vertical lines |||||
• 512: invert pattern: transparent pixels are now filled ones and vica versa
• 1024: horizontal gradient
• 2048: vertical gradient
• 4096: enable background color for text (color2 is used for the background) (with gradient: background does opposite gradient)
  

Transparency and multiply blending together make "mysterious blending".

"do not draw" and "only draw" together form "draw with (color1 + color2)/2 over color2, draw normally over the rest"

Horizontal and vertical gradient together make 45° gradient. The gradient is from one side of the screen to the other side, and uses color1 and color2. "only draw" and "do not draw" are disabled when gradient is enabled.

Dot and stripe patterns mixed form dotted line patterns (the combination of all removed pixels).

Examples

Most of these examples are included with the official interpreter as text files.

X"Hello World!"XXSXrRE

@v     >   r108wv  #        >         r100rv 
 2     1   #       #        8        #     >v
 5     0   #       #        0       #       R
 5     1   #       #        1       #       v
 #######   v11rr<  #        r       #       ^
 w     r   1       #        4       #       #
 w     2   r       #        1       #       #
 K     7   3       #        1        #     # 
 >     ^   >2r119  r111r    ^######   #####  

X"Gammaplex"XXS0#0nv
v    )]21#4201}a4  <
>t650:T124*124+t400v
^DcRrXwX}a1+29*29T:<

@512)u5v
va1l)21<
>W}W&?Pv
^Rs v?< 
;   ^ ="
      h 
;>Ns"w^w
^^?=  y<

Mandelbrot

Draws a colored mandelbrot set @ 200)u150)l1a0#0}>1a{"}4#0XG v Mandelbrot by ^ v?,y(]0 < Lode Vandevenne >1a{s"sN}v v0.1 ^ E?,h(]1R< 0](y2:-1.5*0.5y*:0.5-30]) \ 1](h2:-0.5h*:31]) \ 32]0)u0)u0)u0)u0) \ >36](")34](32])35](33])32](w*33](\ w*-30](+34])2#32](*33](*31](+35])\ 34](w*35](w*+4,?v36](16,?v7#0G \ G0#11< >12#0G \ >255#255#36](16*H3a}PXg >128#128#128#3a}PXg The code has a double loop going through all pixels at the top right corner of the file, a gosub brings you to the mandelbrot calculations starting on line 4, and the mandelbrot loop is on lines 7, 8 and 9 (when the first line is line 0). The mandelbrot calculations work with 2 complex numbers, of which the real and imaginary parts are stored in memory addresses 32, 33, 34 and 35. It leaves the loop and plots a colored pixel when either the squared radius is larger than 4, or there have been more than 16 iterations. The HSV to RGB function is used to get the color for the pixel. To increase the resolution (and make it much slower), change the values 300 and 150 on the first line (line 0). To increase the number of iterations, change the value 16 on line 11. Then you also have to change the value 16 on line 12, so that the product of both is 256 (because there are 256 hue values for HSV color). Here's a screenshot of the result: This program goes very slow. Either an optimized code file, or an optimized interpreter could help. Note: this code only works in version 0.32 and above of the interpreter, in older versions a command used is broken.

@uu   v
>{2a}Mv
avm}a1<
1>;   v
^Rc?L?<

@uuuu      2a} v
>   R    v w821<
^v?v?mL}a\0wwddv
         1      
         M      
}  ?     ^ <vu)<
a; ; >)u)u)^>)uv
^2M< ^ddww552L)<
^>;v;<>1a{2a}M1v
          v  }a<
          >m?v v
   >c^^;?      <
      ^  Rc?L<  

 #030#028GThisProgramWasWrittenByTron3k-tron3k_at_
\gmail.com_BTW..._itWASreallyHARD8]103)9]103)18]15
\8)t19])184]128)184](19](%19])19](64+19])2]255)3]2
\55)4]255)99]0)20]1)21]1)20](_20])c8](50+30])0]5)8
\](1])6]15)8](7])L30](1])30](7])L0]5)8](1])6]5)30]
\(7])L0]15)6]15)L005#032Gomfglol9](50+30])0]250)6]
\240)9](1])9](7])L30](1])30](7])L0]240)6]240)9](1]
\)30](7])L0]250)6]250)L5]8)18](0])19](1])F0]10)1]1
\0)180](iD0]240)181](iDR18](20](+18])19](21](+19])
\30]8)30](19](,31])31](!31])010#004#31](?GDD21](_2
\1])30]247)19](30](,31])31](!31])011#009#31](?GDD2
\1](_21])011#028GTRON3KRULESM22])23])8](25+31])31]
\(23](,30])012#043#30](?GDD8](1+8])013#003G#8](1-8
\])013#025#99](?GDD99]20)99](')40]3)40](99](,41])0
\15#031#41](?GDD9](25+31])31](19](,30])015#022#30]
\(?GDD9](1+9])015#031G#9](1-9])44]23)18](44](=29])
\29](!29])018#014j29](?GDD8](19](,34])018#014#34](
\?GDD8](50+31])19](31](,32])018#014#32](?GDD20](_2
\0])18](2+18])44]232)18](44](=29])29](!29])020#048
\#29](?GDD9](19](,34])020#048#34](?GDD9](50+31])19
\](31](,32])020#048#32](?GDD20](_20])#18](2-18])40
\]13)40](')021#005#40](?GDD30]0)18](30](,31])025#0
\46#31](?GDD0]0)6]255)1]255)7]255)1](')7](')L40]25
\)40](')023#002#40](?GDDR022#034#1](?GDD2]0)3]0)4]
\0)0]0)6]255)1]255)7]255)1](')7](')L40]25)40](')02
\4#042#40](?GDDR024#025#1](?GDD181](")001#033G30]2
\55)30](18](,31])030#018#31](?GDD0]0)6]255)1]255)7
\]255)1](')7](')L40]25)40](')027#023#40](?GDDR027#
\006#1](?GDD2]0)3]0)4]0)0]0)6]255)1]255)7]255)1]('
\)7](')L40]25)40](')029#014#40](?GDDR028#046#1](?G
\DD180](")001#033G003#034GE##6Xj#001#033G#########

#define print(x) main(){printf(x);return 0;} /* >+++++[<++>-]<[>++++
# +++<-]>++.+.[-]>+++++[<++>-]<.[-][
#
# This polyglot prints "HI" when run in
# Brainfuck, C, COW, Perl, Python, Gammaplex, l33t, and ruby
#
# */
print ("HI\n")
#/*
# @X"H"Xr X"I"Xr RE
# moOMoOMoOMoOMoOMoOMOOmOoMoOMoOmoOMOomoo
# mOoMOOmoOMoOMoOMoOMoOMoOMoOMoOmOoMOomoo
# moOMoOMoOMooMoOMooMOOMOomoomoOMoOMoOMoO
# MoOMoOMOOmOoMoOMoOmoOMOomoomOoMooMOOMOo
# moo 5 0 7 99999998 1 7 0 1 8 9999995 1 91
# ] */

Have fun designing your own programs, and mail me the results if you like. Contact information can be found at the bottom of this page.

Tips

When using GOTO and GOSUB, use at least 3 digits for the coordinates, even if the coordinates have less digits, e.g. use 002#035 instead of 2#35 to give the coordinates to go to: since you'll be messing with your code and thus changing positions a lot while designing, positions might change, so it's best to have enough room to type possible bigger numbers for goto coordinates, and this also allows you to spot them easier since they're more recognisable.

There are many shortcuts, for example you can use n instead of 255 to push the often needed 255 to the stack, you can use "stack programs" to push and pop named registers with less commands, and you can use "time anchors" to automaticly limit the speed of loops.

Challenges

• Proof that Gammaplex is or isn't Turing Complete
• Prime number calculator
• Game Of Life
• A quine: such program would lay out it's own 2D source code as characters on the 2D graphical screen, without using the q command or being a trivial "empty" program.
• An adventure game, either with parser or with single character input like "n", "e", "s", "w", ...
• Spinning 3D wireframe cube
• Tic Tac Toe
• A game like Tetris, 2D space shooter, snake, ...

Known bugs of the interpreter

• They keyboard layout may behave strange on some systems with international keyboards. This has more to do with how SDL works on your platform than with Gammaplex.
• Not all Gammaplex commands have been tested in the interpreter, so some bugs may be left undiscovered. The Gammaplex specification should tell what each command does, and if it doesn't do exactly that in the interpreter, it's a bug. Please let me know.
• If a command description in this specification is ambiguous, please let me know.

Contact Information

You can contact me at the address shown in the image below. it's in an image to prevent spam. If you can't read the image, it's just my full name at google's mail.