Ctrl+K
⚠️ You are reading a doc of an undergoing development version. Information can be out of date and/or change at any time. ⚠️

🧱 Block#

#bs.block:help

Manage blocks, including states and NBTs, while offering advanced tools for seamless transformations.

“Architecture is the thoughtful making of space.”

—Louis Kahn

🔧 Functions#

You can find below all functions available in this module.

Fill#

#bs.block:fill_block

Fill all or parts of a region with a specific block.

Inputs:

Storage bs:in block.fill_block [compound]:

block [string]

Block to fill the region with.

from [array]

Starting position (absolute coordinates only).

to [array]

Ending position (absolute coordinates only).

mode [string]

Mode used to set blocks [destroy|keep|replace] (default: replace).

limit [int]

Limit how many blocks can be set in a single tick (default: 4096).

masks [array]

Determine which blocks will be replaced.
Masks syntax:

Each entry must be a compound that respect the following format:

block [string]

Block that act as a filter.

negate [bool]

Reverse the mask filter (default: false).

[x,y,z] [int]

Mask filter offsets (default: 0).
Outputs:

State: Blocks are placed in the world.

Replace the top layer of dirt by grass:

# Setup the input
data modify storage bs:in block.fill_block set value {block:"minecraft:grass_block",from:[-16,100,0],to:[-1,103,15],masks:[{block:"minecraft:dirt"},{block:"minecraft:air",y:1}]}

# Run the process
function #bs.block:fill_block

Fill an area with stone but only by a few blocks each tick:

# Setup the input
data modify storage bs:in block.fill_block set value {block:"minecraft:stone",from:[-16,100,0],to:[-1,103,15],limit:8}

# Run the process
function #bs.block:fill_block
#bs.block:fill_type

Fill all or parts of a region with a specific block type while trying to conserve states and NBTs.

Inputs:

Storage bs:in block.fill_type [compound]:

type [string]

Block id to fill the region with.

from [array]

Starting position (absolute coordinates only).

to [array]

Ending position (absolute coordinates only).

mode [string]

Mode used to set blocks [destroy|keep|replace] (default: replace).

limit [int]

Limit how many blocks can be set in a single tick (default: 4096).

masks [array]

Determine which blocks will be replaced.
Masks syntax:

Each entry must be a compound that respect the following format:

block [string]

Block that act as a filter.

negate [bool]

Reverse the mask filter (default: false).

[x,y,z] [int]

Mask filter offsets (default: 0).
Outputs:

State: Blocks are placed in the world.

Replace oak_stairs by spruce_stairs while conserving states:

# Setup the input
data modify storage bs:in block.fill_type set value {type:"minecraft:spruce_stairs",from:[-16,100,0],to:[-1,103,15],masks:[{block:"minecraft:oak_stairs"}]}

# Run the process
function #bs.block:fill_type

Credits: Aksiome

Get#

#bs.block:get_block

Get all data related to the block at the current location, including its state and NBTs.

Inputs:

Execution at <entity> or positioned <x> <y> <z>: Position to get block data from.

Outputs:

Storage bs:out block [compound]:

id [int]

A numeric id that represents the block type.

group [int]

Blocks within the same group share the same possible state.

block [string]

Full string representation of the block type[state]{nbt}.

type [string]

String representation of the id (e.g., minecraft:stone).

item [string]

Item string id associated with the block, if it exists.

state [string]

Represent the state of a block (e.g., [shape=straight]).

nbt [compound]

Data tags used by block entities.

properties [compound]

Block state as properties (used by entities like falling blocks).

iterable_properties [array]

An iterable array used to manipulate the state of the block.

Get all data related to a block:

# Run the get function on a block
execute positioned ~ ~ ~ run function #bs.block:get_block

# See the result
data get storage bs:out block
#bs.block:get_type

Get the block type at the current location. While state, NBTs, and properties will be empty, the iterable properties still enable state transformations.

Inputs:

Execution at <entity> or positioned <x> <y> <z>: Position to get block data from.

Outputs:

Storage bs:out block [compound]:

id [int]

A numeric id that represents the block type.

group [int]

Blocks within the same group share the same possible state.

block [string]

Full string representation of the block (only the type).

type [string]

String representation of the id (e.g., minecraft:stone).

item [string]

Item string id associated with the block, if it exists.

state [string]

Represent the state of a block (empty string).

nbt [compound]

Data tags used by block entities (empty string).

properties [compound]

Block state as properties (empty compound).

iterable_properties [array]

An iterable array used to manipulate the state of the block.

Get only type data related to a block (no property value is selected):

# Run the get function on a block
execute positioned ~ ~ ~ run function #bs.block:get_type

# See the result
data get storage bs:out block

Read-only output

The bs:out block output is intended to be read-only. Modifying parts manually could lead to potential bugs. That’s why the module provides numerous functions capable of making modifications to the output while preserving its integrity.

Credits: Aksiome, theogiraudet

Manage state#

#bs.block:keep_properties

Filter properties to keep only the desired ones.

Inputs:

Macro var properties [array]: List of properties to keep. Must be compounds with the name of the property.

Outputs:

Storage bs:out block [compound]: The block, state, properties and iterable_properties are updated to reflect this change.

Keep only the facing and shape properties:

# Once (on stairs)
execute positioned ~ ~ ~ run function #bs.block:get_block

# Run the transformation
function #bs.block:keep_properties {properties:[{name:"facing"},{name:"shape"}]}

# See the result
data get storage bs:out block.block
#bs.block:merge_properties

Merge state properties from the current location into the output. The merge occurs if the syntax is correct, regardless of logical coherence (e.g., using ‘age’ for different plants).

Inputs:

Execution at <entity> or positioned <x> <y> <z>: Location of the block that act as input.

Macro var properties [array]: List of properties to merge. Must be compounds with the name of the property.

Outputs:

Storage bs:out block [compound]: The block, state, properties and iterable_properties are updated to reflect this change.

Merge the facing of a block onto stairs:

# Once (on stairs)
execute positioned ~ ~ ~ run function #bs.block:get_block

# Run the transformation (on a block with facing)
execute positioned ~ ~ ~ run function #bs.block:merge_properties {properties:[{name:"facing"}]}

# See the result
data get storage bs:out block.block
#bs.block:remove_properties

Filter properties by removing the undesired ones.

Inputs:

Macro var properties [array]: List of properties to remove. Must be compounds with the name of the property.

Outputs:

Storage bs:out block [compound]: The block, state, properties and iterable_properties are updated to reflect this change.

Remove the facing and shape properties:

# Once (on stairs)
execute positioned ~ ~ ~ run function #bs.block:get_block

# Run the transformation
function #bs.block:remove_properties {properties:[{name:"facing"},{name:"shape"}]}

# See the result
data get storage bs:out block.block
#bs.block:replace_properties

Replace property values. Invalid values will not be replaced.

Inputs:

Macro var properties [array]: List of properties to replace. Must be compounds with the name of the property and the value.

Outputs:

Storage bs:out block [compound]: The block, state, properties and iterable_properties are updated to reflect this change.

Replace the facing property value:

# Once (on stairs)
execute positioned ~ ~ ~ run function #bs.block:get_block

# Run the transformation
function #bs.block:replace_properties {properties:[{name:"facing",value:"east"}]}

# See the result
data get storage bs:out block.block
#bs.block:shift_properties

Shift properties by any amount, allowing cycling through their values.

Inputs:

Macro var properties [array]: List of properties to shift. Must be compounds with the name of the property and the by amount (defaults to 1).

Outputs:

Storage bs:out block [compound]: The block, state, properties and iterable_properties are updated to reflect this change.

Shift the facing property value by 2:

# Once (on stairs)
execute positioned ~ ~ ~ run function #bs.block:get_block

# Run the transformation
function #bs.block:shift_properties {properties:[{name:"facing",by:2}]}

# See the result
data get storage bs:out block.block

Credits: Aksiome

Manage type#

#bs.block:replace_type

Replace the block type while trying to conserve the state. State is preserved only if the group of the output matches the input.

Inputs:

Macro var type [string]: String representation of the id (e.g., minecraft:stone).

Outputs:

Storage bs:out block [compound]: The block, state, properties and iterable_properties are updated to reflect this change.

Replace oak stairs with spruce stairs, preserving the current state:

# Once (on oak_stairs)
execute positioned ~ ~ ~ run function #bs.block:get_block

# Get block type data
function #bs.block:replace_type {type:"minecraft:spruce_stairs"}

# See the result
data get storage bs:out block.block
#bs.block:lookup_item

Get block data from the given item string id.

Inputs:

Macro var item [string]: Item string id associated to a block.

Outputs:

Storage bs:out block [compound]: Equivalent to the #bs.block:get_type function.

Get block data for the stone item:

# Get block type data
function #bs.block:lookup_item {item:"minecraft:stone"}

# See the result
data get storage bs:out block.block
#bs.block:lookup_type

Get block data from the given type string id.

Inputs:

Macro var type [string]: Type string id associated to a block.

Outputs:

Storage bs:out block [compound]: Equivalent to the #bs.block:get_type function.

Get block data for the stone type:

# Get block type data
function #bs.block:lookup_type {type:"minecraft:stone"}

# See the result
data get storage bs:out block.block

Credits: Aksiome

Match#

#bs.block:match

Determine if the block at the specified location matches the provided one.

Inputs:

Execution at <entity> or positioned <x> <y> <z>: Location of the block to check.

Storage bs:in block.match.block [string]: Full string representation of the block to check against.

Outputs:

Return: Whether the check is a success or a failure (1 or 0).

Check that the block at 0 0 0 matches the block at 0 1 0:

# Get block data at 0 0 0
execute positioned 0 0 0 run function #bs.block:get_block

# Setup the input
data modify storage bs:in block.match.block set from storage bs:out block.block

# Run a command if it's a match
execute positioned 0 1 0 if function #bs.block:match run say It's a match

Credits: Aksiome, theogiraudet

Set#

#bs.block:set_block

Place a block at the current location.

Inputs:

Execution at <entity> or positioned <x> <y> <z>: Position to set the block to.

Storage bs:in block.set_block.block [string]: Full string representation of the block to set.

Storage bs:in block.set_block.mode [string]: Mode used to set the block [destroy|keep|replace] (default: replace).

Outputs:

State: A block is placed in the world.

Place a block of stone at 0 0 0 by destroying the existing one:

# Setup the input
data modify storage bs:in block.set_block set value {block:"minecraft:stone",mode:"destroy"}

# Run the function
execute positioned 0 0 0 run function #bs.block:set_block
#bs.block:set_type

Replace the block type at the current location while trying to conserve its state and NBTs.

Inputs:

Execution at <entity> or positioned <x> <y> <z>: Position to set the block to.

Storage bs:in block.set_block.type [string]: Type (string id) of the block to set.

Storage bs:in block.set_block.mode [string]: Mode used to set the block [destroy|keep|replace] (default: replace).

Outputs:

State: A block is placed in the world.

Replace any stairs with oak stairs, preserving the current state:

# Setup the input
data modify storage bs:in block.set_type.type set value "minecraft:oak_stairs"

# Run the function
execute positioned 0 0 0 run function #bs.block:set_type

Credits: Aksiome, theogiraudet

Spawn#

#bs.block:spawn_block_display

Spawn a block display representing the given block.

Inputs:

Execution at <entity> or positioned <x> <y> <z>: Position where the entity will be summoned.

Storage bs:in block.spawn_block_display [compound]:

type [string]

Block type (similar to block output).

properties [compound]

Block properties (similar to block output).

extra_nbt [compound]

Additional NBTs to summon the entity with.
Outputs:

State: The entity is summoned.

Summon a block display using the block at 0 0 0:

# Get block data
execute positioned 0 0 0 run function #bs.block:get_block

# Setup the input
data modify storage bs:in block.spawn_block_display set from storage bs:out block

# Summon the block display
function #bs.block:spawn_block_display
#bs.block:spawn_falling_block

Spawn a falling block representing the given block.

Inputs:

Execution at <entity> or positioned <x> <y> <z>: Position where the entity will be summoned.

Storage bs:in block.spawn_falling_block [compound]:

type [string]

Block type (similar to block output).

properties [compound]

Block properties (similar to block output).

extra_nbt [compound]

Additional NBTs to summon the entity with.
Outputs:

State: The entity is summoned.

Summon a falling block using the block at 0 0 0:

# Get block data
execute positioned 0 0 0 run function #bs.block:get_block

# Setup the input
data modify storage bs:in block.spawn_falling_block set from storage bs:out block

# Summon the block display
function #bs.block:spawn_falling_block
#bs.block:spawn_solid_block_display

Spawn a block display with a hitbox, representing the given block.

Inputs:

Execution at <entity> or positioned <x> <y> <z>: Position where the entity will be summoned.

Storage bs:in block.spawn_solid_block_display [compound]:

type [string]

Block type (similar to block output).

properties [compound]

Block properties (similar to block output).

extra_nbt [compound]

Additional NBTs to summon the entity with.
Outputs:

State: The entity is summoned.

Summon a block display with a hitbox using the block at 0 0 0:

# Get block data
execute positioned 0 0 0 run function #bs.block:get_block

# Setup the input
data modify storage bs:in block.spawn_solid_block_display set from storage bs:out block

# Summon the block display
function #bs.block:spawn_solid_block_display

Credits: Aksiome, theogiraudet

💬 Did it help you?

Feel free to leave your questions and feedbacks below!

On this page
Edit on GitHub
Show Source