A text-based game Bot which supports both Telegram and Discord (Matrix and more in future) at the same time, by running in a universal core logic with adapters to other platforms, all sharing the same game engine and database.
What's README-DEV_Preview.md?
That is a preview of the README file for the private XiuXianBotDev repo, which is the development build of this project.
It provides a quick overview of the future features and architecture of the XiuXianBot project.
It is not the final version and may contain incomplete or placeholder content.
The current README (This file) is slightly outdated, but since the whole architecture will change again, this README will not be updated and instead use the new one.
(Back to top | 简中)
Click To Expand
XiuXianBot is a cultivation-themed RPG text-based game bot originally built for Discord, and hopefully turn into a cross-platform version in future. It will contain:
- A core library containing all game logic, database models, and localization.
- Multiple adapters for different chat platforms (Discord, Telegram, Matrix…).
- Web interfaces for admin control and public account management.
- A single bootstrap (
start.py) that loads configuration and starts the desired adapters.
Main updates since the first internal version of the new architecture:
- Admin dashboard now uses modal dialogs for most actions.
- Database browser table features Copy ID, Ban and Deactivate controls.
- Telegram adapter correctly renders Markdown-formatted messages.
- Core storage migrated to SQLite; SQLite (built-in; automatically created) is no longer required.
(Back to top | 简中)
root/
├── adapters/
│ ├── discord/ # Discord-specific commands, modals, embeds
│ | └── bot.py # To activate the bot
│ ├── telegram/ # Telegram slash commands, inline keyboards
│ | └── bot.py # To activate the bot
│ ├── matrix/ # Matrix (future)
│ | └── bot.py # To activate the bot
│ └── ???/ # More platforms (future)
├── core/
│ ├── commands/ # Game commands (hunt.py, cul.py, asc.py, account.py, ele.py, etc.), which decides how the bot will react
│ ├── config/ # Additional game configurations, for example gacha, shops and maps
│ ├── textmaps/ # Folder where textmaps are stored, the bot uses these for localizations
│ ├── database/ # Allow the bot to connect to database and manage it
│ ├── admin/ # Additional admin logics to assist the web\_local admin dash pages
│ ├── game/ # Migrated core logics for the main game from i3 versions, now fully separated from commands
│ ├── utils/ # Additional utility tools for the bot to execute certain sub-functions of commands
│ └── ???/ # Additional folders containing future features
├── web_local/ # Local admin GUI (config management, server control)
│ ├── app.py # To launch the admin dash page at specified port
│ ├── templates/
│ │ ├── base.html # Common layout (nav-tabs, footer)
│ │ ├── index.html # Home/dashboard overview
│ │ ├── config.html # Page for main configs (root/config.json)
│ │ ├── servers.html # For switching on/off of core and adapters
│ │ ├── admin.html # To use admin commands/functions (e.g. Edit player's values, Change player's permissions)
│ │ ├── logs.html # To view/export logs
│ │ ├── accounts.html # To control accounts status (e.g. Banning, deactivating, linking manually, etc.)
│ │ └── database.html # To query player's information / render info from database in a more user friendly way
│ └── static/
│ ├── css/
│ │ └── styles.css
│ ├── icons/ # SVG icons for the admin dash pages
│ └── js/
│ ├── config.js # Logic for config's page
│ └── ... # Additional logic files
├── web_public/ # Public web portal (account linking, registration)
├── backups/ # Backups of users and items
├── config.json # Tokens, adapter toggles, DB settings
└── start.py # Main switch to load core and adapters
(Back to top | 简中)
- admin/
Additional admin logics to assist the web_local admin dash pages. - game/
Migrated core logics for the main game from i3 versions, now fully separated from commands. - commands/
Implements every game feature as plain Python functions:- Account creation & linking (switching to web GUI in future).
- Cultivation, hunting, ascending, element system, shop, inventory, status...
- config/
Additional game configurations (JSON files for gacha, shops, redemption codes, maps...). - utils/
Additional utility tools for the bot to execute certain sub-functions of commands:account_status.pyhelps the bot retrieve user data/status and generate Markdown‐formatted data output.database.pyhandles backups, universal UID generation, and default values (to prevent errors).localisation.pyfetches localized text and sends it to users.otp.pygenerates one-time passwords for account linking.
- textmaps/
Folder where textmaps are stored, the bot uses these for localizations.
Currently localized for (you’re welcome to contribute):- EN
- CHS
- CHT (Partially done)
- ???
- database/
- connection.py: SQLite connection factory and helpers for automatic table creation.
(Back to top | 简中)
Each adapter translates platform-specific events into calls into the core and formats core responses for that platform:
- Discord
- Slash commands & legacy prefixes.
- Modals for account creation & redemption codes.
- Embeds for rich, formatted responses.
- Telegram
- Slash commands + inline keyboards.
- Fallback to plain text if necessary.
- Messages now correctly support Markdown formatting.
- Matrix
- (Future) Prototyped using a Matrix SDK (e.g.
matrix-nio). - Uses plain text messages and reply buttons.
- (Future) Prototyped using a Matrix SDK (e.g.
(Back to top | 简中)
- Local admin GUI (
web_local/)
A Flask-based dashboard running on your local machine (e.g.http://localhost:11451) that provides a single-page, tabbed interface for:- Modal dialogs are used for editing and confirmations.
- Config Management (
localhost:11451/config)- Loads
config.jsoninto a user-friendly form; each key/value appears as an editable field. - “Save” button sends updated JSON via Fetch to a POST endpoint, writes back to disk, and displays a success feedback—all without reloading the page, and reminds the user if a full restart of
start.pyis required.
- Loads
- Server Control (
localhost:11451/servers)- Lists the Core process and each enabled adapter (Discord, Telegram, etc.) with toggle switches.
- Clicking “Start/Stop” launches or terminates the required service.
- Status indicators (green/red dots) show which components are running at a glance.
- (Future) Options like “Pause/Resume” similar to Docker containers.
- Admin Tools (
localhost:11451/admin)- GUI wrapper around legacy admin commands (e.g. textmap indexing, player data overrides, permission changes).
- Logs Viewer (
localhost:11451/logs)- Streams recent log entries in real time.
- Buttons to download log files.
- Filter by log source and severity.
- Database Browser (
localhost:11451/database)- Query
users(automatically joinsitemscollection info) with filters. - Displays results in a paginated table with export options.
- Each row provides Copy ID, Ban and Deactivate controls.
- See docs/sqlite_guide.md for tips on editing the SQLite database.
- Query
- Account Management (
localhost:11451/accounts)- Browse and search player information.
- Ban/unban, deactivate/reactivate, or manually link third-party IDs.
- TBA (to be added when page is done).
Technical Highlights
- Flask Blueprints organize routes (
admin_bp). - Jinja2 Templates (
base.html,index.html,config.html, etc.) provide a consistent nav-tab layout. - Bootstrap 5 for responsive, polished UI (nav-tabs, cards, badges).
- Static assets in
static/cssandstatic/jsseparate styling and client logic. - No external authentication by default (localhost only), but easily bolted on (API key, IP whitelist).
- Public portal (
web_public/)
Public domain that allows users to:- View server status.
- Register new accounts via web form.
- Link existing accounts with OTP sent to the user’s chat platform.
- View personal stats, inventory, and more via web.
(Back to top | 简中)
Docker Deployment:
- Docker (duh)
Self Build:
- Python 3.12+
- SQLite (built-in; automatically created)
- MongoDB (For
i3version)
(Back to top | 简中)
&&& This Section Is Incomplete &&&
Official Releases (OSRELDocker1.0.0_* and above) {Under Development}
-
Clone the repo
git clone https://github.com/aosumi-rena/XiuXianBot.git cd XiuXianBot -
Configure
- Edit
docker-compose.yml: Add your Discord & Telegram tokens to the environment, and edit other environment variables if needed. docker-compose.yml sample:
# Temporary placeholder, may not be the same after real release services: xiu-xian-bot: image: aosumi-rena/xiu-xian-bot:latest environment: - DISCORD_TOKEN=YOUR_DISCORD_TOKEN - TELEGRAM_TOKEN=YOUR_TELEGRAM_TOKEN ports: - "11451:11451" volumes: - ./config.json:/app/config.json
- Edit
-
Docker compose
docker-compose up -d
-
Start the local admin dashboard webpage
Once compose is up, the required containers start automatically.
Then open your browser to the configured port (e.g.http://localhost:11451) to check/finalize settings. -
Start the bot on respective servers/platforms
From the local admin panel, enable whichever platform adapters you need (Discord, Telegram, etc.), and the containers covering those adapters will launch.
(Back to top | 简中)
Pre-release: OSBLTSDocker0.1.52
-
Download Prebuild
-
Unzip and Configure
- Unzip the prebuild into any directory (7-Zip recommended).
- Configure variables (Bot Token, etc.) in the
config.json
-
Install dependencies
pip install -r requirements.txt
-
Run
python start.py
-
Start the local admin dashboard webpage
Once the running, it opens the port11451as local admin dashboard.
Open your browser to the configured port (e.g.http://localhost:11451) to check/finalize settings. -
Start the bot on respective servers/platforms
From the local admin panel, enable whichever platform adapters you need (Discord, Telegram, etc.), and the containers covering those adapters will launch.
Pre-release: Internal-3 (i3)
-
Download Prebuild
-
Unzip and Configure
- Unzip the prebuild into any directory (7-Zip recommended).
- Configure variables (Bot Token,
admin_ids, etc.) refering to the instructions in README.txt.
-
Install dependencies
pip install -r requirements.txt
-
Run
python bot.py
(Back to top | 简中)
Once running, the bot will:
-
Provide a local web dashboard at
http://localhost:11451(by default; you may change this inconfig.json) for admin control. -
The core game server listens on
http://localhost:11450by default. -
In that dashboard, enable whichever servers/platforms you need, and then:
- Connect to Discord and respond to
^start,^cul,^hunt,^asc,^ele,/shop, etc. - Connect to Telegram (if enabled) and mirror the same slash commands.
- Connect to Matrix (if enabled; prototyping in progress).
- Connect to Discord and respond to
(Back to top | 简中)
- Refactor core logic into core/ package
- Create command listener and response logic in core/commands/
- Re-construct the core server using
C# - Implement Discord adapter
- Add Telegram adapter with slash commands
- Prototype Matrix adapter
- Build web_local admin GUI
- Build web_public portal for account linking
- Dockerize entire application
- Buff systems and consumable items
- Equipment system
- Mail function
- Exploration system (map)
- Alternate cultivating pathways
- Battle system (turn-based)
- Gacha system
- Trading system
(Back to top | 简中)
- All contributions are welcome: you can fork this repo and make pull requests or open issues if you want to help improve the project.
- For localization, a Weblate site will be hosted for public contributions.
|
Project Leader | Game Logic Codes | Local Admin Dash HTML |
|
Game Mechanism Designer | Discord Adapter | Database w/r Logics | Localisations |
|
Telegram Adapter | Documentations |
(Back to top | 简中)
XiuXianBot ©2024-2025 By Aosumi Rena
This program comes with ABSOLUTELY NO WARRANTY; for details, see LICENSE.txt.
This is free software, and you are welcome to redistribute it under the terms of the GNU GPL v3.0.
(Back to top | 简中)
Aosumi Rena – rena.aosumi@mihoyo.day
Project Link: https://github.com/aosumi-rena/XiuXianBot/
(Back to top | 简中)
- BlueArchiveGM – Provided inspiration for the admin dash design
- api.tomys.top – Random anime background image (for local admin dashboard)
(Back to top | 简中)
(Back to top | 简中)