Go package for dice
The package lpdice provides a simple interface for rolling symmetrical dice with 4, 6, 8, 10, 12, 20 sides. A die is retrieved by
an instance of struct type Die. The standard Die has six sides. A new die with 4, 6, 8, 10, 12 or 20 sides can also be retrieved with
NewD{4, 6, 8, 10, 12, 20}. The underlying random number generator is a
cryptographically secure random number generator based on crypto/rand. If the cryptographically secure random
number generator source is not available on the system,
a pseudo-random number generator based on math/rand is used. A die can be seeded to generate deterministic random
numbers based on a seed.
- Simple: Without configuration, just function calls
- Easy to use: Retrieve a die by struct type Die with a simple interface
- Tested: Unit tests with high code coverage
- Dependencies: Only depends on the Go standard library, lpstats, tserr and tsrand
The package is installed with
go get github.com/thorstenrie/lpdice
In the Go app, the package is imported with
import "github.com/thorstenrie/lpdice
An instance of struct type Die has a fixed number of sides. The directly instantiated standard Die has six sides.
A 4, 6, 8, 10, 12, 20 sided die can be retrieved using one of the NewD{4, 6, 8, 10, 12, 20} functions. A die can be rolled by calling
Roll. The result will be randomly generated. To retrieve a random but deterministic series of results, a Die can be seeded with Seed.
With NoSeed the Die behavior can be changed back to the non-seeded random number generation.
A Die holds random number generators to generate results from rolling the die. It contains a pointer to a cryptographically secure random number generator
for non-seeded results and a pointer to a deterministic pseudo-random number generator for seeded results. If the cryptographically secure random number generator
is not available on the platform, a pseudo-random number generator will be used. The deterministic pseudo-random number generator will be used, if the Die is seeded
by calling Seed.
The quality of random results from rolling the die depends on the random number generator source. The unit tests cover a basic evaluation of the results. Therefore, the test functions generate random results from rolling all available dice. The test functions compare for each die the aritmetic mean and variance of the retrieved random numbers with the expected values for mean and variance. If the arithmetic mean and variance of the retrieved random numbers are not near equal to expected values, the test fails. Hence, the unit tests provide an indication if the random number generator sources are providing random values in expected boundaries. However, the unit tests do not evaluate the quality of retrieved random numbers in different dimensions or the implementation of the random number generator source. The output of the random number generator sources might be easily predictable.
package main
import (
"fmt"
"github.com/thorstenrie/lpdice"
)
func main() {
fmt.Println("For each turn, Player 1 and Player 2 will roll a die and compare the results. The higher result wins and the player gains a point. After three turns, the player with the higher number of points wins the game.")
var p1, p2 int // Points
d1, _ := lpdice.NewD6() // Die of Player 1
d2, _ := lpdice.NewD6() // Die of Player 2
for i := 0; i < 3; i++ {
r1, _ := d1.Roll()
r2, _ := d2.Roll()
if r1 > r2 {
p1++
} else if r2 > r1 {
p2++
}
fmt.Printf("ROUND%d\nPlayer 1 rolls a %d\nPlayer 2 rolls a %d\nPlayer 1 %d points\nPlayer 2 %d points\n", i+1, r1, r2, p1, p2)
}
fmt.Printf("RESULT: ")
if p1 > p2 {
fmt.Println("Player 1 wins.")
} else if p2 > p1 {
fmt.Println("Player 2 wins.")
} else {
fmt.Println("Draw.")
}
}