echoes-of-the-ash/docs/game/MECHANICS.md

# Game Mechanics Overview

## Core Systems

### 1. Health & Stamina System

#### Health Points (HP)
- **Purpose:** Measure of character's life force
- **Starting Value:** 100 HP
- **Range:** 0 to max_hp
- **Death:** Occurs when HP reaches 0
- **Regeneration:** Does not auto-regenerate (requires items or rest)
- **Display:** Visual bar with percentage
  ```
  ❤️ HP: ███████░░░ 70% (70/100)
  ```

#### Stamina
- **Purpose:** Resource for actions and movement
- **Starting Value:** 100 Stamina
- **Range:** 0 to max_stamina
- **Usage:**
  - Movement between locations (varies by distance and inventory weight)
  - Actions on interactables (searching, opening, etc.)
- **Regeneration:** Passive over time (1 + endurance/10 per cycle)
- **Display:** Visual bar with percentage
  ```
  ⚡ Stamina: █████░░░░░ 50% (50/100)
  ```

### 2. Character Progression

#### Experience (XP)
- **Gained From:**
  - Defeating enemies
  - Completing actions
  - Exploring new locations
- **Display:** Progress bar showing advancement to next level
  ```
  ⭐ XP: ████░░░░░░ 40% (240/600)
  ```

#### Leveling
- **Formula:** XP required = 100 * (level ^ 1.5)
- **Benefits:**
  - Stat point to allocate
  - Increased base damage
  - Access to new areas

#### Stats
- **Strength (💪)**
  - Increases melee damage
  - Formula: Base Damage = 5 + (strength / 2) + level
  
- **Agility (🏃)**
  - Increases flee chance in combat
  - Formula: Flee Chance = 50% + (agility / 100)
  
- **Endurance (💚)**
  - Increases max HP when leveled
  - Increases stamina regeneration
  - Formula: Stamina Regen = 1 + (endurance / 10)
  
- **Intellect (🧠)**
  - Reserved for future mechanics
  - May affect crafting, dialogue, etc.

#### Stat Points
- **Earned:** 1 point per level
- **Allocation Options:**
  - +10 Max HP
  - +5 Max Stamina
  - +1 Strength
  - +1 Agility
  - +1 Endurance
  - +1 Intellect

### 3. Inventory System

#### Capacity
- **Weight Limit:** 50 kg (base) + equipped backpack bonus
- **Volume Limit:** 100 vol (base) + equipped backpack bonus
- **Overencumbered:** Cannot pick up items when at capacity
- **Movement Penalty:** Higher inventory weight increases stamina cost for travel

#### Item Types
- **Weapons:** Equippable, adds damage
- **Armor:** Equippable, adds protection
- **Consumables:** Single-use, restores HP/Stamina
- **Tools:** Required for certain actions
- **Materials:** Crafting components (future)
- **Quest Items:** Special items for progression

#### Equipment Slots
- **Weapon:** Primary attack tool
- **Backpack:** Increases carrying capacity
- **Armor:** Protection (future implementation)

### 4. Combat System

#### Turn-Based Combat
- Player turn → NPC turn → Repeat until victory or defeat

#### Actions
- **Attack:** Deal damage to enemy
- **Flee:** Attempt to escape (chance-based)
- **Use Item:** Consume healing/buff items

#### Damage Calculation
```python
Base Damage = 5 + (strength / 2) + level
Weapon Damage = random(weapon_min, weapon_max)
Total Damage = Base Damage + Weapon Damage
```

#### Enemy Spawning
- **Static Spawns:** Fixed enemies at locations
- **Random Encounters:** Chance-based when moving
- **Wandering Enemies:** NPCs that patrol locations

#### Death & Respawn
- **Player Death:** Lose all inventory, respawn at start location
- **Corpses:** Player corpses can be looted by others (multiplayer aspect)
- **Enemy Death:** Drop loot, award XP

### 5. World Interaction

#### Locations
- **Types:** Safe zones, dangerous areas, dungeons
- **Connections:** Graph-based navigation
- **Images:** Visual representation of each location
- **Interactables:** Objects to search/interact with

#### Actions
- **Inspect Area:** View location details and items
- **Move:** Travel to connected locations
- **Search Objects:** Loot interactables for items
- **Attack Enemies:** Engage wandering NPCs

#### Cooldowns
- **Purpose:** Prevent infinite resource farming
- **Duration:** Varies by action (typically 5-30 minutes)
- **Per-Object:** Each interactable has independent cooldown

### 6. Item Collection

#### Dropped Items
- **Sources:**
  - Enemy loot
  - Interactable rewards
  - Player-dropped items
- **Pickup:** Choose quantity to take
- **Capacity Check:** Must have room in inventory

#### Looting
- **NPC Corpses:**
  - Requires tools for certain materials
  - Random quantities
  - Disappears when fully looted
  
- **Player Corpses:**
  - Contains all inventory from death
  - Can be looted by any player
  - Encourages retrieval runs

## Game Loop

### Basic Cycle
1. **Explore** → Move to new location
2. **Inspect** → Find interactables and enemies
3. **Action** → Search, fight, or collect
4. **Manage** → Organize inventory, use items
5. **Progress** → Gain XP, level up, allocate stats
6. **Repeat**

### Resource Management
- Monitor HP and Stamina
- Use consumables strategically
- Rest when needed
- Manage inventory weight

### Risk vs. Reward
- Dangerous areas have better loot
- Higher-level enemies give more XP
- Overextending can lead to death
- Strategic retreats preserve progress

## Progression Path

### Early Game (Levels 1-5)
- Learn basic mechanics
- Gather starting equipment
- Explore safe zones
- Build initial stats

### Mid Game (Levels 6-15)
- Venture into dangerous areas
- Face tougher enemies
- Collect better equipment
- Specialize character build

### Late Game (Levels 16+)
- Challenge end-game content
- Optimize builds
- Collect rare items
- Explore all areas

## Future Mechanics

### Planned Features
- **Crafting System:** Combine materials into items
- **Quests:** Story-driven objectives
- **Factions:** Reputation and alliances
- **Trading:** Player-to-player economy
- **Skills:** Special abilities beyond stats
- **Housing:** Personal storage and rest areas

---

**Last Updated:** October 19, 2025  
**Status:** Living document - Updated as mechanics evolve