Fix TypeScript build errors
This commit is contained in:
Joan
371
README.md
371
README.md
@@ -1,371 +0,0 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user