🏗️ Generation#

#bs.generation:help

Iterate over the world in various shapes, executing callbacks at each position. Processes can spread across multiple ticks to avoid lag.

“Nature’s beauty is a reflection of the harmony of numbers and patterns.”

—Anonymous

Watch a demo

🔧 Functions#

You can find below all functions available in this module.

On cuboid#

#bs.generation:on_cuboid

Iterate over a 3D cuboid, executing a callback at each position.

Inputs:

Execution at <entity> or positioned <x> <y> <z>: origin of the shape

Storage bs:in generation.on_cuboid:

iteration data
- run: callback to execute at each step
- direction: 3-letter string defining axis iteration order and direction
  
  e/w for east/west, s/n for south/north, and u/d for up/down (default: eus, +x, +y, +z)
- on_finished: command executed at the end of the process, at the final block position
- width: size along the x axis (default: 1)
- height: size along the y axis (default: 1)
- depth: size along the z axis (default: 1)
- spacing: distance between positions (default: 1)
- limit: maximum steps per tick (default: 256)

Lambdas:

Score $generation.i bs.lambda: first dimension index (0 to size-1, tied to 1st direction letter)

Score $generation.j bs.lambda: second dimension index (0 to size-1, tied to 2nd direction letter)

Score $generation.k bs.lambda: third dimension index (0 to size-1, tied to 3rd direction letter)

Outputs:

State: the callback is executed at each position

Example: replace spruce stairs with oak stairs using the set_block_type callback

data modify storage bs:in generation.on_cuboid set value { \
  width:5, height:5, depth:5, \
  run:'function #bs.generation:callback/set_block_type {type:"minecraft:oak_stairs",with:{masks:[{block:"minecraft:spruce_stairs"}]}}' \
}
function #bs.generation:on_cuboid

Credits: Aksiome

On rectangle#

#bs.generation:on_rectangle

Iterate over a 2D rectangle, executing a callback at each position.

Inputs:

Execution at <entity> or positioned <x> <y> <z>: origin of the shape

Storage bs:in generation.on_rectangle:

iteration data
- run: callback to execute at each step
- direction: 2-letter string defining axis iteration order and direction
  
  e/w for east/west, s/n for south/north, and u/d for up/down (default: es, +x, +z).
- on_finished: command executed at the end of the process, at the final block position
- width: size along the x axis (default: 1)
- height: size along the y axis (default: 1)
- depth: size along the z axis (default: 1)
- spacing: distance between positions (default: 1)
- limit: maximum steps per tick (default: 256)

Lambdas:

Score $generation.i bs.lambda: first dimension index (0 to size-1, tied to 1st direction letter)

Score $generation.j bs.lambda: second dimension index (0 to size-1, tied to 2nd direction letter)

Outputs:

State: the callback is executed at each position

Example: generate terrain using fractal noise

# Once
data modify storage bs:in generation.on_rectangle set value { \
  width:64, depth:64, limit: 64, \
  run:'function #bs.generation:callback/fractal_noise_2d {run:"function mypack:generate",with:{}}' \
}
function #bs.generation:on_rectangle

# mypack:generate
execute store result storage bs:ctx y int .01 run scoreboard players add $generation.noise bs.lambda 1000
function mypack:fill with storage bs:ctx

# mypack:fill
$fill ~ ~ ~ ~ ~$(y) ~ stone

Credits: Aksiome

↩️ Callbacks#

You can find below all callbacks available in this module.

Implementation note

These are not simple callbacks. They hook into internals to inject optimized sub-callbacks. Heavy initialization runs once, then lightweight callbacks handle the actual iteration.

Block callbacks#

Dependency

The set_block_type and set_random_block callbacks require the bs.block module to be installed.

Set block

#bs.generation:callback/set_block {block:<value>,with:{}}

Place a specific block at each position.

Inputs:

Function macro:

arguments
- block: block to place (e.g., minecraft:stone)
- with: additional settings
  - mode: placement mode [destroy|keep|replace] (default: replace)
  - masks: list of masks to filter positions (combine as AND)
    - mask entry
      - block: block to check (e.g., minecraft:stone, #minecraft:logs)
      - negate: invert the condition (default: false)
      - x: x offset (default: 0)
      - y: y offset (default: 0)
      - z: z offset (default: 0)

Example: fill with stone, replacing only air

run:'function #bs.generation:callback/set_block {block:"minecraft:stone",with:{masks:[{block:"minecraft:air"}]}}'

Set block type

#bs.generation:callback/set_block_type {type:<value>,with:{}}

Replace block types while preserving states and NBT data.

Inputs:

Function macro:

arguments
- type: block type ID (e.g., minecraft:oak_stairs)
- with: additional settings
  - mode: placement mode [destroy|keep|replace] (default: replace)
  - masks: list of masks to filter positions (combine as AND)
    - mask entry
      - block: block to check (e.g., minecraft:stone, #minecraft:logs)
      - negate: invert the condition (default: false)
      - x: x offset (default: 0)
      - y: y offset (default: 0)
      - z: z offset (default: 0)

Example: convert spruce stairs to oak, preserving orientation

run:'function #bs.generation:callback/set_block_type {type:"minecraft:oak_stairs",with:{masks:[{block:"minecraft:spruce_stairs"}]}}'

Set random block

#bs.generation:callback/set_random_block {blocks:[],with:{}}

Place a randomly selected block from a weighted list.

Inputs:

Function macro:

arguments
- blocks: weighted block list
  - block entry
    - block | type: full block string or type that preserves states
    - weight: selection weight (default: 1)
- with: additional settings
  - mode: placement mode [destroy|keep|replace] (default: replace)
  - masks: list of masks to filter positions (combine as AND)
    - mask entry
      - block: block to check (e.g., minecraft:stone, #minecraft:logs)
      - negate: invert the condition (default: false)
      - x: x offset (default: 0)
      - y: y offset (default: 0)
      - z: z offset (default: 0)

Example: create a mixed ore vein

run:'function #bs.generation:callback/set_random_block { \
  blocks:[{block:"minecraft:stone",weight:10},{block:"minecraft:coal_ore",weight:5},{block:"minecraft:iron_ore",weight:2}], \
  with:{masks:[{block:"minecraft:air",negate:1b}]} \
}'

Credits: Aksiome

Noise callbacks#

Dependency

Noise callbacks require the bs.random module to be installed.

Fractal noise 2D

#bs.generation:callback/fractal_noise_2d {run:<value>,with:{}}

Compute fractal noise and execute a callback with the noise value. Combines multiple octaves of simplex noise for natural patterns.

Inputs:

Function macro:

arguments
- run: callback to execute with the noise value
- with: noise settings
  - size: noise granularity, lower = more detail (default: 32)
  - seed: seed for reproducibility (default: random)
  - octaves: number of noise layers (default: 2)
  - persistence: amplitude multiplier per octave (default: 0.5)
  - lacunarity: frequency multiplier per octave (default: 2.0)

Lambdas:

Score $generation.noise bs.lambda: noise value in range [-1000, 1000]

Score $generation.i bs.lambda: first dimension index (inherited from iterator)

Score $generation.j bs.lambda: second dimension index (inherited from iterator)

Simplex noise 2D

#bs.generation:callback/simplex_noise_2d {run:<value>,with:{}}

Compute simplex noise and execute a callback with the noise value.

Inputs:

Function macro:

arguments
- run: callback to execute with the noise value
- with: noise settings
  - size: noise granularity, lower = more detail (default: 32)
  - seed: seed for reproducibility (default: random)

Lambdas:

Score $generation.noise bs.lambda: noise value in range [-1000, 1000]

Score $generation.i bs.lambda: first dimension index (inherited from iterator)

Score $generation.j bs.lambda: second dimension index (inherited from iterator)

Credits: Aksiome

💬 Did it help you?

Feel free to leave your questions and feedback below!