Angband
z-rand.h File Reference

A Random Number Generator for Angband. More...

`#include "h-basic.h"`

Go to the source code of this file.

## Data Structures

struct  random
A struct representing a strategy for making a dice roll. More...

## Macros

#define MAX_RAND_DEPTH   128
Assumed maximum dungeon level. More...

#define RAND_DEG   32
The number of 32-bit integers worth of seed state. More...

#define randint0(M)   ((s32b) Rand_div(M))
Generates a random signed long integer X where "0 <= X < M" holds. More...

#define randint1(M)   ((s32b) Rand_div(M) + 1)
Generates a random signed long integer X where "1 <= X <= M" holds. More...

#define rand_spread(A, D)   ((A) + (randint0(1 + (D) + (D))) - (D))
Generate a random signed long integer X where "A - D <= X <= A + D" holds. More...

#define one_in_(x)   (!randint0(x))
Return true one time in `x`. More...

## Typedefs

typedef struct random random_value
A struct representing a strategy for making a dice roll. More...

## Enumerations

enum  aspect {
MINIMISE, AVERAGE, MAXIMISE, EXTREMIFY,
RANDOMISE
}
Random aspects used by damcalc, m_bonus_calc, and ranvals. More...

## Functions

void Rand_state_init (u32b seed)
Initialise the RNG state with the given seed. More...

void Rand_init (void)
Initialise the RNG. More...

u32b Rand_div (u32b m)
Generates a random unsigned long integer X where "0 <= X < M" holds. More...

s16b Rand_normal (int mean, int stand)
Generate a signed random integer within `stand` standard deviations of `mean`, following a normal distribution. More...

int Rand_sample (int mean, int upper, int lower, int stand_u, int stand_l)
Generate a signed random integer following a normal distribution, where `upper` and `lower` are approximate bounds, and `stand_u and`stand_l` are ten times the number of standard deviations from the mean we are assuming the bounds are. More...

u32b Rand_simple (u32b m)
Generate a semi-random number from 0 to m-1, in a way that doesn't affect gameplay. More...

int damroll (int num, int sides)
Emulate a number `num` of dice rolls of dice with `sides` sides. More...

int damcalc (int num, int sides, aspect dam_aspect)
Calculation helper function for damroll. More...

int rand_range (int A, int B)
Generates a random signed long integer X where "A <= X <= B" Note that "rand_range(0, N-1)" == "randint0(N)". More...

s16b m_bonus (int max, int level)
Function used to determine enchantment bonuses, see function header for a more complete description. More...

s16b m_bonus_calc (int max, int level, aspect bonus_aspect)
Calculation helper function for m_bonus. More...

int randcalc (random_value v, int level, aspect rand_aspect)
Calculation helper function for random_value structs. More...

bool randcalc_valid (random_value v, int test)
Test to see if a value is within a random_value's range. More...

bool randcalc_varies (random_value v)
Test to see if a random_value actually varies. More...

void rand_fix (u32b val)

## Variables

bool Rand_quick
Whether we are currently using the "quick" method or not. More...

u32b Rand_value
The state used by the "quick" RNG. More...

u32b state_i
The state used by the "complex" RNG. More...

u32b STATE [RAND_DEG]

u32b z0

u32b z1

u32b z2

## Detailed Description

A Random Number Generator for Angband.

Copyright (c) 1997 Ben Harrison, Randy Hutson Copyright (c) 2010 Erik Osheim

See below for copyright on the WELL random number generator.

This work is free software; you can redistribute it and/or modify it under the terms of either:

b) the "Angband licence": This software may be copied and distributed for educational, research, and not for profit purposes provided that this copyright and statement are included in all such copies. Other copyrights may also apply.

## ◆ MAX_RAND_DEPTH

 #define MAX_RAND_DEPTH   128

Assumed maximum dungeon level.

This value is used for various calculations involving object and monster creation. It must be at least

1. Setting it below 128 may prevent the creation of some objects.

Referenced by m_bonus(), m_bonus_calc(), and player_knows_ego().

## ◆ RAND_DEG

 #define RAND_DEG   32

The number of 32-bit integers worth of seed state.

Referenced by Rand_state_init(), rd_randomizer(), and wr_randomizer().

 #define rand_spread ( A, D ) ((A) + (randint0(1 + (D) + (D))) - (D))

Generate a random signed long integer X where "A - D <= X <= A + D" holds.

Note that "rand_spread(A, D)" == "rand_range(A - D, A + D)"

The integer X falls along a uniform distribution.

Referenced by make_gold(), place_new_monster_one(), rand_loc(), spread_monsters(), and town_gen_layout().

## ◆ random_value

 typedef struct random random_value

A struct representing a strategy for making a dice roll.

The result will be base + XdY + BONUS, where m_bonus is used in a tricky way to determine BONUS.

## ◆ aspect

 enum aspect

Random aspects used by damcalc, m_bonus_calc, and ranvals.

Enumerator
MINIMISE
AVERAGE
MAXIMISE
EXTREMIFY
RANDOMISE

## ◆ damcalc()

 int damcalc ( int num, int sides, aspect dam_aspect )

Calculation helper function for damroll.

References AVERAGE, damroll(), EXTREMIFY, MAXIMISE, MINIMISE, num, and RANDOMISE.

Referenced by randcalc().

## ◆ damroll()

 int damroll ( int num, int sides )

Emulate a number `num` of dice rolls of dice with `sides` sides.

Emulate a number `num` of dice rolls of dice with `sides` sides.

References i, num, and randint1.

## ◆ m_bonus()

 s16b m_bonus ( int max, int level )

Function used to determine enchantment bonuses, see function header for a more complete description.

Function used to determine enchantment bonuses, see function header for a more complete description.

To avoid floating point but still provide a smooth distribution of bonuses, we simply round the results of division in such a way as to "average" the correct floating point value.

This function has been changed. It uses "Rand_normal()" to choose values from a normal distribution, whose mean moves from zero towards the max as the level increases, and whose standard deviation is equal to 1/4 of the max, and whose values are forced to lie between zero and the max, inclusive.

Since the "level" rarely passes 100 before Morgoth is dead, it is very rare to get the "full" enchantment on an object, even a deep levels.

It is always possible (albeit unlikely) to get the "full" enchantment.

A sample distribution of values from "m_bonus(10, N)" is shown below:

N 0 1 2 3 4 5 6 7 8 9 10

0 66.37 13.01 9.73 5.47 2.89 1.31 0.72 0.26 0.12 0.09 0.03 8 46.85 24.66 12.13 8.13 4.20 2.30 1.05 0.36 0.19 0.08 0.05 16 30.12 27.62 18.52 10.52 6.34 3.52 1.95 0.90 0.31 0.15 0.05 24 22.44 15.62 30.14 12.92 8.55 5.30 2.39 1.63 0.62 0.28 0.11 32 16.23 11.43 23.01 22.31 11.19 7.18 4.46 2.13 1.20 0.45 0.41 40 10.76 8.91 12.80 29.51 16.00 9.69 5.90 3.43 1.47 0.88 0.65 48 7.28 6.81 10.51 18.27 27.57 11.76 7.85 4.99 2.80 1.22 0.94 56 4.41 4.73 8.52 11.96 24.94 19.78 11.06 7.18 3.68 1.96 1.78 64 2.81 3.07 5.65 9.17 13.01 31.57 13.70 9.30 6.04 3.04 2.64 72 1.87 1.99 3.68 7.15 10.56 20.24 25.78 12.17 7.52 4.42 4.62 80 1.02 1.23 2.78 4.75 8.37 12.04 27.61 18.07 10.28 6.52 7.33 88 0.70 0.57 1.56 3.12 6.34 10.06 15.76 30.46 12.58 8.47 10.38 96 0.27 0.60 1.25 2.28 4.30 7.60 10.77 22.52 22.51 11.37 16.53 104 0.22 0.42 0.77 1.36 2.62 5.33 8.93 13.05 29.54 15.23 22.53 112 0.15 0.20 0.56 0.87 2.00 3.83 6.86 10.06 17.89 27.31 30.27 120 0.03 0.11 0.31 0.46 1.31 2.48 4.60 7.78 11.67 25.53 45.72 128 0.02 0.01 0.13 0.33 0.83 1.41 3.24 6.17 9.57 14.22 64.07

References MAX_RAND_DEPTH, Rand_normal(), simulate_division(), and value.

## ◆ m_bonus_calc()

 s16b m_bonus_calc ( int max, int level, aspect bonus_aspect )

Calculation helper function for m_bonus.

References AVERAGE, EXTREMIFY, m_bonus(), MAX_RAND_DEPTH, MAXIMISE, MINIMISE, and RANDOMISE.

Referenced by randcalc().

## ◆ Rand_div()

 u32b Rand_div ( u32b m )

Generates a random unsigned long integer X where "0 <= X < M" holds.

The integer X falls along a uniform distribution.

Generates a random unsigned long integer X where "0 <= X < M" holds.

This method selects "random" 28-bit numbers, and then uses division to drop those numbers into "m" different partitions, plus a small non-partition to reduce bias, taking as the final value the first "good" partition that a number falls into.

This method has no bias, and is much less affected by patterns in the "low" bits of the underlying RNG's. However, it is potentially non-terminating.

References LCRNG, rand_fixed, rand_fixval, Rand_quick, Rand_value, and WELLRNG1024a().

Referenced by rand_range().

## ◆ rand_fix()

 void rand_fix ( u32b val )

References getpid(), rand_fixed, and rand_fixval.

Referenced by setup_tests().

## ◆ Rand_init()

 void Rand_init ( void )

Initialise the RNG.

References getpid(), Rand_quick, and Rand_state_init().

Referenced by init_angband().

## ◆ Rand_normal()

 s16b Rand_normal ( int mean, int stand )

Generate a signed random integer within `stand` standard deviations of `mean`, following a normal distribution.

Generate a signed random integer within `stand` standard deviations of `mean`, following a normal distribution.

The table above is used to generate a psuedo-normal distribution, in a manner which is much faster than calling a transcendental function to calculate a true normal distribution.

Basically, entry 64 * N in the table above represents the number of times out of 32767 that a random variable with normal distribution will fall within N standard deviations of the mean. That is, about 68 percent of the time for N=1 and 95 percent of the time for N=2.

The table above contains a "faked" final entry which allows us to pretend that all values in a normal distribution are strictly less than four standard deviations away from the mean. This results in "conservative" distribution of approximately 1/32768 values.

Note that the binary search takes up to 16 quick iterations.

References one_in_, Rand_normal_table, randint0, RANDNOR_NUM, and RANDNOR_STD.

## ◆ rand_range()

 int rand_range ( int A, int B )

Generates a random signed long integer X where "A <= X <= B" Note that "rand_range(0, N-1)" == "randint0(N)".

The integer X falls along a uniform distribution.

Generates a random signed long integer X where "A <= X <= B" Note that "rand_range(0, N-1)" == "randint0(N)".

The integer X falls along a uniform distribution.

Note that "rand_range(0, N-1)" == "randint0(N)".

References Rand_div().

## ◆ Rand_sample()

 int Rand_sample ( int mean, int upper, int lower, int stand_u, int stand_l )

Generate a signed random integer following a normal distribution, where `upper` and `lower` are approximate bounds, and `stand_u and`stand_l` are ten times the number of standard deviations from the mean we are assuming the bounds are.

Generate a signed random integer following a normal distribution, where `upper` and `lower` are approximate bounds, and `stand_u and`stand_l` are ten times the number of standard deviations from the mean we are assuming the bounds are.

We divide the imagined distribution into two halves, above and below the mean, and then treat the bounds as if they are the given number of standard deviations from the mean in the appropriate direction. Note that `stand_u` and `stand_l` are 10 times the number of standart deviations we are asking for. The function chooses an integer from a normal distribution, and then scales it to fit the target distribution.

References mean(), and Rand_normal().

Referenced by design_artifact().

## ◆ Rand_simple()

 u32b Rand_simple ( u32b m )

Generate a semi-random number from 0 to m-1, in a way that doesn't affect gameplay.

This is intended for use by external program parts like the main-*.c files.

Generate a semi-random number from 0 to m-1, in a way that doesn't affect gameplay.

References getpid(), and LCRNG.

Referenced by savefile_save().

## ◆ Rand_state_init()

 void Rand_state_init ( u32b seed )

Initialise the RNG state with the given seed.

Initialise the RNG state with the given seed.

References i, LCRNG, RAND_DEG, STATE, and state_i.

Referenced by Rand_init().

## ◆ randcalc()

 int randcalc ( random_value v, int level, aspect rand_aspect )

Calculation helper function for random_value structs.

## ◆ randcalc_valid()

 bool randcalc_valid ( random_value v, int test )

Test to see if a value is within a random_value's range.

References MAXIMISE, MINIMISE, and randcalc().

## ◆ randcalc_varies()

 bool randcalc_varies ( random_value v )

Test to see if a random_value actually varies.

References MAXIMISE, MINIMISE, and randcalc().

Referenced by object_has_standard_to_h().

## ◆ Rand_quick

 bool Rand_quick

Whether we are currently using the "quick" method or not.

Whether we are currently using the "quick" method or not.

Referenced by do_randart(), flavor_init(), Rand_div(), Rand_init(), and rd_randomizer().

## ◆ Rand_value

 u32b Rand_value

The state used by the "quick" RNG.

The state used by the "quick" RNG.

Referenced by do_randart(), flavor_init(), Rand_div(), randname_make(), rd_randomizer(), and wr_randomizer().

## ◆ STATE

 u32b STATE[RAND_DEG]

## ◆ state_i

 u32b state_i

The state used by the "complex" RNG.

Referenced by Rand_state_init(), rd_randomizer(), WELLRNG1024a(), and wr_randomizer().

## ◆ z0

 u32b z0

## ◆ z1

 u32b z1

## ◆ z2

 u32b z2