🎲 Random#

#bs.random:help

Contains many random functions for different distributions and noise patterns.

../_images/random.png

“Creativity is the ability to introduce order into the randomness of nature.”

—Eric Hoffer

🔧 Functions#

You can find below all functions available in this module.

Random choice#

#bs.random:choice

Selects a random value from a list.

Inputs:

Storage bs:in random.choice.options: The list of values to choose from.

Outputs:

Storage bs:out random.choice: The randomly selected value.

Return: The index of the chosen value.

Pick a random fruit from the list:

# Populate list with values
data modify storage bs:in random.choice.options set value ["Apple", "Banana", "Strawberry", "Blueberry", "Mango", "Watermelon"]

# Randomly select one
function #bs.random:choice

# Display the result
tellraw @a [{"text":"Value: ","color":"dark_gray"},{"nbt":"random.choice","storage":"bs:out","color":"gold"}]
#bs.random:weighted_choice

Selects a random value from a list based on specified weights.

Inputs:

Storage bs:in random.weighted_choice.options: The list of values to choose from.

Storage bs:in random.weighted_choice.weights: The corresponding weights for each value.

Outputs:

Storage bs:out random.weighted_choice: The randomly selected value based on the weights.

Return: The index of the chosen value.

Pick a random fruit from the list based on weights:

# Populate list with values
data modify storage bs:in random.weighted_choice.options set value ["Apple", "Banana", "Strawberry"]

# Populate list with weights
data modify storage bs:in random.weighted_choice.weights set value [5, 3, 2]

# Randomly select one based on weights
function #bs.random:weighted_choice

# Display the result
tellraw @a [{"text":"Value: ","color":"dark_gray"},{"nbt":"random.weighted_choice","storage":"bs:out","color":"gold"}]

Credits: Aksiome, SBtree

Random distributions#

#bs.random:uniform {min:<min>,max:<max>}

Generates a random number uniformly distributed between min and max.

Inputs:

Function macro:

  • Arguments
    • min: The lower bound.
    • max: The upper bound.
Outputs:

Return | Score $random.uniform bs.out: A random integer in range [min, max].

Generate a random number between 1 and 100:

# Generate random number
function #bs.random:uniform {min:1,max:100}

# Display the result
tellraw @a [{"text": "Number: ", "color": "dark_gray"},{"score":{"name":"$random.uniform", "objective": "bs.out"}, "color": "gold"}]

Uniform Distribution… 🥶 What’s this?

Every outcome has an equal chance of happening. It’s like rolling a fair die. Each number (1 through 6) is equally likely.

#bs.random:binomial {trials:<trials>,probability:<probability>}

Generates a random number with a binomial distribution using the specified trials and probability.

Inputs:

Function macro:

  • Arguments
    • trials: The number of Bernoulli trials. Maximum accepted value is 1000.
    • probability: The probability of success of each Bernoulli trial, in range [0,1].
Outputs:

Return | Score $random.binomial bs.out: A random integer in range [0, trials].

Generate a random number with 10 trials and a 20% success chance:

# Generate random number
function #bs.random:binomial {trials:10,probability:0.2}

# Display the result
tellraw @a [{"text": "Number: ", "color": "dark_gray"},{"score":{"name":"$random.binomial", "objective": "bs.out"}, "color": "gold"}]

Binomial Distribution… 🥶 What’s this?

Used when you have a fixed number of trials, each with two possible outcomes (like success or failure). It tells you the probability of getting a certain number of successes. For example, flipping a coin 10 times and counting how many heads you get.

#bs.random:geometric {probability:<probability>}

Generates a random number following a geometric distribution with the given probability.

Inputs:

Function macro:

  • Arguments
    • probability: The probability of stopping at each trial, in range [0,1].
Outputs:

Return | Score $random.geometric bs.out: A random integer in range [0, 1000].

Generate a random number with a 2% chance of stopping:

# Generate random number
function #bs.random:geometric {probability:0.02}

# Display the result
tellraw @a [{"text": "Number: ", "color": "dark_gray"},{"score":{"name":"$random.geometric", "objective": "bs.out"}, "color": "gold"}]

Geometric Distribution… 🥶 What’s this?

Measures the number of trials needed to get the first success in a series of independent and identical trials. For instance, how many times you need to roll a die before getting a six.

#bs.random:poisson {lambda:<lambda>}

Generates a random number following a Poisson distribution with the expected value lambda.

Inputs:

Function macro:

  • Arguments
    • lambda: The expected value in range [0,10].
Outputs:

Return | Score $random.poisson bs.out: A random integer, biased towards the lambda value.

Generate a random number biased towards 5:

# Generate random number
function #bs.random:poisson {lambda:5}

# Display the result
tellraw @a [{"text": "Number: ", "color": "dark_gray"},{"score":{"name":"$random.poisson", "objective": "bs.out"}, "color": "gold"}]

Poisson Distribution… 🥶 What’s this?

A Poisson distribution produces values that tend to cluster around an average value, λ (lambda). Most results will be close to this average, which makes it useful for modeling random events happening at a consistent rate.

../_images/distributions_dark.png ../_images/distributions_light.png

Credits: Aksiome, SBtree

Noise algorithms#

#bs.random:simplex_noise_2d

Computes the simplex noise value at given coordinates. Simplex noise is a type of gradient noise, similar to Perlin noise, used for textures or procedural generation.

Inputs:

Score $random.simplex_noise_2d.seed bs.in: The seed used for generation.

Scores $random.simplex_noise_2d.[x,y] bs.in: Coordinates, scaled by 1000 (e.g., for a cell size of 16, multiply by 1000/16).

Outputs:

Return | Score $random.simplex_noise_2d bs.out: The noise value in range [-1000,1000]

Generate a random noise value:

# Generate random noise value
scoreboard players set $random.simplex_noise_2d.x bs.in 15589
scoreboard players set $random.simplex_noise_2d.y bs.in 812
execute store result score $random.simplex_noise_2d.seed bs.in run random value -1000000000..1000000000
function #bs.random:simplex_noise_2d
#bs.random:fractal_noise_2d

Generates fractal noise by combining multiple noise layers at different scales, often used for terrain generation.

Inputs:

Score $random.fractal_noise_2d.seed bs.in: The seed used for generation.

Scores $random.fractal_noise_2d.[x,y] bs.in: Coordinates, scaled by 1000 (e.g., for a cell size of 16, multiply by 1000/16).

Score $random.fractal_noise_2d.octaves bs.in: Number of noise layers to combine (more octaves = more detail).

Score $random.fractal_noise_2d.persistence bs.in: Contribution of each octave to the total noise, scaled by 1000.

Score $random.fractal_noise_2d.lacunarity bs.in: Increase in frequency for each octave, scaled by 1000.

Outputs:

Return | Score $random.fractal_noise_2d bs.out: The noise value in range [-1000,1000]

Generate a random noise value:

# Generate random noise value
scoreboard players set $random.fractal_noise_2d.x bs.in 15589
scoreboard players set $random.fractal_noise_2d.y bs.in 812
scoreboard players set $random.fractal_noise_2d.octaves bs.in 4
scoreboard players set $random.fractal_noise_2d.persistence bs.in 500
scoreboard players set $random.fractal_noise_2d.lacunarity bs.in 2000
execute store result score $random.fractal_noise_2d.seed bs.in run random value -1000000000..1000000000
function #bs.random:fractal_noise_2d

Credits: Aksiome, SBtree

Noise matrices#

#bs.random:white_noise_mat_1d {length:<length>,with:{}}

Generates a 1-dimensional array of white noise values.

Inputs:

Function macro:

  • Arguments
    • length: Length of the array to generate.
    • with:
      • scale: Scalar for the function’s output (default: 1).
Outputs:

Storage bs:out random.white_noise_mat_1d: Array of values between 0 and {scale}.

Generate 4 random values:

# Generate random noise
function #bs.random:white_noise_mat_1d {length:4,with:{}}

# Display the result
tellraw @a [{"text": "Noise: ", "color": "dark_gray"},{"nbt":"white_noise_mat_1d","storage":"bs:out", "color": "gold"}]
#bs.random:white_noise_mat_2d {width:<width>,height:<height>,with:{}}

Generates a 2-dimensional array of white noise values.

Inputs:

Function macro:

  • Arguments
    • width: Width of the array to generate.
    • height: Height of the array to generate.
    • with:
      • scale: Scalar for the function’s output (default: 1).
Outputs:

Storage bs:out random.white_noise_mat_2d: 2D array of values between 0 and {scale}.

Generate a 4x4 random noise pattern:

# Generate random noise
function #bs.random:white_noise_mat_2d {width:4,height:4,with:{}}

# Display the result
tellraw @a [{"text": "Noise: ", "color": "dark_gray"},{"nbt":"white_noise_mat_2d","storage":"bs:out", "color": "gold"}]
#bs.random:simplex_noise_mat_2d {width:<width>,height:<height>,with:{}}

Generates a 2D simplex noise texture of size width by height. Simplex noise is a gradient noise often used for textures.

Inputs:

Function macro:

  • Arguments
    • width: Width of the array to generate.
    • height: Height of the array to generate.
    • with:
      • size: Size of the noise “cell” (default: 16). Lower size means more detail.
      • seed: Seed for the noise generation, allowing for reproducibility (default: random).
      • scale: Scalar for the function’s output (default: 1).
Outputs:

Storage bs:out random.simplex_noise_mat_2d: 2D array of values between {-scale} and {scale}.

Generate a 16×16 simplex noise pattern:

# Generate random noise
function #bs.random:simplex_noise_mat_2d {width:16,height:16,with:{size:8}}

# Display the result
tellraw @a [{"text": "Noise: ", "color": "dark_gray"},{"nbt":"simplex_noise_mat_2d","storage":"bs:out", "color": "gold"}]
#bs.random:fractal_noise_mat_2d {width:<width>,height:<height>,with:{}}

Generates a 2D fractal noise texture of size width by height. Fractal noise combines multiple layers of noise for detailed textures.

Inputs:

Function macro:

  • Arguments
    • width: Width of the array to generate.
    • height: Height of the array to generate.
    • with:
      • size: Size of the noise “cell” (default: 16). Lower size means more detail.
      • seed: Seed for the noise generation, allowing for reproducibility (default: random).
      • octaves: Number of noise layers (default: 4). More octaves = more detail.
      • persistence: Contribution of each octave (default: 0.5). Higher means more detail.
      • lacunarity: Increase in frequency for each octave (default: 2.0). Higher means more rapid frequency increase.
      • scale: Scalar for the function’s output (default: 1).
Outputs:

Storage bs:out random.fractal_noise_mat_2d: 2D array of values between {-scale} and {scale}.

Generate a 16×16 fractal noise pattern:

# Generate random noise
function #bs.random:fractal_noise_mat_2d {width:16,height:16,with:{size:8}}

# Display the result
tellraw @a [{"text": "Noise: ", "color": "dark_gray"},{"nbt":"fractal_noise_mat_2d","storage":"bs:out", "color": "gold"}]
White noise

Simplex noise

Fractal noise

Credits: Aksiome, SBtree

💬 Did it help you?

Feel free to leave your questions and feedbacks below!