Redstone Programming Language

Last version (1.2) download!

Version 1.0 overview: http://www.youtube.com/watch?v=q-l0Q5lhm6Q
Minecraft Forum thread: http://www.minecraftforum.net/forums/mapping...

RPL quick facts:

• Currently exists as MCEdit filter
• Generates cammand blocks and some other redstone based on a text script
• Has some new cool commands and selectors
• Tremendously simplifies work with operations: @Sheep obj1 = obj2 /= var obj3 += 5
• Has cool text-replacement capabilities: @p obj<<1:5>> = 0 becomes @p obj1 = 0, @p obj2 = 0, ... , @p obj5 = 0
• And much more!

Changelog for 1.2:

• Added trigonometric functions: sin and cos
• Replacements are now also applied in directives
• Added #repeater directive
• New comparison option for selectors: @a[objective==1]
• Unknown selectors now turn into entity`s name: @zombling means @e[name=zombling]

Changelog for 1.1:

• Added #new_onetimeline directive
• Added #used_objectives directive
• Added #coords directive
• Added support for decimal numbers in ranges: <<0.2:-0.2:-0.05>>
• Replaced @Sheeps selector with @Sheep

Documentation

RPL is intended to convert the code from a text file to set of command blocks in Minecraft world. So most of the lines in RPL program transform into one or several (or even hundreds) command blocks. There are also lines which affect RPL's behavior and don't appear in the resulted blocks. You can also write comments after a double slash ("//") at any point in RPL program.

Special RPL directives tell the interpreter how to process the lines coming after them. Every directive always starts with "#" symbol and takes a separate line (except #coords). There are 8 directives in RPL now. Let's go through all of them.

#replace

This one tells the interpreter that the following lines contain a set of replacement pairs. RPL will memorize these pairs and later apply the replacements on all the lines that are intended to turn into command blocks, as well as directives. In each line pairs should be separated by two following symbols: "; ", a semicolon and a space. Each pair should have this format: find = replace. So "=" should have a space on each side. No quotes needed. Multi-line replacements are not supported. Here's an example:

Replacements are applied in the reverse order, so after this example all occurences of NEW MOB will be turned into summon Creeper 239 123 -45 {NoAI:1,Silent:1}

#new_line

This directive means that the following lines should be transformed into command blocks which will be placed in a straight line in the Minecraft world. The direction and coordinates of that line`s starting block are set via directive`s attributes which go right after the directive itself like so:

So the first attribute is direction and it has 3 possible values: x, y and z. Negative directions are not supported because they make little sense due to the fact that in Minecraft generally blocks are updated and executed in the order of positive directions along each axis.

The second, third and fourth arguments here are x, y and z of the first block in the line. You can use standart Minecraft tilde notation here to specify the position relative to the corner of your MCEdit selection with lowest coordinates along each axis.

#new_clockline

This directive is intended to be used with 20Hz clocks. It creates a fill-based clock, which makes a line of redstone blocks which are being replaced with stone and then vice-versa 20 times per second (each game tick). So every command block touching that line gets powered and updated 20 times per second and executes its command with the same frequency. RPL places all the command blocks following this directive around that line in exactly the same order they will be triggered ingame each tick. There is an optional attribute that lets you specify the sides of the clockline you want to use to place command blocks next to:

So this directive has 5 parameters. Unlike #new_line, the first one can only be x or z. The last attribute can be either all or a set of comma-separated available options: right,left,top,bottom. Default value is all.

And both in #new_line and in #new_clockline modes a blank line will cause a one-block gap between resulting command blocks.

#new_functionline

This one is exactly the same as #new_clockline except it doesn't create a 20Hz clock, but you can place a redstone block at the beginning of the line and the whole line will be triggered and the redstone block will be replaced with stone, so you will be able to place it there again later. This way it's kinda like a "function" that you can call.

#new_onetimeline

Same as #new_functionline, but the line gets removed after the first execution. RPL places a block at the end of the line that fills the whole thing with air. This is useful for things like creating objectives and setting up some initial values.

#used_objectives

RPL will generate a set of command blocks that creates all objectives used in the script above. It only counts objectives from selectors (like in score_obj_min=0 and obj<=4) and from operations. It has two optional parameters. The first one specifies the criteria of the objectives (like dummy, trigger, deathCount etc.), the default is dummy. The second one is whether or not you want to remove existing objectives with same names before creating new ones (it will just erase all data from them). If you do, add reset to the directive. Here's some possible usages of this directive:

#coords(~ ~ ~)

Replaces itself with absolute coordinates of the block which is specified in the brackets relative to the MCEdit selection. So if you selected a block with coordinates 20 60 40 then this example

will turn into this:

This applies after all the replacements and after "<<...>>" thing described below.

#repeater

This directive only works in #new_line mode and allows you to place a repeater. It can take a separate line or go at the end of the line like this:

The code above will generate 3 command blocks and 3 repeaters. This directive have two arguments, the first one is repeater`s delay (can be from 1 to 4, default is 1), and the second one is whether or not you want the repeaters to look in the reverse direction. You can use just #repeater if you want a repeater with delay of 1 facing the same direction as your command block line.

Here's a complete script of a simple walking animation for an armor stand:

That's about it for directives, now to the actual command goodness!

Commands

RPL is intended to make writing commands easier so it has some tools to simplify this process and reduce the amount of code you write. The first tool is what you may call an "options" tool. It lets you specify different text options for the portion of the line so the line will be copied with every option you specified. Here's an example:

will turn into:

You can also set ranges for numbers:

turns into:

So you use double angle brackets for it and there can be two types of syntax inside them: comma-separated strings or ranges in one of two following formats: min:max or min:max:step. As you can see above, you can use multiple sets of options in the same line and RPL will use them respectively. You can also mix text options with ranges as long as you keep the same amount of options in each brackets.

For each command RPL reads from a file it first applies all the replacements defined in #replace sections above it, then it checks for these angle brackets and duplicates the line if needed, and then it proceeds to further interpretation of each of the resulting commands.

Preserving original formatting

There's a way to avoid any replacements or interpretation of your command whatsoever, and that is by adding $ symbol at the beginning of the line. If RPL sees a $ as a first symbol of the line, it removes it and makes a command block out of it right away, without even removing comments.

Selectors

The next thing is advansed selectors. RPL introduces a bunch of new selectors and simplifies your work with them a little bit. Here's all the features:

1. Entity selectors. There's a selector for each type of entity: @Creepers, @Boats, @ItemFrames and so on. They are just short versions of @e[type=Creeper], @e[type=Boat] etc. You can still add variables to them like normal: @Zombies[r=5] stands for @e[type=Zombie,r=5]. Here is a complete list of all new selectors:

2. @me selector. This is short version of @e[r=0,c=1] and it's useful in "execute" commands to specify the entity you are executing the command from.

3. More clear comparison: @Sheep[deltav>=0] stands for @Sheep[score_deltav_min=0] and @Sheep[deltav<=-1] stands for @Sheep[score_deltav=-1]. So <= and >= signs are allowed in selectors, but there should be a number on the right side. You can also do this: @Sheep[-2<=deltav<=2]. And one more option: @Sheep[deltav==2]. This is the same as @Sheep[2<=deltav<=2].

4. "Name" selectors. Unknown selectors will turn into entity`s name. Example: @zombling means @e[name=zombling].

5. New selector variable: block. This is based on "detect" feature of the "execute" command. Basically you can check for a block right in the selector. This command will kill all the sheep standing on grass:

Short "execute"

Just a small feature: you can use => sign instead of execute *** ~ ~ ~. Example:

stands for:

So @selector => command turns into execute @selector ~ ~ ~ command

Operations

And now to probably the most handy feature of RPL: intuitive operations. You don't have to write those loooong "scoreboard players operation" or "scoreboard players set" or "add" or "remove", you can just write a few intuitive words and RPL will do the rest for you:

This command will set the score of each sheep in "vx" objective to its score in "vy" objective. If you are interested, it corresponds to this Minecraft command:

In this case the RPL command is 6 times shorter and probably 10 times more clear!
So there always should be two words on the left side of the operation: selector and objective. On the right side you can use either selector and objective or just an objective, RPL will use @me selector by default.
Numbers are also allowed on the right side, but only for "=", "-=" and "+=" operations. If you use numbers, you can add a dataTag on the right just like in "scoreboard players set/add/remove" commands:

So this is pretty cool, but there's more :) You can cascade the operations with the same left side:

means:

The important thing here is that operation`s priorities are NOT considered. The operations are executed in the same order as they appear in the string. For example:

means:

So "a" will be "5 * d", but not "2 + (3 * d)" as you would expect if priorities were considered.

The other important thing is that as of now you are not allowed to use the scoreboard players operation command in RPL, because it will confuse the operation signs with its own format. The only way to use this command in RPL is by using $ sign described above. But RPL implements all the features of this command, so you probably won't need to use it anyway.

New commands

RPL introduces some new commands. Currently there are four of them.

tpsmart

This command allows you to teleport entities based on its score in an objective. You can have an objective that contains velocity values for each entity and teleport them accordingly. I will use the term "velocity" below because it is the most probable usecase of this command. This command creates a set of command blocks and each one of them covers certain range in possible velocity values. It takes 8 parameters:

1. Selector - who do you want to telepot
2. Axis of teleportation. You can use only one axis per one tpsmart command
3. Objective to use. RPL with use the selector from the first parameter to determine the velocity value
4 and 5. Range of possible velocity values.
6. Step. This affects how many blocks will be created and how accurate the correspondence between velocity and tp distance will be. In the above example step is 10, so the command will create a command block for velocity values from 20 to 30, then from 30 to 40 and so on.
7 and 8. The range of distances corresponding to specified range of velocity values. This is the distance the entity will be teleported by. If you are using a 20Hz clock the reasonable values for these parameters are between -1 and 1, 1 stands for 20 blocks per second.

The above example will generate these commands:

sqrt

Square root calculation. As of now there's no way to actually calculate the root in Minecraft, so this command uses the same technique as tpsmart. It creates a command block for every possible resulting square root and each of these blocks checks if the source number is around this block`s number squared, if that makes sense. Example:

converts into (in RPL syntax):

So the first two parameters set the range of resulting square roots you want to get, 3rd and 4th parameters specify the source number and last two parameters specify where to put the square root. In the example above there's only one parameter for it because RPL will use @me selector by default. Full syntax looks like this:

and it will be converted to (in RPL syntax again):

sin & cos

Just what it looks like.

Arguments:
1 and 2. Where to take a value from. This must be a number from 0 to 359 (in degrees). You can also use rx and ry as objective to refer to player`s rotation.
3 and 4. Where to put the result.
5. Number of steps. In this example 180 comand blocks will be generated for angles: 0 to 1, 2 to 3, 4 to 5 and so on. Use 360 here if you want to check every possible angle.
6. Multiplier. Your sine or cosine will be multiplied by this number. In this example @destSelector destObj will contain a number from -1000 to 1000.