Angband
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
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 andstand_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:

a) the GNU General Public License as published by the Free Software Foundation, version 2, or

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

#define one_in_ (   x)    (!randint0(x))
#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,
 
)    ((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 build_streamer(), drop_find_grid(), effect_handler_TELEPORT_TO(), make_gold(), scatter(), spread_monsters(), and town_gen_layout().

#define randint0 (   M)    ((s32b) Rand_div(M))

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

The integer X falls along a uniform distribution.

Referenced by _find_in_range(), add_activation(), add_brand(), add_immunity(), add_low_resist(), add_mod(), add_slay(), add_stat(), add_sustain(), add_to_AC(), add_to_dam(), add_to_hit(), apply_magic(), artifact_prep(), blow_side_effects(), brand_object(), build_circular(), build_crossed(), build_greater_vault(), build_huge(), build_large(), build_moria(), build_nest(), build_pit(), build_room_of_chambers(), build_room_template(), build_store(), build_streamer(), build_tunnel(), build_vault(), call_monster(), cave_light(), cavern_gen(), choose_attack_spell(), choose_profile(), classic_gen(), compact_monsters(), correct_dir(), do_cmd_accept_character(), do_cmd_disarm_aux(), do_cmd_disarm_chest(), do_cmd_lock_door(), do_cmd_open_aux(), do_cmd_open_chest(), do_cmd_study_book(), do_cmd_tunnel_aux(), do_mon_spell(), drop_find_grid(), drop_near(), effect_do(), effect_handler_BOLT_OR_BEAM(), effect_handler_CURSE_ARMOR(), effect_handler_CURSE_WEAPON(), effect_handler_DISENCHANT(), effect_handler_EARTHQUAKE(), effect_handler_RECALL(), effect_handler_TELEPORT(), effect_handler_TELEPORT_LEVEL(), effect_handler_THRUST_AWAY(), ego_find_random(), enchant(), enchant_score(), find_space(), flavor_assign_random(), generate_hole(), generate_starburst_room(), get_chamber_monsters(), get_mon_num(), get_mon_race_aux(), get_move(), get_obj_num(), get_obj_num_by_kind(), hallucinatory_monster(), hallucinatory_object(), hard_centre_gen(), hit_trap(), inven_damage(), labyrinth_check(), labyrinth_gen(), lair_gen(), make_artifact(), make_artifact_special(), make_attack_normal(), make_attack_spell(), make_chamber(), make_gold(), mass_roll(), melee_effect_experience(), melee_effect_handler_DRAIN_CHARGES(), melee_effect_handler_EAT_FOOD(), melee_effect_handler_EAT_GOLD(), melee_effect_handler_EAT_ITEM(), melee_effect_timed(), menu_question(), modified_chunk(), modified_gen(), mon_create_drop(), mon_create_drop_count(), mon_select(), mon_take_hit(), monster_blow_random_insult(), monster_blow_random_moan(), monster_critical(), monster_near_permwall(), monster_reduce_sleep(), monster_turn(), monster_turn_can_move(), monster_turn_should_stagger(), moria_chunk(), moria_gen(), object_find_unknown_rune(), pick_and_place_distant_monster(), pick_trap(), place_feeling(), place_friends(), place_new_monster(), place_random_door(), place_random_stairs(), play_sound(), player_confuse_dir(), process_monster_timed(), process_world(), project_feature_handler_KILL_WALL(), project_player_handler_CHAOS(), project_player_handler_GRAVITY(), project_player_handler_INERTIA(), project_player_handler_NEXUS(), project_player_swap_stats(), prt_welcome(), rand_dir(), Rand_normal(), randname_make(), random_base_resist(), random_high_resist(), sanitize_player_loc(), saving_throw(), set_choose(), shuffle(), simulate_division(), spell_cast(), square_add_stairs(), square_destroy(), square_earthquake(), store_choose_owner(), store_delete_random(), store_get_choice(), store_update(), test_hit(), town_gen_layout(), try_door(), try_supercharge(), unset_spells(), and vault_objects().

#define randint1 (   M)    ((s32b) Rand_div(M) + 1)

Generates a random signed long integer X where "1 <= X <= M" holds.

The integer X falls along a uniform distribution.

Referenced by add_curse(), add_damage_dice(), add_high_resist(), add_mod(), append_random_brand(), append_random_slay(), apply_curse(), apply_magic(), apply_magic_armour(), apply_magic_weapon(), build_circular(), build_crossed(), build_huge(), build_large(), build_moria(), build_overlap(), build_room_of_chambers(), build_room_template(), build_simple(), build_vault(), cavern_gen(), check_devices(), chest_death(), choose_ability(), classic_gen(), critical_norm(), critical_shot(), damroll(), design_artifact(), do_animation(), do_cmd_lock_door(), do_cmd_rerate(), do_curse_effect(), effect_handler_BALL(), effect_handler_BANISH(), effect_handler_BIZARRE(), effect_handler_CURSE_ARMOR(), effect_handler_CURSE_WEAPON(), effect_handler_DARKEN_AREA(), effect_handler_DEEP_DESCENT(), effect_handler_DESTRUCTION(), effect_handler_EARTHQUAKE(), effect_handler_LOSE_RANDOM_STAT(), effect_handler_MASS_BANISH(), effect_handler_RECHARGE(), effect_handler_RUBBLE(), effect_handler_THRUST_AWAY(), ego_apply_magic(), enchant_score(), gauntlet_gen(), generate_starburst_room(), get_ahw(), get_base_item(), get_base_item_tval(), get_history(), get_obj_num(), get_stats(), get_target(), hard_centre_gen(), init_cavern(), labyrinth_gen(), lair_gen(), make_artifact(), make_artifact_special(), make_attack_normal(), make_bad(), make_ego_item(), make_object(), mass_produce(), melee_effect_handler_BLIND(), melee_effect_handler_CONFUSE(), melee_effect_handler_EAT_GOLD(), melee_effect_handler_HALLU(), melee_effect_handler_PARALYZE(), melee_effect_handler_POISON(), melee_effect_handler_TERRIFY(), modified_gen(), mon_restrict(), mon_take_hit(), monster_take_terrain_damage(), monster_turn_glyph(), moria_gen(), place_closed_door(), place_new_monster_one(), player_check_terrain_damage(), player_stat_inc(), process_monster_timed(), project_feature_handler_COLD(), project_feature_handler_FIRE(), project_feature_handler_ICE(), project_feature_handler_PLASMA(), project_m_apply_side_effects(), project_monster_breath(), project_monster_handler_CHAOS(), project_monster_handler_FORCE(), project_monster_handler_GRAVITY(), project_monster_handler_ICE(), project_monster_handler_LIGHT(), project_monster_handler_NETHER(), project_monster_handler_SOUND(), project_monster_resist_other(), project_player_drain_stats(), project_player_handler_CHAOS(), project_player_handler_DARK(), project_player_handler_DARK_WEAK(), project_player_handler_FORCE(), project_player_handler_GRAVITY(), project_player_handler_ICE(), project_player_handler_LIGHT(), project_player_handler_PLASMA(), project_player_handler_POIS(), project_player_handler_SHARD(), project_player_handler_SOUND(), project_player_handler_WATER(), roll_hp(), spell_cast(), store_delete_random(), store_maint(), and try_supercharge().

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

Referenced by add_curse(), apply_curse(), apply_magic_armour(), apply_magic_weapon(), build_room_of_chambers(), do_cmd_lock_door(), effect_handler_CURSE_ARMOR(), effect_handler_CURSE_WEAPON(), and 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().

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, and rand_fixval.

Referenced by setup_tests().

void Rand_init ( void  )

Initialise the RNG.

References getpid(), NULL, 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.

Referenced by cavern_gen(), classic_gen(), gauntlet_gen(), get_ahw(), hard_centre_gen(), labyrinth_chunk(), labyrinth_gen(), lair_gen(), m_bonus(), modified_gen(), mon_hp(), moria_gen(), Rand_sample(), and set_pit_type().

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

Referenced by build_crossed(), build_store(), cavern_chunk(), cavern_gen(), classic_gen(), gauntlet_gen(), hard_centre_gen(), lair_gen(), modified_gen(), mon_create_drop_count(), moria_gen(), player_outfit(), and store_create_random().

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

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(), LCRNG, and NULL.

Referenced by savefile_save().

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

int randcalc ( random_value  v,
int  level,
aspect  rand_aspect 
)
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().

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

Variable Documentation

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

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