echoes-of-the-ash/README.md

Echoes of the Ash

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

🎮 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)

docker compose up echoes_of_the_ashes_pwa echoes_of_the_ashes_api

Electron Development

cd pwa
npm install
npm run electron:dev

Build Electron Apps

npm run electron:build:win    # Windows
npm run electron:build:linux  # Linux
npm run electron:build:mac    # macOS

---

📝 Additional Documentation

• Game Mechanics - Detailed gameplay systems
• API Documentation - Backend endpoints reference
• Development Guide - Contributing and architecture
• Map Editor - World building tools

---

Version: 1.0.0-alpha
Last Updated: December 2025