XEEN: Cleanup and comments for Combat class

3 files changed, 66 insertions, 23 deletions

diff --git a/engines/xeen/combat.cpp b/engines/xeen/combat.cpp
index 94d31bd3b7..35283f2866 100644
--- a/engines/xeen/combat.cpp
+++ b/engines/xeen/combat.cpp
@@ -1678,25 +1678,26 @@ void Combat::getWeaponDamage(Character &c, RangeType rangeType) {
 	_hitChanceBonus = 0;
 
 	for (int idx = 0; idx < INV_ITEMS_TOTAL; ++idx) {
+		XeenItem &weapon = c._weapons[idx];
 		bool flag;
 		if (rangeType) {
-			flag = c._weapons[idx]._frame == 4;
+			flag = weapon._frame == 4;
 		} else {
-			flag = c._weapons[idx]._frame == 1 || c._weapons[idx]._frame == 13;
+			flag = weapon._frame == 1 || weapon._frame == 13;
 		}
 
 		if (flag) {
-			if (!(c._weapons[idx]._bonusFlags & (ITEMFLAG_BROKEN | ITEMFLAG_CURSED))) {
-				_attackWeapon = &c._weapons[idx];
+			if (!(weapon._bonusFlags & (ITEMFLAG_BROKEN | ITEMFLAG_CURSED))) {
+				_attackWeapon = &weapon;
 
-				if (c._weapons[idx]._material >= 37 && c._weapons[idx]._material < 59) {
-					_hitChanceBonus = Res.METAL_DAMAGE_PERCENT[c._weapons[idx]._material - 37];
-					_weaponDamage = Res.METAL_DAMAGE[c._weapons[idx]._material - 37];
+				if (weapon._material >= 37 && weapon._material < 59) {
+					_hitChanceBonus = Res.METAL_DAMAGE_PERCENT[weapon._material - 37];
+					_weaponDamage = Res.METAL_DAMAGE[weapon._material - 37];
 				}
 			}
 
 			_hitChanceBonus += party._heroism;
-			_attackWeaponId = c._weapons[idx]._id;
+			_attackWeaponId = weapon._id;
 			_weaponDice = Res.WEAPON_DAMAGE_BASE[_attackWeaponId];
 			_weaponDie = Res.WEAPON_DAMAGE_MULTIPLIER[_attackWeaponId];
 
diff --git a/engines/xeen/combat.h b/engines/xeen/combat.h
index efff2d521f..e01d4df02e 100644
--- a/engines/xeen/combat.h
+++ b/engines/xeen/combat.h
@@ -26,6 +26,7 @@
 #include "common/scummsys.h"
 #include "common/rect.h"
 #include "xeen/files.h"
+#include "xeen/item.h"
 #include "xeen/sprites.h"
 
 namespace Xeen {
@@ -53,15 +54,6 @@ enum SpecialAttack {
 	SA_ERADICATE = 19, SA_AGING = 20, SA_DEATH = 21, SA_STONE = 22
 };
 
-enum ElementalCategory {
-	ELEM_FIRE = 0, ELEM_ELECTRICITY = 1, ELEM_COLD = 2,
-	ELEM_ACID_POISON = 3, ELEM_ENERGY = 4, ELEM_MAGIC = 5
-};
-
-enum RangeType {
-	RT_SINGLE = 0, RT_GROUP = 1, RT_ALL = 2, RT_HIT = 3
-};
-
 enum ShootType {
 	ST_0 = 0, ST_1 = 1
 };
@@ -119,16 +111,34 @@ class Combat {
 private:
 	XeenEngine *_vm;
 
+	/**
+	 * Handles the logic for attacking with a given amount of damage
+	 */
 	void attack2(int damage, RangeType rangeType);
 
+	/**
+	 * Returns true if the character successfully hits the monster
+	 */
 	bool hitMonster(Character &c, RangeType rangeType);
 
+	/**
+	 * Gets the damage a given character's equipped weapon will do
+	 */
 	void getWeaponDamage(Character &c, RangeType rangeType);
 
+	/**
+	 * Returns how much damage will be done to a monster
+	 */
 	int getMonsterDamage(Character &c);
 
+	/**
+	 * Gets the scale of damage, used for sprite display in the scene
+	 */
 	int getDamageScale(int v);
 
+	/**
+	 * Gets the current monster's damage resistance to the currently set damage type
+	 */
 	int getMonsterResistence(RangeType rangeType);
 
 	/**
@@ -190,6 +200,9 @@ public:
 	 */
 	void clearShooting();
 
+	/**
+	 * Gives damage to character or characters in the party
+	 */
 	void giveCharDamage(int damage, DamageType attackType, int charIndex);
 
 	/**
@@ -197,6 +210,9 @@ public:
 	 */
 	void doCharDamage(Character &c, int charNum, int monsterDataIndex);
 
+	/**
+	 * Handles moving monsters by a space between game turns
+	 */
 	void moveMonsters();
 
 	/**
@@ -204,6 +220,9 @@ public:
 	 */
 	void setupCombatParty();
 
+	/**
+	 * Sets up a table of speeds to determine the order in which characters and monsters fight
+	 */
 	void setSpeedTable();
 
 	/**
@@ -221,6 +240,9 @@ public:
 	 */
 	Common::String getMonsterDescriptions();
 
+	/**
+	 * Main method for characters to attack
+	 */
 	void attack(Character &c, RangeType rangeType);
 
 	/**
@@ -258,10 +280,16 @@ public:
 
 	void doMonsterTurn(int monsterId);
 
+	/**
+	 * Called when combat has ended
+	 */
 	void endAttack();
 
 	void monsterOvercome();
 
+	/**
+	 * Checks whether a given position on the map will stop a ranged attack
+	 */
 	int stopAttack(const Common::Point &diffPt);
 
 	/**
diff --git a/engines/xeen/item.h b/engines/xeen/item.h
index 2b6058c2fd..6e81004298 100644
--- a/engines/xeen/item.h
+++ b/engines/xeen/item.h
@@ -27,7 +27,6 @@
 #include "common/array.h"
 #include "common/rect.h"
 #include "common/serializer.h"
-#include "xeen/combat.h"
 #include "xeen/sprites.h"
 
 namespace Xeen {
@@ -35,6 +34,7 @@ namespace Xeen {
 #define INV_ITEMS_TOTAL 9
 
 class XeenEngine;
+class Character;
 
 enum ItemCategory {
 	CATEGORY_WEAPON = 0, CATEGORY_ARMOR = 1, CATEGORY_ACCESSORY = 2, CATEGORY_MISC = 3,
@@ -47,6 +47,15 @@ enum AttributeCategory {
 	ATTR_ARMOR_CLASS = 8, ATTR_THIEVERY = 9
 };
 
+enum RangeType {
+	RT_SINGLE = 0, RT_GROUP = 1, RT_ALL = 2, RT_HIT = 3
+};
+
+enum ElementalCategory {
+	ELEM_FIRE = 0, ELEM_ELECTRICITY = 1, ELEM_COLD = 2, ELEM_ACID_POISON = 3,
+	ELEM_ENERGY = 4, ELEM_MAGIC = 5
+};
+
 class XeenItem {
 public:
 	int _material;
@@ -85,6 +94,8 @@ public:
 	 * Gets the attribute category for the item
 	 */
 	AttributeCategory getAttributeCategory() const;
+
+	void getWeaponDamage(Character &c, RangeType rangeType);
 };
 
 class InventoryItems : public Common::Array<XeenItem> {
@@ -98,7 +109,7 @@ protected:
 		ItemCategory category2);
 
 	/**
-	 ** Returns a text string listing all the stats/attributes of a given item
+	 * Returns a text string listing all the stats/attributes of a given item
 	 */
 	virtual Common::String getAttributes(XeenItem &item, const Common::String &classes) = 0;
 public:
@@ -161,7 +172,7 @@ public:
 class WeaponItems: public InventoryItems {
 protected:
 	/**
-	 ** Returns a text string listing all the stats/attributes of a given item
+	 * Returns a text string listing all the stats/attributes of a given item
 	 */
 	virtual Common::String getAttributes(XeenItem &item, const Common::String &classes);
 public:
@@ -188,7 +199,7 @@ public:
 class ArmorItems : public InventoryItems {
 protected:
 	/**
-	 ** Returns a text string listing all the stats/attributes of a given item
+	 * Returns a text string listing all the stats/attributes of a given item
 	 */
 	virtual Common::String getAttributes(XeenItem &item, const Common::String &classes);
 public:
@@ -215,7 +226,7 @@ public:
 class AccessoryItems : public InventoryItems {
 protected:
 	/**
-	 ** Returns a text string listing all the stats/attributes of a given item
+	 * Returns a text string listing all the stats/attributes of a given item
 	 */
 	virtual Common::String getAttributes(XeenItem &item, const Common::String &classes);
 public:
@@ -236,7 +247,7 @@ public:
 class MiscItems : public InventoryItems {
 protected:
 	/**
-	 ** Returns a text string listing all the stats/attributes of a given item
+	 * Returns a text string listing all the stats/attributes of a given item
 	 */
 	virtual Common::String getAttributes(XeenItem &item, const Common::String &classes);
 public:
@@ -257,6 +268,9 @@ public:
 	InventoryItemsGroup(InventoryItems &weapons, InventoryItems &armor,
 		InventoryItems &accessories, InventoryItems &misc);
 
+	/**
+	 * Returns the inventory items for a given category
+	 */
 	InventoryItems &operator[](ItemCategory category);
 
 	/**