Class: GamesDice::DieResult

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/games_dice/die_result.rb

Overview

This class models the output of GamesDice::ComplexDie.

An object of the class represents the results of a roll of a ComplexDie, including any re-rolls and value mapping.

Examples:

Building up a result manually

dr = GamesDice::DieResult.new
dr.add_roll 5
dr.add_roll 4, :reroll_replace
dr.value # => 4
dr.rolls # => [5, 4]
dr.roll_reasons # => [:basic, :reroll_replace]
# dr can behave as dr.value due to coercion and support for some operators
dr + 6 # => 10

Using a result from GamesDice::ComplexDie

# An "exploding" six-sided die that needs a result of 8 to score "1 Success"
d = GamesDice::ComplexDie.new( 6, :rerolls => [[6, :<=, :reroll_add]], :maps => [[8, :<=, 1, 'Success']] )
# Generate result object by rolling the die
dr = d.roll
dr.rolls         # => [6, 3]
dr.roll_reasons  # => [:basic, :reroll_add]
dr.total         # => 9
dr.value         # => 1
dr.explain_value # => "[6+3] 9 Success"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(first_roll_result = nil, first_roll_reason = :basic) ⇒ GamesDice::DieResult

Creates new instance of GamesDice::DieResult. The object can be initialised "empty" or with a first result.

Parameters:

  • first_roll_result (Integer, nil) (defaults to: nil) —

    Value for first roll of the die.

  • first_roll_reason (Symbol) (defaults to: :basic) —

    Reason for first roll of the die.



67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/games_dice/die_result.rb', line 67

def initialize(first_roll_result = nil, first_roll_reason = :basic)
  unless GamesDice::REROLL_TYPES.key?(first_roll_reason)
    raise ArgumentError, "Unrecognised reason for roll #{first_roll_reason}"
  end

  if first_roll_result
    init_with_result(first_roll_result, first_roll_reason)
  else
    init_empty
  end
  @mapped = false
  @value = @total
end

Instance Attribute Details

#mapped ⇒ Boolean (readonly)

Whether or not #value has been mapped from #total.

Returns:

  • (Boolean) 


99
100
101
 
# File 'lib/games_dice/die_result.rb', line 99

def mapped
  @mapped
end

#roll_reasons ⇒ Array<Symbol> (readonly)

The individual reasons for each roll of the die. See GamesDice::RerollRule for allowed values.

Returns:

  • (Array<Symbol>) —

    Reasons for each die roll, indexes match the #rolls Array.



87
88
89
 
# File 'lib/games_dice/die_result.rb', line 87

def roll_reasons
  @roll_reasons
end

#rolls ⇒ Array<Integer> (readonly)

The individual die rolls that combined to generate this result.

Returns:

  • (Array<Integer>) —

    Un-processed values of each die roll used for this result.



83
84
85
 
# File 'lib/games_dice/die_result.rb', line 83

def rolls
  @rolls
end

#total ⇒ Integer? (readonly)

Combined result of all rolls, before mapping.

Returns:

  • (Integer, nil) 


91
92
93
 
# File 'lib/games_dice/die_result.rb', line 91

def total
  @total
end

#value ⇒ Integer? (readonly)

Combined result of all rolls, after mapping.

Returns:

  • (Integer, nil) 


95
96
97
 
# File 'lib/games_dice/die_result.rb', line 95

def value
  @value
end

Instance Method Details

#add_roll(roll_result, roll_reason = :basic) ⇒ Integer

Adds value from a new roll to the object. GamesDice::DieResult tracks reasons for the roll and makes the correct adjustment to the total so far. Any mapped value is cleared.

Parameters:

  • roll_result (Integer) —

    Value result from rolling the die.

  • roll_reason (Symbol) (defaults to: :basic) —

    Reason for rolling the die.

Returns:

  • (Integer) —

    Total so far

Raises:

  • (ArgumentError) 


106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/games_dice/die_result.rb', line 106

def add_roll(roll_result, roll_reason = :basic)
  raise ArgumentError, "Unrecognised roll reason #{roll_reason}" unless GamesDice::REROLL_TYPES.key?(roll_reason)

  @rolls << Integer(roll_result)
  @roll_reasons << roll_reason
  @total = 0 if @rolls.length == 1

  apply_roll_to_total(roll_reason, roll_result)

  @mapped = false
  @value = @total
end

#apply_map(to_value, description = '') ⇒ nil

Sets value arbitrarily, and notes that the value has been mapped. Used by GamesDice::ComplexDie when there are one or more GamesDice::MapRule objects to process for a die.

Parameters:

  • to_value (Integer) —

    Replacement value.

  • description (String) (defaults to: '') —

    Description of what the mapped value represents e.g. "Success"

Returns:

  • (nil) 


124
125
126
127
128
129
 
# File 'lib/games_dice/die_result.rb', line 124

def apply_map(to_value, description = '')
  @mapped = true
  @value = to_value
  @map_description = description
  nil
end

#clone ⇒ GamesDice::DieResult

This is a deep clone, all attributes are also cloned.

Returns:



154
155
156
157
158
159
160
161
162
163
 
# File 'lib/games_dice/die_result.rb', line 154

def clone
  cloned = GamesDice::DieResult.new
  cloned.instance_variable_set(:@rolls, @rolls.clone)
  cloned.instance_variable_set(:@roll_reasons, @roll_reasons.clone)
  cloned.instance_variable_set(:@total, @total)
  cloned.instance_variable_set(:@value, @value)
  cloned.instance_variable_set(:@mapped, @mapped)
  cloned.instance_variable_set(:@map_description, @map_description)
  cloned
end

#explain_value ⇒ String

Generates a text description of how #value is determined. If #value has been mapped, includes the map description, but does not include the mapped value.

Returns:

  • (String) —

    Explanation of #value.



134
135
136
137
138
139
140
141
142
 
# File 'lib/games_dice/die_result.rb', line 134

def explain_value
  text = if @rolls.length < 2
           @total.to_s
         else
           explain_value_multiple_rolls
         end
  text += " #{@map_description}" if @mapped && @map_description&.length&.positive?
  text
end