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.
#define RAND_DEG   32
The number of 32-bit integers worth of seed state.
#define randint0(M)   ((s32b) Rand_div(M))
Generates a random signed long integer X where "0 <= X < M" holds.
#define randint1(M)   ((s32b) Rand_div(M) + 1)
Generates a random signed long integer X where "1 <= X <= M" holds.
#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.
#define one_in_(x)   (!randint0(x))
Return TRUE one time in x.

## Typedefs

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

## 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.
void Rand_init (void)
Initialise the RNG.
u32b Rand_div (u32b m)
Generates a random unsigned long integer X where "0 <= X < M" holds.
s16b Rand_normal (int mean, int stand)
Generate a signed random integer within stand standard deviations of mean, following a normal distribution.
u32b Rand_simple (u32b m)
Generate a semi-random number from 0 to m-1, in a way that doesn't affect gameplay.
int damroll (int num, int sides)
Emulate a number num of dice rolls of dice with sides sides.
int damcalc (int num, int sides, aspect dam_aspect)
Calculation helper function for damroll.
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)".
s16b m_bonus (int max, int level)
Function used to determine enchantment bonuses, see function header for a more complete description.
s16b m_bonus_calc (int max, int level, aspect bonus_aspect)
Calculation helper function for m_bonus.
int randcalc (random_value v, int level, aspect rand_aspect)
Calculation helper function for random_value structs.
bool randcalc_valid (random_value v, int test)
Test to see if a value is within a random_value's range.
bool randcalc_varies (random_value v)
Test to see if a random_value actually varies.
void rand_fix (u32b val)

## Variables

bool Rand_quick
Whether we are currently using the "quick" method or not.
u32b Rand_value
The state used by the "quick" RNG.
u32b state_i
The state used by the "complex" RNG.
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.

## Macro Definition Documentation

 #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(), and m_bonus_calc().

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

## Typedef Documentation

 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.

## Enumeration Type Documentation

 enum aspect

Random aspects used by damcalc, m_bonus_calc, and ranvals.

Enumerator:
 MINIMISE AVERAGE MAXIMISE EXTREMIFY RANDOMISE

## Function Documentation

 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().

 int damroll ( int num, int sides )

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

References i, num, and randint1.

 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.

 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().

 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().

 void rand_fix ( u32b val )

References rand_fixed, rand_fixval, and TRUE.

Referenced by setup_tests().

 void Rand_init ( void )

Initialise the RNG.

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

Referenced by init_angband().

 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.

 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().

 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.

References getpid(), and LCRNG.

Referenced by savefile_save().

 void Rand_state_init ( u32b seed )

Initialise the RNG state with the given seed.

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

Referenced by Rand_init().

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

Calculation helper function for random_value structs.

 bool randcalc_valid ( random_value v, int test )

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

References FALSE, MAXIMISE, MINIMISE, randcalc(), and TRUE.

Referenced by ignore_level_of().

 bool randcalc_varies ( random_value v )

Test to see if a random_value actually varies.

References MAXIMISE, MINIMISE, and randcalc().

Referenced by object_flavor_aware().

## Variable Documentation

 bool Rand_quick

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

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

 u32b Rand_value

The state used by the "quick" RNG.

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

 u32b STATE[RAND_DEG]
 u32b state_i

The state used by the "complex" RNG.

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

 u32b z0
 u32b z1
 u32b z2