[~]<x>,[~]<y>,[~]<z>
^<sway>,^<heave>,^<surge>

represents a position in the world with comma-seperated coordinates.

prefixing with ~ specifies a coordinate whose value is relative to the most relevant object (usually either the player's feet or their selection). these relative components can be intermixed with absolute ones.

prefixing with ^ specifies a coordinate whose value is relative and whose axes are based on the player's look direction. these look direction relative components cannot be intermixed with any other type.

"sway" means left from your perspective, "heave" means upward from the top of your head, "surge" means straight ahead. if you are, say, facing north but looking up into the sky, "sway" is -X (west), "heave" is +Z (south), and "surge" is +Y (up).

<id>[:<meta>]

id: (<int>|<key>)

key: <str>[.<str>...]

represents a block of a specific type.

id can be provided as an integer ("1") or a translation key ("stone"). meta is provided as an integer.

the special key "air" can be used as an alias for id 0.

represents a transformation that can be applied to blocks.

there are currently two:

the block type seen above can be interpreted as a pattern that sets any block to that block.

the weighted-random pattern combines several `block`s, seperated by slashes, with an optional integer weight attached:

<weighted-block>[/<weighted-block>...]

weighted-block: [<weight>*]<block>

it randomly chooses one of the blocks to place. higher-weighted blocks are more likely.

example:

wool/3*wool:3/3*wool:6

<component>[/<component...]

component: [!](<filterblock>|#<material>)

filterblock: <fuzzy-id>[:<fuzzy-meta>]

fuzzy-id: (<int>|<range>|<fuzzy-key>|*)
fuzzy-meta: (<int>|<range>|*)

range: (<int>..<int>|<int>..|..<int>)
fuzzy-key: <str>[.<str>...][;]

determines whether a block should be modified or not.

you can place a "!" before each filter component to invert it.

you can specify a (potentially unbounded) range instead of an int for ID and meta.

when you match a block by translation key, grass will match grass.retro (for example). you can avoid this behavior by instead typing grass; (with a semicolon at the end).

X|Y|Z|^

represents a specific coordinate axis.

^ specifies the axis the player is looking in.

N|E|S|W|U|D|^

represents a specific direction.

a letter represents an absolute direction ((N)orth, (E)ast, (S)outh, (W)est, (U)p, (D)own).

^ specifies the direction the player is looking in.

<component>[,<component>...]

component: <boundDirection>[<boundDirection>...][magnitude=0]

boundDirection: N|E|S|W|U|D|F|B|L|R|*

magnitude: <int>

note: this section documents the way bound arguments will work in 0.5.0. in 0.4.x the default magnitude is 1, and each component can only specify one boundDirection.

represents a relative selection that is bigger/smaller than the existing selection in the given directions.

direction can be specified absolutely, or relative to the direction the player is facing ((F)orward, (B)ackward, (L)eft, (R)ight).

* is shorthand for "all directions".

magnitude represents a number of blocks to grow by in that direction. a negative number can be specified to allow for shrinking.

examples:

* : the same as the current selection.
FB1,LR2 : expanded by one block forward and backward, two blocks left and right