first commit

api/app/models/stats.py

@@ -0,0 +1,140 @@
+"""
+Character statistics data model.
+
+This module defines the Stats dataclass which represents a character's core
+attributes and provides computed properties for derived values like HP and MP.
+"""
+
+from dataclasses import dataclass, field, asdict
+from typing import Dict, Any
+
+
+@dataclass
+class Stats:
+    """
+    Character statistics representing core attributes.
+
+    Attributes:
+        strength: Physical power, affects melee damage
+        dexterity: Agility and precision, affects initiative and evasion
+        constitution: Endurance and health, affects HP and defense
+        intelligence: Magical power, affects spell damage and MP
+        wisdom: Perception and insight, affects magical resistance
+        charisma: Social influence, affects NPC interactions
+
+    Computed Properties:
+        hit_points: Maximum HP = 10 + (constitution × 2)
+        mana_points: Maximum MP = 10 + (intelligence × 2)
+        defense: Physical defense = constitution // 2
+        resistance: Magical resistance = wisdom // 2
+    """
+
+    strength: int = 10
+    dexterity: int = 10
+    constitution: int = 10
+    intelligence: int = 10
+    wisdom: int = 10
+    charisma: int = 10
+
+    @property
+    def hit_points(self) -> int:
+        """
+        Calculate maximum hit points based on constitution.
+
+        Formula: 10 + (constitution × 2)
+
+        Returns:
+            Maximum HP value
+        """
+        return 10 + (self.constitution * 2)
+
+    @property
+    def mana_points(self) -> int:
+        """
+        Calculate maximum mana points based on intelligence.
+
+        Formula: 10 + (intelligence × 2)
+
+        Returns:
+            Maximum MP value
+        """
+        return 10 + (self.intelligence * 2)
+
+    @property
+    def defense(self) -> int:
+        """
+        Calculate physical defense from constitution.
+
+        Formula: constitution // 2
+
+        Returns:
+            Physical defense value (damage reduction)
+        """
+        return self.constitution // 2
+
+    @property
+    def resistance(self) -> int:
+        """
+        Calculate magical resistance from wisdom.
+
+        Formula: wisdom // 2
+
+        Returns:
+            Magical resistance value (spell damage reduction)
+        """
+        return self.wisdom // 2
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Serialize stats to a dictionary.
+
+        Returns:
+            Dictionary containing all stat values
+        """
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> 'Stats':
+        """
+        Deserialize stats from a dictionary.
+
+        Args:
+            data: Dictionary containing stat values
+
+        Returns:
+            Stats instance
+        """
+        return cls(
+            strength=data.get("strength", 10),
+            dexterity=data.get("dexterity", 10),
+            constitution=data.get("constitution", 10),
+            intelligence=data.get("intelligence", 10),
+            wisdom=data.get("wisdom", 10),
+            charisma=data.get("charisma", 10),
+        )
+
+    def copy(self) -> 'Stats':
+        """
+        Create a deep copy of this Stats instance.
+
+        Returns:
+            New Stats instance with same values
+        """
+        return Stats(
+            strength=self.strength,
+            dexterity=self.dexterity,
+            constitution=self.constitution,
+            intelligence=self.intelligence,
+            wisdom=self.wisdom,
+            charisma=self.charisma,
+        )
+
+    def __repr__(self) -> str:
+        """String representation showing all stats and computed properties."""
+        return (
+            f"Stats(STR={self.strength}, DEX={self.dexterity}, "
+            f"CON={self.constitution}, INT={self.intelligence}, "
+            f"WIS={self.wisdom}, CHA={self.charisma}, "
+            f"HP={self.hit_points}, MP={self.mana_points}, "
+            f"DEF={self.defense}, RES={self.resistance})"
+        )