echoes-of-the-ash/README.md

Echoes of the Ashes

A post-apocalyptic survival RPG available on Telegram and Web, featuring turn-based exploration, resource management, and a persistent world.

🌐 Play Now

• Telegram Bot: @your_bot_username
• Web/Mobile: echoesoftheashgame.patacuack.net

🎮 Features

Core Gameplay

• 🗺️ Exploration: Navigate through 7 interconnected locations
• 👀 Interact: Search and interact with 24+ unique objects
• 🎒 Inventory: Collect, use, and manage 28 different items
• ⚡️ Stamina System: Actions require stamina management with automatic regeneration
• ❤️ Survival: Heal using consumables, avoid damage
• 🔄 Cooldowns: Per-action cooldown system prevents spam
• ♻️ Auto-Recovery: Stamina regenerates over time (1+ per 5 minutes based on endurance)

Visual Experience

• 📸 Location Images: Every location has a unique image
• 🖼️ Smart Caching: Images cached in database for instant loading
• ✨ Smooth Transitions: Uses edit_message_media for seamless navigation
• 🧭 Context-Aware: Location images persist across menus

Game World

• 7 Locations: Downtown, Gas Station, Residential, Clinic, Plaza, Park, Overpass
• 5 Interactable Types: Rubble, Sedans, Houses, Medical Cabinets, Tool Sheds, Dumpsters, Vending Machines
• 28 Items: Resources, consumables, weapons, equipment, quest items
• Risk vs Reward: Higher risk actions can cause damage but yield better loot

🚀 Quick Start

Telegram Bot

1. Get a Bot Token from @BotFather
2. Create .env file with your credentials
3. Run docker-compose up -d --build
4. Find your bot and send /start

See Installation Guide for detailed instructions.

Progressive Web App (PWA)

1. Run ./setup_pwa.sh to set up the web version
2. Open echoesoftheashgame.patacuack.net
3. Register an account and play!

See PWA_QUICKSTART.md for detailed instructions.

📱 Platform Features

Telegram Bot

• 🤖 Native Telegram integration
• 🔔 Instant push notifications
• 💬 Chat-based gameplay
• 👥 Easy sharing with friends

Web/Mobile PWA

• 🌐 Play in any browser
• 📱 Install as mobile app
• 🎨 Modern responsive UI
• 🔐 Separate authentication
• ⚡ Offline support (coming soon)
• 🔔 Web push notifications (coming soon)

🛠️ Installation

Prerequisites

• Docker and Docker Compose
• For Telegram: Bot Token from @BotFather
• For PWA: Node.js 20+ (for development)

Basic Setup

1. Clone the repository:

cd /opt/dockers/echoes_of_the_ashes

2. Create .env file:

TELEGRAM_BOT_TOKEN=your_bot_token_here
DATABASE_URL=postgresql+psycopg://user:password@echoes_of_the_ashes_db:5432/telegram_rpg
POSTGRES_USER=user
POSTGRES_PASSWORD=password
POSTGRES_DB=telegram_rpg
JWT_SECRET_KEY=generate-with-openssl-rand-hex-32

3. Start services:

# Telegram bot only
docker-compose up -d --build

# With PWA (web version)
./setup_pwa.sh

4. Check logs:

docker logs echoes_of_the_ashes_bot -f
docker logs echoes_of_the_ashes_api -f
docker logs echoes_of_the_ashes_pwa -f

🎯 How to Play

Basic Commands

• /start - Start your journey or return to main menu

Main Menu

• 🗺️ Move - Travel to connected locations
• 👀 Inspect Area - View and interact with objects
• 👤 Profile - View your character stats
• 🎒 Inventory - Manage your items

Actions

• Search/Loot - Find items in the environment (costs stamina)
• Use Items - Consume food/medicine to restore HP/stamina
• Drop Items - Leave items at current location
• Pick Up - Collect items from the ground

Stats

• HP: Health Points (die at 0)
• Stamina: Required for actions (regenerates over time)
• Weight/Volume: Inventory capacity limits

🗺️ World Map

        🛣️ Highway Overpass
             |
    🏥 Clinic --- ⛽️ Gas Station
         |            |
    🏘️ Residential --- 🌆 Downtown --- 🏬 Plaza
         |                                |
         +------------ 🌳 Park ------------+

📦 Items

Consumables

Item	Effect	Emoji
First Aid Kit	+50 HP	🩹
Mystery Pills	+30 HP	💊
Canned Beans	+20 HP, +5 Stamina	🥫
Energy Bar	+15 Stamina	🍫
Bottled Water	+10 Stamina	💧

Resources

• ⚙️ Scrap Metal
• 🪵 Wood Planks
• 📌 Rusty Nails
• 🧵 Cloth Scraps
• 🍶 Plastic Bottles

Equipment

• 🎒 Hiking Backpack (+20 capacity)
• 🔦 Flashlight
• 🔧 Tire Iron
• ⚾ Baseball Bat

🏗️ Architecture

Tech Stack

• Language: Python 3.11
• Bot Framework: python-telegram-bot 21.0.1
• Database: PostgreSQL 15 (async with SQLAlchemy)
• Deployment: Docker Compose
• Scheduler: APScheduler (for stamina regeneration)

Project Structure

telegram-rpg/
├── bot/
│   ├── database.py      # Database operations
│   ├── handlers.py      # Telegram event handlers
│   ├── keyboards.py     # Inline keyboard layouts
│   └── logic.py         # Game logic
├── data/
│   ├── items.py         # Item definitions
│   ├── models.py        # Game world models
│   └── world_loader.py  # World construction
├── docs/                # Comprehensive documentation
├── images/              # Location and interactable images
├── main.py             # Entry point
└── docker-compose.yml  # Container orchestration

Database Schema

• players: Character stats and state
• inventory: Player item storage
• dropped_items: World item storage
• cooldowns: Per-action cooldown tracking
• image_cache: Telegram file_id caching

📚 Documentation

Detailed documentation in docs/:

• INVENTORY_USE.md - Item usage system
• EXPANDED_WORLD.md - All locations and items
• WORLD_MAP.md - Map visualization and strategy
• IMAGE_SYSTEM.md - Image caching implementation
• UX_IMPROVEMENTS.md - Clean chat mechanics
• ACTION_FEEDBACK.md - Action result display
• SMOOTH_TRANSITIONS.md - Message editing system
• UPDATE_SUMMARY.md - Latest changes

🎨 Adding Content

New Item

Edit data/items.py:

"new_item": {
    "name": "New Item",
    "weight": 1.0,
    "volume": 0.5,
    "type": "consumable",
    "effects": {"hp": 20},
    "emoji": "🎁"
}

New Interactable

Edit data/world_loader.py:

NEW_TEMPLATE = Interactable(
    id="new_object",
    name="New Object",
    image_path="images/interactables/new.png"
)
action = Action(id="search", label="🔎 Search", stamina_cost=2)
action.add_outcome("success", Outcome(
    text="You find something!",
    items_reward={"new_item": 1}
))
NEW_TEMPLATE.add_action(action)

New Location

new_location = Location(
    id="new_place",
    name="🏛️ New Place",
    description="Description here",
    image_path="images/locations/new_place.png"
)
new_location.add_interactable("new_place_object", NEW_TEMPLATE)
new_location.add_exit("north", "other_location")
world.add_location(new_location)

🔧 Development

Local Development

# Install dependencies
pip install -r requirements.txt

# Run bot
python main.py

Database Management

# Access database
docker exec -it echoes_of_the_ashes_db psql -U user -d telegram_rpg

# Backup database
docker exec echoes_of_the_ashes_db pg_dump -U user telegram_rpg > backup.sql

# Restore database
docker exec -i echoes_of_the_ashes_db psql -U user telegram_rpg < backup.sql

Logs

# Follow bot logs
docker logs echoes_of_the_ashes_bot -f

# Database logs
docker logs echoes_of_the_ashes_db -f

🎲 Game Mechanics

Outcome Probability

• Critical Failure: Rare, negative effects
• Failure: Common, no reward
• Success: Common, standard rewards

Configured in bot/logic.py:

def roll_outcome(action: Action):
    roll = random.random()
    if roll < 0.1: return "critical_failure"
    elif roll < 0.5: return "failure"
    else: return "success"

Stamina Regeneration

• Rate: 1 stamina per 5 minutes
• Maximum: Defined by player stats
• Automatic: Background scheduler

Cooldowns

• Per-Action: Each action has independent cooldown
• Duration: Configured per action (30-60 minutes typical)
• Storage: Composite key instance_id:action_id

🚧 Future Plans

Planned Features

• Combat system
• Crafting mechanics
• Quest system
• NPC interactions
• Base building
• Equipment slots
• Status effects
• Day/night cycle
• Weather system
• Trading economy

Balance Improvements

• Dynamic difficulty
• Rare item spawns
• Location-based dangers
• Resource scarcity tuning

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📝 License

This project is open source and available under the MIT License.

🙏 Acknowledgments

• Built with python-telegram-bot
• Inspired by classic post-apocalyptic RPGs
• Community feedback and testing

📞 Support

For issues or questions:

• Open a GitHub issue
• Check the documentation in docs/
• Review error logs with docker logs

---

Current Version: 1.1.0 (Expanded World Update) Last Updated: October 16, 2025 Status: ✅ Active Development