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

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