# Echoes of the Ash 🌆

A dark fantasy post-apocalyptic survival RPG featuring exploration, combat, crafting, and scavenging in a ruined world.

## 🎮 Game Features

### Core Gameplay

#### 🗺️ Exploration & Movement
- **Grid-based world navigation** with coordinates (x, y)
- **Stamina-based movement system** - each move costs stamina based on distance
- **Multiple biomes and locations** with varying danger levels (0-4)
- **Dynamic location discovery** as you explore
- **Compass-based directional movement** (North, South, East, West)

#### ⚔️ Combat System
- **Turn-based combat** with real-time intent preview
- **NPC enemy encounters** with weighted spawn tables per location
- **Status effects system**: Bleeding, Infected, Radiation
- **Weapon effects**: Bleeding, Stun, Armor Break
- **Flee mechanics** - escape combat with success/failure chance
- **XP and leveling system** - gain XP from defeating enemies
- **PvP (Player vs Player) combat** - challenge other players
- **Death and respawn mechanics**

#### 🎒 Inventory & Equipment
- **Weight and volume-based inventory** system
- **Equipment slots**: Weapon, Backpack, Armor, Head, Tool
- **Durability system** - items degrade with use
- **Item tiers** (1-3) affecting quality and stats
- **Encumbrance system** - affects stamina costs
- **Ground item drops** - pick up and drop items

#### 🔨 Crafting & Repair
- **Crafting system** with material requirements
- **Tool requirements** for certain recipes
- **Repair mechanics** - restore item durability
- **Uncrafting/Disassembly** - break down items for materials
- **Workbench locations** for advanced crafting
- **Craft level requirements** - unlocked through progression

#### 🔍 Scavenging & Interactables
- **Searchable objects** in each location (dumpsters, cars, houses, etc.)
- **Action-based interaction** system with stamina costs
- **Success/failure mechanics** with critical outcomes
- **Loot tables** with item drop chances
- **One-time and respawning interactables**
- **Status tracking** per player (already looted, depleted, etc.)

#### 📊 Character Progression
- **Level system** (1-50+) with XP requirements
- **Stat points** - allocate to Strength, Defense, Stamina
- **Character customization** on creation
- **Skill progression** tied to crafting levels

#### 🌍 World Features
- **Multi-location world** (Downtown, Gas Station, Residential, Clinic, Plaza, Park, Warehouse, Office Buildings, Subway, etc.)
- **Location tags** - workbench, repair_station, safe_zone
- **Danger zones** with varying encounter rates
- **Location-specific loot** and enemy spawns

#### 💬 Social & Multiplayer
- **Online player tracking** via WebSockets
- **Real-time player position updates**
- **PvP combat system** with challenge mechanics
- **Character browsing** - see other players' stats

#### 🎨 PWA Features
- **Progressive Web App** - installable on mobile/desktop
- **Multi-language support** (English, Spanish)
- **Responsive UI** with mobile-first design
- **Real-time updates** via WebSockets
- **Offline capabilities** (service worker)

---

## 📁 Gamedata Structure

The game uses JSON files in the `gamedata/` directory to define all game content. This modular approach makes it easy to add new content without code changes.

### Directory Layout

```
gamedata/
├── npcs.json          # Enemy NPCs and combat encounters
├── items.json         # All items, weapons, consumables, and resources
├── locations.json     # World map locations and interactables
└── interactables.json # Interactable object templates
```

---

## 📋 `npcs.json` Structure

Defines all enemy NPCs, their stats, loot tables, and spawn locations.

### Top-Level Structure
```json
{
  "npcs": { ... },           // NPC definitions
  "danger_levels": { ... },  // Danger settings per location
  "spawn_tables": { ... }    // Enemy spawn weights per location
}
```

### NPC Definition
```json
"npc_id": {
  "npc_id": "unique_npc_identifier",
  "name": {
    "en": "English Name",
    "es": "Spanish Name"
  },
  "description": {
    "en": "English description",
    "es": "Spanish description"
  },
  "emoji": "🐕",
  "hp_min": 15,              // Minimum HP when spawned
  "hp_max": 25,              // Maximum HP when spawned
  "damage_min": 3,           // Minimum attack damage
  "damage_max": 7,           // Maximum attack damage
  "defense": 0,              // Damage reduction
  "xp_reward": 10,           // XP given on defeat
  "loot_table": [            // Items dropped on death (automatic)
    {
      "item_id": "raw_meat",
      "quantity_min": 1,
      "quantity_max": 2,
      "drop_chance": 0.6     // 60% chance to drop
    }
  ],
  "corpse_loot": [           // Items harvestable from corpse
    {
      "item_id": "animal_hide",
      "quantity_min": 1,
      "quantity_max": 1,
      "required_tool": "knife" // Tool needed to harvest (null = no requirement)
    }
  ],
  "flee_chance": 0.3,        // Chance NPC flees from combat
  "status_inflict_chance": 0.15, // Chance to inflict status effect on hit
  "image_path": "images/npcs/feral_dog.webp",
  "death_message": "The feral dog whimpers and collapses..."
}
```

### Danger Levels
```json
"location_id": {
  "danger_level": 2,         // 0-4 scale
  "encounter_rate": 0.2,     // 20% chance per movement
  "wandering_chance": 0.35   // 35% chance for random encounter while idle
}
```

### Spawn Tables
```json
"location_id": [
  {
    "npc_id": "raider_scout",
    "weight": 50             // Weighted random spawn (higher = more common)
  },
  {
    "npc_id": "infected_human",
    "weight": 30
  }
]
```

**Available NPCs:**
- `feral_dog` - Wild, hungry canine (Tier 1)
- `mutant_rat` - Radiation-mutated rodent (Tier 1)
- `raider_scout` - Hostile human raider (Tier 2)
- `scavenger` - Aggressive survivor (Tier 2)
- `infected_human` - Virus-infected zombie-like human (Tier 3)

---

## 🎒 `items.json` Structure

Defines all items, equipment, weapons, consumables, and crafting materials.

### Item Categories (Types)
- `resource` - Raw materials for crafting
- `consumable` - Food, medicine, usable items
- `weapon` - Melee and ranged weapons
- `backpack` - Inventory capacity upgrades
- `armor` - Protective equipment
- `tool` - Utility items (flashlight, etc.)
- `quest` - Story/quest items

### Basic Item Structure
```json
"item_id": {
  "name": {
    "en": "Item Name",
    "es": "Spanish Name"
  },
  "description": {
    "en": "Description text",
    "es": "Spanish description"
  },
  "type": "resource",
  "weight": 0.5,            // Kilograms
  "volume": 0.2,            // Liters
  "emoji": "⚙️",
  "image_path": "images/items/scrap_metal.webp"
}
```

### Consumable Items
```json
"item_id": {
  ...basic fields...,
  "type": "consumable",
  "hp_restore": 20,         // Health restored
  "stamina_restore": 10,    // Stamina restored
  "treats": "Bleeding"      // Status effect cured (optional)
}
```

### Weapon/Equipment Items
```json
"item_id": {
  ...basic fields...,
  "type": "weapon",
  "equippable": true,
  "slot": "weapon",         // Equipment slot: weapon, backpack, armor, head, tool
  "durability": 100,        // Max durability
  "tier": 2,                // 1-3 quality tier
  "encumbrance": 2,         // Stamina penalty when equipped
  "stats": {
    "damage_min": 5,
    "damage_max": 10,
    "weight_capacity": 20,  // For backpacks
    "volume_capacity": 20,
    "defense": 5            // For armor
  },
  "weapon_effects": {       // Status effects inflicted (optional)
    "bleeding": {
      "chance": 0.15,       // 15% chance on hit
      "damage": 2,          // Damage per turn
      "duration": 3         // Turns
    }
  }
}
```

### Craftable Items
```json
"item_id": {
  ...other fields...,
  "craftable": true,
  "craft_level": 2,         // Required crafting level
  "craft_materials": [
    {
      "item_id": "scrap_metal",
      "quantity": 3
    }
  ],
  "craft_tools": [          // Tools consumed during crafting
    {
      "item_id": "hammer",
      "durability_cost": 3  // Durability consumed
    }
  ]
}
```

### Repairable Items
```json
"item_id": {
  ...other fields...,
  "repairable": true,
  "repair_materials": [
    {
      "item_id": "scrap_metal",
      "quantity": 2
    }
  ],
  "repair_tools": [
    {
      "item_id": "hammer",
      "durability_cost": 2
    }
  ],
  "repair_percentage": 30   // % of max durability restored
}
```

### Uncraftable Items (Disassembly)
```json
"item_id": {
  ...other fields...,
  "uncraftable": true,
  "uncraft_yield": [        // Materials returned
    {
      "item_id": "scrap_metal",
      "quantity": 2
    }
  ],
  "uncraft_loss_chance": 0.25, // 25% chance to lose materials
  "uncraft_tools": [
    {
      "item_id": "hammer",
      "durability_cost": 1
    }
  ]
}
```

**Item Examples:**
- **Resources:** `scrap_metal`, `cloth_scraps`, `wood_planks`, `bone`, `raw_meat`
- **Consumables:** `canned_food`, `water_bottle`, `bandage`, `antibiotics`, `rad_pills`
- **Weapons:** `rusty_knife`, `knife`, `tire_iron`, `makeshift_spear`, `reinforced_bat`
- **Backpacks:** `tattered_rucksack`, `hiking_backpack`
- **Tools:** `flashlight`, `hammer`

---

## 🗺️ `locations.json` Structure

Defines the game world, all locations, coordinates, and interactable objects.

### Location Definition
```json
{
  "id": "location_id",
  "name": {
    "en": "🏚️ Location Name",
    "es": "Spanish Name"
  },
  "description": {
    "en": "Atmospheric description of the location...",
    "es": "Spanish description"
  },
  "image_path": "images/locations/location.webp",
  "x": 0,                   // Grid X coordinate
  "y": 2,                   // Grid Y coordinate
  "tags": [                 // Optional tags
    "workbench",            // Has crafting bench
    "repair_station",        // Can repair items
    "safe_zone"             // No random encounters
  ],
  "interactables": { ... }  // Interactable objects at this location
}
```

### Interactable Object Instance
```json
"unique_interactable_id": {
  "template_id": "dumpster",  // References interactables.json
  "outcomes": {
    "action_id": {
      "stamina_cost": 2,
      "success_rate": 0.5,      // 50% base success chance
      "crit_success_chance": 0.1, // 10% chance for critical success
      "crit_failure_chance": 0.1, // 10% chance for critical failure
      "rewards": {
        "damage": 0,            // Damage on normal failure
        "crit_damage": 8,       // Damage on critical failure
        "items": [              // Items on normal success
          {
            "item_id": "plastic_bottles",
            "quantity": 3,
            "chance": 1.0       // 100% drop rate
          }
        ],
        "crit_items": [         // Items on critical success
          {
            "item_id": "rare_item",
            "quantity": 1,
            "chance": 0.5
          }
        ]
      },
      "text": {                 // Locale-specific text responses
        "success": {
          "en": "You find something useful!",
          "es": "¡Encuentras algo útil!"
        },
        "failure": {
          "en": "Nothing here.",
          "es": "Nada aquí."
        },
        "crit_success": { ... },
        "crit_failure": { ... }
      }
    }
  }
}
```

**Available Locations:**
- `start_point` - Ruined Downtown Core (0, 0) - Starting location
- `gas_station` - Abandoned Gas Station (0, 2) - Has workbench
- `residential` - Residential Street (3, 0)
- `clinic` - Old Clinic (2, 3) - Medical supplies
- `plaza` - Shopping Plaza (-2.5, 0)
- `park` - Suburban Park (-1, -2)
- `overpass` - Highway Overpass (1.0, 4.5)
- `warehouse` - Warehouse District
- `office_building` - Office Tower
- `subway` - Subway Station

---

## 🔍 `interactables.json` Structure

Defines templates for interactable objects that can be placed in locations.

### Interactable Template
```json
"template_id": {
  "id": "template_id",
  "name": {
    "en": "🗑️ Object Name",
    "es": "Spanish Name"
  },
  "description": {
    "en": "Object description",
    "es": "Spanish description"
  },
  "image_path": "images/interactables/object.webp",
  "actions": {              // Available actions for this object
    "action_id": {
      "id": "action_id",
      "label": {
        "en": "🔎 Action Label",
        "es": "Spanish Label"
      },
      "stamina_cost": 2     // Base stamina cost (can be overridden in locations)
    }
  }
}
```

**Available Interactable Templates:**
- `rubble` - Pile of debris (Action: search)
- `dumpster` - Trash container (Action: search_dumpster)
- `sedan` - Abandoned car (Actions: search_glovebox, pop_trunk)
- `house` - Abandoned house (Action: search_house)
- `toolshed` - Tool shed (Action: search_shed)
- `medkit` - Medical supply cabinet (Action: search_medkit)
- `storage_box` - Storage container (Action: search)
- `vending_machine` - Vending machine (Actions: break, search)

---

## 🛠️ Replicating Gamedata

### Adding a New NPC

1. **Create NPC definition** in `npcs.json` under `"npcs"`:
```json
"my_new_npc": {
  "npc_id": "my_new_npc",
  "name": { "en": "My NPC", "es": "Mi NPC" },
  "description": { "en": "Description", "es": "Descripción" },
  "emoji": "👹",
  "hp_min": 20, "hp_max": 30,
  "damage_min": 4, "damage_max": 8,
  "defense": 1,
  "xp_reward": 15,
  "loot_table": [...],
  "corpse_loot": [...],
  "flee_chance": 0.2,
  "status_inflict_chance": 0.1,
  "image_path": "images/npcs/my_new_npc.webp",
  "death_message": "The creature falls..."
}
```

2. **Add to spawn table** in `npcs.json` under `"spawn_tables"`:
```json
"location_id": [
  { "npc_id": "my_new_npc", "weight": 40 }
]
```

3. **Add image** at `images/npcs/my_new_npc.webp`

### Adding a New Item

1. **Create item definition** in `items.json`:
```json
"my_new_item": {
  "name": { "en": "My Item", "es": "Mi Objeto" },
  "description": { "en": "Description", "es": "Descripción" },
  "type": "resource",
  "weight": 1.0,
  "volume": 0.5,
  "emoji": "🔮",
  "image_path": "images/items/my_new_item.webp"
}
```

2. **Add to loot tables** (optional) in locations or NPCs

3. **Add image** at `images/items/my_new_item.webp`

### Adding a New Location

1. **Create location** in `locations.json`:
```json
{
  "id": "my_location",
  "name": { "en": "🏭 My Location", "es": "Mi Ubicación" },
  "description": { "en": "Description", "es": "Descripción" },
  "image_path": "images/locations/my_location.webp",
  "x": 5,
  "y": 3,
  "tags": ["workbench"],
  "interactables": {
    "my_location_box": {
      "template_id": "storage_box",
      "outcomes": {
        "search": { ...outcome definition... }
      }
    }
  }
}
```

2. **Add danger level** in `npcs.json`:
```json
"my_location": {
  "danger_level": 2,
  "encounter_rate": 0.15,
  "wandering_chance": 0.3
}
```

3. **Add spawn table** in `npcs.json`:
```json
"my_location": [
  { "npc_id": "raider_scout", "weight": 60 },
  { "npc_id": "mutant_rat", "weight": 40 }
]
```

4. **Add image** at `images/locations/my_location.webp`

### Adding a New Interactable Template

1. **Create template** in `interactables.json`:
```json
"my_interactable": {
  "id": "my_interactable",
  "name": { "en": "🎰 My Object", "es": "Mi Objeto" },
  "description": { "en": "Description", "es": "Descripción" },
  "image_path": "images/interactables/my_object.webp",
  "actions": {
    "my_action": {
      "id": "my_action",
      "label": { "en": "🔨 Do Action", "es": "Hacer Acción" },
      "stamina_cost": 3
    }
  }
}
```

2. **Use in locations** in `locations.json` interactables

3. **Add image** at `images/interactables/my_object.webp`

---

## 🎯 Key Game Mechanics

### Stamina System
- Base stamina pool (increases with Stamina stat)
- Regenerates passively over time
- Consumed by: Movement, Combat Actions, Interactions, Crafting
- Encumbrance from equipment increases stamina costs

### Combat Flow
1. Player or NPC initiates combat
2. Turn-based with initiative system
3. NPCs show **intent preview** (next planned action)
4. Player chooses: Attack, Defend, Use Item, Flee
5. Status effects tick each turn
6. Combat ends on death or successful flee

### Loot System
- **Immediate drops** from loot_table (on death)
- **Corpse harvesting** from corpse_loot (requires tools)
- **Interactable loot** with success/failure mechanics
- **Respawn timers** for interactables

### Crafting Requirements
- Sufficient materials in inventory
- Required tools with durability
- Crafting level unlocked
- Optional: Workbench location tag

---

## 📚 Additional Documentation

- **[CLAUDE.md](./CLAUDE.md)** - Project structure and development commands
- **[QUICK_REFERENCE.md](./QUICK_REFERENCE.md)** - API endpoints and architecture
- **[docker-compose.yml](./docker-compose.yml)** - Infrastructure setup

---

## 🚀 Quick Start

```bash
# Start the game
docker compose up -d

# View API logs
docker compose logs -f echoes_of_the_ashes_api

# Rebuild after changes
docker compose build && docker compose up -d
```

Game runs at: `http://localhost` (PWA) and `http://localhost/api` (API)

---

## 📝 License

All rights reserved. Post-apocalyptic survival simulation for educational purposes.