rpg-tools 0.1.0 → 0.2.0

data/README.textile

@@ -1,6 +1,12 @@
 h1. RPG Tools 
 
-#TODO
+RPG Tools is a compilation of helpful tools when developing a Role Playing Game (RPG). For now the gem has three classes:
+
+Die: Models the use of a simple die (ie. D6, D10, D20, etc.)
+Throw: Takes an array of Die to be rolled and the offset to be added (ie. 2D6, 3D4+5, 2D10,3D20+2, etc.)
+CheckRoll: Using a Throw and a threshold models a check roll with one or several chances and some other settings (ie. 2D6 to get greater or equal to 10, 3D10 to get les than 15, etc.)
+
+These tools try to be flexible, general and powerful. Most of Die representation in other gems do the job of a Throw (a pack of Dice with a offset) or just return the result of ten rolls as single Fixum giving no information of each of the single ten rolls (which may be important if you want to have detailed info or want to give feedback to the user). With RPG Tools each object acts as it should: a Die acts as a Die, with no more functionality than a normal Die and each. Also each roll has all the information needed just if you want it. By default rolling a Throw just returns the total amount, but if you ask for a detailed roll you will get the total amount and the result of each dice of the Throw.  
 
 h2. Installation
 
@@ -15,7 +21,119 @@ Then run:
 
 h2. Using RPG Tools. API
 
-#TODO
+h3. Using Tools::Die
+
+Creating a new Die:
+<pre><code>
+  die = Tools::Die.new #Creates a new Die with 20 sides (D20) by default
+  die = Tools::Die.new 6 #Creates a new Die with 6 sides (D6)
+  die = Tools::Die.new 100 #Creates a new Die with 100 sides (D100)
+</code></pre>
+
+Rolling a Die:
+<pre><code>
+  die = Tools::Die.new
+  #Rolling the die once 
+  die.roll # => 8
+  #Rolling the die five times
+  die.roll 5 # => [1, 20, 16, 11, 11]
+</code></pre>
+
+More methods of Die:
+<pre><code>
+  #Converting Die into string
+  die1 = Tools::Die.new 20
+  die2 = Tools::Die.new 6
+  die3 = Tools::Die.new 100
+  die1.to_s # => "D20"
+  die2.to_s # => "D6"
+  die3.to_s # => "D100"
+</code></pre>
+<pre><code>
+  #Comparing Dice
+  die1 = Tools::Die.new 20
+  die2 = Tools::Die.new 6
+  die3 = Tools::Die.new 20
+  die1.eql? die1 # => true
+  die1.eql? die2 # => false
+  die1.eql? die3 # => true
+</code></pre>
+
+h3. Using Tools::Throw
+
+Creating a new Throw:
+<pre><code>
+  dice = [Tools::Die.new(6),Tools::Die.new(6),Tools::Die.new(20),Tools::Die.new(100),Tools::Die.new(100),Tools::Die.new(100)]
+  offset = 3
+  throw = Tools::Throw.new dice,offset #Creates a new throw with 2D6, 1D20, 3D100 and +3
+</code></pre>
+
+Rolling a Throw:
+<pre><code>
+  dice = [Tools::Die.new(6),Tools::Die.new(6),Tools::Die.new(20)]
+  offset = 2
+  throw = Tools::Throw.new dice,offset #Creates a new throw with 2D6, 1D20 and +2
+  #Rolling the throw once (simple)
+  throw.roll # => 10
+  #Rolling the throw once (detailed)
+  throw.roll 1,true # => [25, [6, 6, 11]]
+  #Rolling the throw five times (simple)
+  throw.roll 5 # => [23, 22, 18, 18, 16]
+  #Rolling the throw five times (detailed)
+  throw.roll 5, true # => [[26, [1, 4, 19]], [28, [6, 3, 17]], [13, [1, 4, 6]], [23, [5, 6, 10]], [11, [3, 5, 1]]]
+</code></pre>
+
+More methods of Throw:
+<pre><code>
+  #Converting Throw into string
+  dice = [Tools::Die.new(6),Tools::Die.new(6),Tools::Die.new(20),Tools::Die.new(100),Tools::Die.new(100),Tools::Die.new(100)]
+  offset = 3
+  throw = Tools::Throw.new dice,offset #Creates a new throw with 2D6, 1D20, 3D100 and +3
+  throw.to_s # => "2D6,1D20,3D100+3"
+</code></pre>
+
+h3. Using Tools::CheckRoll
+
+Creating a new CheckRoll:
+<pre><code>
+  dice = [Tools::Die.new(6),Tools::Die.new(6)]
+  offset = 2
+  throw = Tools::Throw.new dice,offset #Creates a new throw with 2D6+2
+  threshold = 9
+  check_roll = Tools::CheckRoll.new throw, threshold #Creates a CheckRoll with 2D6+2 throw and a threshold of 9
+</code></pre>
+
+Rolling a CheckRoll:
+<pre><code>
+  dice = [Tools::Die.new(6),Tools::Die.new(6)]
+  offset = 2
+  throw = Tools::Throw.new dice,offset #Creates a new throw with 2D6+2
+  threshold = 9
+  check_roll = Tools::CheckRoll.new throw, threshold #Creates a CheckRoll with 2D6+2 throw and a threshold of 9
+  #Roll the CheckRoll
+  check_roll.roll # => [false, 6]
+  #CheckRoll results
+  check_roll.is_successful? # => false
+  check_roll.result # => [false, 6]
+  check_roll.detailed_result # => [false, [6, [3, 1]]]
+  #Reroll the CheckRoll
+  check_roll.reroll # => [true, 12]
+  #CheckRoll results
+  check_roll.is_successful? # => true 
+  check_roll.result # => [true, 12]
+  check_roll.detailed_result # => [true, [12, [6, 4]]]
+</code></pre>
+
+More methods of CheckRoll:
+<pre><code>
+  #Converting CheckRoll into string
+  dice = [Tools::Die.new(6),Tools::Die.new(6)]
+  offset = 2
+  throw = Tools::Throw.new dice,offset #Creates a new throw with 2D6+2
+  threshold = 9
+  check_roll = Tools::CheckRoll.new throw, threshold #Creates a CheckRoll with 2D6+2 throw and a threshold of 9
+  check_roll.to_s # => "2D6+2 must be greater or equal to 9."
+</code></pre>
 
 h2. License
 

data/Rakefile

@@ -17,7 +17,7 @@ task :default => :spec
 
 Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "Fuzion RPG"
+  rdoc.title = "RPG Tools"
   rdoc.options << '--line-numbers' << '--inline-source'
   rdoc.rdoc_files.include('README.rdoc')
   rdoc.rdoc_files.include('lib/**/*.rb', 'app/**/*.rb')

data/app/models/tools/check_roll.rb

@@ -1,82 +1,104 @@
-class Tools::CheckRoll
+module Tools
+  class CheckRoll
 
-  attr_accessor :throw, :threshold, :rolling_chances, :greater_than_threshold, :equal_than_threshold
-  attr_reader :result
-  def initialize throw, threshold, rolling_chances=1, greater_than_threshold=true, equal_than_threshold=true
-    @throw = throw
-    @threshold = threshold
-    @rolling_chances = rolling_chances
-    @greater_than_threshold = greater_than_threshold
-    @equal_than_threshold = equal_than_threshold
-  end
+    attr_accessor :throw, :threshold, :rolling_chances, :greater_than_threshold, :equal_than_threshold
+    attr_reader :result
+    def initialize throw, threshold, rolling_chances=1, greater_than_threshold=true, equal_than_threshold=true
+      @throw = throw
+      @threshold = threshold
+      @rolling_chances = rolling_chances
+      @greater_than_threshold = greater_than_threshold
+      @equal_than_threshold = equal_than_threshold
+    end
 
-  #[true/false,best_rolled]
-  def roll
-    return @result if @result
-    best_rolled = 0
-    @rolling_chances.times do
-      rolled_throw = @throw.roll 1,true #Detailed throw
-      best_rolled = rolled_throw if rolled_throw[0] > best_rolled[0]
+    # Rolls the Throw as many times as rolling chances are set.If has already
+    # been rolled just returns the last result.
+    # Returns the result as an +Array+ with the format [true/false, simple_best_rolled].
+    # The first element of the array illustrates whether the check was successful or not.
+    # The second element is the best rolled throw as a simple Throw result, a +Fixnum+.
+    # For a more detailed result (with a detailed Throw result), use +detailed_result+.
+    def roll
+      return @result if @result
+      best_rolled = 0
+      @rolling_chances.times do
+        rolled_throw = @throw.roll 1,true #Detailed throw
+        best_rolled = rolled_throw if rolled_throw[0] > best_rolled[0]
+      end
+      @result = [compare(best_rolled[0], @threshold),best_rolled]
+      result
     end
-    @result = [compare(best_rolled[0], @threshold),best_rolled]    
-    result
-  end
 
-  def reroll
-    @result = nil
-    roll
-  end
+    # Forces a new roll by deleting the old result.
+    def reroll
+      @result = nil
+      roll
+    end
 
-  def is_successful?
-    roll if @result.blank?
-    return @result[0]
-  end  
-  
-  def result
-    [@result[0],@result[1][0]]
-  end
-  
-  def detailed_result
-    @result
-  end
+    # Returns whether the check was successful or not. It rolls the check if not done before.
+    def is_successful?
+      roll if @result.blank?
+      return @result[0]
+    end
 
-  def to_s
-    string = "#{@throw.to_s} #{I18n.t('rpg_tools.check_roll.must_be')} #{comparatives_text} #{@threshold}."
-    if @result
-      string << " #{I18n.t('rpg_tools.check_roll.already_checked')}" 
-      string << " #{@result[0] ? I18n.t('rpg_tools.check_roll.success') : I18n.t('rpg_tools.check_roll.failure')}"
-      string << " (#{@result[1][0]})."
+    # Returns the result as an +Array+ with the format [true/false, simple_best_rolled].
+    # The first element of the array illustrates whether the check was successful or not.
+    # The second element is the best rolled throw as a simple Throw result, a +Fixnum+.
+    # For a more detailed result (with a detailed Throw result), use +detailed_result+.
+    # It rolls the check if not done before.
+    def result
+      roll if @result.blank?
+      [@result[0],@result[1][0]]
     end
-    string
-  end
 
-  private
+    # Returns the result as an +Array+ with the format [true/false, detailed_best_rolled].
+    # The first element of the array illustrates whether the check was successful or not.
+    # The second element is the best rolled throw as a detailed Throw result, please
+    # refer to +Tools::Throw.roll+ for more info on detailed Throw.
+    # It rolls the check if not done before.
+    def detailed_result
+      roll if @result.blank?
+      @result
+    end
 
-  def compare rolled_throw, threshold
-    gtt = @greater_than_threshold
-    ett = @equal_than_threshold
-    if gtt and ett
-    return rolled_throw >= threshold
-    elsif gtt and !ett
-    return rolled_throw > threshold
-    elsif !gtt and !ett
-    return rolled_throw < threshold
-    elsif !gtt and ett
-    return rolled_throw <= threshold
+    # Returns the CheckRoll as a string. Example "2D4,1D6,1D20+3 must be greater or equal to 20."
+    def to_s
+      string = "#{@throw.to_s} #{I18n.t('rpg_tools.check_roll.must_be')} #{comparatives_text} #{@threshold}."
+      if @result
+        string << " #{I18n.t('rpg_tools.check_roll.already_checked')}"
+        string << " #{@result[0] ? I18n.t('rpg_tools.check_roll.success') : I18n.t('rpg_tools.check_roll.failure')}"
+        string << " (#{@result[1][0]})."
+      end
+      string
     end
-  end
-  
-  def comparatives_text
-    gtt = @greater_than_threshold
-    ett = @equal_than_threshold
-    if gtt and ett
-    return I18n.t 'rpg_tools.check_roll.greater_and_equal'
-    elsif gtt and !ett
-    return I18n.t 'rpg_tools.check_roll.greater'
-    elsif !gtt and !ett
-    return I18n.t 'rpg_tools.check_roll.less'
-    elsif !gtt and ett
-    return I18n.t 'rpg_tools.check_roll.less_and_equal'
+
+    private
+
+    def compare rolled_throw, threshold
+      gtt = @greater_than_threshold
+      ett = @equal_than_threshold
+      if gtt and ett
+      return rolled_throw >= threshold
+      elsif gtt and !ett
+      return rolled_throw > threshold
+      elsif !gtt and !ett
+      return rolled_throw < threshold
+      elsif !gtt and ett
+      return rolled_throw <= threshold
+      end
+    end
+
+    def comparatives_text
+      gtt = @greater_than_threshold
+      ett = @equal_than_threshold
+      if gtt and ett
+        return I18n.t 'rpg_tools.check_roll.greater_and_equal'
+      elsif gtt and !ett
+        return I18n.t 'rpg_tools.check_roll.greater'
+      elsif !gtt and !ett
+        return I18n.t 'rpg_tools.check_roll.less'
+      elsif !gtt and ett
+        return I18n.t 'rpg_tools.check_roll.less_and_equal'
+      end
     end
   end
 end

data/app/models/tools/die.rb

@@ -1,35 +1,37 @@
-class Tools::Die
-  attr_accessor :sides
-  
-  def initialize sides=20
-    @sides = sides
-  end
-  
-  # Rolls the die and returns result as +Fixnum+ if rolls==1 or as +Array+ of +Fixnum+
-  # if rolls>1.
-  def roll rolls=1
-    return simple_roll if rolls==1
-    results = Array.new
-    rolls.times do 
-      results << simple_roll
+module Tools
+  class Die
+    attr_accessor :sides
+    def initialize sides=20
+      @sides = sides
+    end
+
+    # Rolls the Die and returns the result as +Fixnum+ if rolls==1 or as +Array+ of +Fixnum+
+    # if rolls>1.
+    def roll rolls=1
+      return simple_roll if rolls==1
+      results = Array.new
+      rolls.times do
+        results << simple_roll
+      end
+      return results
+    end
+
+    # Returns the Die as a string with the format Dx, where x is the number of sides. Example "D6", "D20", "D100", etc.
+    def to_s
+      return "D#{@sides}"
+    end
+
+    # Return true if the dice are equal, i.e. they have the same number of sides.
+    def eql? die
+      return false if die==nil or die.sides!=@sides
+      return true
+    end
+
+    private
+
+    #Returns a simple die roll
+    def simple_roll
+      1 + rand(sides)
     end
-    return results
-  end
-  
-  # Returns the die as a string with the format Dx, where x is the number of sides. Example "D6", "D20", "D100", etc.
-  def to_s
-    return "D#{@sides}"
-  end
-  
-  # Return true if the dice are equal, i.e. they have the same number of sides.
-  def eql? die
-    return false if die==nil or die.sides!=@sides
-    return true
-  end
-  
-  private 
-  
-  def simple_roll
-    1 + rand(sides)
   end
 end

data/app/models/tools/throw.rb

@@ -1,71 +1,81 @@
-class Tools::Throw
-  attr_accessor :dice, :offset
-  
-  def initialize dice, offset=0
-    @dice = dice.sort_by{|die| die.sides}
-    @offset = offset
-  end
-  
-  # Rolls the dice, add the offset and returns result as +Fixnum+ if rolls==1 or as 
-  # +Array+ of +Fixnum+ if rolls>1.
-  def roll rolls=1, detailed=false
-    return simple_roll if rolls==1 and !detailed
-    return detailed_roll if rolls==1 and detailed
-    results = Array.new
-    rolls.times do 
-      results << simple_roll if !detailed
-      results << detailed_roll if detailed
+module Tools
+  class Throw
+    attr_accessor :dice, :offset
+    def initialize dice, offset=0
+      @dice = dice.sort_by{|die| die.sides}
+      @offset = offset
     end
-    return results
-  end  
-  
-  # Returns the dice as a string with the format aDx,bDy,cDz+n, where a,b,c are the number of dice,
-  # x,y,z are the number of sides and n the offset. Example "D6,D20,D100+8", etc.
-  def to_s
-    throw_dice_number = Array.new
-    throw_dice = Array.new
-    temp_dice = dice.sort_by{|die| die.sides}    
-    last_die = nil
-    temp_dice.each do |temp_die|
-      if !temp_die.eql? last_die
-        last_die = temp_die
-        throw_dice << temp_die
-        throw_dice_number << temp_dice.count{|die| die.eql? temp_die}
+
+    # Rolls the Throw and returns the result in different ways according to the params.
+    # If +detailed=false+ it will call +simple_roll+ and +detailed_roll+ in case of +true+.
+    # Refer to these methods for more info of the format.
+    # Returns the result as +simple_roll/detailed_roll+ if rolls==1 or as +Array+ of
+    # +simple_roll/detailed_roll+ if rolls>1.
+    def roll rolls=1, detailed=false
+      return simple_roll if rolls==1 and !detailed
+      return detailed_roll if rolls==1 and detailed
+      results = Array.new
+      rolls.times do
+        results << simple_roll if !detailed
+        results << detailed_roll if detailed
       end
+      return results
     end
-    throw_string = ""
-    throw_dice.each_index do |i|
-      throw_string << "," if i>0
-      throw_string << throw_dice_number[i].to_s + throw_dice[i].to_s
+
+    # Returns the Trhow as a string with the format aDx,bDy,cDz+n, where a,b,c are the number of dice,
+    # x,y,z are the number of sides and n the offset. Example "D6,D20,D100+8", etc.
+    def to_s
+      throw_dice_number = Array.new
+      throw_dice = Array.new
+      temp_dice = dice.sort_by{|die| die.sides}
+      last_die = nil
+      temp_dice.each do |temp_die|
+        if !temp_die.eql? last_die
+          last_die = temp_die
+          throw_dice << temp_die
+          throw_dice_number << temp_dice.count{|die| die.eql? temp_die}
+        end
+      end
+      throw_string = ""
+      throw_dice.each_index do |i|
+        throw_string << "," if i>0
+        throw_string << throw_dice_number[i].to_s + throw_dice[i].to_s
+      end
+      throw_string << "+" if @offset>0
+      throw_string << "#{@offset}" if @offset!=0
+      return throw_string
     end
-    throw_string << "+" if @offset>0
-    throw_string << "#{@offset}" if @offset!=0
-    return throw_string
-  end
-  
-  private 
-  
-  def simple_roll
-    total = 0
-    dice.each do |die|
-      total+= die.roll
+
+    private
+
+    # Rolls all the dice and adds the offset returning just the total sum.
+    def simple_roll
+      total = 0
+      dice.each do |die|
+        total+= die.roll
+      end
+      total += offset
+      return total
     end
-    total += offset
-    return total
-  end
-  
-  def detailed_roll
-    results = Array.new
-    total = 0
-    dice.each do |die|
-      roll = die.roll
-      total+= roll
-      results << roll
+
+    # Rolls all the dice and adds the offset returning and +Array+ with detailed info.
+    # The first element of the +Array+ is the total sum of the rolled Throw and the second
+    # is another +Array+ containing the result of each one of therolled die of the Throw in
+    # the same order as returned by +dice+ (it may be different from the one used for
+    # initialize the Throw as it is ordered).
+    def detailed_roll
+      results = Array.new
+      total = 0
+      dice.each do |die|
+        roll = die.roll
+        total+= roll
+        results << roll
+      end
+      total += offset
+      detailed_throw = Array.new
+      detailed_throw[0] = total
+      detailed_throw[1] = results
+      return detailed_throw
     end
-    total += offset
-    detailed_throw = Array.new
-    detailed_throw[0] = total
-    detailed_throw[1] = results
-    return detailed_throw
   end
-end
+end

data/lib/rpg_tools.rb

@@ -1,4 +1,4 @@
-module FuzionRPG 
+module RPG_Tools 
    class << self
     def setup
       yield self

data/rpg_tools.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
 	s.name = "rpg-tools"
-	s.version = "0.1.0"
+	s.version = "0.2.0"
 	s.authors = ["Eduardo Casanova Cuesta"]
 	s.summary = "Some tools useful when creating a RPG: Die, Throw and CheckRoll."
 	s.description = "Some tools useful when creating a RPG: Die, Throw and CheckRoll."

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rpg-tools
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: 
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Eduardo Casanova Cuesta
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-08-20 00:00:00 +02:00
+date: 2011-08-21 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency