🎲 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

Select 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.

Example: 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

Select 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.

Example: 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>}

Generate 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].

Example: 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"}]
What is a Uniform Distribution?

Every outcome has an equal probability of occurring. It’s like rolling a fair die where each number (1 through 6) has the same probability.

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

Generate 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].

Example: 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"}]
What is a Binomial Distribution?

Used when you have a fixed number of trials, each with two possible outcomes (success or failure). It calculates the probability of obtaining a specific number of successes. For example, flipping a coin 10 times and counting the number of heads.

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

Generate 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].

Example: 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"}]
What is a Geometric Distribution?

Measures the number of trials required to achieve the first success in a sequence of independent and identical trials. For example, the number of dice rolls needed to obtain a six.

#bs.random:normal {mean:<mean>,spread:<spread>}

Generate a random number following a normal (Gaussian) distribution with specified mean and spread (standard deviation).

Inputs:

Function macro:

  • Arguments

    • mean: The average (center) value of the distribution.

    • spread: The standard deviation controlling how spread out the values are.

Outputs:

Return | Score $random.normal bs.out: A random integer centered near mean.

Example: Generate a random number with mean 10 and spread 3:

# Generate random number
function #bs.random:normal {mean:10,spread:3}

# Display the result
tellraw @a [{"text": "Number: ", "color": "dark_gray"},{"score":{"name":"$random.normal", "objective": "bs.out"}, "color": "gold"}]
What is a Normal Distribution?

Also known as the Gaussian distribution, it produces values clustered around the mean with a bell-shaped probability curve. Widely used to model natural variations and measurement errors.

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

Generate 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.

Example: 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"}]
What is a Poisson Distribution?

A Poisson distribution generates values that cluster around an average value, λ (lambda). Results tend to concentrate near this average, making it ideal for modeling random events occurring at a consistent rate.

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

Credits: Aksiome, SBtree

Noise Algorithms#

#bs.random:simplex_noise_2d

Compute 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]

Example: 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

Generate 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]

Example: 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:{}}

Generate 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}.

Example: 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:{}}

Generate 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}.

Example: 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:{}}

Generate 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}.

Example: 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:{}}

Generate 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}.

Example: 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 feedback below!