Mask

A mask is a condition that decides whether a block or position can participate in an operation.

<mask>

The placeholder is not written literally. Replace it with a valid mask expression.

A mask does not determine which block is placed. It only determines which existing blocks or positions match the condition.

;replace stone dirt

In this example:

• stone is the mask.
• dirt is the pattern.

Block Masks

The simplest mask is a block identifier.

stone

A block identifier without states matches that block regardless of its current states.

A namespace can be included:

minecraft:stone

Blocks from another add-on must use their own namespace:

my_addon:custom_block

To inspect the identifier and states of the block you are looking at:

;blockid

Block State Masks

A block mask can require one or more exact states.

block[state=value]

Separate multiple states with commas:

block[state1=value,state2=value]

Example:

oak_stairs[weirdo_direction=0,upside_down_bit=false]

State names and accepted values can change between Minecraft versions.

Union with ,

A comma represents OR. Only one condition needs to match.

mask1,mask2,mask3

Example:

stone,dirt,gravel

This matches stone, dirt, or gravel.

Do not add spaces after commas inside a union.

Intersection with Spaces

A space represents AND. Every condition must match.

mask1 mask2

Because commands also use spaces to separate arguments, wrap the complete mask expression in quotes:

"stone #surface"

This matches blocks that are both stone and exposed surface blocks.

Grouping with Parentheses

Parentheses group parts of a complex expression and make operator precedence explicit.

"(stone,andesite) #surface"

This means:

(stone OR andesite) AND surface

Use parentheses when combining unions, intersections, negation, or offset masks.

Negation with !

The ! prefix inverts a mask.

!mask

Match everything except air:

!air

Exclude an entire group:

!(sand,gravel,dirt)

Negation can also apply to advanced masks:

"#surface !#shadow"

Existing Blocks with #existing

#existing matches every block that is not air.

#existing

It is approximately equivalent to:

!air

#existing means not air. It does not necessarily mean solid. It can include fluids, vegetation, and other non-air blocks.

Offset Masks with < and >

Offset masks inspect a neighboring vertical block.

Match dirt with air above it:

"dirt <air"

Match air with stone below it:

"air >stone"

Offset conditions can contain grouped masks:

"air >(dirt,grass_block)"

Nested offsets are supported by the current parser:

<<air

This checks two blocks above the evaluated position. Test nested offsets on a small area before using them in a large operation.

Random Masks with %

A random mask matches each position independently with the specified probability.

%percentage

Match approximately 20% of all evaluated positions:

%20

Combine it with another mask to match approximately 20% of stone:

"stone %20"

The result is probabilistic, not an exact block count. Repeating the same operation can match different positions.

State-Only Masks

State-only masks compare block states without requiring a specific block identifier.

Two modes are available:

• Flexible: ^[state=value]
• Strict: ^=[state=value]

Flexible State Matching

^[state=value]

The flexible form matches when:

• The block has the state with the requested value, or
• The block does not have that state.

Because of this, it can match more blocks than expected.

Strict State Matching

^=[state=value]

The strict form requires the block to contain the state and have exactly the requested value.

Example:

^=[pillar_axis=0]

Use the strict form when the state must exist.

Multiple State Conditions

^[state1=value,state2=value]

^=[state1=value,state2=value]

Surface Masks

#surface matches a non-air block with at least one directly adjacent air block.

#surface

Alias:

#exposed

The six adjacent directions are checked:

• Up
• Down
• North
• South
• East
• West

Combine it with a block mask:

"stone #surface"

The implementation specifically checks for adjacent air. A block next to water or lava is not necessarily considered exposed.

Surface Slope Ranges

A surface mask can restrict the approximate slope angle.

#surface[min:max]

Examples:

#surface[0:15]

#surface[10:45]

#surface[50:90]

The range is conceptually measured from 0° to 90°.

Vegetation, flowers, and small decorative blocks can affect the calculated slope.

In latest, use #surface[min:max] instead of the older #slope[min:max] syntax.

Shadow Masks

#shadow matches blocks that are not visible from WorldEdit’s current placement reference.

#shadow

Match hidden exposed blocks:

"#surface #shadow"

Match visible exposed blocks:

"#surface !#shadow"

For better performance, combine #shadow with #surface instead of evaluating every internal block.

Block Tag Masks

The current parser supports masks based on block tags.

##tag

Namespaced example:

##my_addon:natural_block

Available tags depend on Minecraft, installed add-ons, and tags exposed by the API. Do not assume that a tag exists without confirming it.

Global Masks with ;gmask

A global mask is stored in the player’s WorldEdit session and applies to compatible operations.

;gmask [mask]

Set a global mask:

;gmask #existing

Set a compound global mask:

;gmask "stone #surface"

Clear the active global mask by running the command without an argument:

;gmask

A global mask belongs to the current player session. It is not a server-wide rule.

Not every command uses the global mask. When a command accepts a direct <mask>, [mask], or -m <mask> argument, prefer that direct mask.

Mask Picker

The WorldEdit kit includes a Mask Picker.

;kit

• Use it on a block without crouching to create a new global mask.
• Crouch and use it on additional blocks to add them as a union.
• Clear the resulting global mask with ;gmask.

The Mask Picker stores the selected block’s full permutation, including its states. A manually written mask such as oak_stairs is broader because it does not require one exact orientation unless states are specified.

Brush Destination Masks with ;mask

;mask controls which destination blocks a held brush can modify.

;mask [mask]

Set a brush destination mask:

;mask #existing

Clear it:

;mask

The mask belongs to the brush configuration attached to the held item.

Brush Trace Masks with ;tracemask

;tracemask controls which blocks a brush can target or use as an impact point.

;tracemask [mask]

Set a trace mask:

;tracemask stone

Clear it:

;tracemask

The difference is:

Combining Active Masks

Masks applied through different systems are combined as an intersection. Every active condition must match.

Conceptually:

direct mask
AND global mask
AND brush mask

An incompatible combination can prevent an operation from changing anything.

Before diagnosing a mask problem, clear temporary masks:

;mask
;tracemask
;gmask

Then enable only the condition required for the current operation.

Common Mistakes

Confusing a Mask with a Pattern

A mask selects the existing destination. A pattern determines the result that is placed.

Forgetting Quotes

An intersection containing spaces must be quoted.

Incorrect:

stone #surface

Correct:

"stone #surface"

Adding Spaces after Commas

Avoid:

stone, dirt, gravel

Use:

stone,dirt,gravel

Confusing < and >

<air   = air above
>stone = stone below

Treating #existing as Solid Only

#existing means any block that is not air.

Using Flexible State Matching When Strict Matching Is Required

Use ^=[state=value] when the state must exist on the block.

Expecting an Exact Random Percentage

%20 is an independent probability for each position. It does not guarantee an exact 20% total.

Forgetting an Active Global or Brush Mask

An old mask can silently combine with the current one and make the final condition too restrictive.

Quick Reference

Reusable Templates

<block>

<mask1>,<mask2>,<mask3>

"<mask1> <mask2>"

!<mask>

"<mask> >(<mask1>,<mask2>)"

"<mask> %<percentage>"

^=[state=value]

#surface[min:max]