Hazard
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
- Installation
- Basic Usage
- Roll a simple die
- Roll multiple dice
- Advanced Usage
- Roll dice and get the details
- Roll dice from string input
- Some real cases
- Weighted Tables
- If you have the weights
- If you don't have the weights (or are too lazy to get them)
- 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.