# Echoes of the Ash

> A post-apocalyptic survival RPG - Browser-based MUD-style game

![Status](https://img.shields.io/badge/Status-In%20Development-yellow)
![Platform](https://img.shields.io/badge/Platform-Web%20%7C%20PWA%20%7C%20Electron%20%7C%20Steam-blue)
![License](https://img.shields.io/badge/License-Proprietary-red)

## 🎮 What is Echoes of the Ash?

Echoes of the Ash is a **browser-based RPG** set in a dark, post-apocalyptic world. Inspired by classic MUD (Multi-User Dungeon) games, it combines text-driven exploration with visual elements, real-time combat, and survival mechanics.

---

## 🌟 Current Game Features

### Core Systems

| Feature | Status | Description |
|---------|--------|-------------|
| **Character System** | ✅ Complete | Create characters with 4 stats (Strength, Agility, Endurance, Intellect) |
| **Health & Stamina** | ✅ Complete | HP/Stamina management with visual progress bars |
| **Leveling & XP** | ✅ Complete | XP-based progression with stat point allocation |
| **Inventory** | ✅ Complete | Weight/volume-based carrying capacity |
| **Equipment** | ✅ Complete | Weapon, armor, and backpack slots |
| **Combat (PvE)** | ✅ Complete | Turn-based combat with visual effects |
| **Combat (PvP)** | ✅ Complete | Player vs Player combat system |
| **Real-time Updates** | ✅ Complete | WebSocket-based live game state |

### Exploration & Interaction

| Feature | Status | Description |
|---------|--------|-------------|
| **World Map** | ✅ Complete | Graph-based location system with connections |
| **Movement** | ✅ Complete | Navigate between connected locations |
| **Interactables** | ✅ Complete | Search containers, objects for loot |
| **Enemy Spawning** | ✅ Complete | Static and wandering NPCs |
| **Corpse Looting** | ✅ Complete | Loot fallen enemies and players |
| **Dropped Items** | ✅ Complete | Pick up items on the ground |

### Crafting & Economy

| Feature | Status | Description |
|---------|--------|-------------|
| **Workbench** | ✅ Complete | Craft, repair, and salvage items |
| **Crafting System** | ✅ Complete | Create items from materials |
| **Repair System** | ✅ Complete | Restore durability to equipment |
| **Salvage System** | ✅ Complete | Break down items for materials |

### Social & Multiplayer

| Feature | Status | Description |
|---------|--------|-------------|
| **Accounts** | ✅ Complete | Registration, login, JWT authentication |
| **Multiple Characters** | ✅ Complete | Create up to 3 characters per account |
| **Leaderboards** | ✅ Complete | Rankings by level, kills, XP |
| **Player Profiles** | ✅ Complete | View player stats and equipment |
| **Online Players** | ✅ Complete | See who's currently online |

### Platforms

| Platform | Status | Description |
|----------|--------|-------------|
| **Web Browser** | ✅ Complete | Play at any time via modern browser |
| **PWA (Mobile)** | ✅ Complete | Install as app on mobile devices |
| **Electron Desktop** | ✅ Complete | Standalone Windows/Mac/Linux app |
| **Steam Integration** | 🔧 Setup | Steamworks SDK ready for deployment |

---

## 🎯 What Can Players Do?

### Getting Started
1. **Create an Account** - Register with username and password
2. **Create a Character** - Name your survivor and choose starting stats
3. **Enter the World** - Spawn at the starting location

### Gameplay Loop
1. **Explore** - Move between connected locations to discover new areas
2. **Scavenge** - Search containers, corpses, and interactables for supplies
3. **Fight** - Engage hostile NPCs in turn-based combat
4. **Craft** - Use workbenches to create, repair, or salvage items
5. **Level Up** - Gain XP from combat and allocate stat points
6. **Survive** - Manage HP, stamina, and inventory weight

### Combat
- **Attack** enemies with equipped weapons
- **Use Items** during battle (healing, buffs)
- **Flee** when outmatched (success based on Agility)
- **PvP** - Challenge other players in combat

### Character Progression
- **4 Core Stats**: Strength, Agility, Endurance, Intellect
- **Equipment**: Weapons, armor, backpacks
- **Stat Points**: Earn 1 per level to customize your build

---

## 🛠️ Technical Stack

### Frontend (PWA)
- **Framework**: React 18 + TypeScript
- **Build Tool**: Vite
- **State Management**: Zustand
- **Real-time**: WebSocket connections
- **Styling**: Custom CSS with dark theme

### Backend (API)
- **Framework**: FastAPI (Python)
- **Database**: SQLite (development) / PostgreSQL (production)
- **Cache**: Redis for real-time state
- **Auth**: JWT tokens

### Desktop (Electron)
- **Framework**: Electron 28
- **Steam SDK**: steamworks.js integration
- **Builds**: Windows (NSIS, Portable), Linux (AppImage, DEB), macOS

---

## 📊 Asset Summary

| Category | Count | Size |
|----------|-------|------|
| Location Images | 14 | - |
| Item Images | 40 | - |
| NPC Images | 5 | - |
| Interactable Images | 8 | - |
| Icon Sets | 1 | - |
| **Total Images** | **134 files** | **~79 MB** |
| Sound Effects | 0 | 0 |
| Music | 0 | 0 |

---

## 🗺️ Roadmap

### In Progress
- [ ] Sound effects and ambient music
- [ ] Quest/mission system
- [ ] NPC dialogue trees

### Planned Features
- [ ] Crafting recipes expansion
- [ ] Faction/reputation system
- [ ] Player trading
- [ ] Housing/storage
- [ ] Skill tree system
- [ ] Status effects (poison, bleeding, etc.)
- [ ] Weather/day-night cycle
- [ ] Achievements

---

## 🚀 Running the Game

### Web/PWA (Docker)
```bash
docker compose up echoes_of_the_ashes_pwa echoes_of_the_ashes_api
```

### Electron Development
```bash
cd pwa
npm install
npm run electron:dev
```

### Build Electron Apps
```bash
npm run electron:build:win    # Windows
npm run electron:build:linux  # Linux
npm run electron:build:mac    # macOS
```

---

## 📝 Additional Documentation

- [Game Mechanics](docs/game/MECHANICS.md) - Detailed gameplay systems
- [API Documentation](docs/api/) - Backend endpoints reference
- [Development Guide](docs/development/) - Contributing and architecture
- [Map Editor](web-map/README.md) - World building tools

---

**Version**: 1.0.0-alpha  
**Last Updated**: December 2025