Add more documentation and fix rubocop warnings

data/plugins/combat/ammo.rb

@@ -11,7 +11,7 @@ def create_ammo(item_matcher, properties, &block)
 
   items.each do |item_id|
     AMMO[item_id] = Ammo.new(item_id, properties)
-    AMMO[item_id].instance_eval &block if block_given?
+    AMMO[item_id].instance_eval(&block) if block_given?
   end
 end
 

data/plugins/combat/attack.rb

@@ -99,7 +99,6 @@ end
 # damage delayed by the speed and travel distance of the projectile.
 
 class MagicAttack < BaseAttack
-
   ##
   # The maximum distance that a magic attack can be performed from.
   MAX_DISTANCE = 8
@@ -118,7 +117,6 @@ class MagicAttack < BaseAttack
   end
 
   def apply(source, target)
-
     projectile!(source, target, @projectile, @projectile_type)
 
     distance = source.position.get_distance(target.position)
@@ -136,7 +134,6 @@ class MagicAttack < BaseAttack
 
     end
   end
-
 end
 
 ##
@@ -154,7 +151,7 @@ end
 class AttackDSL
   attr_accessor :animation, :speed, :range, :graphic
 
-  def initialize()
+  def initialize
     @requirements = []
     @subattacks = []
   end
@@ -200,11 +197,11 @@ end
 
 private
 
-def schedule_damage!(source, target, amount, delay, secondary = false, &callback)
+def schedule_damage!(source, target, amount, delay, secondary = false, &_callback)
   schedule delay do |task|
 
     do_damage!(source, target, amount, secondary)
-    callback.call if block_given?
+    yield if block_given?
 
     task.stop
   end
@@ -225,7 +222,7 @@ end
 def auto_retaliate!(source, target)
   target_combat_state = target.get_combat_state
 
-  if target.auto_retaliate && !target_combat_state.is_attacking?
+  if target.auto_retaliate && !target_combat_state.attacking?
     target_combat_state.target = source
     target.start_action(CombatAction.new(target))
   end

data/plugins/combat/attack_requirements.rb

@@ -32,9 +32,9 @@ end
 
 class AttackRequirementDSL
   RUNES = {
-    :air => 556, :water => 555, :earth => 557, :fire => 554,
-    :mind => 558, :chaos => 562, :death => 560, :blood => 565,
-    :cosmic => 564, :law => 563, :nature => 561, :soul => 566
+    air: 556, water: 555, earth: 557, fire: 554,
+    mind: 558, chaos: 562, death: 560, blood: 565,
+    cosmic: 564, law: 563, nature: 561, soul: 566
   }
 
   attr_reader :requirements
@@ -65,7 +65,7 @@ class SpecialEnergyRequirement < AttackRequirement
       player.using_special = false
 
       update_special_bar(player)
-      fail AttackRequirementException.new('Not enough special attack energy.')
+      fail AttackRequirementException, 'Not enough special attack energy.'
     end
   end
 
@@ -79,11 +79,11 @@ end
 
 class LevelRequirement < AttackRequirement
   SKILLS = {
-    :magic => Skill::MAGIC
+    magic: Skill::MAGIC
   }
 
   def initialize(type, level)
-    fail "Could not find '#{type}' skill." unless SKILLS.has_key?(type)
+    fail "Could not find '#{type}' skill." unless SKILLS.key?(type)
 
     @skill = SKILLS[type]
     @level = level
@@ -92,7 +92,7 @@ class LevelRequirement < AttackRequirement
   def validate(player)
     current_level = player.skill_set.current_level(@skill)
     
-    throw AttackRequirementException.new(skill_requirement_message) unless current_level >= @level
+    fail AttackRequirementException, skill_requirement_message unless current_level >= @level
   end
 
   def apply!(player)
@@ -101,7 +101,7 @@ class LevelRequirement < AttackRequirement
   private
 
   def skill_requirement_message
-    "TODO"
+    'TODO'
   end
 end
 
@@ -112,7 +112,7 @@ class ItemRequirement < AttackRequirement
   end
 
   def validate(player)
-    throw AttackRequirementException.new(item_missing_message) unless player.inventory.get_amount(@item) >= @amount
+    fail AttackRequirementException, item_missing_message unless player.inventory.get_amount(@item) >= @amount
   end
 
   def apply!(player)
@@ -122,8 +122,6 @@ class ItemRequirement < AttackRequirement
   private
 
   def item_missing_message
-    definition = ItemDefinition.lookup(@item)
-
     "You don't have enough #{lookup_item(@item).name}s"
   end
 end
@@ -141,19 +139,19 @@ class AmmoRequirement < AttackRequirement
     equipped_ammo_amt = player.equipment.get(EquipmentConstants::AMMO).amount
 
     if equipped_ammo.nil?
-      fail AttackRequirementException.new('You have no ammo left in your quiver!')
+      fail AttackRequirementException, 'You have no ammo left in your quiver!'
     end
 
     if @amount > 1 && equipped_ammo_amt < @amount
-      fail AttackRequirementException.new('You don\'t have enough ammo left in your quiver!')
+      fail AttackRequirementException, 'You don\'t have enough ammo left in your quiver!'
     end
 
     unless equipped_ammo.weapon_classes.include? equipped_weapon.weapon_class.name
-      fail AttackRequirementException.new('You can\'t use this ammo with this weapon.')
+      fail AttackRequirementException, 'You can\'t use this ammo with this weapon.'
     end
 
     if equipped_ammo.level_requirement > equipped_weapon_def.ranged_level
-      fail AttackRequirementException.new('You can\'t use this ammo with this weapon.')
+      fail AttackRequirementException, 'You can\'t use this ammo with this weapon.'
     end
   end
   

data/plugins/combat/bonuses.rb

@@ -1,4 +1,5 @@
 module Combat
+  ##
   # A module for units which can have their own bonuses. E.G., weapons, equipment, ammo.
   module BonusContainer
     def attack_bonus(type)

data/plugins/combat/combat.rb

@@ -21,7 +21,7 @@ end
 on :message, :magic_on_mob do |player, message|
   target = $world.npc_repository.get(message.index)
 
-  next unless SPELLBOOKS.has_key? message.interface_id
+  next unless SPELLBOOKS.key? message.interface_id
 
   player_combat_state = player.get_combat_state
   player_combat_state.target = target

data/plugins/combat/combat_action.rb

@@ -4,21 +4,20 @@ java_import 'org.apollo.game.model.entity.EntityType'
 class CombatAction < Action
   def initialize(source, once = false)
     super(0, true, source)
-
-    mob.attacking = true
-
     @combat_state = source.get_combat_state
     @attack_timer = 100
     @once         = once
+    mob.attacking = true
   end
 
   def can_attack?
     next_attack           = @combat_state.next_attack true
     target                = @combat_state.target
     current_distance      = mob.position.get_distance target.position
-    attack_collision_type = next_attack.range > 1 ? EntityType::PROJECTILE : EntityType::NPC
 
-    in_range = current_distance <= next_attack.range# && !$world.intersects(mob.position, target.position, attack_collision_type)
+    in_range = current_distance <= next_attack.range
+    in_range = in_range && !$world.intersects(mob.position, target.position, 
+                                     next_attack.range > 1 ? EntityType::PROJECTILE : EntityType::NPC)
     
     unless in_range
       mob.follow @combat_state.target, next_attack.range

data/plugins/combat/combat_spell.rb

@@ -1,5 +1,4 @@
 class CombatSpell
-
   attr_reader :button
 
   attr_reader :spellbook
@@ -29,11 +28,9 @@ class CombatSpell
     @projectile = projectile
     @projectile_type = projectile_type
   end
-
 end
 
 class CombatSpellDSL
-
   def initialize(&block)
     instance_eval(&block)
   end
@@ -73,9 +70,8 @@ class CombatSpellDSL
   end
 
   def to_combat_spell
-    return CombatSpell.new(@button, @spellbook, @requirements, @damage, @animation, @graphic, @hit_graphic, @projectile, @projectile_type)
+    CombatSpell.new(@button, @spellbook, @requirements, @damage, @animation, @graphic, @hit_graphic, @projectile, @projectile_type)
   end
-
 end
 
 COMBAT_SPELLS = {}
@@ -89,8 +85,7 @@ def create_combat_spell(name, &block)
 end
 
 def spell_for(spellbook, button)
-
-  COMBAT_SPELLS.each do |name, spell|
+  COMBAT_SPELLS.each do |_name, spell|
     return spell if spell.spellbook == spellbook && spell.button == button
   end
 

data/plugins/combat/combat_state.rb

@@ -2,9 +2,7 @@ java_import 'org.apollo.game.model.entity.Mob'
 
 module MobCombatState
   def get_combat_state
-    if @combat_state.nil?
-      @combat_state = CombatState.new(self, true)
-    end
+    @combat_state = CombatState.new(self, true) if @combat_state.nil?
 
     @combat_state
   end
@@ -30,10 +28,10 @@ class CombatState
   end
 
   def will_attack?
-    is_attacking? && next_attack(true).speed >= @mob.attack_timer
+    attacking? && next_attack(true).speed >= @mob.attack_timer
   end
 
-  def is_attacking?
+  def attacking?
     !target.nil? && @mob.attacking
   end
 

data/plugins/combat/util.rb

@@ -8,7 +8,7 @@ class CombatUtil
     strength      = source.skill_set.get_skill(Skill::STRENGTH)
     strength_stat = 5 # source.bonus_stat(:other, :strength)
 
-    effective_strength_damage = (strength.current_level) # * prayer_multiplier
+    effective_strength_damage = strength.current_level # * prayer_multiplier
 
     if [:aggressive, :alt_aggressive].include? source.combat_style
       effective_strength_damage += 3

data/plugins/combat/weapon.rb

@@ -8,6 +8,13 @@ java_import 'org.apollo.game.model.inv.SynchronizationInventoryListener'
 
 WEAPONS       = {}
 NAMED_WEAPONS = {}
+## 
+# Create a new {@code Weapon} and configure it with the Weapon DSL.
+#
+# @param [Symbol] identifier A unique identifier for the weapon if {@code named} is true, otherwise the item name
+#                            of the weapon
+# @param [Symbol] class_name A symbol representing the {@code WeaponClass} this weapon belongs to.
+# @param [Boolean]           True if this is a uniquely identified weapon, false if it belongs to an item.
 
 def create_weapon(identifier, class_name = nil, named: false, &block)
   if named
@@ -52,13 +59,13 @@ def create_normal_weapon(item_matcher, class_name = nil, &block)
     end
 
     WEAPONS[item_id] = Weapon.new(definition.name, WEAPON_CLASSES[class_name])
-    WEAPONS[item_id].instance_eval &block if block_given?
+    WEAPONS[item_id].instance_eval(&block) if block_given?
   end
 end
 
 def create_named_weapon(name, class_name, &block)
   NAMED_WEAPONS[name] = Weapon.new name.to_s.capitalize, WEAPON_CLASSES[class_name]
-  NAMED_WEAPONS[name].instance_eval &block if block_given?
+  NAMED_WEAPONS[name].instance_eval(&block) if block_given?
 end
 
 # Represents an equippable weapon, and the class it belongs to.
@@ -87,7 +94,7 @@ class Weapon
     attack_dsl.animation = animation
     attack_dsl.graphic = graphic
     attack_dsl.add_requirement SpecialEnergyRequirement.new(energy_requirement)
-    attack_dsl.instance_eval &block
+    attack_dsl.instance_eval(&block)
 
     @special_attack = attack_dsl.to_attack
   end

data/plugins/combat/weapon_class.rb

@@ -157,6 +157,7 @@ class WeaponClass
   end
 
   ##
+  # Set the character animations associated with this weapon class.
   
   def animations(stand: nil, walk: nil, run: nil, idle_turn: nil, turn_around: nil, turn_left: nil, turn_right: nil)
     @animations = {

data/plugins/combat/weapons/melee/daggers.rb

@@ -29,7 +29,7 @@ create_weapon_class :dragon_dagger, widget: DAGGER_WIDGET_ID do
   style :defensive, button: 5
 end
 
-create_weapon /(?:drag|dragon) dagger.*/, :dragon_dagger do
+create_weapon(/(?:drag|dragon) dagger.*/, :dragon_dagger) do
   set_special_attack speed: 4, energy_requirement: 25, animation: 1062, graphic: { id: 252, height: 100 } do
     damage!
     damage! secondary: true

data/plugins/combat/weapons/melee/scimitars.rb

@@ -25,7 +25,7 @@ create_weapon :steel_scimitar do
   other_bonuses melee_strength: 14
 end
 
-create_weapon /(black|white) scimitar/ do
+create_weapon(/(black|white) scimitar/) do
   attack_bonuses stab: 4, slash: 19
   other_bonuses melee_strength: 14
 end

data/plugins/combat/weapons/melee/two_handed_swords.rb

@@ -6,7 +6,8 @@ create_weapon_class :two_handed_sword, widget: TWO_HANDED_SWORD_WIDGET_ID do
   defaults speed: 7, animation: 7041, attack_type: :slash
   special_bar TWO_HANDED_SWORD_SPECIAL_CONFIG_ID, TWO_HANDED_SWORD_SPECIAL_BUTTON_ID
 
-  animations stand: 7047, walk: 7046, run: 7039, idle_turn: 7044, turn_around: 7044, turn_left: 7043, turn_right: 7044
+  animations stand: 7047, walk: 7046, run: 7039, idle_turn: 7044, turn_around: 7044,
+             turn_left: 7043, turn_right: 7044
 
   attack_bonuses stab: -4, magic: -4
   defence_bonuses range: -1
@@ -27,7 +28,7 @@ create_weapon :steel_2h_sword do
   other_bonuses melee_strength: 22
 end
 
-create_weapon /(?:black|white) 2h sword/ do
+create_weapon(/(?:black|white) 2h sword/) do
   attack_bonuses slash: 27, crush: 21
   other_bonuses melee_strength: 26
 end

data/plugins/combat/weapons/ranged/crossbows.rb

@@ -8,4 +8,4 @@ create_weapon_class :crossbow, widget: CROSSBOW_WIDGET_ID, type: :ranged do
   style :long_range, range: 9, button: 4
 end
 
-create_weapon /rune c'bow/, :crossbow
+create_weapon(/rune c'bow/, :crossbow)