games_dice 0.0.3 → 0.0.5

data/lib/games_dice/constants.rb

@@ -0,0 +1,16 @@
+module GamesDice
+
+  # reasons for making a reroll, and text explanation symbols for them
+  REROLL_TYPES = {
+    :basic => ',',
+    :reroll_add => '+',
+    :reroll_subtract => '-',
+    :reroll_replace => '|',
+    :reroll_use_best => '/',
+    :reroll_use_worst => '\\',
+    # These are not yet implemented:
+    # :reroll_new_die => '*',
+    # :reroll_new_keeper => '*',
+  }
+
+end

data/lib/games_dice/dice.rb

@@ -0,0 +1,43 @@
+# models any combination of zero or more Bunches, plus a constant offset, summing them
+# to create a total result when rolled
+class GamesDice::Dice
+  # bunches is an Array of Hashes, each of which describes either a GamesDice::Bunch
+  # a Hash in the Array that describes a Bunch may contain any of the keys that can be used to initialize
+  # the Bunch, plus the following optional key:
+  #  :multiplier => any Integer, but typically 1 or -1 to describe whether the Bunch total is to be added or subtracted
+  # offset is an Integer which will be added to the result when rolling all the bunches
+  # name can be any String, and is used to identify the dice being rolled.
+  def initialize( bunches, offset = 0, name = '' )
+    @name = name
+    @offset = offset
+    @bunches = bunches.map { |b| GamesDice::Bunch.new( b ) }
+    @bunch_multipliers = bunches.map { |b| b[:multiplier] || 1 }
+    @result = nil
+  end
+
+  # the string name as provided to the constructor, it will appear in explain_result
+  attr_reader :name
+
+  # an array of GamesDice::Bunch objects that together describe all the dice and roll-altering
+  # rules that apply to the GamesDice::Dice object
+  attr_reader :bunches
+
+  # an array of Integers, used to multiply result from each bunch when total results are summed
+  attr_reader :bunch_multipliers
+
+  # the integer offset that is added to the total result from all bunches
+  attr_reader :offset
+
+  # after calling #roll, this is set to the total integer value as calculated by simulating all the
+  # defined dice and their rules
+  attr_reader :result
+
+  # simulate dice roll. Returns integer final total, and also stores same value in #result
+  def roll
+    @result = @offset + @bunch_multipliers.zip(@bunches).inject(0) do |total,mb|
+      m,b = mb
+      total += m * b.roll
+    end
+  end
+
+end # class Dice

data/lib/games_dice/die.rb

@@ -1,92 +1,58 @@
-module GamesDice
-  # basic die that rolls 1..N, typically with equal weighting for each value
-  #  d = Die.new(6)
-  #  d.roll # => Integer in range 1..6
-  #  d.result # => same Integer value as returned by d.roll
-  class Die
-    # sides is e.g. 6 for traditional cubic die, or 20 for icosahedron.
-    # It can take non-traditional values, such as 7, but must be at least 1.
-    # prng is an object that has a rand(x) method. If provided, it will be called as
-    # prng.rand(sides), and is expected to return an integer in range 0...sides
-    def initialize( sides, prng=nil )
-      @sides = Integer(sides)
-      raise ArgumentError, "sides value #{sides} is too low, it must be 1 or greater" if @sides < 1
-      raise ArgumentError, "prng does not support the rand() method" if prng && ! prng.respond_to?(:rand)
-      @prng = prng
-      @result = nil
-    end
-
-    # number of sides as set by #new
-    attr_reader :sides
-
-    # integer result of last call to #roll, nil if no call made yet
-    attr_reader :result
-
-    # minimum possible value
-    def min
-      1
-    end
-
-    # maximum possible value
-    def max
-      @sides
-    end
-
-    # returns a hash of value (Integer) => probability (Float) pairs
-    def probabilities
-      return @probabilities if @probabilities
-      density = 1.0/@sides
-      @probabilities = (1..@sides).inject({}) { |h,x| h[x] = density; h }
-    end
-
-    # returns mean expected value as a Float
-    def expected_result
-      0.5 * (1 + @sides)
-    end
-
-    # returns probability than a roll will produce a number greater than target integer
-    def probability_gt target
-      probability_ge( Integer(target) + 1 )
-    end
-
-    # returns probability than a roll will produce a number greater than or equal to target integer
-    def probability_ge target
-      target = Integer(target)
-      return 1.0 if target <= 1
-      return 0.0 if target > @sides
-      return 1.0 * (1.0 + @sides - target )/@sides
-    end
-
-    # returns probability than a roll will produce a number less than or equal to target integer
-    def probability_le target
-      target = Integer(target)
-      return 1.0 if target >= @sides
-      return 0.0 if target < 1
-      return 1.0 * target/@sides
-    end
-
-    # returns probability than a roll will produce a number less than target integer
-    def probability_lt target
-      probability_le( Integer(target) - 1 )
-    end
-
-    # generates Integer between #min and #max, using rand()
-    def roll
-      if @prng
-        @result = @prng.rand(@sides) + 1
-      else
-        @result = rand(@sides) + 1
-      end
-    end
-
-    # always nil, available for compatibility with ComplexDie
-    def rerolls
-      nil
-    end
-
-    # always nil, available for compatibility with ComplexDie
-    def maps
-      nil
-    end
-  end # class Die
-end # module GamesDice
+# basic die that rolls 1..N, typically with equal weighting for each value
+#  d = Die.new(6)
+#  d.roll # => Integer in range 1..6
+#  d.result # => same Integer value as returned by d.roll
+class GamesDice::Die
+  # sides is e.g. 6 for traditional cubic die, or 20 for icosahedron.
+  # It can take non-traditional values, such as 7, but must be at least 1.
+  # prng is an object that has a rand(x) method. If provided, it will be called as
+  # prng.rand(sides), and is expected to return an integer in range 0...sides
+  def initialize( sides, prng=nil )
+    @sides = Integer(sides)
+    raise ArgumentError, "sides value #{sides} is too low, it must be 1 or greater" if @sides < 1
+    raise ArgumentError, "prng does not support the rand() method" if prng && ! prng.respond_to?(:rand)
+    @prng = prng
+    @result = nil
+  end
+
+  # number of sides as set by #new
+  attr_reader :sides
+
+  # integer result of last call to #roll, nil if no call made yet
+  attr_reader :result
+
+  # minimum possible value
+  def min
+    1
+  end
+
+  # maximum possible value
+  def max
+    @sides
+  end
+
+  # returns a GamesDice::Probabilities object that models distribution of the die
+  def probabilities
+    return @probabilities if @probabilities
+    @probabilities = GamesDice::Probabilities.for_fair_die( @sides )
+  end
+
+  # generates Integer between #min and #max, using rand()
+  def roll
+    if @prng
+      @result = @prng.rand(@sides) + 1
+    else
+      @result = rand(@sides) + 1
+    end
+  end
+
+  # always nil, available for compatibility with ComplexDie
+  def rerolls
+    nil
+  end
+
+  # always nil, available for compatibility with ComplexDie
+  def maps
+    nil
+  end
+end # class Die

data/lib/games_dice/die_result.rb

@@ -10,21 +10,9 @@
 class GamesDice::DieResult
   include Comparable
 
-  # allowed reasons for making a roll, and symbol to use before number in #explain
-  REASONS = {
-    :basic => ',',
-    :reroll_add => '+',
-    :reroll_new_die => '*', # TODO: This needs to be flagged *before* value, and maybe linked to cause
-    :reroll_new_keeper => '*',
-    :reroll_subtract => '-',
-    :reroll_replace => '|',
-    :reroll_use_best => '/',
-    :reroll_use_worst => '\\',
-  }
-
   # first_roll_result is optional value of first roll of the die
   def initialize( first_roll_result=nil, first_roll_reason=:basic )
-    unless REASONS.has_key?(first_roll_reason)
+    unless GamesDice::REROLL_TYPES.has_key?(first_roll_reason)
       raise ArgumentError, "Unrecognised reason for roll #{first_roll_reason}"
     end
 
@@ -63,7 +51,7 @@ class GamesDice::DieResult
   # roll_reason is an optional symbol description of why the roll was made
   # #total and #value are calculated based on roll_reason
   def add_roll( roll_result, roll_reason=:basic )
-    unless REASONS.has_key?(roll_reason)
+    unless GamesDice::REROLL_TYPES.has_key?(roll_reason)
       raise ArgumentError, "Unrecognised reason for roll #{roll_reason}"
     end
     @rolls << Integer(roll_result)
@@ -109,7 +97,7 @@ class GamesDice::DieResult
       text = @total.to_s
     else
       text = '[' + @rolls[0].to_s
-      text = (1..@rolls.length-1).inject( text ) { |so_far,i| so_far + REASONS[@roll_reasons[i]] + @rolls[i].to_s }
+      text = (1..@rolls.length-1).inject( text ) { |so_far,i| so_far + GamesDice::REROLL_TYPES[@roll_reasons[i]] + @rolls[i].to_s }
       text += '] ' + @total.to_s
     end
     text += ' ' + @map_description if @mapped && @map_description && @map_description.length > 0

data/lib/games_dice/map_rule.rb

@@ -1,46 +1,44 @@
-module GamesDice
-  # convert integer die result into value used in a game (e.g. 1 for a 'success')
-  class MapRule
-
-    # trigger_op, trigger_value, mapped_value and mapped_name set the attributes of the same name
-    #  rule = RPGMapRule.new( 6, :<=, 1, 'Success' ) # score 1 for a result of 6 or more
-    def initialize trigger_value, trigger_op, mapped_value=0, mapped_name=''
-
-      if ! trigger_value.respond_to?( trigger_op )
-        raise ArgumentError, "trigger_value #{trigger_value.inspect} cannot respond to trigger_op #{trigger_value.inspect}"
-      end
-
-      @trigger_value = trigger_value
-      @trigger_op = trigger_op
-      raise TypeError if ! mapped_value.is_a? Numeric
-      @mapped_value = Integer(mapped_value)
-      @mapped_name = mapped_name.to_s
+# helps model complex dice systems such as "count number of dice showing X or more"
+class GamesDice::MapRule
+
+  # trigger_op, trigger_value, mapped_value and mapped_name set the attributes of the same name
+  #  rule = RPGMapRule.new( 6, :<=, 1, 'Success' ) # score 1 for a result of 6 or more
+  def initialize trigger_value, trigger_op, mapped_value=0, mapped_name=''
+
+    if ! trigger_value.respond_to?( trigger_op )
+      raise ArgumentError, "trigger_value #{trigger_value.inspect} cannot respond to trigger_op #{trigger_value.inspect}"
     end
 
-    # an Integer value or Range that will be mapped to a single value. #trigger_op is called against it
-    attr_reader :trigger_value
-
-    # a valid symbol for a method, which will be called against #trigger_value with the current
-    # die result as a param. If the operator returns true for a specific die result, then the
-    # mapped_value will be used in its stead. If the operator returns nil or false, the map is not
-    # triggered. All other values will be returned as the result of the map (allowing you to
-    # specify any method that takes an integer as input and returns something else as the end result)
-    attr_reader :trigger_op
-
-    # an integer value
-    attr_reader :mapped_value
-
-    # a string description of the mapping, e.g. 'S' for a success
-    attr_reader :mapped_name
-
-    # runs the rule against test_value, returning either a new value, or nil if the rule does not apply
-    def map_from test_value
-      op_result = @trigger_value.send( @trigger_op, test_value )
-      return nil unless op_result
-      if op_result == true
-        return @mapped_value
-      end
-      return op_result
+    @trigger_value = trigger_value
+    @trigger_op = trigger_op
+    raise TypeError if ! mapped_value.is_a? Numeric
+    @mapped_value = Integer(mapped_value)
+    @mapped_name = mapped_name.to_s
+  end
+
+  # an Integer value or Range that will be mapped to a single value. #trigger_op is called against it
+  attr_reader :trigger_value
+
+  # a valid symbol for a method, which will be called against #trigger_value with the current
+  # die result as a param. If the operator returns true for a specific die result, then the
+  # mapped_value will be used in its stead. If the operator returns nil or false, the map is not
+  # triggered. All other values will be returned as the result of the map (allowing you to
+  # specify any method that takes an integer as input and returns something else as the end result)
+  attr_reader :trigger_op
+
+  # an integer value
+  attr_reader :mapped_value
+
+  # a string description of the mapping, e.g. 'S' for a success
+  attr_reader :mapped_name
+
+  # runs the rule against test_value, returning either a new value, or nil if the rule does not apply
+  def map_from test_value
+    op_result = @trigger_value.send( @trigger_op, test_value )
+    return nil unless op_result
+    if op_result == true
+      return @mapped_value
     end
-  end # class MapRule
-end # module GamesDice
+    return op_result
+  end
+end # class MapRule

data/lib/games_dice/probabilities.rb

@@ -0,0 +1,97 @@
+# utility class for calculating with probabilities for reuslts from GamesDice objects
+class GamesDice::Probabilities
+  # prob_hash is a Hash with each key as an Integer, and the associated value being the probability
+  # of getting that value. It is not validated. Avoid using the default constructor if
+  # one of the factory methods or calculation methods already does what you need.
+  def initialize( prob_hash = { 0 => 1.0 } )
+    # This should *probably* be validated in future
+    @ph = prob_hash
+  end
+
+  # the Hash representation of probabilities. TODO: Hide this from public interface, but make it available
+  # to factory methods
+  attr_reader :ph
+
+  # a clone of probability data (as provided to constructor), safe to pass to methods that modify in place
+  def to_h
+    @ph.clone
+  end
+
+  def min
+    (@minmax ||= @ph.keys.minmax )[0]
+  end
+
+  def max
+    (@minmax ||= @ph.keys.minmax )[1]
+  end
+
+  # returns mean expected value as a Float
+  def expected
+    @expected ||= @ph.inject(0.0) { |accumulate,p| accumulate + p[0] * p[1] }
+  end
+
+  # returns Float probability fram Range (0.0..1.0) that a value chosen from the distribution will
+  # be equal to target integer
+  def p_eql target
+    @ph[ Integer(target) ] || 0.0
+  end
+
+  # returns Float probability fram Range (0.0..1.0) that a value chosen from the distribution will
+  # be a number greater than target integer
+  def p_gt target
+    p_ge( Integer(target) + 1 )
+  end
+
+  # returns Float probability fram Range (0.0..1.0) that a value chosen from the distribution will
+  # be a number greater than or equal to target integer
+  def p_ge target
+    target = Integer(target)
+    return @prob_ge[target] if @prob_ge && @prob_ge[target]
+    @prob_ge = {} unless @prob_ge
+
+    return 1.0 if target <= min
+    return 0.0 if target > max
+    @prob_ge[target] = @ph.select {|k,v| target <= k}.inject(0.0) {|so_far,pv| so_far + pv[1] }
+  end
+
+  # returns probability than a roll will produce a number less than or equal to target integer
+  def p_le target
+    target = Integer(target)
+    return @prob_le[target] if @prob_le && @prob_le[target]
+    @prob_le = {} unless @prob_le
+
+    return 1.0 if target >= max
+    return 0.0 if target < min
+    @prob_le[target] = @ph.select {|k,v| target >= k}.inject(0.0) {|so_far,pv| so_far + pv[1] }
+  end
+
+  # returns probability than a roll will produce a number less than target integer
+  def p_lt target
+    p_le( Integer(target) - 1 )
+  end
+
+  # constructor returns probability distrubution for a simple fair die
+  def self.for_fair_die sides
+    sides = Integer(sides)
+    raise ArgumentError, "sides must be at least 1" unless sides > 0
+    h = {}
+    p = 1.0/sides
+    (1..sides).each { |x| h[x] = p }
+    GamesDice::Probabilities.new( h )
+  end
+
+  # adding two probability distributions calculates a new distribution, representing what would
+  # happen if you created a random number using the sum of numbers from both distributions
+  def self.add_distributions pd_a, pd_b
+    h = {}
+    pd_a.ph.each do |ka,pa|
+      pd_b.ph.each do |kb,pb|
+        kc = ka + kb
+        pc = pa * pb
+        h[kc] = h[kc] ? h[kc] + pc : pc
+      end
+    end
+    GamesDice::Probabilities.new( h )
+  end
+
+end # class Dice

data/lib/games_dice/reroll_rule.rb

@@ -1,64 +1,47 @@
-module GamesDice
+# specifies when and how a ComplexDie should be re-rolled
+class GamesDice::RerollRule
 
-  # specifies when and how a ComplexDie should be re-rolled
-  class RerollRule
+  # trigger_op, trigger_value, type and limit set the attributes of the same name
+  #  rule = GamesDice::RerollRule.new( 10, :<=, :reroll_add ) # an 'exploding' die
+  def initialize trigger_value, trigger_op, type, limit=nil
 
-    # allowed reasons for making a reroll
-    TYPES = {
-      :reroll_add => '+',
-      :reroll_new_die => '*',
-      :reroll_new_keeper => '*',
-      :reroll_subtract => '-',
-      :reroll_replace => '|',
-      :reroll_use_best => '/',
-      :reroll_use_worst => '\\',
-    }
-
-    # trigger_op, trigger_value, type and limit set the attributes of the same name
-    #  rule = GamesDice::RerollRule.new( 10, :<=, :reroll_add ) # an 'exploding' die
-    def initialize trigger_value, trigger_op, type, limit=nil
-
-      if ! trigger_value.respond_to?( trigger_op )
-        raise ArgumentError, "trigger_value #{trigger_value.inspect} cannot respond to trigger_op #{trigger_value.inspect}"
-      end
-
-      unless TYPES.has_key?(type)
-        raise ArgumentError, "Unrecognised reason for a re-roll #{type}"
-      end
-
-      @trigger_value = trigger_value
-      @trigger_op = trigger_op
-      @type = type
-      @limit = limit ? Integer(limit) : 1000
-      @limit = 1 if @type == :reroll_subtract
+    if ! trigger_value.respond_to?( trigger_op )
+      raise ArgumentError, "trigger_value #{trigger_value.inspect} cannot respond to trigger_op #{trigger_value.inspect}"
     end
 
-    # a valid symbol for a method, which will be called against #trigger_value with the current
-    # die result as a param. It should return true or false
-    attr_reader :trigger_op
-
-    # an Integer value or Range that will cause the reroll to occur. #trigger_op is called against it
-    attr_reader :trigger_value
-
-    # a symbol, should be one of the following:
-    #   :reroll_add - add result of reroll to running total, and ignore :reroll_subtract for this die
-    #   :reroll_new_die - roll a new die of the same type
-    #   :reroll_new_keeper - roll a new die of the same type, and keep the result
-    #   :reroll_subtract - subtract result of reroll from running total, and reverse sense of any further :reroll_add results
-    #   :reroll_replace - use the new value in place of existing value for the die
-    #   :reroll_use_best - use the new value if it is higher than the erxisting value
-    #   :reroll_use_worst - use the new value if it is higher than the existing value
-    attr_reader :type
-
-    # maximum number of times this rule should be applied to a single die. If type is:reroll_subtract,
-    # this value is always 1. A default value of 100 is used if not set in the constructor
-    attr_reader :limit
-
-    # runs the rule against a test value, returning truth value from calling the trigger_op method
-    def applies? test_value
-      @trigger_value.send( @trigger_op, test_value ) ? true : false
+    unless GamesDice::REROLL_TYPES.has_key?(type)
+      raise ArgumentError, "Unrecognised reason for a re-roll #{type}"
     end
 
-  end # class RerollRule
-
-end # module GamesDice
+    @trigger_value = trigger_value
+    @trigger_op = trigger_op
+    @type = type
+    @limit = limit ? Integer(limit) : 1000
+    @limit = 1 if @type == :reroll_subtract
+  end
+
+  # a valid symbol for a method, which will be called against #trigger_value with the current
+  # die result as a param. It should return true or false
+  attr_reader :trigger_op
+
+  # an Integer value or Range that will cause the reroll to occur. #trigger_op is called against it
+  attr_reader :trigger_value
+
+  # a symbol, should be one of the following:
+  #   :reroll_add - add result of reroll to running total, and ignore :reroll_subtract for this die
+  #   :reroll_subtract - subtract result of reroll from running total, and reverse sense of any further :reroll_add results
+  #   :reroll_replace - use the new value in place of existing value for the die
+  #   :reroll_use_best - use the new value if it is higher than the erxisting value
+  #   :reroll_use_worst - use the new value if it is higher than the existing value
+  attr_reader :type
+
+  # maximum number of times this rule should be applied to a single die. If type is:reroll_subtract,
+  # this value is always 1. A default value of 100 is used if not set in the constructor
+  attr_reader :limit
+
+  # runs the rule against a test value, returning truth value from calling the trigger_op method
+  def applies? test_value
+    @trigger_value.send( @trigger_op, test_value ) ? true : false
+  end
+
+end # class RerollRule