My Settlement (Моё Поселение)

English | Русский

A feature-rich text-based MMORPG for Telegram group chats. Built with Python, Aiogram 3, and SQLAlchemy.

🏰 About The Project

My Settlement is a chat-based RPG where group members build their own settlement together. The bot analyzes chat activity to generate resources, while users can choose professions, play mini-games, and construct buildings.

This is not just a simple bot; it features a custom Game Engine that handles multi-step workflows, QTE events, and state management.

✨ Key Features

• Modular Game Engine: Custom OOP-based system for handling interactive steps (Harvesting, Hitting, QTEs).
• Economy System: Resources, currency, crafting, and trading.
• Professions: 5 unique classes (Farmer, Healer, Hunter, etc.) with specific abilities.
• Activity Tracking: Intelligent text analysis (using wordfreq & langdetect) to reward meaningful conversations.
• Building System: Construct town and personal buildings to gain bonuses.
• Async Database: Fully asynchronous operations using SQLAlchemy and PostgreSQL.

🛠️ Tech Stack

• Framework: Aiogram 3.x
• Database: PostgreSQL + SQLAlchemy (Async)
• Validation: Pydantic
• Text Analysis: wordfreq, langdetect, rapidfuzz

🚀 Quick Start

Prerequisites

• Python 3.11+
• uv
• PostgreSQL OR Docker (optional)

Local Installation

# 1. Clone the repository
git clone [https://github.com/mysettlement/my_settlement.git](https://github.com/mysettlement/my_settlement.git)
cd my_settlement

# 2. Sync dependencies and create .venv
uv sync --locked

Configuration

Create a .env file in the root directory:

BOT_TOKEN=your_telegram_bot_token
DB_URL=postgresql+asyncpg://user:password@localhost/dbname
DEVELOPER_IDS=[1234567890, 0987654321]
DEBUG=True

Running

uv run python -m main

Admin Panel

uv run python admin-entrypoint.py

🐳 Docker Support

You can easily run the bot using Docker Compose:

# Available profiles: main, admin, tools
docker-compose up --profile main -d --build

🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests.

📝 License

GNUv3 - see LICENSE for more information.

👤 Author

Created with ❤️ by megatocha

⭐ Add a star to my project!