`(sigil random)`

(sigil random) - Random Number Generation

Provides seedable pseudo-random number generation for games, simulations, and general applications. Uses xorshift128 algorithm for fast, high-quality random numbers with full reproducibility when seeded.

Basic Usage

(import (sigil random))

(random)              ; => random float in [0, 1)
(random-integer 6)    ; => random integer in [0, 6), like a die roll
(random-range 10 20)  ; => random integer in [10, 20)

Reproducible Sequences

(random-seed! 12345)
(random)              ; => always the same value for this seed

Game Utilities

(random-choice '(rock paper scissors))  ; => random element
(shuffle '(1 2 3 4 5))                  ; => shuffled list
(dice 2 6)                              ; => roll 2d6 (sum of two d6)

Exports

randomprocedure

Generate a random floating-point number in [0, 1).

Returns a uniformly distributed double-precision float.

(random)  ; => 0.7234...
(random)  ; => 0.1456...

random-integerprocedure

Generate a random integer in [0, n).

Returns a uniformly distributed integer from 0 to n-1 inclusive.

(random-integer 6)   ; => 0, 1, 2, 3, 4, or 5
(random-integer 100) ; => 0 to 99

random-rangeprocedure

Generate a random integer in [lo, hi).

Returns a uniformly distributed integer from lo to hi-1 inclusive.

(random-range 1 7)   ; => 1, 2, 3, 4, 5, or 6 (like a die)
(random-range 10 20) ; => 10 to 19

random-realprocedure

Generate a random floating-point number in [lo, hi).

Returns a uniformly distributed double-precision float in the range.

(random-real 0.0 1.0)   ; => same as (random)
(random-real -1.0 1.0)  ; => -1.0 to just under 1.0

random-seed!procedure

Seed the global random number generator.

Use this to get reproducible random sequences. The same seed will always produce the same sequence of random numbers.

(random-seed! 12345)
(random)  ; => always the same value for this seed

random-stateprocedure

Get a copy of the current random state.

The returned state can be saved and restored later to replay a random sequence.

(define saved (random-state))
(random)  ; => 0.123...
(random)  ; => 0.456...
(with-random-state saved
  (random))  ; => 0.123... again

make-random-stateprocedure

Create a new random state from a seed.

Returns a state object that can be used with with-random-state.

(define my-state (make-random-state 42))
(with-random-state my-state
  (random))  ; => deterministic value

with-random-statesyntax

Execute body with a specific random state, then restore original.

Useful for getting reproducible random sequences within a scope without affecting the global state.

(with-random-state (make-random-state 42)
  (random)   ; => deterministic
  (random))  ; => deterministic
;; Global state unchanged

random-choiceprocedure

Select a random element from a non-empty list.

(random-choice '(a b c d e))       ; => one of a, b, c, d, e
(random-choice '(rock paper scissors))  ; => rock, paper, or scissors

random-sampleprocedure

Select k random elements from a list without replacement.

Returns a list of k distinct elements chosen randomly from lst. If k >= length of lst, returns a shuffled copy of lst.

(random-sample 3 '(a b c d e))  ; => e.g., (c a e)
(random-sample 2 '(1 2 3 4 5))  ; => e.g., (4 1)

shuffleprocedure

Randomly shuffle a list using Fisher-Yates algorithm.

Returns a new list with elements in random order. The original list is not modified.

(shuffle '(1 2 3 4 5))  ; => e.g., (3 1 5 2 4)

diceprocedure

Roll dice and return the sum.

Simulates rolling count dice with sides faces each. Returns the sum of all dice.

(dice 1 6)   ; => 1-6 (one d6)
(dice 2 6)   ; => 2-12 (two d6, like craps)
(dice 3 8)   ; => 3-24 (three d8)

weighted-choiceprocedure

Select a random element based on weights.

Takes a list of (weight . value) pairs and returns a value with probability proportional to its weight.

(weighted-choice '((70 . common) (25 . uncommon) (5 . rare)))
;; => common 70% of the time, uncommon 25%, rare 5%

(weighted-choice '((1 . heads) (1 . tails)))
;; => fair coin flip

chance?procedure

Return #t with the given probability (0.0 to 1.0).

Useful for random chance checks in games.

(chance? 0.5)   ; => #t or #f with 50% probability each
(chance? 0.1)   ; => #t 10% of the time
(chance? 1.0)   ; => always #t
(chance? 0.0)   ; => always #f