A simple Telegram bot that offers a text-based adventure game experience. Players make choices by clicking on buttons, navigating through different story paths. Easily customizable and extensible to create your own unique adventures.
- Features
- Prerequisites
- Installation
- Configuration
- Running the Bot
- Usage
- Customization
- Ideas for Improvement
- Interactive Storytelling: Navigate through the adventure by making choices via Telegram buttons.
- Customizable Storyline: Easily modify the story through a JSON file.
- User-Friendly Commands:
/start
- Begin the game/restart
- Restart the game from the beginning/back
- Go back one step in the story
- State Management: Keeps track of user progress, allowing players to restart or backtrack.
- Logging: Logs user interactions for monitoring and debugging.
- Extensible: Designed to be easily expanded with additional features like multi-language support or dynamic content.
- Python: Version 3.6 or higher
- Telegram Account: To interact with the bot
- Telegram Bot Token: Obtainable from BotFather
git clone https://github.com/yourusername/telegram-text-adventure-bot.git
cd telegram-text-adventure-bot
It's recommended to use a virtual environment to manage dependencies:
python3 -m venv venv
source venv/bin/activate # On Windows use `venv\Scripts\activate`
Install the required Python packages using pip:
pip install -r requirements.txt
Open the config.py
file in the project root directory and set up the token, admin_id for logging and logging level.
BOT_TOKEN = 'BOT_TOKEN'
ADMIN_ID = 'ADMIN_TELEGRAM_ID'
# Set the logging level:
# 0 - No logging
# 1 - Log only start and end messages (with user ID and username)
# 2 - Log every user response (with user ID and username)
LOGGING_LEVEL = 1
Ensure that the texts.json
file is present in the project directory. This file contains the game's storyline and choices. An example structure:
{
"start": {
"text": "Welcome to the adventure! Do you go left or right?",
"buttons": {
"Left": "left_path",
"Right": "right_path"
}
},
"left_path": {
"text": "You took the left path and encountered a river. Do you swim across or build a raft?",
"buttons": {
"Swim": "swim_river",
"Build": "build_raft"
}
},
"right_path": {
"text": "You took the right path and found a treasure chest. Do you open it or leave it?",
"buttons": {
"Open": "open_chest",
"Leave": "leave_chest"
}
}
// Add more states as needed
}
Start the bot by running the following command:
python main.py
The bot will begin polling for messages. Ensure that the texts.json
and config.py
files are correctly set up before running.
Interact with your bot on Telegram using the following commands:
/start
- Begin the game/restart
- Restart the game from the beginning/back
- Go back one step in the story/stop
- (Optional) Gracefully stop the bot (requires implementation)
- User:
/start
- Bot: "Welcome to the adventure! Do you go left or right?" with "Left" and "Right" buttons.
- User: Clicks "Left"
- Bot: "You took the left path and encountered a river. Do you swim across or build a raft?" with "Swim" and "Build" buttons.
And so on...
The game's story is stored in texts.json
. You can modify this file to create your own narrative. The structure for each state is as follows:
"state_name": {
"text": "The narrative text displayed to the player at this state.",
"buttons": {
"Button Label": "next_state_name"
}
}
- state_name: A unique identifier for each state in the game.
- text: The message displayed to the player.
- buttons: A dictionary where each key is the label of a button, and the value is the
state_name
it leads to.
- Define a New State: Add a new entry in
texts.json
:
"new_state": {
"text": "Your new story segment here.",
"buttons": {
"Choice 1": "next_state_1",
"Choice 2": "next_state_2"
}
}
- Reference the New State: In an existing state, add a button that points to the new state:
"existing_state": {
"text": "Existing story text.",
"buttons": {
"New Choice": "new_state",
// Other choices
}
}
To support multiple languages:
- Create Separate JSON Files: For each language, create a separate JSON file (e.g.,
texts_en.json
,texts_es.json
). - Load Based on User Preference: Modify the bot to detect or allow users to select their preferred language and load the corresponding JSON file.
Consider implementing the following features to improve the bot:
- State Persistence: Use a database to save user states, ensuring continuity even if the bot restarts.
- Inline Keyboards: Replace reply keyboards with inline keyboards for a more polished user interface.
- Dynamic Content: Allow users to input text to make the game more interactive and personalized.
- Advanced Logging: Implement comprehensive logging to monitor errors and user interactions effectively.
- Unit Testing: Add tests to ensure all functionalities work as expected.
- Deploy to Cloud Platforms: Host the bot on platforms like Heroku, AWS, or Google Cloud for better accessibility.
- User Profiles: Maintain user profiles to track progress, preferences, or achievements.
- Rich Media Integration: Incorporate images, videos, or audio to enhance storytelling.
- Branching Narratives: Develop more complex storylines with multiple branching paths and endings.