Random Functions

These functions are for generating random numbers, to add variation and unpredictability to your vaults.

Syntax:

crawl.coinflip()

Returns: boolean

50% chance each of true or false.

Syntax:

crawl.one_chance_in(num)

Returns: boolean

This function has one chance in num of returning true. Otherwise, it returns false.

Empirically, this function appears to resolve real-valued parameters by first rounding num to an integer. It is NOT possible to use crawl.one_chance_in(1.5) to get a two-thirds chance. If you need a two-thirds chance, use the x_chance_in_y function.

If numerator is greater than or equal to denominator, true is always returned.

Syntax:

crawl.x_chance_in_y(numerator, denominator)

Returns: boolean

This function has numerator in denominator of returning true. Otherwise, it returns false.

Empirically, this function appears to resolve real-valued parameters as follows:

1. Both parameters are rounded to integers n and d.
2. A random integer i in the range [0, d) is calculated. 0 is a possible value but d is not.
3. If i is less than n, true is returned. Otherwise, false is returned.

If numerator is negative (or less then 0.5), false is always returned.

Examples:

• crawl.x_chance_in_y(1) crashes while Crawl is loading.
• crawl.x_chance_in_y(1, 1) always returns true.
• crawl.x_chance_in_y(0, 1) always returns false.
• crawl.x_chance_in_y(100, 200) has a 50% chance of true or false.
• crawl.x_chance_in_y(3, 8) has a 37.5% chance of true and a 62.5% chance of false.
• crawl.x_chance_in_y(1, 0) always returns true.
• crawl.x_chance_in_y(0, 0) always returns false.
• crawl.x_chance_in_y(-3, 5) always returns false.

Syntax:

crawl.roll_dice(count, sides)

Returns: integer

This function simulates rolling count dice, each with sides sides (numbered from 1 to sides) and returns the total. This allows random numbers to be generated that are weighted towards the center of a range. The mode sides are used, the stronger the weighting to the center.

For example, suppose you want to generate a random number in the range [10, 20], including both 10 and 20 as possibilities. The chance of getting 15 can be varied by changing the count of dice rolled. We will also have to change the number of sides and add on different constants to get the same range.

• crawl.roll_dice( 1, 11) + 9 has a 1-in-1 = 9.1% chance of getting 15
• crawl.roll_dice( 2, 6) + 8 has a 6-in-36 = 16.7% chance of getting 15
• crawl.roll_dice(10, 2) + 0 has a 525-in-1024 = 24.6% chance of getting 15

Empirically, this function appears to resolve real-valued parameters as follows:

1. Both parameters are rounded to integers c and s.
2. c random numbers in the range [1, s] is calculated. 1 and s are both possible values.
3. The sum of the numbers is returned.

If count or sides is negative (or less then 0.5), 0 is always returned.

Examples:

• crawl.roll_dice(1) crashes while Crawl is loading.
• crawl.roll_dice(1, 1) always returns 1.
• crawl.roll_dice(1, 4) has a 25% chance of returning 1, 2, 3, or 4.
• crawl.roll_dice(2, 4) has a 1-in-16 chance of returning 2 or 8, a 1-in-8 chance of returning 3 or 7, a 3-in-16 chance of returning 4 or 6, and a 1-in-4 chance or returning 5. This is equivalent to crawl.roll_dice(1, 4) + crawl.roll_dice(1, 4).
• crawl.roll_dice(0, 4) always returns 0.
• crawl.roll_dice(-5, 6) always returns 0.
• crawl.roll_dice(3, 0) always returns 0.
• crawl.roll_dice(8, -5) always returns 0.
• crawl.roll_dice(-3, -2) always returns 0.

Syntax:

val = crawl.random2(num)

Returns: integer

Empirically, this function appears to resolve real-valued parameters as follows:

1. The parameter is rounded to an integer i.
2. A random integer in the range [0, i) is returned. 0 is a possible value but i is not.

Passing a negative value (or any value less than 1.5) causes it to always return 0.

Examples:

• crawl.random2(1.4) always returns 0.
• crawl.random2(1.5) has a 50% chance of 0 or 1.
• crawl.random2(5) has a 20% chance of 0, 1, 2, 3, or 4.
• crawl.random2(0) always returns 0.
• crawl.random2(-3) always returns 0.
• crawl.random2(-0.5) always returns 0.

Syntax:

val = crawl.random_real()

Returns: floating point

This function returns a random real number ion the range [0, 1). 0 is a possible value, but 1 is not.

Syntax:

val = crawl.random2avg(n1, n2)

Returns:

Syntax:

val = crawl.random2(low, high)

Returns: integer

Empirically, this function appears to resolve real-valued parameters as follows:

1. The low and high parameters are rounded to integers L and H. 0.5 and -0.5 both round to 0.
2. A random integer in the range [L, H] is returned.

If low is greater than high, low is always returned.

Examples:

• crawl.random2(1) crashes at run-time.
• crawl.random2(1, 1) always returns 1.
• crawl.random2(0, 1) has a 50% chance of 0 or 1.
• crawl.random2(0, 4) has a 20% chance of 0, 1, 2, 3, or 4.
• crawl.random2(-1, 2) has a 25% chance of -1, 0, 1, or 2.
• crawl.random2(-10, -6) has a 20% chance of -10, -9, -8, -7, or -6.
• crawl.random2(2, 1) always returns 1.

Syntax:

val = crawl.div_rand_round(num, dem)

Returns: integer

This function returns num / dem, truncated to an integer. If num / dem does not divide evenly, there is a chance that 1 is added to the result based on the remainder. The result always lies in the range [floor(num/den), ceil(num/den)].

For example, crawl.div_rand_round(5, 3) would have a 33% chance of returning 1 and a 67% chance of returning 2.

From layout.des:

local fill = crawl.random_element({
    ["."] = 10,
    ["w"] = 5,
    ["l"] = 1,
})

This function appears to return one of the values provided as an table index, using the values in the table as ratios.