Push
This commit is contained in:
Joan
729
README.md
729
README.md
@@ -1,627 +1,188 @@
|
||||
# Echoes of the Ash 🌆
|
||||
# Echoes of the Ash
|
||||
|
||||
A dark fantasy post-apocalyptic survival RPG featuring exploration, combat, crafting, and scavenging in a ruined world.
|
||||
> A post-apocalyptic survival RPG - Browser-based MUD-style game
|
||||
|
||||
## 🎮 Game Features
|
||||
|
||||
|
||||
|
||||
|
||||
### Core Gameplay
|
||||
## 🎮 What is Echoes of the Ash?
|
||||
|
||||
#### 🗺️ 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)
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 📁 Gamedata Structure
|
||||
## 🌟 Current Game Features
|
||||
|
||||
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.
|
||||
### Core Systems
|
||||
|
||||
### Directory Layout
|
||||
| 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 |
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
### 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 |
|
||||
|
||||
---
|
||||
|
||||
## 📋 `npcs.json` Structure
|
||||
## 🎯 What Can Players Do?
|
||||
|
||||
Defines all enemy NPCs, their stats, loot tables, and spawn locations.
|
||||
### 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
|
||||
|
||||
### Top-Level Structure
|
||||
```json
|
||||
{
|
||||
"npcs": { ... }, // NPC definitions
|
||||
"danger_levels": { ... }, // Danger settings per location
|
||||
"spawn_tables": { ... } // Enemy spawn weights per 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
|
||||
|
||||
### 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..."
|
||||
}
|
||||
```
|
||||
### 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
|
||||
|
||||
### 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)
|
||||
### Character Progression
|
||||
- **4 Core Stats**: Strength, Agility, Endurance, Intellect
|
||||
- **Equipment**: Weapons, armor, backpacks
|
||||
- **Stat Points**: Earn 1 per level to customize your build
|
||||
|
||||
---
|
||||
|
||||
## 🎒 `items.json` Structure
|
||||
## 🛠️ Technical Stack
|
||||
|
||||
Defines all items, equipment, weapons, consumables, and crafting materials.
|
||||
### Frontend (PWA)
|
||||
- **Framework**: React 18 + TypeScript
|
||||
- **Build Tool**: Vite
|
||||
- **State Management**: Zustand
|
||||
- **Real-time**: WebSocket connections
|
||||
- **Styling**: Custom CSS with dark theme
|
||||
|
||||
### 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
|
||||
### Backend (API)
|
||||
- **Framework**: FastAPI (Python)
|
||||
- **Database**: SQLite (development) / PostgreSQL (production)
|
||||
- **Cache**: Redis for real-time state
|
||||
- **Auth**: JWT tokens
|
||||
|
||||
### 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`
|
||||
### Desktop (Electron)
|
||||
- **Framework**: Electron 28
|
||||
- **Steam SDK**: steamworks.js integration
|
||||
- **Builds**: Windows (NSIS, Portable), Linux (AppImage, DEB), macOS
|
||||
|
||||
---
|
||||
|
||||
## 🗺️ `locations.json` Structure
|
||||
## 📊 Asset Summary
|
||||
|
||||
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
|
||||
| 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 |
|
||||
|
||||
---
|
||||
|
||||
## 🔍 `interactables.json` Structure
|
||||
## 🗺️ Roadmap
|
||||
|
||||
Defines templates for interactable objects that can be placed in locations.
|
||||
### In Progress
|
||||
- [ ] Sound effects and ambient music
|
||||
- [ ] Quest/mission system
|
||||
- [ ] NPC dialogue trees
|
||||
|
||||
### 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)
|
||||
### 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
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 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
|
||||
## 🚀 Running the Game
|
||||
|
||||
### Web/PWA (Docker)
|
||||
```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
|
||||
docker compose up echoes_of_the_ashes_pwa echoes_of_the_ashes_api
|
||||
```
|
||||
|
||||
Game runs at: `http://localhost` (PWA) and `http://localhost/api` (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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 License
|
||||
## 📝 Additional Documentation
|
||||
|
||||
All rights reserved. Post-apocalyptic survival simulation for educational purposes.
|
||||
- [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
|
||||
|
||||
Reference in New Issue
Block a user