games_dice 0.3.12 → 0.4.2

data/lib/games_dice/complex_die_helpers.rb

@@ -1,60 +1,260 @@
-# @!visibility private
-module GamesDice::ComplexDieHelpers
-
-  private
-
-  def recursive_probabilities probabilities={},prior_probability=1.0,depth=0,prior_result=nil,rerolls_left=nil,roll_reason=:basic,subtracting=false
-    each_probability = prior_probability / @basic_die.sides
-    depth += 1
-    if depth >= 20 || each_probability < 1.0e-16
-      @probabilities_complete = false
-      stop_recursing = true
-    end
-
-    @basic_die.each_value do |v|
-      recurse_probs_for_value( v, roll_reason, probabilities, each_probability, depth, prior_result, rerolls_left, subtracting, stop_recursing )
-    end
-    probabilities
-  end
-
-  def recurse_probs_for_value v, roll_reason, probabilities, each_probability, depth, prior_result, rerolls_left, subtracting, stop_recursing
-    # calculate value, recurse if there is a reroll
-    result_so_far, rerolls_remaining = calc_result_so_far(prior_result, rerolls_left, v, roll_reason )
-
-    # Find which rule, if any, is being triggered
-    rule_idx = find_matching_reroll_rule( v, result_so_far.rolls.length, rerolls_remaining )
-
-    if rule_idx && ! stop_recursing
-      recurse_probs_with_rule( probabilities, each_probability, depth, result_so_far, rerolls_remaining, rule_idx, subtracting )
-    else
-      t = result_so_far.total
-      probabilities[ t ] ||= 0.0
-      probabilities[ t ] += each_probability
-    end
-  end
-
-  def recurse_probs_with_rule probabilities, each_probability, depth, result_so_far, rerolls_remaining, rule_idx, subtracting
-    rule = @rerolls[ rule_idx ]
-    rerolls_remaining[ rule_idx ] -= 1
-    is_subtracting = true if subtracting || rule.type == :reroll_subtract
-
-    # Apply the rule (note reversal for additions, after a subtract)
-    if subtracting && rule.type == :reroll_add
-      recursive_probabilities probabilities, each_probability, depth, result_so_far, rerolls_remaining, :reroll_subtract, is_subtracting
-    else
-      recursive_probabilities probabilities, each_probability, depth, result_so_far, rerolls_remaining, rule.type, is_subtracting
-    end
-  end
-
-  def calc_result_so_far prior_result, rerolls_left, v, roll_reason
-    if prior_result
-      result_so_far = prior_result.clone
-      result_so_far.add_roll(v,roll_reason)
-      rerolls_remaining = rerolls_left.clone
-    else
-      result_so_far = GamesDice::DieResult.new(v,roll_reason)
-      rerolls_remaining = @rerolls.map { |rule| rule.limit }
-    end
-    [result_so_far, rerolls_remaining]
-  end
-end
+# frozen_string_literal: true
+
+module GamesDice
+  class ComplexDie
+    # @!visibility private
+    # Private extension methods for GamesDice::ComplexDie probability calculations
+    module ProbabilityHelpers
+      private
+
+      def calculate_probabilities
+        if @rerolls && @maps
+          GamesDice::Probabilities.from_h(prob_hash_with_rerolls_and_maps)
+        elsif @rerolls
+          GamesDice::Probabilities.from_h(recursive_probabilities)
+        elsif @maps
+          GamesDice::Probabilities.from_h(prob_hash_with_just_maps)
+        else
+          @basic_die.probabilities
+        end
+      end
+
+      def prob_hash_with_rerolls_and_maps
+        prob_hash = {}
+        reroll_probs = recursive_probabilities
+        reroll_probs.each do |v, p|
+          add_mapped_to_prob_hash(prob_hash, v, p)
+        end
+        prob_hash
+      end
+
+      def prob_hash_with_just_maps
+        prob_hash = {}
+        @basic_die.probabilities.each do |v, p|
+          add_mapped_to_prob_hash(prob_hash, v, p)
+        end
+        prob_hash
+      end
+
+      def add_mapped_to_prob_hash(prob_hash, orig_val, prob)
+        mapped_val, = calc_maps(orig_val)
+        prob_hash[mapped_val] ||= 0.0
+        prob_hash[mapped_val] += prob
+      end
+
+      RecurseStack = Struct.new(:depth, :roll_reason, :subtracting, :probabilities, :prior_probability, :prior_result,
+                                :rerolls_left) do
+        def initialize
+          self.depth = 0
+          self.roll_reason = :basic
+          self.subtracting = false
+          self.probabilities = {}
+          self.prior_probability = 1.0
+        end
+      end
+      private_constant :RecurseStack
+
+      def recursive_probabilities(stack = RecurseStack.new)
+        stack.prior_probability = stack.prior_probability / @basic_die.sides
+        stack.depth += 1
+
+        @basic_die.each_value do |die_val|
+          recurse_probs_for_value(die_val, stack)
+        end
+        stack.probabilities
+      end
+
+      def recurse_probs_for_value(die_val, stack)
+        result_so_far, rerolls_remaining = calc_result_so_far(die_val, stack)
+        rule_idx = find_matching_reroll_rule(die_val, result_so_far.rolls.length, rerolls_remaining)
+
+        if conintue_recursing?(stack, rule_idx)
+          continue_recursion(stack, result_so_far, rerolls_remaining, rule_idx)
+        else
+          end_recursion_store_probs(stack, result_so_far)
+        end
+      end
+
+      def conintue_recursing?(stack, rule_idx)
+        if stack.depth >= 20 || stack.prior_probability < 1.0e-16
+          @probabilities_complete = false
+          return false
+        end
+
+        !rule_idx.nil?
+      end
+
+      def continue_recursion(stack, result_so_far, rerolls_remaining, rule_idx)
+        rule = @rerolls[rule_idx]
+        rerolls_remaining[rule_idx] -= 1
+        recurse_probs_with_rule(stack, result_so_far, rerolls_remaining, rule)
+      end
+
+      def end_recursion_store_probs(stack, result_so_far)
+        t = result_so_far.total
+        stack.probabilities[t] ||= 0.0
+        stack.probabilities[t] += stack.prior_probability
+      end
+
+      def recurse_probs_with_rule(stack, result_so_far, rerolls_remaining, rule)
+        next_stack = stack.clone
+        next_stack.prior_result = result_so_far
+        next_stack.rerolls_left = rerolls_remaining
+        next_stack.subtracting = true if stack.subtracting || rule.type == :reroll_subtract
+
+        # Apply the rule (note reversal for additions, after a subtract)
+        next_stack.roll_reason = if stack.subtracting && rule.type == :reroll_add
+                                   :reroll_subtract
+                                 else
+                                   rule.type
+                                 end
+
+        recursive_probabilities next_stack
+      end
+
+      def calc_result_so_far(die_val, stack)
+        if stack.prior_result
+          result_so_far = stack.prior_result.clone
+          rerolls_remaining = stack.rerolls_left.clone
+          result_so_far.add_roll(die_val, stack.roll_reason)
+        else
+          rerolls_remaining = @rerolls.map(&:limit)
+          result_so_far = GamesDice::DieResult.new(die_val, stack.roll_reason)
+        end
+        [result_so_far, rerolls_remaining]
+      end
+    end
+
+    # @!visibility private
+    # Private extension methods for GamesDice::ComplexDie simulating rolls
+    module RollHelpers
+      private
+
+      def roll_apply_rerolls
+        return unless @rerolls
+
+        subtracting = false
+        rerolls_remaining = @rerolls.map(&:limit)
+
+        rerolls_loop(subtracting, rerolls_remaining)
+      end
+
+      def rerolls_loop(subtracting, rerolls_remaining)
+        loop do
+          rule_idx = find_matching_reroll_rule(@basic_die.result, @result.rolls.length, rerolls_remaining)
+          break unless rule_idx
+
+          rule = @rerolls[rule_idx]
+          rerolls_remaining[rule_idx] -= 1
+          subtracting = true if rule.type == :reroll_subtract
+          roll_apply_reroll_rule rule, subtracting
+        end
+      end
+
+      def roll_apply_reroll_rule(rule, is_subtracting)
+        # Apply the rule (note reversal for additions, after a subtract)
+        if is_subtracting && rule.type == :reroll_add
+          @result.add_roll(@basic_die.roll, :reroll_subtract)
+        else
+          @result.add_roll(@basic_die.roll, rule.type)
+        end
+      end
+
+      # Find which rule, if any, is being triggered
+      def find_matching_reroll_rule(check_value, num_rolls, rerolls_remaining)
+        @rerolls.zip(rerolls_remaining).find_index do |rule, remaining|
+          next if rule.type == :reroll_subtract && num_rolls > 1
+
+          remaining.positive? && rule.applies?(check_value)
+        end
+      end
+
+      def roll_apply_maps
+        return unless @maps
+
+        m, n = calc_maps(@result.value)
+        @result.apply_map(m, n)
+      end
+
+      def calc_maps(original_value)
+        y = 0
+        n = ''
+        @maps.find do |rule|
+          if (maybe_y = rule.map_from(original_value))
+            y = maybe_y
+            n = rule.mapped_name
+          end
+          maybe_y
+        end
+        [y, n]
+      end
+    end
+
+    # @!visibility private
+    # Private extension methods for GamesDice::ComplexDie calculating min and max (which is surprisingly complex)
+    module MinMaxHelpers
+      private
+
+      def calc_minmax
+        @min_result = probabilities.min
+        @max_result = probabilities.max
+        return if @probabilities_complete
+
+        logical_min, logical_max = logical_minmax
+        @min_result, @max_result = [@min_result, @max_result, logical_min, logical_max].minmax
+      end
+
+      def minmax_mappings(possible_values)
+        possible_values.map do |x|
+          map_val, = calc_maps(x)
+          map_val
+        end.minmax
+      end
+
+      # This isn't 100% accurate, but does cover most "normal" scenarios, and we're only falling back to it when we
+      # have to. The inaccuracy is that min_result..max_result may contain 'holes' which have extreme map values that
+      # cannot actually occur. In practice it is likely a non-issue unless someone went out of their way to invent a
+      # dice schem that broke it.
+      def logical_minmax
+        return @basic_die.minmax unless @rerolls || @maps
+        return minmax_mappings(@basic_die.all_values) unless @rerolls
+
+        min_result, max_result = logical_rerolls_minmax
+        return minmax_mappings(min_result..max_result) if @maps
+
+        [min_result, max_result]
+      end
+
+      def logical_rerolls_minmax
+        min_result = @basic_die.min
+        max_result = @basic_die.max
+        min_subtract = find_minimum_possible_subtract
+        max_add = find_maximum_possible_adds
+        min_result = [min_subtract - max_add, min_subtract - max_result].min if min_subtract
+        [min_result, max_add + max_result]
+      end
+
+      def find_minimum_possible_subtract
+        min_subtract = nil
+        @rerolls.select { |r| r.type == :reroll_subtract }.each do |rule|
+          min_reroll = @basic_die.all_values.select { |v| rule.applies?(v) }.min
+          next unless min_reroll
+
+          min_subtract = [min_reroll, min_subtract].compact.min
+        end
+        min_subtract
+      end
+
+      def find_maximum_possible_adds
+        total_add = 0
+        @rerolls.select { |r| r.type == :reroll_add }.each do |rule|
+          max_reroll = @basic_die.all_values.select { |v| rule.applies?(v) }.max
+          next unless max_reroll
+
+          total_add += max_reroll * rule.limit
+        end
+        total_add
+      end
+    end
+  end
+end

data/lib/games_dice/constants.rb

@@ -1,16 +1,16 @@
-module GamesDice
+# frozen_string_literal: true
 
+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 => '\\',
+    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
+  }.freeze
+end

data/lib/games_dice/dice.rb

@@ -1,143 +1,153 @@
-# This class models a combination of GamesDice::Bunch objects plus a fixed offset.
-#
-# An object of this class is a dice "recipe" that specifies the numbers and types of
-# dice that can be rolled to generate an integer value.
-#
-# @example '3d6+6' hitpoints, whatever that means in the game you are playing
-#  d = GamesDice::Dice.new( [{:ndice => 3, :sides => 6}], 6, 'Hit points' )
-#  d.roll # => 20
-#  d.result # => 20
-#  d.explain_result # => "3d6: 3 + 5 + 6 = 14. 14 + 6 = 20"
-#  d.probabilities.expected # => 16.5
-#
-# @example Roll d20 twice, take best result, and add 5.
-#  d = GamesDice::Dice.new( [{:ndice => 2, :sides => 20 , :keep_mode => :keep_best, :keep_number => 1}], 5 )
-#  d.roll # => 21
-#  d.result # => 21
-#  d.explain_result # => "2d20: 4, 16. Keep: 16. 16 + 5 = 21"
-#
-class GamesDice::Dice
-  # The first parameter is an array of values that are passed to GamesDice::Bunch constructors.
-  # @param [Array<Hash>] bunches Array of options for creating bunches
-  # @param [Integer] offset Total offset
-  # @param [String] name Optional label for the dice
-  # @option bunches [Integer] :ndice Number of dice in the bunch, *mandatory*
-  # @option bunches [Integer] :sides Number of sides on a single die in the bunch, *mandatory*
-  # @option bunches [String] :name Optional name for the bunch
-  # @option bunches [Array<GamesDice::RerollRule,Array>] :rerolls Optional rules that cause the die to roll again
-  # @option bunches [Array<GamesDice::MapRule,Array>] :maps Optional rules to convert a value into a final result for the die
-  # @option bunches [#rand] :prng Optional alternative source of randomness to Ruby's built-in #rand, passed to GamesDice::Die's constructor
-  # @option bunches [Symbol] :keep_mode Optional, either *:keep_best* or *:keep_worst*
-  # @option bunches [Integer] :keep_number Optional number of dice to keep when :keep_mode is not nil
-  # @option bunches [Integer] :multiplier Optional, defaults to 1, and typically 1 or -1 to describe whether the Bunch total is to be added or subtracted
-  # @return [GamesDice::Dice]
-  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
-
-  # Name to help identify dice
-  # @return [String]
-  attr_reader :name
-
-  # Bunches of dice that are components of the object
-  # @return [Array<GamesDice::Bunch>]
-  attr_reader :bunches
-
-  # Multipliers for each bunch of identical dice. Typically 1 or -1 to represent groups of dice that
-  # are either added or subtracted from the total.
-  # @return [Array<Integer>]
-  attr_reader :bunch_multipliers
-
-  # Fixed offset added to sum of all bunches.
-  # @return [Integer]
-  attr_reader :offset
-
-  # Result of most-recent roll, or nil if no roll made yet.
-  # @return [Integer,nil]
-  attr_reader :result
-
-  # Simulates rolling dice
-  # @return [Integer] Sum of all rolled dice
-  def roll
-    @result = @offset + bunches_weighted_sum( :roll )
-  end
-
-  # @!attribute [r] min
-  # Minimum possible result from a call to #roll
-  # @return [Integer]
-  def min
-    @min ||= @offset + bunches_weighted_sum( :min )
-  end
-
-  # @!attribute [r] max
-  # Maximum possible result from a call to #roll
-  # @return [Integer]
-  def max
-    @max ||= @offset + bunches_weighted_sum( :max )
-  end
-
-  # @!attribute [r] minmax
-  # Convenience method, same as [dice.min, dice.max]
-  # @return [Array<Integer>]
-  def minmax
-    [min,max]
-  end
-
-  # Calculates the probability distribution for the dice. When the dice include components with
-  # open-ended re-roll rules, there are some arbitrary limits imposed to prevent large amounts of
-  # recursion.
-  # @return [GamesDice::Probabilities] Probability distribution of dice.
-  def probabilities
-    return @probabilities if @probabilities
-    probs = @bunch_multipliers.zip(@bunches).inject( GamesDice::Probabilities.new( [1.0], @offset ) ) do |probs, mb|
-      m,b = mb
-      GamesDice::Probabilities.add_distributions_mult( 1, probs, m, b.probabilities )
-    end
-  end
-
-  # @!attribute [r] explain_result
-  # @return [String,nil] Explanation of result, or nil if no call to #roll yet.
-  def explain_result
-    return nil unless @result
-    explanations = @bunches.map { |bunch| bunch.label + ": " + bunch.explain_result }
-
-    if explanations.count == 0
-      return @offset.to_s
-    end
-
-    if explanations.count == 1
-      if @offset !=0
-        return explanations[0] + '. ' + array_to_sum( [ @bunches[0].result, @offset ] )
-      else
-        return explanations[0]
-      end
-    end
-
-    bunch_values = @bunch_multipliers.zip(@bunches).map { |m,b| m * b.result }
-    bunch_values << @offset if @offset != 0
-    explanations << array_to_sum( bunch_values )
-    return explanations.join('. ')
-  end
-
-  private
-
-  def array_to_sum array
-    ( numbers_to_strings(array) + [ '=', array.inject(:+) ] ).join(' ')
-  end
-
-  def numbers_to_strings array
-    [ array.first.to_s ] + array.drop(1).map { |n| n < 0 ? '- ' + n.abs.to_s : '+ ' + n.to_s }
-  end
-
-  def bunches_weighted_sum summed_method
-    @bunch_multipliers.zip(@bunches).inject(0) do |total,mb|
-      m,b = mb
-      total += m * b.send( summed_method )
-    end
-  end
-
-end # class Dice
+# frozen_string_literal: true
+
+module GamesDice
+  # This class models a combination of GamesDice::Bunch objects plus a fixed offset.
+  #
+  # An object of this class is a dice "recipe" that specifies the numbers and types of
+  # dice that can be rolled to generate an integer value.
+  #
+  # @example '3d6+6' hitpoints, whatever that means in the game you are playing
+  #  d = GamesDice::Dice.new( [{:ndice => 3, :sides => 6}], 6, 'Hit points' )
+  #  d.roll # => 20
+  #  d.result # => 20
+  #  d.explain_result # => "3d6: 3 + 5 + 6 = 14. 14 + 6 = 20"
+  #  d.probabilities.expected # => 16.5
+  #
+  # @example Roll d20 twice, take best result, and add 5.
+  #  d = GamesDice::Dice.new( [{:ndice => 2, :sides => 20 , :keep_mode => :keep_best, :keep_number => 1}], 5 )
+  #  d.roll # => 21
+  #  d.result # => 21
+  #  d.explain_result # => "2d20: 4, 16. Keep: 16. 16 + 5 = 21"
+  #
+  class Dice
+    # The first parameter is an array of values that are passed to GamesDice::Bunch constructors.
+    # @param [Array<Hash>] bunches Array of options for creating bunches
+    # @param [Integer] offset Total offset
+    # @param [String] name Optional label for the dice
+    # @option bunches [Integer] :ndice Number of dice in the bunch, *mandatory*
+    # @option bunches [Integer] :sides Number of sides on a single die in the bunch, *mandatory*
+    # @option bunches [String] :name Optional name for the bunch
+    # @option bunches [Array<GamesDice::RerollRule,Array>] :rerolls Optional rules that cause the die to roll again
+    # @option bunches [Array<GamesDice::MapRule,Array>] :maps Optional rules to convert a value into a final result
+    #   for the die
+    # @option bunches [#rand] :prng Optional alternative source of randomness to Ruby's built-in #rand, passed to
+    #   GamesDice::Die's constructor
+    # @option bunches [Symbol] :keep_mode Optional, either *:keep_best* or *:keep_worst*
+    # @option bunches [Integer] :keep_number Optional number of dice to keep when :keep_mode is not nil
+    # @option bunches [Integer] :multiplier Optional, defaults to 1, and typically 1 or -1 to describe whether the
+    #   Bunch total is to be added or subtracted
+    # @return [GamesDice::Dice]
+    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
+
+    # Name to help identify dice
+    # @return [String]
+    attr_reader :name
+
+    # Bunches of dice that are components of the object
+    # @return [Array<GamesDice::Bunch>]
+    attr_reader :bunches
+
+    # Multipliers for each bunch of identical dice. Typically 1 or -1 to represent groups of dice that
+    # are either added or subtracted from the total.
+    # @return [Array<Integer>]
+    attr_reader :bunch_multipliers
+
+    # Fixed offset added to sum of all bunches.
+    # @return [Integer]
+    attr_reader :offset
+
+    # Result of most-recent roll, or nil if no roll made yet.
+    # @return [Integer,nil]
+    attr_reader :result
+
+    # Simulates rolling dice
+    # @return [Integer] Sum of all rolled dice
+    def roll
+      @result = @offset + bunches_weighted_sum(:roll)
+    end
+
+    # @!attribute [r] min
+    # Minimum possible result from a call to #roll
+    # @return [Integer]
+    def min
+      @min ||= @offset + bunches_weighted_sum(:min)
+    end
+
+    # @!attribute [r] max
+    # Maximum possible result from a call to #roll
+    # @return [Integer]
+    def max
+      @max ||= @offset + bunches_weighted_sum(:max)
+    end
+
+    # @!attribute [r] minmax
+    # Convenience method, same as [dice.min, dice.max]
+    # @return [Array<Integer>]
+    def minmax
+      [min, max]
+    end
+
+    # Calculates the probability distribution for the dice. When the dice include components with
+    # open-ended re-roll rules, there are some arbitrary limits imposed to prevent large amounts of
+    # recursion.
+    # @return [GamesDice::Probabilities] Probability distribution of dice.
+    def probabilities
+      return @probabilities if @probabilities
+
+      @bunch_multipliers.zip(@bunches).inject(GamesDice::Probabilities.new([1.0], @offset)) do |probs, mb|
+        m, b = mb
+        GamesDice::Probabilities.add_distributions_mult(1, probs, m, b.probabilities)
+      end
+    end
+
+    # @!attribute [r] explain_result
+    # @return [String,nil] Explanation of result, or nil if no call to #roll yet.
+    def explain_result
+      return nil unless @result
+
+      explanations = @bunches.map { |bunch| "#{bunch.label}: #{bunch.explain_result}" }
+
+      return @offset.to_s if explanations.none?
+
+      return simple_explanation(explanations.first) if explanations.one?
+
+      multi_explanations(explanations)
+    end
+
+    private
+
+    def simple_explanation(explanation)
+      return explanation if @offset.zero?
+
+      "#{explanation}. #{array_to_sum([@bunches[0].result, @offset])}"
+    end
+
+    def multi_explanations(explanations)
+      bunch_values = @bunch_multipliers.zip(@bunches).map { |m, b| m * b.result }
+      bunch_values << @offset if @offset != 0
+      explanations << array_to_sum(bunch_values)
+      explanations.join('. ')
+    end
+
+    def array_to_sum(array)
+      (numbers_to_strings(array) + ['=', array.sum]).join(' ')
+    end
+
+    def numbers_to_strings(array)
+      [array.first.to_s] + array.drop(1).map { |n| n.negative? ? "- #{n.abs}" : "+ #{n}" }
+    end
+
+    def bunches_weighted_sum(summed_method)
+      @bunch_multipliers.zip(@bunches).inject(0) do |total, mb|
+        m, b = mb
+        total + (m * b.send(summed_method))
+      end
+    end
+  end
+end