372 lines
9.9 KiB
Markdown
372 lines
9.9 KiB
Markdown
# 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](https://t.me/your_bot_username)
|
|
- **Web/Mobile**: [echoesoftheashgame.patacuack.net](https://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](https://t.me/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](#installation) for detailed instructions.
|
|
|
|
### Progressive Web App (PWA)
|
|
|
|
1. Run `./setup_pwa.sh` to set up the web version
|
|
2. Open [echoesoftheashgame.patacuack.net](https://echoesoftheashgame.patacuack.net)
|
|
3. Register an account and play!
|
|
|
|
See [PWA_QUICKSTART.md](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](https://t.me/botfather)
|
|
- For PWA: Node.js 20+ (for development)
|
|
|
|
### Basic Setup
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
cd /opt/dockers/echoes_of_the_ashes
|
|
```
|
|
|
|
2. Create `.env` file:
|
|
```env
|
|
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:
|
|
```bash
|
|
# Telegram bot only
|
|
docker-compose up -d --build
|
|
|
|
# With PWA (web version)
|
|
./setup_pwa.sh
|
|
```
|
|
|
|
4. Check logs:
|
|
```bash
|
|
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`:
|
|
```python
|
|
"new_item": {
|
|
"name": "New Item",
|
|
"weight": 1.0,
|
|
"volume": 0.5,
|
|
"type": "consumable",
|
|
"effects": {"hp": 20},
|
|
"emoji": "🎁"
|
|
}
|
|
```
|
|
|
|
### New Interactable
|
|
Edit `data/world_loader.py`:
|
|
```python
|
|
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
|
|
```python
|
|
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
|
|
```bash
|
|
# Install dependencies
|
|
pip install -r requirements.txt
|
|
|
|
# Run bot
|
|
python main.py
|
|
```
|
|
|
|
### Database Management
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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`:
|
|
```python
|
|
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](https://python-telegram-bot.org/)
|
|
- 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
|