Project

hazard

0.0
No commit activity in last 3 years
No release in over 3 years
A very simple dice library for ruby
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

 Project Readme

Hazard

Gem Version Build Status Code Climate Test Coverage

Hazard is a very simple dice library for ruby that allows you to :

  • Roll dice and get the sum
  • Roll dice and work with the detail
  • Random pick elements from weighted lists
  1. Installation
  2. Basic Usage
    1. Roll a simple die
    2. Roll multiple dice
  3. Advanced Usage
    1. Roll dice and get the details
    2. Roll dice from string input
    3. Some real cases
  4. Weighted Tables
    1. If you have the weights
    2. If you don't have the weights (or are too lazy to get them)
    3. Saving and loading

Installation

Add this line to your application's Gemfile:

gem 'hazard', '>= 1.3.1'

And then execute:

$ bundle

Or install it yourself as:

$ gem install hazard

If needed :

$ require 'hazard'  

Basic Usage

Roll a simple die

>> Hazard.d<n>        # where n is an number
=> Roll a n-sided die

Examples :

>> Hazard.d6
=> 2

>> Hazard.d8
=> 4
 
>> Hazard.d42
=> 38

Roll multiple dice

>> Hazard.r<m>d<n>    # where m and n are numbers
=> Roll m n-sided dice and return the sum

# You can also use
>> Hazard.m<m>d<n>    # where m and n are numbers       
>> Hazard.d<m>d<n>    # where m and n are numbers

Examples :

>> Hazard.r2d6
=> 4
 
>> Hazard.r4d8
=> 12
 
>> Hazard.r48d42
=> 356

>> Hazard.m2d6
=> 6    
 
>> Hazard.d2d6
=> 8      

Lucky

Some times, you just need to test an unlikely case. Lucky roll a die and return true if you rolled the highest value.

Examples :

>> Hazard.lucky?( 6 )
=> true
# Means that you rolled 6
 
>> Hazard.lucky?( 6 )
=> false
# Means that you rolled something else than 6

Advanced Usage

Roll dice and get the details

>> Hazard.s<m>d<n>    # where m and n are numbers
=> Roll m n-sided dice and return a RolledDice object

Examples :

>> Hazard.s2d6.rolls
=> [1, 6]     
      
>> Hazard.s2d6.result
=> 3

# Caution, each time you call Hazard it will reroll the dice
# If you want to work on result and rolls, save them in a variable    
>> roll = Hazard.s2d6

>> roll.rolls
=> [1, 6]

>> roll.result
=> 7

# Under the hood
>> Hazard.s2d6
=> #<RolledDice:0x007f62e55a0010 @rolls=[1, 6], @result=7>

Roll dice from string input

>> Hazard.from_string( 's<m>d<n>' )    # where m and n are numbers
=> Roll m n-sided dice and return a RolledDice object

Examples :

>> Hazard.from_string( 'r2d6' )
=> 3     

Some real cases

Assuming you are playing DD Next

# You may want to roll 2 d20 dice with advantage (take the greatest)
# This will rolls 2 d20, get the rolls and get the best of them
>> Hazard.s2d20.rolls.max 
=> 19

# Obviously a disadvantage is
>> Hazard.s2d20.rolls.min
=> 13

# Maybe you want to roll with an advantage and make the check (because you are as lazy as me)
>> Hazard.s2d20.rolls.max > 12
=> true or false

# Should you have the Elemental Adept feat, which mean that you treat all 1 as 2
# If you cast a fireball, this will do the trick : 
>> Hazard.s8d6.rolls.map{ |d| d == 1 ? 2 : d }.reduce(:+)
=> 24   

Weighted Tables

Weighted tables are object that allow to get weighted random.

If you have the weights

>> wt = WeightedTable.from_weighted_table( [ <weight1>, <object1> ], [ <weight2>, <object2> ], ... ]
# Create a weighted table storing objects according to theire weights

>> wt.sample
# Return weighted random object

Examples :

>> wt = WeightedTable.from_weighted_table( [ 2, :foo ], [ 1, :bar ] ]
>> wt.sample
# This ensure that you will get 66% foo and 33% bar

If you don't have the weights (or are too lazy to get them)

>> wt = WeightedTable.from_flat_table( <object1>, <object1>, <object2>, ... ]
# Create a weighted table storing objects computing the weight of the objects according to theire occurences

>> wt.sample
# Return weighted random object

Examples :

>> wt = WeightedTable.from_flat_table( :foo, :foo, :bar ]
>> wt.sample
# This ensure that you will get 66% foo and 33% bar

Weighted tables can also be used with floating points numbers

>> wt = WeightedTable.new( floating_points: true )
>> wt.from_weighted_table( [ <weight1>, <object1> ], [ <weight2>, <object2> ], ... ] )
# Create a weighted table storing objects according to theire weights

>> wt.sample
# Return weighted random object

Examples :

>> wt = WeightedTable.new( floating_points: true )
>> wt.from_weighted_table( [ 2.6, :foo ], [ 1.5, :bar ] ] )
>> wt.sample

Saving and loading

# You can save your builded table for future usage
>> wt.to_file( filename )

# And load it
>> wt = WeightedTable.from_file( filename )  

# Note : backup format is YAML

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/czuger/hazard. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.